qamomile.circuit.qsvt

Apply quantum singular value transformation to an LCU block encoding.

The public :func:qsvt helper composes a static :class:~qamomile.circuit.stdlib.LCUBlockEncoding with a QSVT phase sequence. Both inputs may remain unresolved while an enclosing qkernel is traced and serialized. The block encoding is supplied through Qamomile’s static-binding contract at transpile time, while phase values may be compile-time bindings or backend runtime parameters when an explicit compile-time phase_count is provided.

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.

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.

qsvt [source]¶

def qsvt(
    signal: qmc.Vector[qmc.Qubit],
    system: qmc.Vector[qmc.Qubit],
    phases: qmc.Vector[qmc.Float],
    encoding: LCUBlockEncoding,
    phase_count: int | qmc.UInt | None = None,
) -> tuple[qmc.Vector[qmc.Qubit], qmc.Vector[qmc.Qubit]]

Apply quantum singular value transformation to a block encoding.

For phases = (phi_0, ..., phi_d), Qamomile applies R(phi_0), U, R(phi_1), U dagger, ..., where R(phi) = exp(i * phi * (2 Pi - I)) and Pi projects the complete signal register onto all zero. One clean internal auxiliary qubit realizes these projector rotations and is restored after every phase. At least one phase is required.

If the leading block of encoding.unitary is A / alpha, with alpha = encoding.normalization, the supplied phase sequence transforms singular values of A / alpha. Phase synthesis, polynomial parity, and approximation-domain checks are problem dependent and remain the caller’s responsibility; this helper implements the quantum sequence itself. The input values must already use the projector-rotation convention above. Raw phases produced for a different QSP signal operator or rotation convention, including pyqsp’s Wx convention, must be converted first.

By default, phase_count comes from phases.shape[0]. This is the shortest API when phases are supplied through bindings at transpile time. To compile once and retain phases as a backend runtime parameter array, pass a separate phase_count argument and bind that count at transpile time; the phase values can then be supplied when the executable runs. For a phase vector resolved through transpile-time bindings, an explicit count selects a prefix; the vector must contain at least that many values, and any remaining values are ignored. For a phase vector preserved as a runtime parameter, the executable ABI requires exactly phase_count values; shorter and longer runtime vectors are rejected. Omitting the count applies the complete compile-time vector.

The helper emits serializable IR directly into the enclosing qkernel. That qkernel may therefore be traced and serialized before either encoding or the phase values are known. Do not capture a concrete descriptor in a module global; declare an LCUBlockEncoding argument on the enclosing qkernel and bind it after deserialization. A source-backed call rejects a non-positive concrete count immediately; the equivalent invalid binding on a deserialized template is rejected as a compilation error when the empty selected phase prefix is resolved.

Parameters:

Returns:

tuple[qmc.Vector[qmc.Qubit], qmc.Vector[qmc.Qubit]] — tuple[qmc.Vector[qmc.Qubit], qmc.Vector[qmc.Qubit]]: Transformed signal and system registers.

Raises:

• TypeError — If phases is not a qmc.Vector[qmc.Float] handle, or if an explicit phase_count is a boolean or is neither an integer nor a UInt handle.

• ValueError — If a concrete count is not positive.

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 transform(
...     encoding: qmc.LCUBlockEncoding,
...     phases: qmc.Vector[qmc.Float],
... ) -> tuple[qmc.Vector[qmc.Bit], qmc.Vector[qmc.Bit]]:
...     signal = qmc.qubit_array(encoding.num_signal_qubits, "signal")
...     system = qmc.qubit_array(encoding.num_system_qubits, "system")
...     signal, system = qmc.qsvt(signal, system, phases, encoding)
...     return qmc.measure(signal), qmc.measure(system)
>>> payload = serialize(transform)
>>> received = deserialize(payload)
>>> lcu = PeriodicShiftLCU.from_coefficients(
...     {-1: 1.0, 0: -2.0, 1: 1.0},
...     register_sizes=(2,),
... )
>>> block_encoding = qmc.periodic_shift_lcu_block_encoding(lcu)
>>> executable = QiskitTranspiler().transpile(
...     received,
...     bindings={
...         "encoding": block_encoding,
...         "phases": [0.2, -0.4, 0.7],
...     },
... )

Classes¶

CallPolicy [source]¶

class CallPolicy(enum.Enum)

Describe the default lowering policy for a callable call.

Attributes¶

• INLINE

• NATIVE_FIRST

• PRESERVE_BOX