qamomile.circuit.stdlib

Expose standard-library quantum callables.

The reader-facing circuit API is function-oriented: use :func:qft, :func:iqft, :func:qpe, :func:qsvt, state-preparation helpers, arithmetic helpers, and :func:mcx inside qkernels. Factories that must also expose algorithm metadata may return frozen non-callable descriptors; invoke the descriptor’s documented qkernel field rather than the descriptor itself. Internally these functions emit named callables with Qamomile bodies and optional backend-native implementations.

Standard composites use the same composite_gate mechanism as user callables; there is no separate class-based gate hierarchy.

Example:

import qamomile.circuit as qmc

@qmc.qkernel
def my_algorithm(qubits: qmc.Vector[qmc.Qubit]) -> qmc.Vector[qmc.Qubit]:
    qubits = qmc.qft(qubits)
    return qmc.iqft(qubits)

Overview¶

Constants¶

• mcx = multi_controlled_x Short public alias for :func:multi_controlled_x.

Functions¶

grover_iteration_count [source]¶

def grover_iteration_count(
    num_qubits: int | np.integer[Any] | sp.Expr,
    num_marked: int | np.integer[Any] | sp.Expr = 1,
) -> int | sp.Expr

Return the optimal Grover iteration count floor((pi/4) sqrt(N/m)).

Parameters:

Returns:

int | sp.Expr — int | sp.Expr: Concrete iteration count when both arguments are concrete Python or NumPy integers, otherwise the symbolic expression floor((pi/4) sqrt(2**n / m)). SymPy integers remain SymPy expressions.

Raises:

• TypeError — If num_qubits or num_marked is a boolean.

• ValueError — If concrete num_qubits or num_marked is not positive.

Example:

>>> grover_iteration_count(4, 1)
3

grover_search [source]¶

def grover_search(
    reg: Vector[Qubit],
    oracle: Oracle | QKernelLike,
    iterations: int | qmc.UInt,
) -> Vector[Qubit]

Run the Grover amplitude-amplification loop on reg.

Prepares the uniform superposition, then applies iterations rounds of oracle followed by the diffusion operator. Leaving iterations symbolic makes resource estimation report the universal O(sqrt(N/m)) query complexity: the oracle’s opaque cost contributes the per-query gate cost and the diffusion contributes O(n) gates, both summed over the symbolic iteration count.

Parameters:

Returns:

Vector[Qubit] — Vector[Qubit]: Register after amplitude amplification.

Example:

>>> import qamomile.circuit as qmc
>>> from qamomile.circuit.stdlib import grover_search, grover_iteration_count
>>> mark = qmc.opaque("mark", num_qubits=3)
>>> @qmc.qkernel
... def search(reg: qmc.Vector[qmc.Qubit]) -> qmc.Vector[qmc.Qubit]:
...     return grover_search(reg, mark, grover_iteration_count(3))

iqft [source]¶

def iqft(qubits: Vector[Qubit]) -> Vector[Qubit]

Apply the inverse quantum Fourier transform.

Parameters:

Returns:

Vector[Qubit] — Vector[Qubit]: Transformed register.

qamomile.circuit.stdlib.arithmetic¶

Expose standard-library arithmetic callables.

The package groups arithmetic primitives by implementation strategy while keeping the original arithmetic-module import surface stable. Public callables are re-exported here; selected internal helpers remain available for Qamomile’s algorithm implementations and focused tests.

Overview¶

Functions¶

add_const [source]¶

def add_const(
    target: Vector[Qubit],
    overflow: Qubit,
    value: UInt,
) -> tuple[Vector[Qubit], Qubit]

Add a classical constant to an extended quantum register.

Parameters:

Returns:

tuple[Vector[Qubit], Qubit] — tuple[Vector[Qubit], Qubit]: Updated low bits and overflow bit.

controlled_add_const [source]¶

def controlled_add_const(
    control: Qubit,
    target: Vector[Qubit],
    overflow: Qubit,
    value: UInt,
) -> tuple[Qubit, Vector[Qubit], Qubit]

Condition a classical constant addition on one qubit.

Parameters:

Returns:

tuple[Qubit, Vector[Qubit], Qubit] — tuple[Qubit, Vector[Qubit], Qubit]: Updated control, low bits, and overflow bit.

controlled_modular_add [source]¶

def controlled_modular_add(
    control: Qubit,
    addend: Vector[Qubit],
    modulus: Vector[Qubit],
    target: Vector[Qubit],
    carry: Qubit,
    overflow: Qubit,
    flag: Qubit,
) -> tuple[Qubit, Vector[Qubit], Vector[Qubit], Vector[Qubit], Qubit, Qubit, Qubit]

Condition a modular addition on one qubit.

Parameters:

Returns:

Qubit — tuple[Qubit, Vector[Qubit], Vector[Qubit], Vector[Qubit], Qubit, Qubit, Vector[Qubit] — Qubit]: Preserved control and constants, conditionally updated target, and restored workspaces.

controlled_modular_add_const [source]¶

def controlled_modular_add_const(
    control: Qubit,
    target: Vector[Qubit],
    overflow: Qubit,
    flag: Qubit,
    addend: UInt,
    modulus: UInt,
) -> tuple[Qubit, Vector[Qubit], Qubit, Qubit]

Condition a constant modular addition on one qubit.

Parameters:

Returns:

tuple[Qubit, Vector[Qubit], Qubit, Qubit] — tuple[Qubit, Vector[Qubit], Qubit, Qubit]: Updated control, modular target, and restored workspace qubits.

controlled_modular_add_const_modulus [source]¶

def controlled_modular_add_const_modulus(
    control: Qubit,
    addend: Vector[Qubit],
    target: Vector[Qubit],
    carry: Qubit,
    overflow: Qubit,
    flag: Qubit,
    modulus: UInt,
) -> tuple[Qubit, Vector[Qubit], Vector[Qubit], Qubit, Qubit, Qubit]

Condition a quantum-register addition modulo a classical constant.

Parameters:

Returns:

tuple[Qubit, Vector[Qubit], Vector[Qubit], Qubit, Qubit, Qubit] — tuple[Qubit, Vector[Qubit], Vector[Qubit], Qubit, Qubit, Qubit]: Preserved control and addend, modular target, and workspaces.

lookup_xor [source]¶

def lookup_xor(
    address: Vector[Qubit],
    target: Vector[Qubit],
    scale: UInt,
    modulus: UInt,
) -> tuple[Vector[Qubit], Vector[Qubit]]

XOR a modular multiplication lookup into a clean target register.

The table maps j to (scale * j) % modulus. Its body is expressed entirely in Qamomile operations, so resource estimation counts the actual candidate-enumeration lookup network rather than an opaque table-cost formula.

Parameters:

Returns:

tuple[Vector[Qubit], Vector[Qubit]] — tuple[Vector[Qubit], Vector[Qubit]]: Preserved address and updated lookup target.

modmul_const [source]¶

def modmul_const(
    reg: Vector[Qubit],
    *,
    multiplier: int | UInt,
    modulus: int | UInt,
    window_size: int = 2,
    inverse_multiplier: int | UInt | None = None,
    control: Qubit | None = None,
) -> Vector[Qubit] | tuple[Qubit, Vector[Qubit]]

Apply constant modular multiplication |x> -> |a*x mod N>.

The standard implementation uses lookup windows and reversible modular additions. Resource estimation walks this same executable body; it never substitutes an external arithmetic cost formula. Basis states x >= N are left unchanged so the operation is a unitary permutation over the full register space. The FTQC body contains measurement and reset operations; condition it through the control argument rather than wrapping the complete operation with :func:qamomile.circuit.control.

Parameters:

Returns:

Vector[Qubit] | tuple[Qubit, Vector[Qubit]] — Vector[Qubit] | tuple[Qubit, Vector[Qubit]]: The register after modular Vector[Qubit] | tuple[Qubit, Vector[Qubit]] — multiplication, or (control, register) when a control qubit is Vector[Qubit] | tuple[Qubit, Vector[Qubit]] — supplied.

Raises:

• ValueError — If concrete constants are invalid or symbolic constants omit inverse_multiplier.

Example:

>>> import qamomile.circuit as qmc
>>> from qamomile.circuit.stdlib import modmul_const
>>> @qmc.qkernel
... def mul(reg: qmc.Vector[qmc.Qubit]) -> qmc.Vector[qmc.Qubit]:
...     return modmul_const(reg, multiplier=2, modulus=15)

modular_add [source]¶

def modular_add(
    addend: Vector[Qubit],
    modulus: Vector[Qubit],
    target: Vector[Qubit],
    carry: Qubit,
    overflow: Qubit,
    flag: Qubit,
) -> tuple[Vector[Qubit], Vector[Qubit], Vector[Qubit], Qubit, Qubit, Qubit]

Add one register into another modulo a preserved modulus register.

All registers are equally sized and little-endian. Inputs must encode addend < modulus and target < modulus. The three workspace qubits must start in |0> and are restored before returning.

Parameters:

Returns:

tuple[Vector[Qubit], Vector[Qubit], Vector[Qubit], Qubit, Qubit, Qubit] — tuple[Vector[Qubit], Vector[Qubit], Vector[Qubit], Qubit, Qubit, Qubit]: Preserved addend and modulus, modular sum, and restored workspaces.

modular_add_const [source]¶

def modular_add_const(
    target: Vector[Qubit],
    overflow: Qubit,
    flag: Qubit,
    addend: UInt,
    modulus: UInt,
) -> tuple[Vector[Qubit], Qubit, Qubit]

Add a classical constant to a quantum register modulo a constant.

Parameters:

Returns:

tuple[Vector[Qubit], Qubit, Qubit] — tuple[Vector[Qubit], Qubit, Qubit]: Modular target and restored workspace qubits.

ripple_carry_add [source]¶

def ripple_carry_add(
    left: Vector[Qubit],
    right: Vector[Qubit],
    carry: Qubit,
    overflow: Qubit,
) -> tuple[Vector[Qubit], Vector[Qubit], Qubit, Qubit]

Add left into right with a reversible ripple-carry network.

The equally sized registers are little-endian. carry must start in |0> and is restored to |0>. overflow receives the final carry, so the output represents the full n + 1 bit sum without discarding quantum information.

Parameters:

Returns:

tuple[Vector[Qubit], Vector[Qubit], Qubit, Qubit] — tuple[Vector[Qubit], Vector[Qubit], Qubit, Qubit]: Preserved addend, summed accumulator, restored carry, and updated overflow qubit.

qamomile.circuit.stdlib.arithmetic.bitwise¶

Implement bitwise helpers for constant modular multiplication.

qamomile.circuit.stdlib.arithmetic.carry_venting¶

Implement carry-venting constant addition primitives.

Overview¶

Functions¶

get_size [source]¶

def get_size(arr: Vector[_H]) -> int

Return the size of a Vector handle as a Python integer.

Resolves the leading axis of arr.shape through two forms a Vector shape entry can take:

1. A plain Python int (built-in bound shape; this is what you get from qmc.qubit_array(N, ...) for literal N).

2. A UInt handle whose underlying Value carries a compile-time constant (set by uint(literal), _create_bound_input, or partial evaluation).

A UInt handle whose underlying Value is not a constant is treated as an unresolved symbolic dimension and raises ValueError even when the handle has the dataclass-default init_value=0. Falling back to init_value for that case would silently turn a runtime-symbolic Vector[Float] parameter into a “size 0” array, hiding programming errors. Callers that need to handle symbolic shapes (e.g., to emit a deferred callable when the size is unknown) must catch the ValueError themselves.

Parameters:

Returns:

int — The first-axis size as a plain Python int.

Raises:

• TypeError — If arr is not a 1-D Vector handle (Vector or its VectorView subclass) — e.g., a scalar Qubit was passed where a Vector is required, a higher-rank Matrix / Tensor was passed (this helper only resolves a 1-D first-axis size), or an unrelated shape-bearing object such as a numpy array. This is a clearer signal than the bare AttributeError that arr.shape would otherwise raise, and it guards the stdlib / composite callers that resolve a register size through this helper.

• ValueError — If the shape cannot be resolved to a concrete integer — e.g., the Vector is a runtime-parametric handle without compile-time bindings, or carries a UInt dimension whose underlying Value has not been promoted to a constant.

qamomile.circuit.stdlib.arithmetic.constant¶

Implement Fourier-based constant addition primitives.

Overview¶

Functions¶

add_const [source]¶

def add_const(
    target: Vector[Qubit],
    overflow: Qubit,
    value: UInt,
) -> tuple[Vector[Qubit], Qubit]

Add a classical constant to an extended quantum register.

Parameters:

Returns:

tuple[Vector[Qubit], Qubit] — tuple[Vector[Qubit], Qubit]: Updated low bits and overflow bit.

controlled_add_const [source]¶

def controlled_add_const(
    control: Qubit,
    target: Vector[Qubit],
    overflow: Qubit,
    value: UInt,
) -> tuple[Qubit, Vector[Qubit], Qubit]

Condition a classical constant addition on one qubit.

Parameters:

Returns:

tuple[Qubit, Vector[Qubit], Qubit] — tuple[Qubit, Vector[Qubit], Qubit]: Updated control, low bits, and overflow bit.

qamomile.circuit.stdlib.arithmetic.increment¶

Implement modular increment, decrement, and fixed-window shifts.

Overview¶

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.stdlib.arithmetic.modular¶

Implement modular addition primitives.

Overview¶

Functions¶

controlled_add_const [source]¶

def controlled_add_const(
    control: Qubit,
    target: Vector[Qubit],
    overflow: Qubit,
    value: UInt,
) -> tuple[Qubit, Vector[Qubit], Qubit]

Condition a classical constant addition on one qubit.

Parameters:

Returns:

tuple[Qubit, Vector[Qubit], Qubit] — tuple[Qubit, Vector[Qubit], Qubit]: Updated control, low bits, and overflow bit.

controlled_modular_add [source]¶

def controlled_modular_add(
    control: Qubit,
    addend: Vector[Qubit],
    modulus: Vector[Qubit],
    target: Vector[Qubit],
    carry: Qubit,
    overflow: Qubit,
    flag: Qubit,
) -> tuple[Qubit, Vector[Qubit], Vector[Qubit], Vector[Qubit], Qubit, Qubit, Qubit]

Condition a modular addition on one qubit.

Parameters:

Returns:

Qubit — tuple[Qubit, Vector[Qubit], Vector[Qubit], Vector[Qubit], Qubit, Qubit, Vector[Qubit] — Qubit]: Preserved control and constants, conditionally updated target, and restored workspaces.

controlled_modular_add_const [source]¶

def controlled_modular_add_const(
    control: Qubit,
    target: Vector[Qubit],
    overflow: Qubit,
    flag: Qubit,
    addend: UInt,
    modulus: UInt,
) -> tuple[Qubit, Vector[Qubit], Qubit, Qubit]

Condition a constant modular addition on one qubit.

Parameters:

Returns:

tuple[Qubit, Vector[Qubit], Qubit, Qubit] — tuple[Qubit, Vector[Qubit], Qubit, Qubit]: Updated control, modular target, and restored workspace qubits.

controlled_modular_add_const_modulus [source]¶

def controlled_modular_add_const_modulus(
    control: Qubit,
    addend: Vector[Qubit],
    target: Vector[Qubit],
    carry: Qubit,
    overflow: Qubit,
    flag: Qubit,
    modulus: UInt,
) -> tuple[Qubit, Vector[Qubit], Vector[Qubit], Qubit, Qubit, Qubit]

Condition a quantum-register addition modulo a classical constant.

Parameters:

Returns:

tuple[Qubit, Vector[Qubit], Vector[Qubit], Qubit, Qubit, Qubit] — tuple[Qubit, Vector[Qubit], Vector[Qubit], Qubit, Qubit, Qubit]: Preserved control and addend, modular target, and workspaces.

modular_add [source]¶

def modular_add(
    addend: Vector[Qubit],
    modulus: Vector[Qubit],
    target: Vector[Qubit],
    carry: Qubit,
    overflow: Qubit,
    flag: Qubit,
) -> tuple[Vector[Qubit], Vector[Qubit], Vector[Qubit], Qubit, Qubit, Qubit]

Add one register into another modulo a preserved modulus register.

All registers are equally sized and little-endian. Inputs must encode addend < modulus and target < modulus. The three workspace qubits must start in |0> and are restored before returning.

Parameters:

Returns:

tuple[Vector[Qubit], Vector[Qubit], Vector[Qubit], Qubit, Qubit, Qubit] — tuple[Vector[Qubit], Vector[Qubit], Vector[Qubit], Qubit, Qubit, Qubit]: Preserved addend and modulus, modular sum, and restored workspaces.

modular_add_const [source]¶

def modular_add_const(
    target: Vector[Qubit],
    overflow: Qubit,
    flag: Qubit,
    addend: UInt,
    modulus: UInt,
) -> tuple[Vector[Qubit], Qubit, Qubit]

Add a classical constant to a quantum register modulo a constant.

Parameters:

Returns:

tuple[Vector[Qubit], Qubit, Qubit] — tuple[Vector[Qubit], Qubit, Qubit]: Modular target and restored workspace qubits.

ripple_carry_add [source]¶

def ripple_carry_add(
    left: Vector[Qubit],
    right: Vector[Qubit],
    carry: Qubit,
    overflow: Qubit,
) -> tuple[Vector[Qubit], Vector[Qubit], Qubit, Qubit]

Add left into right with a reversible ripple-carry network.

The equally sized registers are little-endian. carry must start in |0> and is restored to |0>. overflow receives the final carry, so the output represents the full n + 1 bit sum without discarding quantum information.

Parameters:

Returns:

tuple[Vector[Qubit], Vector[Qubit], Qubit, Qubit] — tuple[Vector[Qubit], Vector[Qubit], Qubit, Qubit]: Preserved addend, summed accumulator, restored carry, and updated overflow qubit.

qamomile.circuit.stdlib.arithmetic.modular_multiplication¶

Implement constant modular multiplication primitives.

Overview¶

Functions¶

get_size [source]¶

def get_size(arr: Vector[_H]) -> int

Return the size of a Vector handle as a Python integer.

Resolves the leading axis of arr.shape through two forms a Vector shape entry can take:

1. A plain Python int (built-in bound shape; this is what you get from qmc.qubit_array(N, ...) for literal N).

2. A UInt handle whose underlying Value carries a compile-time constant (set by uint(literal), _create_bound_input, or partial evaluation).

A UInt handle whose underlying Value is not a constant is treated as an unresolved symbolic dimension and raises ValueError even when the handle has the dataclass-default init_value=0. Falling back to init_value for that case would silently turn a runtime-symbolic Vector[Float] parameter into a “size 0” array, hiding programming errors. Callers that need to handle symbolic shapes (e.g., to emit a deferred callable when the size is unknown) must catch the ValueError themselves.

Parameters:

Returns:

int — The first-axis size as a plain Python int.

Raises:

• TypeError — If arr is not a 1-D Vector handle (Vector or its VectorView subclass) — e.g., a scalar Qubit was passed where a Vector is required, a higher-rank Matrix / Tensor was passed (this helper only resolves a 1-D first-axis size), or an unrelated shape-bearing object such as a numpy array. This is a clearer signal than the bare AttributeError that arr.shape would otherwise raise, and it guards the stdlib / composite callers that resolve a register size through this helper.

• ValueError — If the shape cannot be resolved to a concrete integer — e.g., the Vector is a runtime-parametric handle without compile-time bindings, or carries a UInt dimension whose underlying Value has not been promoted to a constant.

lookup_xor [source]¶

def lookup_xor(
    address: Vector[Qubit],
    target: Vector[Qubit],
    scale: UInt,
    modulus: UInt,
) -> tuple[Vector[Qubit], Vector[Qubit]]

XOR a modular multiplication lookup into a clean target register.

The table maps j to (scale * j) % modulus. Its body is expressed entirely in Qamomile operations, so resource estimation counts the actual candidate-enumeration lookup network rather than an opaque table-cost formula.

Parameters:

Returns:

tuple[Vector[Qubit], Vector[Qubit]] — tuple[Vector[Qubit], Vector[Qubit]]: Preserved address and updated lookup target.

modmul_const [source]¶

def modmul_const(
    reg: Vector[Qubit],
    *,
    multiplier: int | UInt,
    modulus: int | UInt,
    window_size: int = 2,
    inverse_multiplier: int | UInt | None = None,
    control: Qubit | None = None,
) -> Vector[Qubit] | tuple[Qubit, Vector[Qubit]]

Apply constant modular multiplication |x> -> |a*x mod N>.

The standard implementation uses lookup windows and reversible modular additions. Resource estimation walks this same executable body; it never substitutes an external arithmetic cost formula. Basis states x >= N are left unchanged so the operation is a unitary permutation over the full register space. The FTQC body contains measurement and reset operations; condition it through the control argument rather than wrapping the complete operation with :func:qamomile.circuit.control.

Parameters:

Returns:

Vector[Qubit] | tuple[Qubit, Vector[Qubit]] — Vector[Qubit] | tuple[Qubit, Vector[Qubit]]: The register after modular Vector[Qubit] | tuple[Qubit, Vector[Qubit]] — multiplication, or (control, register) when a control qubit is Vector[Qubit] | tuple[Qubit, Vector[Qubit]] — supplied.

Raises:

• ValueError — If concrete constants are invalid or symbolic constants omit inverse_multiplier.

Example:

>>> import qamomile.circuit as qmc
>>> from qamomile.circuit.stdlib import modmul_const
>>> @qmc.qkernel
... def mul(reg: qmc.Vector[qmc.Qubit]) -> qmc.Vector[qmc.Qubit]:
...     return modmul_const(reg, multiplier=2, modulus=15)

qamomile.circuit.stdlib.arithmetic.ripple_carry¶

Implement reversible ripple-carry addition primitives.

Overview¶

Functions¶

configure_composite [source]¶

def configure_composite(
    kernel: QKernel[..., Any],
    *,
    name: str | None = None,
    namespace: str | None = None,
    gate_type: CompositeGateType = CompositeGateType.CUSTOM,
    policy: CallPolicy = CallPolicy.PRESERVE_BOX,
    implementations: Sequence[CallableImplementation] | None = None,
    semantic_arguments: Mapping[str, Any] | None = None,
) -> QKernel[..., Any]

Configure a QKernel to remain visible as a named composite call.

This mutates and returns the same QKernel object. No wrapper class or alternate call protocol is introduced.

Parameters:

Returns:

QKernel[..., Any] — QKernel[..., Any]: The same configured kernel instance.

ripple_carry_add [source]¶

def ripple_carry_add(
    left: Vector[Qubit],
    right: Vector[Qubit],
    carry: Qubit,
    overflow: Qubit,
) -> tuple[Vector[Qubit], Vector[Qubit], Qubit, Qubit]

Add left into right with a reversible ripple-carry network.

The equally sized registers are little-endian. carry must start in |0> and is restored to |0>. overflow receives the final carry, so the output represents the full n + 1 bit sum without discarding quantum information.

Parameters:

Returns:

tuple[Vector[Qubit], Vector[Qubit], Qubit, Qubit] — tuple[Vector[Qubit], Vector[Qubit], Qubit, Qubit]: Preserved addend, summed accumulator, restored carry, and updated overflow qubit.

Classes¶

CallPolicy [source]¶

class CallPolicy(enum.Enum)

Describe the default lowering policy for a callable call.

Attributes¶

• INLINE

• NATIVE_FIRST

• PRESERVE_BOX

qamomile.circuit.stdlib.block_encoding¶

Expose exact block-encoding descriptors and construction factories.

The subpackage groups algorithm-independent operator encodings. Consumers normally use the stable top-level qamomile.circuit exports, while direct imports may use this namespace when producer-specific types are needed.

Overview¶

Functions¶

identity_block_encoding [source]¶

def identity_block_encoding(num_system_qubits: int) -> LCUBlockEncoding

Create an exact identity encoding with one pass-through signal.

The unitary acts as identity on both registers and satisfies V0^dagger U V0 = I with normalization 1.0. One signal qubit is retained so the descriptor has the same positive-width ABI required by reusable circuits, nested SELECT, and all-zero projector consumers.

Parameters:

Returns:

LCUBlockEncoding — Exact identity descriptor with one signal qubit.

Raises:

• TypeError — If num_system_qubits is not an integer.

• ValueError — If num_system_qubits is non-positive.

ising_z_block_encoding [source]¶

def ising_z_block_encoding(
    coefficients: Mapping[tuple[int, ...], complex],
    num_system_qubits: int,
) -> IsingZBlockEncoding

Create an exact block encoding of a diagonal Ising-Z operator.

Each mapping key is a product of Z operators at the listed system-qubit indices. Repeated indices cancel pairwise because Z**2 = I; the empty tuple denotes identity. Algebraically equivalent words are aggregated before constructing

Aggregation is deterministic for the same converted coefficient multiset on one host/runtime. Inputs that make the host math.fsum overflow an intermediate partial may be rejected even when their exact final sum is representable.

A multi-term encoding uses PREPARE amplitudes sqrt(abs(c_j) / alpha) and SELECT cases exp(1j * arg(c_j)) * Z_{S_j}. The returned encoding can be used as a child of another block encoding without converting the operator to a PauliLCU.

Parameters:

Returns:

IsingZBlockEncoding — Frozen non-callable block-encoding descriptor.

Raises:

• TypeError — If coefficients is not a mapping, a word is not a tuple, an index is not an integer, or a coefficient has an unsupported scalar type.

• ValueError — If a width is non-positive, an index is out of range, a coefficient or aggregate is non-finite, or finite coefficient aggregation overflows.

• RuntimeError — If internal state-preparation width derivation disagrees with the Ising-Z selector width.

Example:

>>> import qamomile.circuit as qmc
>>> encoding = qmc.ising_z_block_encoding(
...     {(): 0.25, (0,): -1.0, (0, 1): 0.5j},
...     num_system_qubits=2,
... )
>>> @qmc.qkernel
... def circuit() -> tuple[qmc.Vector[qmc.Qubit], qmc.Vector[qmc.Qubit]]:
...     signal = qmc.qubit_array(encoding.num_signal_qubits, "signal")
...     system = qmc.qubit_array(encoding.num_system_qubits, "system")
...     return encoding.unitary(signal, system)

lcu_block_encoding [source]¶

def lcu_block_encoding(terms: Sequence[LCUBlockEncodingTerm]) -> LCUBlockEncoding

Compose an ordered LCU of exact child block encodings.

Given child encodings U_j satisfying

and logical coefficients c_j, this factory encodes

PREPARE amplitudes are sqrt(abs(c_j) * alpha_j / Lambda) and SELECT case j applies exp(1j * arg(c_j)) * U_j. Heterogeneous child signal registers share a pool whose width is the maximum child width. Every uniform-signature case routes only its leading child-sized slice and acts exactly as identity on unused padding for arbitrary pool states. The private parent lowering is [outer selector | shared child pool]; consumers only allocate the reported flat signal register and project all of it onto zero.

Child descriptors are concrete when this factory runs. Their coefficient data, angles, and layouts do not become public arguments of the completed parent unitary. The returned common descriptor may itself be supplied as a child of another composition or bound later to a reusable qkernel argument annotated with :class:LCUBlockEncoding.

Children must interpret the ordered system wires in the same logical basis; the common descriptor can validate their widths but cannot infer basis conventions. Generated callable semantic identity across separately constructed descriptors is not part of this API yet. Concrete children are captured when the factory runs, and the completed descriptor supports nesting and compile-time static binding without exposing those children as public qkernel arguments. Qiskit, QuriParts, and CUDA-Q inline these generated bodies. The HUGR target does not currently support recursive LCU composition because SELECT lowering and multiple inline callable-body variants sharing one source-derived reference are not yet supported.

Zero-coefficient terms are removed before normalization and SELECT construction. A nonempty sequence containing only zero coefficients creates an exact zero encoding with normalization 1.0 and one signal qubit; its child system widths must agree so the zero operator’s domain is defined. An empty sequence is rejected because its system width is unknowable.

Parameters:

Returns:

LCUBlockEncoding — Exact recursively composable parent descriptor.

Raises:

• TypeError — If terms is not an ordered sequence or contains a non-term value.

• ValueError — If terms is empty, relevant child system widths differ, or the composed normalization overflows or is non-finite.

• RuntimeError — If internal state-preparation width derivation disagrees with the recursive selector width.

Example:

>>> import qamomile.circuit as qmc
>>> identity = qmc.identity_block_encoding(1)
>>> encoding = qmc.lcu_block_encoding(
...     [
...         qmc.LCUBlockEncodingTerm(2.0, identity),
...         qmc.LCUBlockEncodingTerm(-0.5j, identity),
...     ]
... )
>>> encoding.normalization
2.5

pauli_lcu_block_encoding [source]¶

def pauli_lcu_block_encoding(lcu: PauliLCU) -> PauliLCUBlockEncoding

Create a static exact block encoding of a complex Pauli LCU.

For a nonzero decomposition

the descriptor’s qkernel unitary implements U and satisfies

Multi-term encodings use real-amplitude PREPARE weights sqrt(abs(c_j) / alpha) and SELECT cases exp(1j * arg(c_j)) * P_j. The identity Pauli word is a normal case, so its coefficient phase is retained. The zero operator uses one signal qubit and an X gate, giving an exact zero all-zero block with normalization 1.0; its PauliLCU.alpha remains 0.0.

The retained Pauli LCU is square, static, and encoded exactly. When :meth:PauliLCU.from_matrix truncated coefficients, its source-to-retained error remains available as lcu.truncation_error_bound and is not an error in this unitary. The unitary accepts arbitrary signal states, returns the same signal and system wires in the same order, supports :func:~qamomile.circuit.inverse, and allocates no hidden source-level logical workspace. Backend-only decomposition scratch is permitted only when resource-accounted and exactly uncomputed for all inputs, including under inverse and control.

Parameters:

Returns:

PauliLCUBlockEncoding — Frozen non-callable descriptor. Allocate its registers with num_signal_qubits and num_system_qubits, then invoke unitary(signal, system).

Raises:

• TypeError — If lcu is not a PauliLCU.

• ValueError — If lcu represents a scalar zero-qubit system.

Example:

>>> import numpy as np
>>> import qamomile.circuit as qmc
>>> from qamomile.linalg import PauliLCU
>>> lcu = PauliLCU.from_matrix(np.array([[0, 1], [0, 0]], complex))
>>> encoding = qmc.pauli_lcu_block_encoding(lcu)
>>> @qmc.qkernel
... def circuit() -> tuple[qmc.Vector[qmc.Qubit], qmc.Vector[qmc.Qubit]]:
...     signal = qmc.qubit_array(encoding.num_signal_qubits, "signal")
...     system = qmc.qubit_array(encoding.num_system_qubits, "system")
...     return encoding.unitary(signal, system)

periodic_shift_lcu_block_encoding [source]¶

def periodic_shift_lcu_block_encoding(lcu: PeriodicShiftLCU) -> PeriodicShiftLCUBlockEncoding

Build an LCU block encoding from a periodic-shift decomposition.

lcu defines A = sum_k c_k T_k, where T_k is the modular translation for one canonical offset tuple. The system is the flattened concatenation of the decomposition’s LSB-first axis registers. A shift uses the shorter signed displacement, then emits one ancilla-free increment or decrement ladder for each set bit of its magnitude. This bounds the number of Qamomile-level X and multi-controlled-X operations by a quadratic function of an axis register’s width; backend elementary-gate cost depends on how that backend decomposes multi-controlled X operations.

The returned descriptor’s unitary acts on arbitrary signal states. Projecting its signal register onto all zero before and after the unitary yields A / lambda, where lambda is available as result.normalization. The zero operator uses one signal qubit and an X gate, giving an exact zero all-zero block with normalization 1.0 while lcu.alpha remains 0.0. A single term retains one pass-through signal qubit for composition but omits PREPARE and SELECT entirely.

When :meth:PeriodicShiftLCU.from_matrix or :meth:PeriodicShiftLCU.from_coefficients pruned coefficients, the source error remains available as lcu.truncation_error_bound and is not an error in the retained unitary.

Parameters:

Returns:

PeriodicShiftLCUBlockEncoding — Frozen non-callable descriptor containing the generated shift-LCU unitary and method-specific canonical metadata.

Raises:

• TypeError — If lcu is not a :class:PeriodicShiftLCU.

• ValueError — If lcu represents a scalar zero-qubit system.

Example:

>>> import qamomile.circuit as qmc
>>> from qamomile.circuit.serialization import deserialize, serialize
>>> from qamomile.linalg import PeriodicShiftLCU
>>> from qamomile.qiskit import QiskitTranspiler
>>> @qmc.qkernel
... def apply_encoding(
...     encoding: qmc.LCUBlockEncoding,
... ) -> tuple[qmc.Vector[qmc.Qubit], qmc.Vector[qmc.Qubit]]:
...     signal = qmc.qubit_array(encoding.num_signal_qubits, "signal")
...     system = qmc.qubit_array(encoding.num_system_qubits, "system")
...     return encoding.unitary(signal, system)
>>> payload = serialize(apply_encoding)
>>> received = deserialize(payload)
>>> lcu = PeriodicShiftLCU.from_coefficients(
...     {-1: 1.0, 0: -2.0, 1: 1.0},
...     register_sizes=(3,),
... )
>>> neighbor_difference = qmc.periodic_shift_lcu_block_encoding(lcu)
>>> isinstance(neighbor_difference, qmc.LCUBlockEncoding)
True
>>> neighbor_difference.normalization
4.0
>>> executable = QiskitTranspiler().transpile(
...     received,
...     bindings={"encoding": neighbor_difference},
... )

Classes¶

IsingZBlockEncoding [source]¶

class IsingZBlockEncoding(LCUBlockEncoding)

Describe one static exact block encoding of an Ising-Z operator.

The inherited unitary field has the quantum ABI unitary(signal, system) -> (signal, system) and no classical arguments. For the isometry V0 that initializes the complete signal register to zero, it satisfies

including the complex phases of the Ising-Z coefficients. The unitary allocates no hidden logical qubits and preserves the order of all input wires. Descriptor equality and hashing use object identity.

This producer-specific subtype adds no qkernel-visible fields. Reusable qkernels should annotate inputs with :class:LCUBlockEncoding so Ising-Z, Pauli, and recursively composed descriptors share one static binding slot.

Parameters:

Raises:

• TypeError — If a field has an invalid runtime type or unitary does not have the required static block-encoding ABI.

• ValueError — If normalization is non-finite or non-positive, or a register width is non-positive.

Constructor¶

def __init__(
    self,
    unitary: _BlockEncodingUnitary,
    normalization: float,
    num_signal_qubits: int,
    num_system_qubits: int,
) -> None

LCUBlockEncoding [source]¶

class LCUBlockEncoding

Describe one static exact LCU block encoding.

unitary is the qkernel implementing the larger unitary U; it is neither the encoded matrix A nor a dense matrix value. It has no classical arguments and its quantum ABI is unitary(signal, system) -> (signal, system). system is the ordered logical data register on which A acts. signal is the complete source-level ancilla bundle whose all-zero state selects the encoded block. The unitary returns the same logical wires in the same order and acts unitarily for arbitrary signal inputs; after one application, the signal may have non-zero components rather than returning entirely to zero.

For the all-zero signal isometry V0, the producer must guarantee

including coefficient phase. normalization is finite and positive; an encoding of the zero operator uses 1.0. Implementations allocate no hidden source-level logical qubits. A backend may still use temporary decomposition scratch that is resource-accounted, exactly uncomputed for every public input, and preserved under inverse and control. Descriptor comparison and hashing use object identity rather than field values.

This common descriptor deliberately excludes decomposition-specific metadata. Reusable qkernels should annotate an encoding argument with this class so descriptors produced by Pauli and future LCU factories can occupy the same compile-time binding slot.

Parameters:

Raises:

• TypeError — If unitary is not a QKernel with the exact static positional ABI above, normalization is not a real scalar, or either width is not an integer.

• ValueError — If normalization is non-finite or non-positive, or either width is non-positive.

Constructor¶

def __init__(
    self,
    unitary: _BlockEncodingUnitary,
    normalization: float,
    num_signal_qubits: int,
    num_system_qubits: int,
) -> None

Attributes¶

• normalization: float

• num_signal_qubits: int

• num_system_qubits: int

• unitary: _BlockEncodingUnitary

LCUBlockEncodingTerm [source]¶

class LCUBlockEncodingTerm

Pair a logical coefficient with one exact child block encoding.

coefficient multiplies the child target matrix A_j, not its normalized projected block A_j / alpha_j. The recursive composer therefore assigns the term weight abs(coefficient) * encoding.normalization. Children are concrete construction-time descriptors; the completed parent, rather than unresolved children, is the object intended for qkernel static binding.

Parameters:

Raises:

• TypeError — If the coefficient is not a non-boolean complex numeric scalar or encoding is not an LCUBlockEncoding.

• ValueError — If a numeric coefficient cannot be converted to a finite built-in complex value or either component is non-finite.

Constructor¶

def __init__(self, coefficient: complex, encoding: LCUBlockEncoding) -> None

Attributes¶

• coefficient: complex

• encoding: LCUBlockEncoding

PauliLCUBlockEncoding [source]¶

class PauliLCUBlockEncoding(LCUBlockEncoding)

Identify an LCU block encoding produced from a Pauli decomposition.

The subtype adds no qkernel-visible fields. Reusable qkernels should annotate encoding arguments with :class:LCUBlockEncoding; the Pauli subtype remains available for producer-specific host-side code and backward-compatible serialized templates.

Parameters:

Raises:

• TypeError — If an inherited descriptor field has an invalid type or the unitary ABI is invalid.

• ValueError — If normalization or a register width is non-positive or non-finite.

Constructor¶

def __init__(
    self,
    unitary: _BlockEncodingUnitary,
    normalization: float,
    num_signal_qubits: int,
    num_system_qubits: int,
) -> None

PeriodicShiftLCUBlockEncoding [source]¶

class PeriodicShiftLCUBlockEncoding(LCUBlockEncoding)

Describe one static exact periodic-shift LCU block encoding.

unitary is the qkernel implementing the larger unitary U; it is neither the encoded periodic-shift matrix A nor a dense matrix value. It has no classical arguments and its quantum ABI is unitary(signal, system) -> (signal, system). system is the ordered flattened data register on which A acts. signal is the complete source-level ancilla bundle whose all-zero state selects the encoded block. The unitary returns the same logical wires in the same order and acts unitarily for arbitrary signal inputs; signal need not return to zero after one application.

For the all-zero signal isometry V0, the encoded periodic-shift matrix satisfies

including coefficient phase. The construction is exact in ideal logical arithmetic; host floating-point roundoff in state-preparation angles and backend gate synthesis are outside this semantic equality. This producer allocates no hidden source-level logical qubits. Backend decomposition scratch is permitted only when resource-accounted and exactly uncomputed for every input, including under inverse and control. Descriptor comparison and hashing use object identity rather than field values.

The inherited fields form the qkernel-visible static LCU contract. register_sizes, offsets, and coefficients are deeply immutable producer metadata for host-side inspection only. A producer-specific qkernel may annotate an argument with this class. Reusable qkernels should instead annotate descriptor arguments with :class:LCUBlockEncoding, allowing the same serialized template to accept this and other exact LCU producers.

Parameters:

Raises:

• TypeError — If the common block-encoding fields or method-specific metadata have invalid runtime types.

• ValueError — If normalization or a width is invalid, method-specific metadata is inconsistent, or offsets are not canonical.

Constructor¶

def __init__(
    self,
    unitary: _BlockEncodingUnitary,
    normalization: float,
    num_signal_qubits: int,
    num_system_qubits: int,
    register_sizes: tuple[int, ...],
    offsets: tuple[tuple[int, ...], ...],
    coefficients: tuple[complex, ...],
) -> None

Attributes¶

• coefficients: tuple[complex, ...]

• offsets: tuple[tuple[int, ...], ...]

• register_sizes: tuple[int, ...]

qamomile.circuit.stdlib.block_encoding.ising_z¶

Build exact block encodings of diagonal Ising-Z operators.

Overview¶

Functions¶

configure_composite [source]¶

def configure_composite(
    kernel: QKernel[..., Any],
    *,
    name: str | None = None,
    namespace: str | None = None,
    gate_type: CompositeGateType = CompositeGateType.CUSTOM,
    policy: CallPolicy = CallPolicy.PRESERVE_BOX,
    implementations: Sequence[CallableImplementation] | None = None,
    semantic_arguments: Mapping[str, Any] | None = None,
) -> QKernel[..., Any]

Configure a QKernel to remain visible as a named composite call.

This mutates and returns the same QKernel object. No wrapper class or alternate call protocol is introduced.

Parameters:

Returns:

QKernel[..., Any] — QKernel[..., Any]: The same configured kernel instance.

global_phase [source]¶

def global_phase(target: QKernel | Callable[..., Any], phase: PhaseValue) -> GlobalPhaseGate

Apply a qkernel call followed by exp(i * phase).

The phase is represented as a zero-qubit operation and is retained even when it is not observable in the surrounding program. A reversible qkernel containing the operation acquires an observable relative phase when it is coherently controlled. Measurement, reset, allocation, classical outputs, and classical-only qkernels remain valid for ordinary standalone use.

Parameters:

Returns:

GlobalPhaseGate — Callable wrapper with the target’s call interface.

Raises:

• TypeError — If target cannot be interpreted as a gate-like callable.

Example:

>>> import qamomile.circuit as qmc
>>> @qmc.qkernel
... def step(q: qmc.Qubit) -> qmc.Qubit:
...     return qmc.x(q)
>>> @qmc.qkernel
... def phased_step(q: qmc.Qubit) -> qmc.Qubit:
...     return qmc.global_phase(step, 0.7)(q)

ising_z_block_encoding [source]¶

def ising_z_block_encoding(
    coefficients: Mapping[tuple[int, ...], complex],
    num_system_qubits: int,
) -> IsingZBlockEncoding

Create an exact block encoding of a diagonal Ising-Z operator.

Each mapping key is a product of Z operators at the listed system-qubit indices. Repeated indices cancel pairwise because Z**2 = I; the empty tuple denotes identity. Algebraically equivalent words are aggregated before constructing

Aggregation is deterministic for the same converted coefficient multiset on one host/runtime. Inputs that make the host math.fsum overflow an intermediate partial may be rejected even when their exact final sum is representable.

A multi-term encoding uses PREPARE amplitudes sqrt(abs(c_j) / alpha) and SELECT cases exp(1j * arg(c_j)) * Z_{S_j}. The returned encoding can be used as a child of another block encoding without converting the operator to a PauliLCU.

Parameters:

Returns:

IsingZBlockEncoding — Frozen non-callable block-encoding descriptor.

Raises:

• TypeError — If coefficients is not a mapping, a word is not a tuple, an index is not an integer, or a coefficient has an unsupported scalar type.

• ValueError — If a width is non-positive, an index is out of range, a coefficient or aggregate is non-finite, or finite coefficient aggregation overflows.

• RuntimeError — If internal state-preparation width derivation disagrees with the Ising-Z selector width.

Example:

>>> import qamomile.circuit as qmc
>>> encoding = qmc.ising_z_block_encoding(
...     {(): 0.25, (0,): -1.0, (0, 1): 0.5j},
...     num_system_qubits=2,
... )
>>> @qmc.qkernel
... def circuit() -> tuple[qmc.Vector[qmc.Qubit], qmc.Vector[qmc.Qubit]]:
...     signal = qmc.qubit_array(encoding.num_signal_qubits, "signal")
...     system = qmc.qubit_array(encoding.num_system_qubits, "system")
...     return encoding.unitary(signal, system)

qkernel [source]¶

def qkernel(func: Callable[P, R]) -> QKernel[P, R]

Decorator to define a Qamomile quantum kernel.

Parameters:

Returns:

QKernel[P, R] — QKernel[P, R]: QKernel wrapping the function.

z [source]¶

def z(target: Union[Qubit, Vector[Qubit]]) -> Union[Qubit, Vector[Qubit]]

Pauli-Z gate.

Broadcasts over a Vector[Qubit] when applied to one.

Parameters:

Returns:

Union[Qubit, Vector[Qubit]] — A Qubit for scalar input, a Vector[Qubit] for array input.

Raises:

• TypeError — If target is neither a Qubit nor a Vector[Qubit].

Classes¶

CallPolicy [source]¶

class CallPolicy(enum.Enum)

Describe the default lowering policy for a callable call.

Attributes¶

• INLINE

• NATIVE_FIRST

• PRESERVE_BOX

IsingZBlockEncoding [source]¶

class IsingZBlockEncoding(LCUBlockEncoding)

Describe one static exact block encoding of an Ising-Z operator.

The inherited unitary field has the quantum ABI unitary(signal, system) -> (signal, system) and no classical arguments. For the isometry V0 that initializes the complete signal register to zero, it satisfies

including the complex phases of the Ising-Z coefficients. The unitary allocates no hidden logical qubits and preserves the order of all input wires. Descriptor equality and hashing use object identity.

This producer-specific subtype adds no qkernel-visible fields. Reusable qkernels should annotate inputs with :class:LCUBlockEncoding so Ising-Z, Pauli, and recursively composed descriptors share one static binding slot.

Parameters:

Raises:

• TypeError — If a field has an invalid runtime type or unitary does not have the required static block-encoding ABI.

• ValueError — If normalization is non-finite or non-positive, or a register width is non-positive.

Constructor¶

def __init__(
    self,
    unitary: _BlockEncodingUnitary,
    normalization: float,
    num_signal_qubits: int,
    num_system_qubits: int,
) -> None

LCUBlockEncoding [source]¶

class LCUBlockEncoding

Describe one static exact LCU block encoding.

unitary is the qkernel implementing the larger unitary U; it is neither the encoded matrix A nor a dense matrix value. It has no classical arguments and its quantum ABI is unitary(signal, system) -> (signal, system). system is the ordered logical data register on which A acts. signal is the complete source-level ancilla bundle whose all-zero state selects the encoded block. The unitary returns the same logical wires in the same order and acts unitarily for arbitrary signal inputs; after one application, the signal may have non-zero components rather than returning entirely to zero.

For the all-zero signal isometry V0, the producer must guarantee

including coefficient phase. normalization is finite and positive; an encoding of the zero operator uses 1.0. Implementations allocate no hidden source-level logical qubits. A backend may still use temporary decomposition scratch that is resource-accounted, exactly uncomputed for every public input, and preserved under inverse and control. Descriptor comparison and hashing use object identity rather than field values.

This common descriptor deliberately excludes decomposition-specific metadata. Reusable qkernels should annotate an encoding argument with this class so descriptors produced by Pauli and future LCU factories can occupy the same compile-time binding slot.

Parameters:

Raises:

• TypeError — If unitary is not a QKernel with the exact static positional ABI above, normalization is not a real scalar, or either width is not an integer.

• ValueError — If normalization is non-finite or non-positive, or either width is non-positive.

Constructor¶

def __init__(
    self,
    unitary: _BlockEncodingUnitary,
    normalization: float,
    num_signal_qubits: int,
    num_system_qubits: int,
) -> None

Attributes¶

• normalization: float

• num_signal_qubits: int

• num_system_qubits: int

• unitary: _BlockEncodingUnitary

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.stdlib.block_encoding.lcu¶

Define the common static descriptor contract for exact LCU encodings.

Overview¶

Functions¶

get_size [source]¶

def get_size(arr: Vector[_H]) -> int

Return the size of a Vector handle as a Python integer.

Resolves the leading axis of arr.shape through two forms a Vector shape entry can take:

1. A plain Python int (built-in bound shape; this is what you get from qmc.qubit_array(N, ...) for literal N).

2. A UInt handle whose underlying Value carries a compile-time constant (set by uint(literal), _create_bound_input, or partial evaluation).

A UInt handle whose underlying Value is not a constant is treated as an unresolved symbolic dimension and raises ValueError even when the handle has the dataclass-default init_value=0. Falling back to init_value for that case would silently turn a runtime-symbolic Vector[Float] parameter into a “size 0” array, hiding programming errors. Callers that need to handle symbolic shapes (e.g., to emit a deferred callable when the size is unknown) must catch the ValueError themselves.

Parameters:

Returns:

int — The first-axis size as a plain Python int.

Raises:

• TypeError — If arr is not a 1-D Vector handle (Vector or its VectorView subclass) — e.g., a scalar Qubit was passed where a Vector is required, a higher-rank Matrix / Tensor was passed (this helper only resolves a 1-D first-axis size), or an unrelated shape-bearing object such as a numpy array. This is a clearer signal than the bare AttributeError that arr.shape would otherwise raise, and it guards the stdlib / composite callers that resolve a register size through this helper.

• ValueError — If the shape cannot be resolved to a concrete integer — e.g., the Vector is a runtime-parametric handle without compile-time bindings, or carries a UInt dimension whose underlying Value has not been promoted to a constant.

global_phase [source]¶

def global_phase(target: QKernel | Callable[..., Any], phase: PhaseValue) -> GlobalPhaseGate

Apply a qkernel call followed by exp(i * phase).

The phase is represented as a zero-qubit operation and is retained even when it is not observable in the surrounding program. A reversible qkernel containing the operation acquires an observable relative phase when it is coherently controlled. Measurement, reset, allocation, classical outputs, and classical-only qkernels remain valid for ordinary standalone use.

Parameters:

Returns:

GlobalPhaseGate — Callable wrapper with the target’s call interface.

Raises:

• TypeError — If target cannot be interpreted as a gate-like callable.

Example:

>>> import qamomile.circuit as qmc
>>> @qmc.qkernel
... def step(q: qmc.Qubit) -> qmc.Qubit:
...     return qmc.x(q)
>>> @qmc.qkernel
... def phased_step(q: qmc.Qubit) -> qmc.Qubit:
...     return qmc.global_phase(step, 0.7)(q)

identity_block_encoding [source]¶

def identity_block_encoding(num_system_qubits: int) -> LCUBlockEncoding

Create an exact identity encoding with one pass-through signal.

The unitary acts as identity on both registers and satisfies V0^dagger U V0 = I with normalization 1.0. One signal qubit is retained so the descriptor has the same positive-width ABI required by reusable circuits, nested SELECT, and all-zero projector consumers.

Parameters:

Returns:

LCUBlockEncoding — Exact identity descriptor with one signal qubit.

Raises:

• TypeError — If num_system_qubits is not an integer.

• ValueError — If num_system_qubits is non-positive.

inverse [source]¶

def inverse(target: Oracle | TransformedOracle | QKernelLike | Callable[..., Any]) -> Any

Create an inverse operation wrapper.

Native Qamomile gate functions are first synthesized into tiny QKernel objects, then inverted with the same block walker used for user-defined kernels. Qkernel-like composite gate callables created by qmc.composite_gate reuse their wrapped qkernel body. Known QFT/IQFT functions map directly to their counterpart so backend-native composite emission remains available. Opaque Oracles retain their original definition and cost boundary while the call records an inverse transform; the result can be passed directly to qmc.control. Inverting an already controlled Oracle produces the same transformed invocation as controlling its inverse.

Parameters:

Returns:

Any — A callable inverse wrapper, or the opposite QFT/IQFT function.

Raises:

• TypeError — If target cannot be interpreted as a gate-like callable, or if a body-free class-based composite instance is passed directly.

• NotImplementedError — If an inverted kernel uses unsupported operations such as if/while/for items control flow, QInit, or a ForOperation whose bounds are not compile-time constants when the inverse wrapper is traced. Loop-carried classical values are supported for UInt carries with a constant additive recurrence and for unchanged Float carries. Nonzero Float recurrences, non-additive recurrences, and coupled carries are rejected uniformly before backend emission.

Example:

>>> import qamomile.circuit as qmc
>>> @qmc.qkernel
... def layer(q: qmc.Qubit, angle: qmc.Float) -> qmc.Qubit:
...     q = qmc.h(q)
...     q = qmc.rz(q, angle)
...     return q
>>> @qmc.qkernel
... def circuit(angle: qmc.Float) -> qmc.Qubit:
...     q = qmc.qubit("q")
...     q = layer(q, angle)
...     q = qmc.inverse(layer)(q, angle)
...     return q

lcu_block_encoding [source]¶

def lcu_block_encoding(terms: Sequence[LCUBlockEncodingTerm]) -> LCUBlockEncoding

Compose an ordered LCU of exact child block encodings.

Given child encodings U_j satisfying

and logical coefficients c_j, this factory encodes

PREPARE amplitudes are sqrt(abs(c_j) * alpha_j / Lambda) and SELECT case j applies exp(1j * arg(c_j)) * U_j. Heterogeneous child signal registers share a pool whose width is the maximum child width. Every uniform-signature case routes only its leading child-sized slice and acts exactly as identity on unused padding for arbitrary pool states. The private parent lowering is [outer selector | shared child pool]; consumers only allocate the reported flat signal register and project all of it onto zero.

Child descriptors are concrete when this factory runs. Their coefficient data, angles, and layouts do not become public arguments of the completed parent unitary. The returned common descriptor may itself be supplied as a child of another composition or bound later to a reusable qkernel argument annotated with :class:LCUBlockEncoding.

Children must interpret the ordered system wires in the same logical basis; the common descriptor can validate their widths but cannot infer basis conventions. Generated callable semantic identity across separately constructed descriptors is not part of this API yet. Concrete children are captured when the factory runs, and the completed descriptor supports nesting and compile-time static binding without exposing those children as public qkernel arguments. Qiskit, QuriParts, and CUDA-Q inline these generated bodies. The HUGR target does not currently support recursive LCU composition because SELECT lowering and multiple inline callable-body variants sharing one source-derived reference are not yet supported.

Zero-coefficient terms are removed before normalization and SELECT construction. A nonempty sequence containing only zero coefficients creates an exact zero encoding with normalization 1.0 and one signal qubit; its child system widths must agree so the zero operator’s domain is defined. An empty sequence is rejected because its system width is unknowable.

Parameters:

Returns:

LCUBlockEncoding — Exact recursively composable parent descriptor.

Raises:

• TypeError — If terms is not an ordered sequence or contains a non-term value.

• ValueError — If terms is empty, relevant child system widths differ, or the composed normalization overflows or is non-finite.

• RuntimeError — If internal state-preparation width derivation disagrees with the recursive selector width.

Example:

>>> import qamomile.circuit as qmc
>>> identity = qmc.identity_block_encoding(1)
>>> encoding = qmc.lcu_block_encoding(
...     [
...         qmc.LCUBlockEncodingTerm(2.0, identity),
...         qmc.LCUBlockEncodingTerm(-0.5j, identity),
...     ]
... )
>>> encoding.normalization
2.5

merge_quantum_operand_widths [source]¶

def merge_quantum_operand_widths(
    attrs: Mapping[str, Any],
    widths: Sequence[QuantumOperandWidth],
    *,
    source: str,
    operand_count: int | None = None,
    conflict_labels: Mapping[int, str] | None = None,
) -> dict[str, Any]

Merge exact quantum widths into serializer-friendly callable attrs.

Existing resource-contract keys are preserved. Width entries are merged by quantum-operand index, compatible partial declarations are completed, and the encoded list is canonicalized by index.

Parameters:

Returns:

dict[str, Any] — dict[str, Any]: Copied attributes with the merged resource contract.

Raises:

• ValueError — If the existing or requested contract is malformed, repeats or conflicts at an operand index, or references an index outside operand_count.

qkernel [source]¶

def qkernel(func: Callable[P, R]) -> QKernel[P, R]

Decorator to define a Qamomile quantum kernel.

Parameters:

Returns:

QKernel[P, R] — QKernel[P, R]: QKernel wrapping the function.

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.

quantum_operand_widths [source]¶

def quantum_operand_widths(attrs: Mapping[str, Any], *, source: str) -> tuple[QuantumOperandWidth, ...]

Decode exact quantum-operand widths from callable resource metadata.

Parameters:

Returns:

tuple[QuantumOperandWidth, ...] — tuple[QuantumOperandWidth, ...]: Validated exact-width entries, or an empty tuple when the callable declares no such contract.

Raises:

• ValueError — If present resource metadata is malformed or repeats an operand index.

register_static_binding [source]¶

def register_static_binding(spec: StaticBindingSpec) -> None

Register one closed compile-time object adapter.

Parameters:

Raises:

• TypeError — If the annotation or type key has the wrong type, or if a field getter, field handle, or deferred member ABI is unsupported.

• ValueError — If the annotation or stable type key is already registered, or if the contract is empty or malformed.

select [source]¶

def select(
    cases: Sequence['QKernel | Callable[..., Any]'],
    num_index_qubits: int | UInt | None = None,
) -> SelectGate

Create a quantum multiplexer (SELECT) over a list of unitaries.

The returned gate applies cases[i] to a shared target register when the index register reads the integer i with index qubit zero as the least-significant bit. len(cases) need not be a power of two; index values >= len(cases) apply no operation.

A scalar Qubit case called with a Vector[Qubit] or VectorView[Qubit] target is applied independently to every element. This is the same tensor-product unitary as an explicit per-element loop, including one copy of the scalar case’s global phase per element. A phase intended for the complete register belongs on a case whose parameter is itself Vector[Qubit].

Circuit-family lowering retains the abstract SELECT identity while its portable fallback invokes each case under the corresponding mixed 0/1 (anti-/normal) index pattern.

Parameters:

Returns:

SelectGate — A callable applied as sel(index, *targets, **params).

Raises:

• ValueError — If fewer than two cases are supplied, a concrete width is too small, or the cases do not share an identical parameter signature. Case-body footprint and unitarity are validated when the returned gate is called.

• TypeError — If the width has an unsupported type or a case cannot be wrapped into a qkernel.

Example:

>>> import qamomile.circuit as qm
>>> @qm.qkernel
... def pick() -> qm.Vector[qm.Bit]:
...     idx = qm.qubit_array(2, name="idx")
...     idx = qm.h(idx)
...     t = qm.qubit(name="t")
...     idx, t = qm.select([qm.x, qm.y, qm.z, qm.h])(idx, t)
...     return qm.measure(idx)

uint [source]¶

def uint(arg: int | str) -> UInt

Create a UInt handle from an integer literal or a named parameter.

Parameters:

Returns:

UInt — A constant-valued handle for an int argument, or a named symbolic handle for a str argument.

Raises:

• TypeError — If arg is neither a plain int nor a str (in particular, if it is a bool).

x [source]¶

def x(target: Union[Qubit, Vector[Qubit]]) -> Union[Qubit, Vector[Qubit]]

Pauli-X gate (NOT gate).

Broadcasts over a Vector[Qubit] when applied to one.

Parameters:

Returns:

Union[Qubit, Vector[Qubit]] — A Qubit for scalar input, a Vector[Qubit] for array input.

Raises:

• TypeError — If target is neither a Qubit nor a Vector[Qubit].

Classes¶

CallPolicy [source]¶

class CallPolicy(enum.Enum)

Describe the default lowering policy for a callable call.

Attributes¶

• INLINE

• NATIVE_FIRST

• PRESERVE_BOX

LCUBlockEncoding [source]¶

class LCUBlockEncoding

Describe one static exact LCU block encoding.

unitary is the qkernel implementing the larger unitary U; it is neither the encoded matrix A nor a dense matrix value. It has no classical arguments and its quantum ABI is unitary(signal, system) -> (signal, system). system is the ordered logical data register on which A acts. signal is the complete source-level ancilla bundle whose all-zero state selects the encoded block. The unitary returns the same logical wires in the same order and acts unitarily for arbitrary signal inputs; after one application, the signal may have non-zero components rather than returning entirely to zero.

For the all-zero signal isometry V0, the producer must guarantee

including coefficient phase. normalization is finite and positive; an encoding of the zero operator uses 1.0. Implementations allocate no hidden source-level logical qubits. A backend may still use temporary decomposition scratch that is resource-accounted, exactly uncomputed for every public input, and preserved under inverse and control. Descriptor comparison and hashing use object identity rather than field values.

This common descriptor deliberately excludes decomposition-specific metadata. Reusable qkernels should annotate an encoding argument with this class so descriptors produced by Pauli and future LCU factories can occupy the same compile-time binding slot.

Parameters:

Raises:

• TypeError — If unitary is not a QKernel with the exact static positional ABI above, normalization is not a real scalar, or either width is not an integer.

• ValueError — If normalization is non-finite or non-positive, or either width is non-positive.

Constructor¶

def __init__(
    self,
    unitary: _BlockEncodingUnitary,
    normalization: float,
    num_signal_qubits: int,
    num_system_qubits: int,
) -> None

Attributes¶

• normalization: float

• num_signal_qubits: int

• num_system_qubits: int

• unitary: _BlockEncodingUnitary

LCUBlockEncodingTerm [source]¶

class LCUBlockEncodingTerm

Pair a logical coefficient with one exact child block encoding.

coefficient multiplies the child target matrix A_j, not its normalized projected block A_j / alpha_j. The recursive composer therefore assigns the term weight abs(coefficient) * encoding.normalization. Children are concrete construction-time descriptors; the completed parent, rather than unresolved children, is the object intended for qkernel static binding.

Parameters:

Raises:

• TypeError — If the coefficient is not a non-boolean complex numeric scalar or encoding is not an LCUBlockEncoding.

• ValueError — If a numeric coefficient cannot be converted to a finite built-in complex value or either component is non-finite.

Constructor¶

def __init__(self, coefficient: complex, encoding: LCUBlockEncoding) -> None

Attributes¶

• coefficient: complex

• encoding: LCUBlockEncoding

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

QuantumOperandWidth [source]¶

class QuantumOperandWidth

Describe one exact source-callable quantum operand width.

Parameters:

Constructor¶

def __init__(self, index: int, name: str, width: int) -> None

Attributes¶

• index: int

• name: str

• width: int

StaticBindingFieldSpec [source]¶

class StaticBindingFieldSpec

Describe one scalar field exposed by a static-binding proxy.

Parameters:

Constructor¶

def __init__(self, handle_type: type[Handle], getter: Callable[[Any], int | float]) -> None

Attributes¶

• getter: Callable[[Any], int | float]

• handle_type: type[Handle]

StaticBindingMemberSpec [source]¶

class StaticBindingMemberSpec

Describe one deferred qkernel-valued member of a static binding.

Parameters:

Constructor¶

def __init__(
    self,
    input_types: Mapping[str, Any],
    output_types: tuple[Any, ...],
    return_annotation: Any,
    getter: Callable[[Any], Any],
    qubit_width_fields: Mapping[str, str] = dict(),
) -> None

Attributes¶

• getter: Callable[[Any], Any]

• input_types: Mapping[str, Any]

• output_types: tuple[Any, ...]

• qubit_width_fields: Mapping[str, str]

• return_annotation: Any

StaticBindingSpec [source]¶

class StaticBindingSpec

Register the closed qkernel surface of one compile-time object type.

Parameters:

Constructor¶

def __init__(
    self,
    annotation: type[Any],
    type_key: str,
    fields: Mapping[str, StaticBindingFieldSpec],
    members: Mapping[str, StaticBindingMemberSpec],
) -> None

Attributes¶

• annotation: type[Any]

• fields: Mapping[str, StaticBindingFieldSpec]

• members: Mapping[str, StaticBindingMemberSpec]

• type_key: str

qamomile.circuit.stdlib.block_encoding.pauli¶

Build block encodings from complex Pauli linear combinations.

Overview¶

Functions¶

configure_composite [source]¶

def configure_composite(
    kernel: QKernel[..., Any],
    *,
    name: str | None = None,
    namespace: str | None = None,
    gate_type: CompositeGateType = CompositeGateType.CUSTOM,
    policy: CallPolicy = CallPolicy.PRESERVE_BOX,
    implementations: Sequence[CallableImplementation] | None = None,
    semantic_arguments: Mapping[str, Any] | None = None,
) -> QKernel[..., Any]

Configure a QKernel to remain visible as a named composite call.

This mutates and returns the same QKernel object. No wrapper class or alternate call protocol is introduced.

Parameters:

Returns:

QKernel[..., Any] — QKernel[..., Any]: The same configured kernel instance.

global_phase [source]¶

def global_phase(target: QKernel | Callable[..., Any], phase: PhaseValue) -> GlobalPhaseGate

Apply a qkernel call followed by exp(i * phase).

The phase is represented as a zero-qubit operation and is retained even when it is not observable in the surrounding program. A reversible qkernel containing the operation acquires an observable relative phase when it is coherently controlled. Measurement, reset, allocation, classical outputs, and classical-only qkernels remain valid for ordinary standalone use.

Parameters:

Returns:

GlobalPhaseGate — Callable wrapper with the target’s call interface.

Raises:

• TypeError — If target cannot be interpreted as a gate-like callable.

Example:

>>> import qamomile.circuit as qmc
>>> @qmc.qkernel
... def step(q: qmc.Qubit) -> qmc.Qubit:
...     return qmc.x(q)
>>> @qmc.qkernel
... def phased_step(q: qmc.Qubit) -> qmc.Qubit:
...     return qmc.global_phase(step, 0.7)(q)

pauli_lcu_block_encoding [source]¶

def pauli_lcu_block_encoding(lcu: PauliLCU) -> PauliLCUBlockEncoding

Create a static exact block encoding of a complex Pauli LCU.

For a nonzero decomposition

the descriptor’s qkernel unitary implements U and satisfies

Multi-term encodings use real-amplitude PREPARE weights sqrt(abs(c_j) / alpha) and SELECT cases exp(1j * arg(c_j)) * P_j. The identity Pauli word is a normal case, so its coefficient phase is retained. The zero operator uses one signal qubit and an X gate, giving an exact zero all-zero block with normalization 1.0; its PauliLCU.alpha remains 0.0.

The retained Pauli LCU is square, static, and encoded exactly. When :meth:PauliLCU.from_matrix truncated coefficients, its source-to-retained error remains available as lcu.truncation_error_bound and is not an error in this unitary. The unitary accepts arbitrary signal states, returns the same signal and system wires in the same order, supports :func:~qamomile.circuit.inverse, and allocates no hidden source-level logical workspace. Backend-only decomposition scratch is permitted only when resource-accounted and exactly uncomputed for all inputs, including under inverse and control.

Parameters:

Returns:

PauliLCUBlockEncoding — Frozen non-callable descriptor. Allocate its registers with num_signal_qubits and num_system_qubits, then invoke unitary(signal, system).

Raises:

• TypeError — If lcu is not a PauliLCU.

• ValueError — If lcu represents a scalar zero-qubit system.

Example:

>>> import numpy as np
>>> import qamomile.circuit as qmc
>>> from qamomile.linalg import PauliLCU
>>> lcu = PauliLCU.from_matrix(np.array([[0, 1], [0, 0]], complex))
>>> encoding = qmc.pauli_lcu_block_encoding(lcu)
>>> @qmc.qkernel
... def circuit() -> tuple[qmc.Vector[qmc.Qubit], qmc.Vector[qmc.Qubit]]:
...     signal = qmc.qubit_array(encoding.num_signal_qubits, "signal")
...     system = qmc.qubit_array(encoding.num_system_qubits, "system")
...     return encoding.unitary(signal, system)

qkernel [source]¶

def qkernel(func: Callable[P, R]) -> QKernel[P, R]

Decorator to define a Qamomile quantum kernel.

Parameters:

Returns:

QKernel[P, R] — QKernel[P, R]: QKernel wrapping the function.

x [source]¶

def x(target: Union[Qubit, Vector[Qubit]]) -> Union[Qubit, Vector[Qubit]]

Pauli-X gate (NOT gate).

Broadcasts over a Vector[Qubit] when applied to one.

Parameters:

Returns:

Union[Qubit, Vector[Qubit]] — A Qubit for scalar input, a Vector[Qubit] for array input.

Raises:

• TypeError — If target is neither a Qubit nor a Vector[Qubit].

y [source]¶

def y(target: Union[Qubit, Vector[Qubit]]) -> Union[Qubit, Vector[Qubit]]

Pauli-Y gate.

Broadcasts over a Vector[Qubit] when applied to one.

Parameters:

Returns:

Union[Qubit, Vector[Qubit]] — A Qubit for scalar input, a Vector[Qubit] for array input.

Raises:

• TypeError — If target is neither a Qubit nor a Vector[Qubit].

z [source]¶

def z(target: Union[Qubit, Vector[Qubit]]) -> Union[Qubit, Vector[Qubit]]

Pauli-Z gate.

Broadcasts over a Vector[Qubit] when applied to one.

Parameters:

Returns:

Union[Qubit, Vector[Qubit]] — A Qubit for scalar input, a Vector[Qubit] for array input.

Raises:

• TypeError — If target is neither a Qubit nor a Vector[Qubit].

Classes¶

CallPolicy [source]¶

class CallPolicy(enum.Enum)

Describe the default lowering policy for a callable call.

Attributes¶

• INLINE

• NATIVE_FIRST

• PRESERVE_BOX

LCUBlockEncoding [source]¶

class LCUBlockEncoding

Describe one static exact LCU block encoding.

unitary is the qkernel implementing the larger unitary U; it is neither the encoded matrix A nor a dense matrix value. It has no classical arguments and its quantum ABI is unitary(signal, system) -> (signal, system). system is the ordered logical data register on which A acts. signal is the complete source-level ancilla bundle whose all-zero state selects the encoded block. The unitary returns the same logical wires in the same order and acts unitarily for arbitrary signal inputs; after one application, the signal may have non-zero components rather than returning entirely to zero.

For the all-zero signal isometry V0, the producer must guarantee

including coefficient phase. normalization is finite and positive; an encoding of the zero operator uses 1.0. Implementations allocate no hidden source-level logical qubits. A backend may still use temporary decomposition scratch that is resource-accounted, exactly uncomputed for every public input, and preserved under inverse and control. Descriptor comparison and hashing use object identity rather than field values.

This common descriptor deliberately excludes decomposition-specific metadata. Reusable qkernels should annotate an encoding argument with this class so descriptors produced by Pauli and future LCU factories can occupy the same compile-time binding slot.

Parameters:

Raises:

• TypeError — If unitary is not a QKernel with the exact static positional ABI above, normalization is not a real scalar, or either width is not an integer.

• ValueError — If normalization is non-finite or non-positive, or either width is non-positive.

Constructor¶

def __init__(
    self,
    unitary: _BlockEncodingUnitary,
    normalization: float,
    num_signal_qubits: int,
    num_system_qubits: int,
) -> None

Attributes¶

• normalization: float

• num_signal_qubits: int

• num_system_qubits: int

• unitary: _BlockEncodingUnitary

PauliLCUBlockEncoding [source]¶

class PauliLCUBlockEncoding(LCUBlockEncoding)

Identify an LCU block encoding produced from a Pauli decomposition.

The subtype adds no qkernel-visible fields. Reusable qkernels should annotate encoding arguments with :class:LCUBlockEncoding; the Pauli subtype remains available for producer-specific host-side code and backward-compatible serialized templates.

Parameters:

Raises:

• TypeError — If an inherited descriptor field has an invalid type or the unitary ABI is invalid.

• ValueError — If normalization or a register width is non-positive or non-finite.

Constructor¶

def __init__(
    self,
    unitary: _BlockEncodingUnitary,
    normalization: float,
    num_signal_qubits: int,
    num_system_qubits: int,
) -> None

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.stdlib.block_encoding.periodic_shift¶

Build LCU block encodings from constant-coefficient periodic shifts.

For axis registers with widths register_sizes, this module represents

where T_k adds the integer offset tuple k modulo the corresponding power-of-two axis sizes. The construction prepares real amplitudes sqrt(abs(c_k) / lambda), applies exp(1j * arg(c_k)) * T_k through qmc.select, and unprepares the signal register. Consequently the all-zero signal block is A / lambda for lambda = sum(abs(c_k)).

Only periodic boundaries, constant coefficients, and power-of-two axis sizes are in scope. Non-periodic boundary corrections and position-dependent coefficients require different block-encoding constructions. Each constant shift is decomposed into ancilla-free increment or decrement ladders for the set bits of its displacement. A dense circulant kernel may still require exponentially many LCU terms, so this factory is intended for shift-sparse decompositions.

Overview¶

Functions¶

periodic_shift_lcu_block_encoding [source]¶

def periodic_shift_lcu_block_encoding(lcu: PeriodicShiftLCU) -> PeriodicShiftLCUBlockEncoding

Build an LCU block encoding from a periodic-shift decomposition.

lcu defines A = sum_k c_k T_k, where T_k is the modular translation for one canonical offset tuple. The system is the flattened concatenation of the decomposition’s LSB-first axis registers. A shift uses the shorter signed displacement, then emits one ancilla-free increment or decrement ladder for each set bit of its magnitude. This bounds the number of Qamomile-level X and multi-controlled-X operations by a quadratic function of an axis register’s width; backend elementary-gate cost depends on how that backend decomposes multi-controlled X operations.

The returned descriptor’s unitary acts on arbitrary signal states. Projecting its signal register onto all zero before and after the unitary yields A / lambda, where lambda is available as result.normalization. The zero operator uses one signal qubit and an X gate, giving an exact zero all-zero block with normalization 1.0 while lcu.alpha remains 0.0. A single term retains one pass-through signal qubit for composition but omits PREPARE and SELECT entirely.

When :meth:PeriodicShiftLCU.from_matrix or :meth:PeriodicShiftLCU.from_coefficients pruned coefficients, the source error remains available as lcu.truncation_error_bound and is not an error in the retained unitary.

Parameters:

Returns:

PeriodicShiftLCUBlockEncoding — Frozen non-callable descriptor containing the generated shift-LCU unitary and method-specific canonical metadata.

Raises:

• TypeError — If lcu is not a :class:PeriodicShiftLCU.

• ValueError — If lcu represents a scalar zero-qubit system.

Example:

>>> import qamomile.circuit as qmc
>>> from qamomile.circuit.serialization import deserialize, serialize
>>> from qamomile.linalg import PeriodicShiftLCU
>>> from qamomile.qiskit import QiskitTranspiler
>>> @qmc.qkernel
... def apply_encoding(
...     encoding: qmc.LCUBlockEncoding,
... ) -> tuple[qmc.Vector[qmc.Qubit], qmc.Vector[qmc.Qubit]]:
...     signal = qmc.qubit_array(encoding.num_signal_qubits, "signal")
...     system = qmc.qubit_array(encoding.num_system_qubits, "system")
...     return encoding.unitary(signal, system)
>>> payload = serialize(apply_encoding)
>>> received = deserialize(payload)
>>> lcu = PeriodicShiftLCU.from_coefficients(
...     {-1: 1.0, 0: -2.0, 1: 1.0},
...     register_sizes=(3,),
... )
>>> neighbor_difference = qmc.periodic_shift_lcu_block_encoding(lcu)
>>> isinstance(neighbor_difference, qmc.LCUBlockEncoding)
True
>>> neighbor_difference.normalization
4.0
>>> executable = QiskitTranspiler().transpile(
...     received,
...     bindings={"encoding": neighbor_difference},
... )

Classes¶

LCUBlockEncoding [source]¶

class LCUBlockEncoding

Describe one static exact LCU block encoding.

unitary is the qkernel implementing the larger unitary U; it is neither the encoded matrix A nor a dense matrix value. It has no classical arguments and its quantum ABI is unitary(signal, system) -> (signal, system). system is the ordered logical data register on which A acts. signal is the complete source-level ancilla bundle whose all-zero state selects the encoded block. The unitary returns the same logical wires in the same order and acts unitarily for arbitrary signal inputs; after one application, the signal may have non-zero components rather than returning entirely to zero.

For the all-zero signal isometry V0, the producer must guarantee

including coefficient phase. normalization is finite and positive; an encoding of the zero operator uses 1.0. Implementations allocate no hidden source-level logical qubits. A backend may still use temporary decomposition scratch that is resource-accounted, exactly uncomputed for every public input, and preserved under inverse and control. Descriptor comparison and hashing use object identity rather than field values.

This common descriptor deliberately excludes decomposition-specific metadata. Reusable qkernels should annotate an encoding argument with this class so descriptors produced by Pauli and future LCU factories can occupy the same compile-time binding slot.

Parameters:

Raises:

• TypeError — If unitary is not a QKernel with the exact static positional ABI above, normalization is not a real scalar, or either width is not an integer.

• ValueError — If normalization is non-finite or non-positive, or either width is non-positive.

Constructor¶

def __init__(
    self,
    unitary: _BlockEncodingUnitary,
    normalization: float,
    num_signal_qubits: int,
    num_system_qubits: int,
) -> None

Attributes¶

• normalization: float

• num_signal_qubits: int

• num_system_qubits: int

• unitary: _BlockEncodingUnitary

PeriodicShiftLCUBlockEncoding [source]¶

class PeriodicShiftLCUBlockEncoding(LCUBlockEncoding)

Describe one static exact periodic-shift LCU block encoding.

unitary is the qkernel implementing the larger unitary U; it is neither the encoded periodic-shift matrix A nor a dense matrix value. It has no classical arguments and its quantum ABI is unitary(signal, system) -> (signal, system). system is the ordered flattened data register on which A acts. signal is the complete source-level ancilla bundle whose all-zero state selects the encoded block. The unitary returns the same logical wires in the same order and acts unitarily for arbitrary signal inputs; signal need not return to zero after one application.

For the all-zero signal isometry V0, the encoded periodic-shift matrix satisfies

including coefficient phase. The construction is exact in ideal logical arithmetic; host floating-point roundoff in state-preparation angles and backend gate synthesis are outside this semantic equality. This producer allocates no hidden source-level logical qubits. Backend decomposition scratch is permitted only when resource-accounted and exactly uncomputed for every input, including under inverse and control. Descriptor comparison and hashing use object identity rather than field values.

The inherited fields form the qkernel-visible static LCU contract. register_sizes, offsets, and coefficients are deeply immutable producer metadata for host-side inspection only. A producer-specific qkernel may annotate an argument with this class. Reusable qkernels should instead annotate descriptor arguments with :class:LCUBlockEncoding, allowing the same serialized template to accept this and other exact LCU producers.

Parameters:

Raises:

• TypeError — If the common block-encoding fields or method-specific metadata have invalid runtime types.

• ValueError — If normalization or a width is invalid, method-specific metadata is inconsistent, or offsets are not canonical.

Constructor¶

def __init__(
    self,
    unitary: _BlockEncodingUnitary,
    normalization: float,
    num_signal_qubits: int,
    num_system_qubits: int,
    register_sizes: tuple[int, ...],
    offsets: tuple[tuple[int, ...], ...],
    coefficients: tuple[complex, ...],
) -> None

Attributes¶

• coefficients: tuple[complex, ...]

• offsets: tuple[tuple[int, ...], ...]

• register_sizes: tuple[int, ...]

qamomile.circuit.stdlib.computational_basis_state¶

Overview¶

Functions¶

computational_basis_state [source]¶

def computational_basis_state(q: qmc.Vector[qmc.Qubit], bits: qmc.Vector[qmc.UInt]) -> qmc.Vector[qmc.Qubit]

Prepare the computational basis state labeled by bits.

Applies an exact X ** bits[i] to each qubit. The implementation uses Rx(pi * bits[i]) plus its compensating exp(+i*pi*bits[i]/2) global phase, so controlling this kernel preserves the intended unitary rather than turning the RX phase into an observable relative phase.

Assumes q starts in $\lvert 0 \rangle^{\otimes n}$ and q.shape[0] == bits.shape[0].

Parameters:

Returns:

qmc.Vector[qmc.Qubit] — qmc.Vector[qmc.Qubit]: Qubit register prepared in the exact |bits> qmc.Vector[qmc.Qubit] — state convention.

qamomile.circuit.stdlib.grover¶

Grover search building blocks with query-complexity resource estimation.

This module provides :func:grover_search, the amplitude-amplification loop from the book’s Section 4.1 (“Search algorithms a la Grover”), and helpers to compute the optimal iteration count. Grover search over N = 2**n items with m marked solutions needs O(sqrt(N/m)) iterations, each applying one oracle query and one diffusion (reflection about the uniform superposition).

The oracle is supplied by the caller as a costed opaque box (e.g. qmc.opaque(..., cost=...)), so the total gate cost is iterations x (oracle_cost + diffusion_cost) while the query complexity is the universal O(sqrt(N/m)). Leaving the iteration count symbolic makes estimate_resources report that scaling directly; :func:grover_iteration_count returns the concrete or symbolic floor((pi/4) sqrt(N/m)). Plug it in with the inputs argument to get the optimal query complexity straight from one estimate call::

est = kernel.estimate_resources(
    inputs={"iterations": grover_iteration_count(n, m)}
)
est.calls.queries_by_name[oracle_name]  # floor((pi/4) sqrt(2^n / m))

Overview¶

Functions¶

for_loop [source]¶

def for_loop(
    start,
    stop,
    step = 1,
    var_name: str = '_loop_idx',
    *,
    captures: tuple[tuple[str, Any], ...] = (),
) -> Generator[UInt, None, None]

Create a traced for loop in the Qamomile frontend.

Parameters:

Yields:

UInt — The loop iteration variable (can be used as array index)

Raises:

• TypeError — If a bound cannot be represented as a scalar IR value.

• ValueError — If the constructed loop has inconsistent region-result metadata.

Example:

@QKernel
def my_kernel(qubits: Array[Qubit, Literal[3]]) -> Array[Qubit, Literal[3]]:
    for i in qm.range(3):
        qubits[i] = h(qubits[i])
    return qubits

@QKernel
def my_kernel2(qubits: Array[Qubit, Literal[5]]) -> Array[Qubit, Literal[5]]:
    for i in qm.range(1, 4):  # i = 1, 2, 3
        qubits[i] = h(qubits[i])
    return qubits

Classical scalar updates (total = total + i) become explicit RegionArg records on the ForOperation: the loop enters with the initializer, each iteration reads the previous iteration’s value, and post-loop code reads the loop result.

grover_iteration_count [source]¶

def grover_iteration_count(
    num_qubits: int | np.integer[Any] | sp.Expr,
    num_marked: int | np.integer[Any] | sp.Expr = 1,
) -> int | sp.Expr

Return the optimal Grover iteration count floor((pi/4) sqrt(N/m)).

Parameters:

Returns:

int | sp.Expr — int | sp.Expr: Concrete iteration count when both arguments are concrete Python or NumPy integers, otherwise the symbolic expression floor((pi/4) sqrt(2**n / m)). SymPy integers remain SymPy expressions.

Raises:

• TypeError — If num_qubits or num_marked is a boolean.

• ValueError — If concrete num_qubits or num_marked is not positive.

Example:

>>> grover_iteration_count(4, 1)
3

grover_search [source]¶

def grover_search(
    reg: Vector[Qubit],
    oracle: Oracle | QKernelLike,
    iterations: int | qmc.UInt,
) -> Vector[Qubit]

Run the Grover amplitude-amplification loop on reg.

Prepares the uniform superposition, then applies iterations rounds of oracle followed by the diffusion operator. Leaving iterations symbolic makes resource estimation report the universal O(sqrt(N/m)) query complexity: the oracle’s opaque cost contributes the per-query gate cost and the diffusion contributes O(n) gates, both summed over the symbolic iteration count.

Parameters:

Returns:

Vector[Qubit] — Vector[Qubit]: Register after amplitude amplification.

Example:

>>> import qamomile.circuit as qmc
>>> from qamomile.circuit.stdlib import grover_search, grover_iteration_count
>>> mark = qmc.opaque("mark", num_qubits=3)
>>> @qmc.qkernel
... def search(reg: qmc.Vector[qmc.Qubit]) -> qmc.Vector[qmc.Qubit]:
...     return grover_search(reg, mark, grover_iteration_count(3))

Classes¶

Oracle [source]¶

class Oracle

Represent an opaque oracle callable.

Parameters:

Raises:

• TypeError — If a supplied num_qubits or num_control_qubits is boolean or not an integral scalar.

• ValueError — If either width is negative, or neither num_qubits nor signature supplies enough target-arity information.

Constructor¶

def __init__(
    self,
    name: str,
    num_qubits: int | None = None,
    *,
    num_control_qubits: int = 0,
    signature: CallableSignature | None = None,
    cost: ResourceEstimate | Callable[[OpaqueCostContext], ResourceEstimate] | None = None,
) -> None

Initialize an opaque oracle callable.

Parameters:

Raises:

• TypeError — If a supplied num_qubits or num_control_qubits is not a non-boolean integral scalar.

• ValueError — If neither num_qubits nor signature supplies enough target-arity information, or if either width is negative.

Attributes¶

• cost: ResourceEstimate | Callable[[OpaqueCostContext], ResourceEstimate] | None

• name: str

• num_control_qubits: int

• num_qubits: int | None

• signature: CallableSignature | None

QKernelLike [source]¶

class QKernelLike(Protocol)

Describe the frontend surface required by compiler entrypoints.

This protocol is intentionally structural. It lets decorator-created composites reuse the qkernel inspection and build interface without making them inherit from QKernel or exposing the compiler-facing callable descriptor model as a frontend concept.

Attributes¶

• block: Block Return the cached hierarchical body block.

• effects: KernelEffect Return cached semantic effects of the qkernel body.

• input_types: dict[str, Any] Return frontend input annotations by parameter name.

• name: str Return the user-facing callable name.

• output_types: list[Any] Return frontend output annotations.

• signature: inspect.Signature Return the Python call signature.

Methods¶

build¶

def build(self, parameters: list[str] | None = None, **kwargs: Any = {}) -> Block

Build a traced body block.

Parameters:

Returns:

Block — Traced hierarchical body block.

qamomile.circuit.stdlib.mottonen_amplitude_encoding¶

Amplitude encoding with generic and Möttönen-specific APIs.

Prepares the n-qubit state

from $|0\rangle^{\otimes n}$ for a normalised amplitude vector a. The construction follows Möttönen et al., “Transformation of quantum states using uniformly controlled rotations” (arXiv:quant-ph/0407010). Both the RY-only “amplitude distribution” stage and the RZ “phase restoration” stage are supported, so general complex amplitudes work end-to-end.

.. important::

**Pre-condition: the input register must be in the all-zero state**
$|0\rangle^{\otimes n}$.  The Möttönen construction
decomposes the unitary that takes $|0\rangle^{\otimes n}$
to the target $|\psi\rangle$; applying it to any other
initial state yields a *different* output (the same unitary
applied to a different input), not the target amplitude vector.
There is no runtime guard for this — Qamomile does not track
qubit states — so it is the caller's responsibility to ensure the
register has not yet been mutated when an amplitude-encoding helper is
invoked. In practice, call these helpers immediately after
``qmc.qubit_array(n, ...)`` inside a kernel.

The generic :func:amplitude_encoding API specifies the prepared state but not the synthesis algorithm. Backends may therefore replace it with a native state preparation implementation. Its portable Qamomile body currently uses the Möttönen construction described below.

The :func:mottonen_amplitude_encoding API makes that construction part of the callable identity, so a backend cannot replace it with a generic state preparation implementation. The parametric companion :func:mottonen_amplitude_encoding_from_angles emits the Möttönen Gray walk directly. :func:amplitude_encoding_from_angles remains as a compatibility wrapper for the parametric companion. Classical angle precomputation lives in :mod:qamomile.linalg.mottonen so hybrid loops can compute angles outside a kernel and bind them as runtime parameters.

Pipeline¶

1. Validate and normalise the input — see :func:qamomile.linalg.mottonen.validate_and_normalize_amplitudes (length must be a power of two, all-zero rejected).

2. Determine whether the input is genuinely complex (has a non-zero imaginary part). Real inputs (including complex with zero imag) keep the original signed-RY path — negative real amplitudes flow through the sign of arctan2(a_1, a_0) naturally, with no RZ overhead. Complex inputs use the iterative disentangling construction.

3. For real inputs, compute the per-level RY rotation angles by splitting each chunk into upper / lower halves and using arctan2 of the two sub-block norms (or signed arctan2 at the leaf). See :func:qamomile.linalg.mottonen.compute_all_ry_angles_per_level.

4. For complex inputs, iteratively disentangle the target amplitude vector qubit-by-qubit from LSB to MSB. See :func:qamomile.linalg.mottonen.compute_disentangling_angles_per_level.

5. At each level k >= 1 apply a uniformly controlled rotation over the previously prepared k qubits. We use the standard Gray-code RY / CNOT decomposition for the magnitude stage and the same structure with RZ for the phase stage. The emitted gate order is “all RY layers, then all RZ layers”. Pairwise [U_y^(k), U_z^(k')] does NOT commute in general (including k != k' cases, because earlier RY targets can be controls of later RZ multiplexers), but the FULL sweep product equals the per-level interleaved product (U_z^(0) U_y^(0)) ... (U_z^(n-1) U_y^(n-1)) as unitaries — this is a structural identity verified by :class:tests.circuit.stdlib.state_preparation.test_mottonen_amplitude_encoding.TestRyRzOrdering with arbitrary (non-disentangling) per-level angles. Within each level the order RY-before-RZ is preserved in both schemes.

_MottonenAngles validates and normalizes eagerly, then caches the more expensive angle precomputation. It is an internal classical helper rather than a second frontend gate type; the frontend objects produced here are normal QKernel instances decorated with @composite_gate.

Overview¶

Functions¶

amplitude_encoding [source]¶

def amplitude_encoding(
    qubits: Vector[Qubit],
    amplitudes: Sequence[float] | Sequence[complex] | np.ndarray | Vector[Float],
) -> Vector[Qubit]

Prepare an amplitude-encoded state with a backend-selected synthesis.

The semantic contract is that an all-zero n-qubit register becomes the normalized state $\sum_i a_i |i\rangle$. The synthesis algorithm is intentionally unspecified: a backend may use its native state-preparation implementation. Qamomile’s portable fallback currently uses the Möttönen construction.

State-preparation algorithms can implement different unitaries away from the all-zero input even when they prepare the same target state. Use :func:mottonen_amplitude_encoding when the exact construction, its resource profile, or transformed uses such as inverse and control matter.

A concrete sequence or NumPy array may contain real or complex amplitudes. A Vector[Float] parameter must be resolved through bindings at compile time. For runtime-parametric Möttönen angles, use :func:mottonen_amplitude_encoding_from_angles.

Parameters:

Returns:

Vector[Qubit] — Vector[Qubit]: The input vector updated to the prepared-state handles.

Raises:

• ValueError — If a vector shape is unresolved, the amplitudes are invalid or unavailable at trace time, or the register width does not match the amplitude-vector length.

Example::

@qmc.qkernel
def prepare() -> qmc.Vector[qmc.Bit]:
    q = qmc.qubit_array(2, name="q")
    q = amplitude_encoding(q, [1.0, 0.0, 0.0, 1.0])
    return qmc.measure(q)

amplitude_encoding_from_angles [source]¶

def amplitude_encoding_from_angles(
    qubits: Vector[Qubit],
    ry_angles: Sequence[float] | np.ndarray | Vector[Float],
    rz_angles: Sequence[float] | np.ndarray | Vector[Float] | None = None,
) -> Vector[Qubit]

Apply Möttönen encoding from angles through the compatibility API.

This function preserves the original public name and delegates directly to :func:mottonen_amplitude_encoding_from_angles. New code should prefer the algorithm-specific name because angle vectors define the Möttönen Gray-walk decomposition rather than generic amplitude encoding.

Parameters:

Returns:

Vector[Qubit] — Vector[Qubit]: The input vector updated to the prepared-state handles.

Raises:

• ValueError — If a concrete angle vector has the wrong length or the qubit-vector shape cannot be resolved.

composite_gate [source]¶

def composite_gate(
    func: Callable[..., Any] | None = None,
    *,
    name: str = '',
    implementations: Sequence[CallableImplementation] | None = None,
) -> QKernel[..., Any] | Callable[[Callable[..., Any]], QKernel[..., Any]]

Define a named composite using the normal qkernel programming model.

The decorated object is a QKernel. Calls keep their named box in the IR, while build(), draw(), estimate_resources(), control(), and inverse() use the same interface as every other qkernel.

Parameters: