qamomile.circuit.algorithm

Algorithm building blocks for quantum circuits.

Overview¶

Functions¶

cost_layer [source]¶

def cost_layer(
    q: qmc.Vector[qmc.Qubit],
    gamma: qmc.Float,
    linear: qmc.Dict[qmc.UInt, qmc.Float],
    quad: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
) -> qmc.Vector[qmc.Qubit]

Apply the cost (phase separation) layer.

cx_entangling_layer [source]¶

def cx_entangling_layer(q: qmc.Vector[qmc.Qubit]) -> qmc.Vector[qmc.Qubit]

Apply CX entangling layer with linear connectivity.

Applies CX gates between consecutive qubits: (0,1), (1,2), ..., (n-2,n-1).

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — qmc.Vector[qmc.Qubit]: Qubit vector after entanglement

cz_entangling_layer [source]¶

def cz_entangling_layer(q: qmc.Vector[qmc.Qubit]) -> qmc.Vector[qmc.Qubit]

Apply CZ entangling layer with linear connectivity.

Applies CZ gates between consecutive qubits: (0,1), (1,2), ..., (n-2,n-1).

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — Qubit vector after entanglement

ekera_hastad_factoring [source]¶

def ekera_hastad_factoring(
    generator: int,
    modulus: int,
    *,
    window_size: int = 2,
) -> QKernel[..., qmc.Vector[qmc.Bit]]

Create the quantum short-DLP stage for Ekerå–Håstad factoring.

For a balanced semiprime N = p*q, this measures the two modular phase schedules associated with g and y**-1, where y = g**(N + 1) mod N. Their precisions are 2m and m for m = ceil(n / 2) + 1. Both schedules recycle the same phase qubit and arithmetic workspace; classical lattice post-processing remains outside this qkernel.

Parameters:

Returns:

QKernel[..., qmc.Vector[qmc.Bit]] — QKernel[..., qmc.Vector[qmc.Bit]]: Argument-free kernel returning the 2m long-schedule bits followed by the m short-schedule bits. Each group is little-endian.

Raises:

• ValueError — If the modular map or lookup width is invalid.

fqaoa_layers [source]¶

def fqaoa_layers(
    q: qmc.Vector[qmc.Qubit],
    betas: qmc.Vector[qmc.Float],
    gammas: qmc.Vector[qmc.Float],
    p: qmc.UInt,
    linear: qmc.Dict[qmc.UInt, qmc.Float],
    quad: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
    hopping: qmc.Float,
    num_qubits: qmc.UInt,
) -> qmc.Vector[qmc.Qubit]

Apply p layers of cost + mixer.

fqaoa_state [source]¶

def fqaoa_state(
    p: qmc.UInt,
    linear: qmc.Dict[qmc.UInt, qmc.Float],
    quad: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
    num_qubits: qmc.UInt,
    num_fermions: qmc.UInt,
    givens_ij: qmc.Matrix[qmc.UInt],
    givens_theta: qmc.Vector[qmc.Float],
    hopping: qmc.Float,
    gammas: qmc.Vector[qmc.Float],
    betas: qmc.Vector[qmc.Float],
) -> qmc.Vector[qmc.Qubit]

Generate complete FQAOA state.

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — FQAOA state vector.

givens_rotation [source]¶

def givens_rotation(
    q: qmc.Vector[qmc.Qubit],
    i: qmc.UInt,
    j: qmc.UInt,
    theta: qmc.Float,
) -> qmc.Vector[qmc.Qubit]

Apply a single Givens rotation between qubits i and j.

The controlled-RY factory is constructed inside the function rather than at module level so importing fqaoa does not trigger eager wrapper synthesis (compile/exec + tracing) for every install. The synthesized wrapper is cached per-callable inside qmc.control, so the only real cost happens on the first Givens rotation; subsequent calls hit the cache.

givens_rotations [source]¶

def givens_rotations(
    q: qmc.Vector[qmc.Qubit],
    givens_ij: qmc.Matrix[qmc.UInt],
    givens_theta: qmc.Vector[qmc.Float],
) -> qmc.Vector[qmc.Qubit]

Apply a sequence of Givens rotations.

Parameters:

hopping_gate [source]¶

def hopping_gate(
    q: qmc.Vector[qmc.Qubit],
    i: qmc.UInt,
    j: qmc.UInt,
    beta: qmc.Float,
    hopping: qmc.Float,
) -> qmc.Vector[qmc.Qubit]

Apply the fermionic hopping gate between qubits i and j.

hubo_ising_cost [source]¶

def hubo_ising_cost(
    quad: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
    linear: qmc.Dict[qmc.UInt, qmc.Float],
    higher: qmc.Dict[qmc.Vector[qmc.UInt], qmc.Float],
    q: qmc.Vector[qmc.Qubit],
    gamma: qmc.Float,
) -> qmc.Vector[qmc.Qubit]

Apply the full cost layer including higher-order terms.

Applies the standard quadratic Ising cost circuit, then decomposes each higher-order term into phase gadgets.

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — qmc.Vector[qmc.Qubit]: Updated qubit register.

hubo_qaoa_layers [source]¶

def hubo_qaoa_layers(
    p_val: qmc.UInt,
    quad: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
    linear: qmc.Dict[qmc.UInt, qmc.Float],
    higher: qmc.Dict[qmc.Vector[qmc.UInt], qmc.Float],
    q: qmc.Vector[qmc.Qubit],
    gammas: qmc.Vector[qmc.Float],
    betas: qmc.Vector[qmc.Float],
) -> qmc.Vector[qmc.Qubit]

Apply p layers of the HUBO QAOA circuit (cost + mixer).

Each layer applies the HUBO cost circuit (quadratic + higher-order terms) followed by the X-mixer circuit.

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — qmc.Vector[qmc.Qubit]: Updated qubit register after all layers.

hubo_qaoa_state [source]¶

def hubo_qaoa_state(
    p_val: qmc.UInt,
    quad: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
    linear: qmc.Dict[qmc.UInt, qmc.Float],
    higher: qmc.Dict[qmc.Vector[qmc.UInt], qmc.Float],
    n: qmc.UInt,
    gammas: qmc.Vector[qmc.Float],
    betas: qmc.Vector[qmc.Float],
) -> qmc.Vector[qmc.Qubit]

Generate HUBO QAOA state.

Creates a uniform superposition and applies p layers of the HUBO QAOA circuit.

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — qmc.Vector[qmc.Qubit]: HUBO QAOA state vector.

initial_occupations [source]¶

def initial_occupations(q: qmc.Vector[qmc.Qubit], num_fermions: qmc.UInt) -> qmc.Vector[qmc.Qubit]

Apply X gates to the first num_fermions qubits.

ising_cost [source]¶

def ising_cost(
    quad: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
    linear: qmc.Dict[qmc.UInt, qmc.Float],
    q: qmc.Vector[qmc.Qubit],
    gamma: qmc.Float,
) -> qmc.Vector[qmc.Qubit]

Apply the Ising cost layer for quadratic interactions.

Applies RZZ gates for quadratic terms and RZ gates for linear terms. Qamomile rotation gates implement exp(-i * angle * P / 2), so each angle is 2 * coefficient * gamma to realize exp(-i * gamma * H_cost).

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — qmc.Vector[qmc.Qubit]: Updated qubit register.

mixer_layer [source]¶

def mixer_layer(
    q: qmc.Vector[qmc.Qubit],
    beta: qmc.Float,
    hopping: qmc.Float,
    num_qubits: qmc.UInt,
) -> qmc.Vector[qmc.Qubit]

Apply the fermionic mixer layer (even-odd-boundary hopping).

qaoa_layers [source]¶

def qaoa_layers(
    p: qmc.UInt,
    quad: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
    linear: qmc.Dict[qmc.UInt, qmc.Float],
    q: qmc.Vector[qmc.Qubit],
    gammas: qmc.Vector[qmc.Float],
    betas: qmc.Vector[qmc.Float],
) -> qmc.Vector[qmc.Qubit]

Apply p layers of the QAOA circuit (cost + mixer).

Each layer applies the Ising cost circuit followed by the X-mixer circuit.

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — qmc.Vector[qmc.Qubit]: Updated qubit register after all layers.

qaoa_state [source]¶

def qaoa_state(
    p: qmc.UInt,
    quad: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
    linear: qmc.Dict[qmc.UInt, qmc.Float],
    n: qmc.UInt,
    gammas: qmc.Vector[qmc.Float],
    betas: qmc.Vector[qmc.Float],
) -> qmc.Vector[qmc.Qubit]

Generate QAOA State for Ising model.

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — qmc.Vector[qmc.Qubit]: QAOA state vector.

rx_layer [source]¶

def rx_layer(
    q: qmc.Vector[qmc.Qubit],
    thetas: qmc.Vector[qmc.Float],
    offset: qmc.UInt,
) -> qmc.Vector[qmc.Qubit]

Apply RX rotation to each qubit.

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — Qubit vector after rotations

ry_layer [source]¶

def ry_layer(
    q: qmc.Vector[qmc.Qubit],
    thetas: qmc.Vector[qmc.Float],
    offset: qmc.UInt,
) -> qmc.Vector[qmc.Qubit]

Apply RY rotation to each qubit.

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — Qubit vector after rotations

rz_layer [source]¶

def rz_layer(
    q: qmc.Vector[qmc.Qubit],
    thetas: qmc.Vector[qmc.Float],
    offset: qmc.UInt,
) -> qmc.Vector[qmc.Qubit]

Apply RZ rotation to each qubit.

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — Qubit vector after rotations

shor_order_finding [source]¶

def shor_order_finding(
    base: int,
    modulus: int,
    *,
    window_size: int = 2,
    precision: int | None = None,
) -> QKernel[..., qmc.Vector[qmc.Bit]]

Create an executable order-finding qkernel for base mod modulus.

The modulus fixes the work-register width, so the returned kernel has no artificial n runtime argument. It uses one recycled phase qubit and measurement feed-forward instead of a coherent 2n counting register. With fixed window_size, the body therefore has 3n + O(1) peak width and O(n**3) gates at the default 2n phase precision. The example’s 23-qubit estimate uses the default algorithmic decomposition model: 21 program qubits plus two reusable clean ancillas. An engine that emits the relevant multi-controlled operations natively can therefore produce a 21-qubit circuit.

Parameters:

Returns:

QKernel[..., qmc.Vector[qmc.Bit]] — QKernel[..., qmc.Vector[qmc.Bit]]: Argument-free executable kernel returning little-endian phase bits.

Raises:

• ValueError — If the inputs do not define a reversible modular map.

Example:

>>> order_finding = shor_order_finding(base=2, modulus=15)
>>> estimate = order_finding.estimate_resources()
>>> estimate.qubits
23

superposition_vector [source]¶

def superposition_vector(n: qmc.UInt) -> qmc.Vector[qmc.Qubit]

Create a uniform superposition state by applying Hadamard to all qubits.

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — qmc.Vector[qmc.Qubit]: Qubit register in the |+>^n state.

trotterized_time_evolution [source]¶

def trotterized_time_evolution(
    q: qmc.Vector[qmc.Qubit],
    hamiltonian: qmc.Vector[qmc.Observable] | Sequence[Hamiltonian],
    order: int | qmc.UInt,
    gamma: float | qmc.Float,
    step: int | qmc.UInt,
) -> qmc.Vector[qmc.Qubit]

Apply Suzuki-Trotter time evolution exp(-i gamma H) to q.

H = sum_k hamiltonian[k]. The evolution is split into step Trotter slices of size dt = gamma / step; each slice applies the order-th Suzuki-Trotter formula via :func:_trotter_evolve.

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — The evolved qubit register.

Raises:

• ValueError — If hamiltonian has fewer than two terms, if order is a bool, or if order is not 1 or a positive even integer, or if step is not a positive integer. When these arguments are still symbolic (e.g. the enclosing kernel has not been re-traced with bindings yet) validation silently defers.

x_mixer [source]¶

def x_mixer(q: qmc.Vector[qmc.Qubit], beta: qmc.Float) -> qmc.Vector[qmc.Qubit]

Apply the X-mixer layer.

Applies RX(2*beta) to every qubit in the register.

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — qmc.Vector[qmc.Qubit]: Updated qubit register.

qamomile.circuit.algorithm.basic¶

Basic building blocks for variational quantum circuits.

This module provides fundamental rotation layers and entanglement layers that can be composed to build variational ansatze.

Overview¶

Functions¶

cx_entangling_layer [source]¶

def cx_entangling_layer(q: qmc.Vector[qmc.Qubit]) -> qmc.Vector[qmc.Qubit]

Apply CX entangling layer with linear connectivity.

Applies CX gates between consecutive qubits: (0,1), (1,2), ..., (n-2,n-1).

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — qmc.Vector[qmc.Qubit]: Qubit vector after entanglement

cz_entangling_layer [source]¶

def cz_entangling_layer(q: qmc.Vector[qmc.Qubit]) -> qmc.Vector[qmc.Qubit]

Apply CZ entangling layer with linear connectivity.

Applies CZ gates between consecutive qubits: (0,1), (1,2), ..., (n-2,n-1).

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — Qubit vector after entanglement

phase_gadget [source]¶

def phase_gadget(
    q: qmc.Vector[qmc.Qubit],
    indices: qmc.Vector[qmc.UInt],
    angle: qmc.Float,
) -> qmc.Vector[qmc.Qubit]

Apply exp(-i * angle/2 * Z_{i0} Z_{i1} ... Z_{ik-1}).

Decomposes a k-body Z-rotation into CX + RZ primitives.

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — qmc.Vector[qmc.Qubit]: Updated qubit register.

rx_layer [source]¶

def rx_layer(
    q: qmc.Vector[qmc.Qubit],
    thetas: qmc.Vector[qmc.Float],
    offset: qmc.UInt,
) -> qmc.Vector[qmc.Qubit]

Apply RX rotation to each qubit.

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — Qubit vector after rotations

ry_layer [source]¶

def ry_layer(
    q: qmc.Vector[qmc.Qubit],
    thetas: qmc.Vector[qmc.Float],
    offset: qmc.UInt,
) -> qmc.Vector[qmc.Qubit]

Apply RY rotation to each qubit.

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — Qubit vector after rotations

rz_layer [source]¶

def rz_layer(
    q: qmc.Vector[qmc.Qubit],
    thetas: qmc.Vector[qmc.Float],
    offset: qmc.UInt,
) -> qmc.Vector[qmc.Qubit]

Apply RZ rotation to each qubit.

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — Qubit vector after rotations

superposition_vector [source]¶

def superposition_vector(n: qmc.UInt) -> qmc.Vector[qmc.Qubit]

Create a uniform superposition state by applying Hadamard to all qubits.

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — qmc.Vector[qmc.Qubit]: Qubit register in the |+>^n state.

qamomile.circuit.algorithm.fqaoa¶

FQAOA (Fermionic QAOA) circuit building blocks.

This module provides the quantum circuit components for the Fermionic Quantum Approximate Optimization Algorithm (FQAOA), including Givens rotations for initial state preparation, hopping gates for the fermionic mixer, and cost layer construction.

All functions are decorated with @qm_c.qkernel and use Handle-typed parameters so they can be composed inside other @qkernel functions.

Overview¶

Functions¶

cost_layer [source]¶

def cost_layer(
    q: qmc.Vector[qmc.Qubit],
    gamma: qmc.Float,
    linear: qmc.Dict[qmc.UInt, qmc.Float],
    quad: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
) -> qmc.Vector[qmc.Qubit]

Apply the cost (phase separation) layer.

fqaoa_layers [source]¶

def fqaoa_layers(
    q: qmc.Vector[qmc.Qubit],
    betas: qmc.Vector[qmc.Float],
    gammas: qmc.Vector[qmc.Float],
    p: qmc.UInt,
    linear: qmc.Dict[qmc.UInt, qmc.Float],
    quad: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
    hopping: qmc.Float,
    num_qubits: qmc.UInt,
) -> qmc.Vector[qmc.Qubit]

Apply p layers of cost + mixer.

fqaoa_state [source]¶

def fqaoa_state(
    p: qmc.UInt,
    linear: qmc.Dict[qmc.UInt, qmc.Float],
    quad: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
    num_qubits: qmc.UInt,
    num_fermions: qmc.UInt,
    givens_ij: qmc.Matrix[qmc.UInt],
    givens_theta: qmc.Vector[qmc.Float],
    hopping: qmc.Float,
    gammas: qmc.Vector[qmc.Float],
    betas: qmc.Vector[qmc.Float],
) -> qmc.Vector[qmc.Qubit]

Generate complete FQAOA state.

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — FQAOA state vector.

givens_rotation [source]¶

def givens_rotation(
    q: qmc.Vector[qmc.Qubit],
    i: qmc.UInt,
    j: qmc.UInt,
    theta: qmc.Float,
) -> qmc.Vector[qmc.Qubit]

Apply a single Givens rotation between qubits i and j.

The controlled-RY factory is constructed inside the function rather than at module level so importing fqaoa does not trigger eager wrapper synthesis (compile/exec + tracing) for every install. The synthesized wrapper is cached per-callable inside qmc.control, so the only real cost happens on the first Givens rotation; subsequent calls hit the cache.

givens_rotations [source]¶

def givens_rotations(
    q: qmc.Vector[qmc.Qubit],
    givens_ij: qmc.Matrix[qmc.UInt],
    givens_theta: qmc.Vector[qmc.Float],
) -> qmc.Vector[qmc.Qubit]

Apply a sequence of Givens rotations.

Parameters:

hopping_gate [source]¶

def hopping_gate(
    q: qmc.Vector[qmc.Qubit],
    i: qmc.UInt,
    j: qmc.UInt,
    beta: qmc.Float,
    hopping: qmc.Float,
) -> qmc.Vector[qmc.Qubit]

Apply the fermionic hopping gate between qubits i and j.

initial_occupations [source]¶

def initial_occupations(q: qmc.Vector[qmc.Qubit], num_fermions: qmc.UInt) -> qmc.Vector[qmc.Qubit]

Apply X gates to the first num_fermions qubits.

mixer_layer [source]¶

def mixer_layer(
    q: qmc.Vector[qmc.Qubit],
    beta: qmc.Float,
    hopping: qmc.Float,
    num_qubits: qmc.UInt,
) -> qmc.Vector[qmc.Qubit]

Apply the fermionic mixer layer (even-odd-boundary hopping).

qamomile.circuit.algorithm.qaoa¶

Overview¶

Functions¶

hubo_ising_cost [source]¶

def hubo_ising_cost(
    quad: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
    linear: qmc.Dict[qmc.UInt, qmc.Float],
    higher: qmc.Dict[qmc.Vector[qmc.UInt], qmc.Float],
    q: qmc.Vector[qmc.Qubit],
    gamma: qmc.Float,
) -> qmc.Vector[qmc.Qubit]

Apply the full cost layer including higher-order terms.

Applies the standard quadratic Ising cost circuit, then decomposes each higher-order term into phase gadgets.

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — qmc.Vector[qmc.Qubit]: Updated qubit register.

hubo_qaoa_layers [source]¶

def hubo_qaoa_layers(
    p_val: qmc.UInt,
    quad: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
    linear: qmc.Dict[qmc.UInt, qmc.Float],
    higher: qmc.Dict[qmc.Vector[qmc.UInt], qmc.Float],
    q: qmc.Vector[qmc.Qubit],
    gammas: qmc.Vector[qmc.Float],
    betas: qmc.Vector[qmc.Float],
) -> qmc.Vector[qmc.Qubit]

Apply p layers of the HUBO QAOA circuit (cost + mixer).

Each layer applies the HUBO cost circuit (quadratic + higher-order terms) followed by the X-mixer circuit.

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — qmc.Vector[qmc.Qubit]: Updated qubit register after all layers.

hubo_qaoa_state [source]¶

def hubo_qaoa_state(
    p_val: qmc.UInt,
    quad: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
    linear: qmc.Dict[qmc.UInt, qmc.Float],
    higher: qmc.Dict[qmc.Vector[qmc.UInt], qmc.Float],
    n: qmc.UInt,
    gammas: qmc.Vector[qmc.Float],
    betas: qmc.Vector[qmc.Float],
) -> qmc.Vector[qmc.Qubit]

Generate HUBO QAOA state.

Creates a uniform superposition and applies p layers of the HUBO QAOA circuit.

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — qmc.Vector[qmc.Qubit]: HUBO QAOA state vector.

ising_cost [source]¶

def ising_cost(
    quad: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
    linear: qmc.Dict[qmc.UInt, qmc.Float],
    q: qmc.Vector[qmc.Qubit],
    gamma: qmc.Float,
) -> qmc.Vector[qmc.Qubit]

Apply the Ising cost layer for quadratic interactions.

Applies RZZ gates for quadratic terms and RZ gates for linear terms. Qamomile rotation gates implement exp(-i * angle * P / 2), so each angle is 2 * coefficient * gamma to realize exp(-i * gamma * H_cost).

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — qmc.Vector[qmc.Qubit]: Updated qubit register.

qaoa_layers [source]¶

def qaoa_layers(
    p: qmc.UInt,
    quad: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
    linear: qmc.Dict[qmc.UInt, qmc.Float],
    q: qmc.Vector[qmc.Qubit],
    gammas: qmc.Vector[qmc.Float],
    betas: qmc.Vector[qmc.Float],
) -> qmc.Vector[qmc.Qubit]

Apply p layers of the QAOA circuit (cost + mixer).

Each layer applies the Ising cost circuit followed by the X-mixer circuit.

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — qmc.Vector[qmc.Qubit]: Updated qubit register after all layers.

qaoa_state [source]¶

def qaoa_state(
    p: qmc.UInt,
    quad: qmc.Dict[qmc.Tuple[qmc.UInt, qmc.UInt], qmc.Float],
    linear: qmc.Dict[qmc.UInt, qmc.Float],
    n: qmc.UInt,
    gammas: qmc.Vector[qmc.Float],
    betas: qmc.Vector[qmc.Float],
) -> qmc.Vector[qmc.Qubit]

Generate QAOA State for Ising model.

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — qmc.Vector[qmc.Qubit]: QAOA state vector.

x_mixer [source]¶

def x_mixer(q: qmc.Vector[qmc.Qubit], beta: qmc.Float) -> qmc.Vector[qmc.Qubit]

Apply the X-mixer layer.

Applies RX(2*beta) to every qubit in the register.

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — qmc.Vector[qmc.Qubit]: Updated qubit register.

qamomile.circuit.algorithm.shor¶

Build executable Shor order-finding kernels with body-derived resources.

Overview¶

Functions¶

ekera_hastad_factoring [source]¶

def ekera_hastad_factoring(
    generator: int,
    modulus: int,
    *,
    window_size: int = 2,
) -> QKernel[..., qmc.Vector[qmc.Bit]]

Create the quantum short-DLP stage for Ekerå–Håstad factoring.

For a balanced semiprime N = p*q, this measures the two modular phase schedules associated with g and y**-1, where y = g**(N + 1) mod N. Their precisions are 2m and m for m = ceil(n / 2) + 1. Both schedules recycle the same phase qubit and arithmetic workspace; classical lattice post-processing remains outside this qkernel.

Parameters:

Returns:

QKernel[..., qmc.Vector[qmc.Bit]] — QKernel[..., qmc.Vector[qmc.Bit]]: Argument-free kernel returning the 2m long-schedule bits followed by the m short-schedule bits. Each group is little-endian.

Raises:

• ValueError — If the modular map or lookup width is invalid.

shor_order_finding [source]¶

def shor_order_finding(
    base: int,
    modulus: int,
    *,
    window_size: int = 2,
    precision: int | None = None,
) -> QKernel[..., qmc.Vector[qmc.Bit]]

Create an executable order-finding qkernel for base mod modulus.

The modulus fixes the work-register width, so the returned kernel has no artificial n runtime argument. It uses one recycled phase qubit and measurement feed-forward instead of a coherent 2n counting register. With fixed window_size, the body therefore has 3n + O(1) peak width and O(n**3) gates at the default 2n phase precision. The example’s 23-qubit estimate uses the default algorithmic decomposition model: 21 program qubits plus two reusable clean ancillas. An engine that emits the relevant multi-controlled operations natively can therefore produce a 21-qubit circuit.

Parameters:

Returns:

QKernel[..., qmc.Vector[qmc.Bit]] — QKernel[..., qmc.Vector[qmc.Bit]]: Argument-free executable kernel returning little-endian phase bits.

Raises:

• ValueError — If the inputs do not define a reversible modular map.

Example:

>>> order_finding = shor_order_finding(base=2, modulus=15)
>>> estimate = order_finding.estimate_resources()
>>> estimate.qubits
23

Classes¶

QKernel [source]¶

class QKernel(QKernelBuildMixin, QKernelVisualizationMixin, Generic[P, R])

Decorator class for Qamomile quantum kernels.

Constructor¶

def __init__(self, func: Callable[P, R]) -> None

Attributes¶

• block: Block Compile the function to a hierarchical Block if not already compiled.

• effects: KernelEffect Return cached semantic effects of this qkernel.

• func

• input_types: dict[str, Any] Return resolved and frozen frontend input annotations.

• name

• output_types: list[Any] Return the resolved frontend annotation for every output slot.

• raw_func

• return_type: Any Return the resolved and frozen complete return annotation.

• signature

qamomile.circuit.algorithm.trotter¶

Suzuki-Trotter time evolution as a self-recursive @qkernel.

The public :func:trotterized_time_evolution wrapper validates the hamiltonian length and order and then delegates to the @qkernel :func:_trotter_evolve, which slices the evolution into step Trotter steps and applies a single-step operator from :func:_suzuki_trotter_step. That step kernel branches on order:

• order == 1 — Lie-Trotter forward sweep (base case).

• order == 2 — Strang splitting with the palindrome center merged (base case).

• order >= 4 (even) — Suzuki’s fractal recursion

  $$S_{2k}(\Delta t) = S_{2k-2}(p_k \Delta t)^2 S_{2k-2}((1 - 4 p_k)\Delta t) S_{2k-2}(p_k \Delta t)^2, \quad p_k = \frac{1}{4 - 4^{1/(2k-1)}}.$$

  (1)

  The recursion calls back into :func:_suzuki_trotter_step with order - 2. Qamomile’s transpiler resolves the self-call by iterating inline + partial-eval under the concrete order binding, so the emitted circuit is flat regardless of recursion depth.

order must be bound to a compile-time constant at transpile time — without it the base-case if never folds and the unroll loop has nothing to terminate on. Only order == 1 or even orders 2, 4, 6, ... are accepted; other values raise ValueError at the call site. hamiltonian must contain at least two terms.

Example::

import qamomile.circuit as qmc
import qamomile.observable as qm_o
from qamomile.circuit.algorithm.trotter import (
    trotterized_time_evolution,
)

@qmc.qkernel
def my_circuit(
    Hs: qmc.Vector[qmc.Observable],
    gamma: qmc.Float,
    order: qmc.UInt,
    step: qmc.UInt,
) -> qmc.Vector[qmc.Qubit]:
    q = qmc.qubit_array(1, name="q")
    q = trotterized_time_evolution(q, Hs, order, gamma, step)
    return q

Hs = [qm_o.Z(0), qm_o.X(0)]  # list of qamomile.observable.Hamiltonian

Overview¶

Functions¶

merge_product_formula_contract [source]¶

def merge_product_formula_contract(
    attrs: Mapping[str, Any],
    formula: ProductFormulaContract,
    *,
    source: str,
    operand_count: int | None = None,
) -> dict[str, Any]

Merge one product-formula declaration into callable attrs.

Parameters:

Returns:

dict[str, Any] — dict[str, Any]: Copied attributes with the product-formula contract.

Raises:

• ValueError — If existing resource metadata is malformed or conflicts with formula.

qkernel_callable_attrs [source]¶

def qkernel_callable_attrs(kernel: Any) -> dict[str, Any]

Return compiler attrs for a qkernel invocation.

Composite metadata lives directly on QKernel. This helper is the single translation point from that frontend state into serializer-safe IR attributes, so direct, controlled, and inverse calls share one identity.

Parameters:

Returns:

dict[str, Any] — dict[str, Any]: Serializer-friendly callable attributes.

trotterized_time_evolution [source]¶

def trotterized_time_evolution(
    q: qmc.Vector[qmc.Qubit],
    hamiltonian: qmc.Vector[qmc.Observable] | Sequence[Hamiltonian],
    order: int | qmc.UInt,
    gamma: float | qmc.Float,
    step: int | qmc.UInt,
) -> qmc.Vector[qmc.Qubit]

Apply Suzuki-Trotter time evolution exp(-i gamma H) to q.

H = sum_k hamiltonian[k]. The evolution is split into step Trotter slices of size dt = gamma / step; each slice applies the order-th Suzuki-Trotter formula via :func:_trotter_evolve.

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — The evolved qubit register.

Raises:

• ValueError — If hamiltonian has fewer than two terms, if order is a bool, or if order is not 1 or a positive even integer, or if step is not a positive integer. When these arguments are still symbolic (e.g. the enclosing kernel has not been re-traced with bindings yet) validation silently defers.

Classes¶

ProductFormulaContract [source]¶

class ProductFormulaContract

Describe one product-formula family and its semantic operand roles.

Operand positions use the callable’s untransformed input ABI. Coherent controls added by a later call transform are therefore not included.

Parameters:

Constructor¶

def __init__(self, kind: str, operands: Mapping[str, int]) -> None

Attributes¶

• kind: str

• operands: Mapping[str, int]