Resource estimation

oracq.infrastructure.estimate

Toffoli+Clifford+T+QRAM level resource estimation.

Counting descends the OriginIR-ext → basis lowering chain following the real emission recipes (basis.mcx and basis.controlled_u3): the module graph aggregates compositionally, Repeat multiplies symbolic counts, and no exponential expansion happens. Rotation gates are classified by angle: integer multiples of π/4 fall into exact Clifford+T (T/SDG/S/Z counts), the rest are recorded as rotation atoms pending synthesis, with the T cost estimated by the Ross–Selinger style model synthesis_t_per_rotation (default ceil(3*log2(1/eps))). Global phase is not counted (consistent with strict export).

Control costs align with the exporter line by line: zero-valued control bits are flipped once on each side of every emitted line group (primitive gate / call / Repeat call lines), for 2 X gates per zero bit; controlled single-qubit gates follow the controlled_u3 recipe (a 2(c−1) Toffoli ladder + an intermediate network when c≥2), and X-type multi-controls follow the mcx recipe (2c−3 Toffoli when c≥3).

QRAM query counts are tallied per resource over Load nodes (each Load = 1 query) as a first-class metric independent of gate-level cost. QRAM random writes are tallied per resource over Store nodes into qram_writes: storage cells are modeled as classical cells, and random writes do not enter gate cost.

oracq.infrastructure.estimate.CLIFFORD_ATOMS = ('h', 'x', 'y', 'z', 's', 'sdg', 'cnot', 'cz')

Set of Clifford atom names; ResourceEstimate.clifford summarizes atoms counts over these names.

oracq.infrastructure.estimate.classify_rz(angle)

Classify an rz/phase atom: exact Clifford+T or a rotation pending synthesis.

Parameters:

angle – rotation angle in radians.

Returns:

pair (exact atom counts, rotations pending synthesis); an angle that is an integer multiple of π/4 goes into the former, otherwise the whole entry is recorded as the rotation ("rz", angle) pending synthesis.

Return type:

tuple[Counter[str], list[tuple[str, float]]]

oracq.infrastructure.estimate.classify_ry(angle)

Classify an ry atom: RY(θ) = S·H·RZ(θ)·H·S†.

Parameters:

angle – rotation angle in radians.

Returns:

pair (exact atom counts, rotations pending synthesis); an angle that is not an integer multiple of π/4 is recorded whole as the rotation ("ry", angle) pending synthesis, and a zero angle returns two empty containers.

Return type:

tuple[Counter[str], list[tuple[str, float]]]

oracq.infrastructure.estimate.classify_u3(theta, phi, lam)

U3(θ,φ,λ) = RZ(φ)·RY(θ)·RZ(λ), dropping global phase, consistent with strict export.

Common gates H/X/Y are first matched as exact single atoms, then fall back to the Euler decomposition.

Parameters:

• theta – Y-axis Euler angle in radians.

• phi – left Z-axis Euler angle in radians.

• lam – right Z-axis Euler angle in radians.

Returns:

pair (exact atom counts, rotations pending synthesis); the H/X/Y special cases match a single atom, the rest are summarized item by item via the Euler decomposition.

Return type:

tuple[Counter[str], list[tuple[str, float]]]

oracq.infrastructure.estimate.mcx_counts(n_controls)

basis.mcx recipe, the X-type multi-control.

Parameters:

n_controls – number of effective control bits, a nonnegative integer.

Returns:

atom counts of the multi-control X; c of 0/1/2 gives a single X, H-CZ-H and a single Toffoli respectively, and c≥3 gives 2c−3 Toffoli gates.

Return type:

Counter[str]

class oracq.infrastructure.estimate.RotationCounts(values=())

Bases: Sequence[tuple[str, float]]

Store rotation multiplicities by axis and angle; supports read-only length, indexing and lazy iteration.

counts

property total

Total number of rotations; not limited by the machine integer bound on Python sequence lengths.

add_scaled(other, factor=1)

Combine multiplicities without copying the rotation list.

class oracq.infrastructure.estimate.OracleCall(module, controls=0, adjoint=False, resources=())

Bases: object

Call form of an open oracle; resource names are relative to the current module, with argument substitution already done in the entry report.

module

controls = 0

adjoint = False

resources = ()

class oracq.infrastructure.estimate.ResourceEstimate(qubits, atoms=<factory>, rotations=<factory>, qram_queries=<factory>, qram_writes=<factory>, mcx_ancilla=0, oracle_calls=<factory>, unknown_workspace=(), qubits_lower_bound=0)

Bases: object

Toffoli+Clifford+T+QRAM level resource ledger.

qubits

atoms

rotations

qram_queries

qram_writes

mcx_ancilla = 0

oracle_calls

unknown_workspace = ()

qubits_lower_bound = 0

property complete

Whether known implementations cover all entry-reachable slots.

property toffoli

Total number of Toffoli gates in atoms.

property t_exact

Total number of T and TDG gates falling exactly into Clifford+T, excluding the T cost of rotations pending synthesis.

property clifford

Sum of counts of the atoms listed in CLIFFORD_ATOMS within atoms.

property qram_total

Sum of query counts over all resources in qram_queries.

property qram_write_total

Sum of random-write counts over all resources in qram_writes.

property gate_total

Sum of all atom counts in atoms, excluding QRAM queries and writes.

synthesis_t_per_rotation(epsilon=1e-10)

Ross–Selinger style leading-term model; replaceable as a whole.

Parameters:

epsilon – synthesis precision of a single rotation, in (0, 1).

Returns:

T gate cost per rotation pending synthesis, i.e. ceil(3*log2(1/epsilon)), at least 1.

Return type:

int

t_synthesis(epsilon=1e-10)

Total T cost of rotations pending synthesis: rotation count times synthesis_t_per_rotation(epsilon).

Parameters:

epsilon – synthesis precision of a single rotation.

Returns:

estimated T gate cost of all rotations pending synthesis.

Return type:

int

t_total(epsilon=1e-10)

Sum of the exact T count and the T cost of rotations pending synthesis, i.e. t_exact + t_synthesis.

Parameters:

epsilon – synthesis precision of a single rotation.

Returns:

total T gate count: exact T/TDG counts plus the synthesis T cost.

Return type:

int

to_dict(epsilon=1e-10)

Export a JSON-friendly flat resource ledger.

Parameters:

epsilon – rotation synthesis precision, also recorded in the result under the epsilon key.

Returns:

includes the qubit count and mcx_ancilla, Toffoli/Clifford/exact T counts, the total of rotations pending synthesis with per-axis statistics, T cost estimates, per-atom atoms details, per-resource QRAM query/write counts and totals, plus gate_total.

Return type:

dict

oracq.infrastructure.estimate.estimate_resources(program, *, require_closed=True)

Composable resource estimation: memoized by module and control count, with Repeat counts multiplied symbolically.

Parameters:

• program – RIR program to estimate; module implementations must be closed unless validation is relaxed.

• require_closed – when false, open declaration modules may remain; by default all must be closed.

Returns:

aggregated resource ledger; the qubit count includes the workspace, and the maximum control count determines mcx_ancilla.

Return type:

ResourceEstimate