pyqres.algorithms

幅度放大

class pyqres.algorithms.amplitude_amplification.AmplitudeAmplification(reg_list, param_list, submodules)

基类：AbstractComposite

__init__(reg_list, param_list, submodules)

sum_t_count(t_count_list)

量子层析

class pyqres.algorithms.tomography.Tomography(reg_list, param_list, submodules)

基类：AbstractComposite

__init__(reg_list, param_list, submodules)

traverse_children(visitor, dagger_ctx=False, controllers_ctx=None)

sum_t_count(t_count_list)

线性求解器

class pyqres.algorithms.linear_solver.LinearSolver(reg_list, param_list, submodules)

基类：AbstractComposite

__init__(reg_list, param_list, submodules)

sum_t_count(t_count_list)

Grover 搜索

class pyqres.algorithms.grover.GroverOracle(reg_list, param_list=None, qram=None, addr_reg=None, data_reg=None, search_reg=None)

基类：Primitive

Oracle for Grover's search that marks target values.

Operation sequence:

1. QRAM load: |addr>|0> → |addr>|data[addr]>

2. Compare: Check if data matches search value

3. Phase flip: Apply -1 phase to matching states

4. Uncompute: Reverse comparison and QRAM load

Self-adjoint: the uncomputation makes O† = O.

qram

pysparq.QRAMCircuit_qutrit containing search data

addr_reg

Address register name

data_reg

Data register name

search_reg

Search value register name

condition_regs

Optional controller registers

__init__(reg_list, param_list=None, qram=None, addr_reg=None, data_reg=None, search_reg=None)

pyqsparse_object(dagger_ctx=False, controllers_ctx=None)

t_count(dagger_ctx=False, controllers_ctx=None)

T-count for one Grover oracle invocation.

Dominated by the Compare_UInt_UInt operation between data and search registers (O(m) Toffoli for m-bit comparison). Phase flip is O(1). QRAM loading is excluded (bucket-brigade has different cost model).

class pyqres.algorithms.grover.DiffusionOperator(reg_list, param_list=None)

基类：Primitive

HPH (Hadamard-Phase-Hadamard) diffusion operator.

Implements D = H ⊗⊗n (2|0⟩⟨0| - I) H ⊗⊗n = 2|s⟩⟨s| - I where |s⟩ is the uniform superposition over all n-qubit states.

Self-adjoint: D† = D.

addr_reg

Address register to diffuse over

__init__(reg_list, param_list=None)

pyqsparse_object(dagger_ctx=False, controllers_ctx=None)

t_count(dagger_ctx=False, controllers_ctx=None)

T-count for diffusion operator.

Cost = 2 * ZeroConditionalPhaseFlip(n) where n = address bits. Each n-qubit ZeroConditionalPhaseFlip costs 4n + 1 T-gates.

class pyqres.algorithms.grover.GroverOperator(reg_list, param_list=None, submodules=None, qram=None)

基类：StandardComposite

One complete Grover iteration: Oracle followed by Diffusion.

G = D · O

where O is the Grover oracle and D is the diffusion operator. Self-adjoint: G† = G.

addr_reg

Address register

data_reg

Data register (temporary)

search_reg

Search value register

qram

pysparq QRAM circuit

__init__(reg_list, param_list=None, submodules=None, qram=None)

pyqsparse_object(dagger_ctx=False, controllers_ctx=None)

t_count(dagger_ctx=False, controllers_ctx=None)

class pyqres.algorithms.grover.GroverSearch(reg_list, param_list=None, submodules=None, qram=None)

基类：AbstractComposite

Grover's quantum search algorithm.

Finds a target value in an unsorted memory of N items in O(√N) queries, providing a quadratic speedup over classical search.

参数:

• reg_list -- [addr_reg, data_reg, search_reg]

• param_list -- [memory, target, n_iterations, data_size] - memory: List[int] — search data - target: int — value to find - n_iterations: int — number of Grover iterations (auto if None) - data_size: int — bits for data register (auto if None)

• submodules -- Not used; grover_ops built internally

Resource estimation (per iteration):

T-count ≈ 2 * (4(n+m) + 1) + 4m where n = ceil(log2 N), m = data_size

示例

>>> search = GroverSearch(
...     reg_list=["addr", "data", "search"],
...     param_list=[[5, 12, 3, 8], 8, None, None]
... )
>>> tc = search.t_count()
>>> print(f"T-count estimate: {tc}")

__init__(reg_list, param_list=None, submodules=None, qram=None)

sum_t_count(t_count_list)

Sum T-counts of all Grover operations.

Formula per iteration (ignoring QRAM):

Oracle: 4 * data_size (m-bit comparison)

• 4 * n_bits + 1 (phase flip on match)

Diffusion: 2 * (4 * n_bits + 1) (two ZeroConditionalPhaseFlip)

Total per iteration: 4 * data_size + 3 * (4 * n_bits + 1)

t_count(dagger_ctx=False, controllers_ctx=None)

pyqres.algorithms.grover.grover_search(memory, target, n_iterations=None, data_size=None)

Execute Grover's search on a pysparq SparseState.

参数:

• memory (List[int]) -- List of integers to search through

• target (int) -- Value to find

• n_iterations (Optional[int]) -- Number of Grover iterations (auto-computed if None)

• data_size (Optional[int]) -- Bit size for data register (auto-computed if None)

返回类型:

tuple[int, float]

返回:

(index, probability) — most likely index containing target

Note: Requires pysparq installed. Falls back gracefully if not available.

pyqres.algorithms.grover.grover_count(memory, target, precision_bits=8, data_size=None)

Quantum counting variant of Grover's algorithm.

Uses phase estimation to count how many memory entries equal target.

参数:

• memory (List[int]) -- List of integers to search

• target (int) -- Value to count

• precision_bits (int) -- Bits in precision register

• data_size (Optional[int]) -- Bits for data register (auto if None)

返回类型:

tuple[int, float]

返回:

(estimated_count, probability)

Shor 分解

class pyqres.algorithms.shor.ModMul(reg_list, param_list=None, reg=None, a=None, x=None, N=None)

基类：Primitive

Controlled modular multiplication: |y⟩ → |y * a^(2^x) mod N⟩.

Wraps pysparq.C++ ModMul backend. In-place semantics: reg = reg * opnum mod N. Uses ripple-carry addition with O(n) multi-controlled Toffoli gates per bit.

reg

Register name (UnsignedInteger)

a

Base for exponentiation

x

Power of 2 exponent (computes a^(2^x) mod N)

N

Modulus

__init__(reg_list, param_list=None, reg=None, a=None, x=None, N=None)

pyqsparse_object(dagger_ctx=False, controllers_ctx=None)

t_count(dagger_ctx=False, controllers_ctx=None)

T-count for controlled modular multiplication.

Ripple-carry approach: n controlled additions × O(1) mcx per bit. Each n-bit ripple-carry Toffoli = (n-1) * mcx_t_count(ncontrols+2). Total ≈ 4n * mcx_t_count(ncontrols+2).

class pyqres.algorithms.shor.ExpMod(reg_list, param_list=None, input_reg=None, output_reg=None, a=None, N=None, period=None)

基类：Primitive

Modular exponentiation: |x⟩|z⟩ → |x⟩|z XOR (a^x mod N)⟩.

Wraps pysparq.CustomArithmetic. Used in the full-quantum Shor algorithm.

input_reg

Input register (holds exponent x)

output_reg

Output register (holds a^x mod N)

a

Base

N

Modulus

period

Period of a^x mod N (precomputed)

__init__(reg_list, param_list=None, input_reg=None, output_reg=None, a=None, N=None, period=None)

pyqsparse_object(dagger_ctx=False, controllers_ctx=None)

t_count(dagger_ctx=False, controllers_ctx=None)

T-count for modular exponentiation.

Implements |x⟩|z⟩ → |x⟩|z⊕a^x⟩ using a lookup table via CustomArithmetic. The period (number of distinct outputs) determines the table size. Each output bit requires a multi-controlled XOR chain:

≈ period * 4 * output_bits * mcx_t_count(ncontrols + 2)

Simplified: O(period * n²).

class pyqres.algorithms.shor.SemiClassicalShor(reg_list, param_list=None, submodules=None)

基类：AbstractComposite

Semi-classical Shor algorithm using iterative phase estimation.

Each iteration: Hadamard → controlled ModMul → phase correction → measure.

参数:

• reg_list -- [anc_reg] - auxiliary register for modular arithmetic

• param_list -- [a, N] - base and modulus

Resource estimation:

T-count ≈ size × (1 + 4n × mcx_t_count(3)) where n = ceil(log2 N), size = 2n

__init__(reg_list, param_list=None, submodules=None)

sum_t_count(t_count_list)

Total T-count for semi-classical Shor.

Each iteration: 1 Hadamard + controlled ModMul (≈ 4n × mcx_t_count(3))

t_count(dagger_ctx=False, controllers_ctx=None)

class pyqres.algorithms.shor.Shor(reg_list, param_list=None, submodules=None)

基类：AbstractComposite

Full quantum Shor algorithm with quantum phase estimation.

Circuit: Hadamard(work) → ExpMod(work, anc) → InverseQFT(work)

参数:

• reg_list -- [work_reg, anc_reg]

• param_list -- [a, N, period]

__init__(reg_list, param_list=None, submodules=None)

sum_t_count(t_count_list)

Total T-count for full quantum Shor.

Components:

• Hadamard(work): 0 T-gates

• ExpMod: O(period × n²) Toffoli

• InverseQFT: O(n²) Toffoli

t_count(dagger_ctx=False, controllers_ctx=None)

pyqres.algorithms.shor.factor(N, a=None)

Factor N using semi-classical Shor's algorithm (pysparq simulation).

参数:

• N (int) -- Integer to factor

• a (int | None) -- Random base (auto-selected if None)

返回:

(p, q) such that p * q = N

pyqres.algorithms.shor.factor_full_quantum(N, a=None)

Factor N using full quantum Shor with QFT (pysparq simulation).

pyqres.algorithms.shor.general_expmod(a, x, N)

Compute a^x mod N using square-and-multiply.

返回类型:

int

pyqres.algorithms.shor.shor_postprocess(meas, size, a, N)

Extract factors from measurement result via continued fractions.

块编码

pyqres.algorithms.block_encoding.get_tridiagonal_matrix(alpha, beta, dim)

Return the dim×dim tridiagonal matrix alpha*I + beta*T.

The off-diagonal matrix T has ones on the first sub- and super-diagonal.

返回类型:

ndarray

pyqres.algorithms.block_encoding.get_u_plus(size)

Return the size×size shift-down (sub-diagonal) matrix.

返回类型:

ndarray

pyqres.algorithms.block_encoding.get_u_minus(size)

Return the size×size shift-up (super-diagonal) matrix.

返回类型:

ndarray

class pyqres.algorithms.block_encoding.BlockEncodingTridiagonal(reg_list=None, param_list=None, submodules=None, main_reg='main', anc_UA='anc_UA', alpha=0.0, beta=0.0)

基类：StandardComposite

Block encoding of a tridiagonal matrix alpha*I + beta*T.

Uses a 4-element ancilla state for state preparation, then applies conditional increment/decrement on the main register. Self-adjoint when beta >= 0.

main_reg

Main index register

anc_UA

Ancilla register for unitary encoding (4-element)

alpha

Diagonal coefficient

beta

Off-diagonal coefficient

__init__(reg_list=None, param_list=None, submodules=None, main_reg='main', anc_UA='anc_UA', alpha=0.0, beta=0.0)

t_count(dagger_ctx=False, controllers_ctx=None)

pyqsparse_object(dagger_ctx=False, controllers_ctx=None)

class pyqres.algorithms.block_encoding.UR(reg_list=None, param_list=None, submodules=None, qram=None, column_index='col', data_size=32, rational_size=16)

基类：StandardComposite

Right-multiplication operator for QRAM-based block encoding.

Encodes column norms of the target matrix. Iterates over address bits, performing QRAM loads, division, conditional rotation, and uncomputation.

__init__(reg_list=None, param_list=None, submodules=None, qram=None, column_index='col', data_size=32, rational_size=16)

pyqsparse_object(dagger_ctx=False, controllers_ctx=None)

class pyqres.algorithms.block_encoding.UL(reg_list=None, param_list=None, submodules=None, qram=None, row_index='row', column_index='col', data_size=32, rational_size=16)

基类：StandardComposite

Left-multiplication operator for QRAM-based block encoding.

Encodes the row structure of the target matrix. Iterates over upper address bits, constructing parent/child addresses, loading from QRAM, computing rotation angles, and applying conditional rotations.

__init__(reg_list=None, param_list=None, submodules=None, qram=None, row_index='row', column_index='col', data_size=32, rational_size=16)

pyqsparse_object(dagger_ctx=False, controllers_ctx=None)

class pyqres.algorithms.block_encoding.BlockEncodingViaQRAM(reg_list=None, param_list=None, submodules=None, qram=None, row_index='row', column_index='col', data_size=32, rational_size=16)

基类：StandardComposite

Block encoding of an arbitrary matrix via QRAM.

Composed as: U_A = SWAP(row, col) · U_R†(col) · U_L(row, col)

qram

pysparq.QRAMCircuit_qutrit

row_index

Row index register

column_index

Column index register

data_size

Data register bit size

rational_size

Rational rotation register bit size

__init__(reg_list=None, param_list=None, submodules=None, qram=None, row_index='row', column_index='col', data_size=32, rational_size=16)

pyqsparse_object(dagger_ctx=False, controllers_ctx=None)

class pyqres.algorithms.block_encoding.PlusOneOverflow(reg_list, param_list=None)

基类：Primitive

Increment main register by 1, with overflow flag.

Used in BlockEncodingTridiagonal for controlled increment. Implements ps.PlusOneAndOverflow(main_reg, overflow_reg).

The forward operation conditions on anc_UA=1, the dagger on anc_UA=2.

__init__(reg_list, param_list=None)

dagger()

pyqsparse_object(dagger_ctx=False, controllers_ctx=None)

t_count(dagger_ctx=False, controllers_ctx=None)

QRAM 态制备

pyqres.algorithms.state_prep.pow2(n)

Return 2**n as an integer left-shift.

返回类型:

int

pyqres.algorithms.state_prep.get_complement(data, data_sz)

Sign-extend unsigned data to a signed integer.

Ported from pysparq/algorithms/qram_utils.py.

返回类型:

int

pyqres.algorithms.state_prep.make_complement(data, data_sz)

Convert signed integer to unsigned two's-complement.

返回类型:

int

pyqres.algorithms.state_prep.make_vector_tree(dist, data_size)

Build a binary tree from leaf distribution data for QRAM circuits.

Ported from pysparq/algorithms/qram_utils.py.

返回类型:

list[int]

pyqres.algorithms.state_prep.make_func(value, n_digit)

Compute a 2x2 rotation matrix from a rational register value.

theta = value / 2**n_digit * 2 * pi Matrix: [cos(theta), -sin(theta), sin(theta), cos(theta)]

返回类型:

list[complex]

pyqres.algorithms.state_prep.make_func_inv(value, n_digit)

Inverse 2x2 rotation matrix (off-diagonal signs flipped).

返回类型:

list[complex]

class pyqres.algorithms.state_prep.StatePrepViaQRAM(reg_list=None, param_list=None, submodules=None, qram=None, work_qubit='main', data_size=32, rational_size=16)

基类：StandardComposite

QRAM-based quantum state preparation via binary tree decomposition.

Given a QRAM circuit storing a binary-tree representation of a target amplitude distribution, prepares the corresponding quantum state by traversing the tree level-by-level, loading parent/child norms from QRAM, and applying conditional rotations at each level.

qram

QRAMCircuit_qutrit holding the tree-encoded distribution

work_qubit

Register on which the state is prepared

data_size

Bit-width of signed integer data stored in QRAM

rational_size

Bit-width of the rational rotation-angle register

__init__(reg_list=None, param_list=None, submodules=None, qram=None, work_qubit='main', data_size=32, rational_size=16)

pyqsparse_object(dagger_ctx=False, controllers_ctx=None)

class pyqres.algorithms.state_prep.StatePreparation(qubit_number, data_size=8, data_range=4)

基类：object

High-level pipeline for QRAM-based state preparation.

Manages: random distribution generation, binary tree construction, QRAM creation, and execution.

qubit_number

Number of qubits (log2 of distribution length)

data_size

Bit-width for signed integer amplitude encoding

data_range

Bit-range controlling random amplitude magnitude

rational_size

Bit-width for rational rotation-angle register

dist

Raw distribution values (unsigned two's complement)

tree

Binary tree built from dist for QRAM storage

qram

QRAM circuit instance

__init__(qubit_number, data_size=8, data_range=4)

random_distribution()

Generate a random amplitude distribution.

Each entry is sampled uniformly from [0, 2**data_range). Values in the upper half are mapped to negative via two's complement.

返回类型:

None

set_distribution(dist)

Set a specific distribution instead of generating randomly.

返回类型:

None

make_tree()

Build the binary tree from the current distribution.

返回类型:

None

make_qram()

Create an empty QRAM circuit sized for the tree data.

返回类型:

None

set_qram()

Load the binary tree data into the QRAM circuit.

返回类型:

None

get_real_dist()

Return normalized amplitude distribution as floats.

返回类型:

list[float]

get_fidelity()

Compute fidelity of prepared state vs target distribution.

返回类型:

float

run()

Execute the full state-preparation pipeline.

Creates registers, initializes state, and applies StatePrepViaQRAM.

返回类型:

None