Operations

This is a list of the operations that are built-in in Qmod. For more information regarding classical types see the Statements section in the language reference.

operations

Functions:

Name	Description
`allocate`	Initialize a quantum variable to a new quantum object in the zero state:
`assign`	Initialize a scalar quantum variable using an arithmetic expression.
`assign_amplitude`	Perform an amplitude-encoding assignment operation on a quantum variable and a
`assign_amplitude_poly_sin`	Encodes the value of the sine/cosine of a polynomial into the amplitude of the
`bind`	Reassign qubit or arrays of qubits by redirecting their logical identifiers.
`block`
`control`	Conditionally executes quantum operations based on the value of quantum variables or expressions.
`if_`	Conditionally executes quantum operations based on a symbolic or boolean expression.
`inplace_add`	Add an arithmetic expression to a quantum variable.
`inplace_xor`	Bitwise-XOR a quantum variable with an arithmetic expression.
`invert`	Apply the inverse of a quantum gate.
`lookup_table`	Reduces a classical function into a lookup table over all the possible values
`phase`	Applies a state-dependent or fixed phase shift (Z rotation) to the quantum state.
`power`	Apply a quantum operation raised to a symbolic or integer power.
`repeat`	Executes a quantum loop a specified number of times, applying a quantum operation on each iteration.
`reset_bounds`
`skip_control`	Applies quantum statements unconditionally.
`within_apply`	Given two operations \(U\) and \(V\), performs the sequence of operations \(U^{-1} V U\).

allocate

allocate(
    num_qubits: int | SymbolicExpr, out: Output[QVar]
) -> None

allocate(out: Output[QVar]) -> None

allocate(
    num_qubits: int | SymbolicExpr,
    is_signed: bool | SymbolicExpr,
    fraction_digits: int | SymbolicExpr,
    out: Output[QVar],
) -> None

allocate(*args: Any, **kwargs: Any) -> None

Initialize a quantum variable to a new quantum object in the zero state:

\[ \left|\text{out}\right\rangle = \left|0\right\rangle^{\otimes \text{num_qubits}} \]

If 'num_qubits' is not specified, it will be inferred according to the type of 'out'. In case the quantum variable is of type QNum, its numeric attributes can be specified as well.

Parameters:

Name	Description	Default
`num_qubits`	The number of qubits to allocate (positive integer, optional).	required
`out`	The quantum variable that will receive the allocated qubits. Must be uninitialized before allocation.	required
`is_signed`	The sign of the allocated variable, valid only for `QNum` (boolean, optional).	required
`fraction_digits`	The number of fraction digits in the allocated variable, valid only for `QNum` (positive integer, optional).	required

Notes

If the output variable has been declared with a specific number of qubits or numeric attributes, the passed values must match the declared values.
The synthesis engine automatically handles the allocation, either by drawing new qubits from the available pool or by reusing existing ones.

assign

assign(
    expression: SymbolicExpr, target_var: QScalar
) -> None

Initialize a scalar quantum variable using an arithmetic expression. If specified, the variable numeric properties (size, signedness, and fraction digits) must match the expression properties.

Equivalent to <target_var> |= <expression>.

Parameters:

Name	Type	Description	Default
`expression`	`SymbolicExpr`	A classical or quantum arithmetic expression	required
`target_var`	`QScalar`	An uninitialized scalar quantum variable	required

assign_amplitude

assign_amplitude(
    expression: SymbolicExpr, target_var: QScalar
) -> None

Perform an amplitude-encoding assignment operation on a quantum variable and a quantum expression.

Equivalent to <target_var> *= <expression>.

Parameters:

Name	Type	Description	Default
`expression`	`SymbolicExpr`	A quantum arithmetic expression	required
`target_var`	`QScalar`	A scalar quantum variable	required

assign_amplitude_poly_sin

assign_amplitude_poly_sin(
    indicator: QBit, expr: Callable, *vars: QNum
) -> None

Encodes the value of the sine/cosine of a polynomial into the amplitude of the respective computational basis state: \( |x_1, x_2, \ldots, x_n\rangle|0\rangle \rightarrow cos(poly(x_1, x_2, \ldots, x_n)) + sin(poly(x_1, x_2, \ldots, x_n))|x_1, x_2, \ldots, x_n\rangle|1\rangle \)

Parameters:

Name	Type	Description	Default
`indicator`	`QBit`	The quantum indicator qubit	required
`expr`	`Callable`	A polynomial function over `len(vars)` QNums	required
`*vars`	`QNum`	Quantum numerics	`()`

bind

bind(
    source: Input[QVar] | list[Input[QVar]],
    destination: Output[QVar] | list[Output[QVar]],
) -> None

Reassign qubit or arrays of qubits by redirecting their logical identifiers.

This operation rewires the logical identity of the source qubits to new objects given in destination. For example, an array of two qubits X can be mapped to individual qubits Y and Z.

Parameters:

Name	Type	Description	Default
`source`	`Input[QVar] \| list[Input[QVar]]`	A qubit or list of initialized qubits to reassign.	required
`destination`	`Output[QVar] \| list[Output[QVar]]`	A qubit or list of target qubits to bind to. Must match the number of qubits in `source`.	required

Notes

After this operation, source qubits are unbound and considered uninitialized.
source and destination must be of the same length.

For more details, see Qmod Reference.

block

block(
    statements: QCallable | Callable[[], Statements]
) -> None

control

control(
    ctrl: SymbolicExpr | QBit | QArray[QBit] | list[QVar],
    stmt_block: QCallable | Callable[[], Statements],
    else_block: (
        QCallable | Callable[[], Statements] | None
    ) = None,
) -> None

Conditionally executes quantum operations based on the value of quantum variables or expressions.

This operation enables quantum control flow similar to classical if statements. It evaluates a quantum condition and executes one of the provided quantum code blocks accordingly.

Parameters:

Name	Type	Description	Default
`ctrl`	`SymbolicExpr \| QBit \| QArray[QBit] \| list[QVar]`	A quantum control expression, which can be a logical expression, a single `QBit`, or a `QArray[QBit]`. If `ctrl` is a logical expression, `stmt_block` is executed when it evaluates to `True`. If `ctrl` is a `QBit` or `QArray[QBit]`, `stmt_block` is executed if all qubits are in the \|1> state.	required
`stmt_block`	`QCallable \| Callable[[], Statements]`	The quantum operations to execute when the condition holds. This can be a `QCallable` or a function returning a `Statements` block.	required
`else_block`	`QCallable \| Callable[[], Statements] \| None`	(Optional) Quantum operations to execute when the condition does not hold.	`None`

For more details, see Qmod Reference.

if_

if_(
    condition: SymbolicExpr | bool,
    then: QCallable | Callable[[], Statements],
    else_: (
        QCallable | Callable[[], Statements] | int
    ) = _MISSING_VALUE,
) -> None

Conditionally executes quantum operations based on a symbolic or boolean expression.

This function defines classical control flow within a quantum program. It allows quantum operations to be conditionally executed based on symbolic expressions - such as parameters used in variational algorithms, loop indices, or other classical variables affecting quantum control flow.

Parameters:

Name	Type	Description	Default
`condition`	`SymbolicExpr \| bool`	A symbolic or boolean expression evaluated at runtime to determine the execution path.	required
`then`	`QCallable \| Callable[[], Statements]`	A quantum operation executed when `condition` evaluates to True.	required
`else_`	`QCallable \| Callable[[], Statements] \| int`	(Optional) A quantum operation executed when `condition` evaluates to False.	`_MISSING_VALUE`

inplace_add

inplace_add(
    expression: SymbolicExpr, target_var: QScalar
) -> None

Add an arithmetic expression to a quantum variable.

Equivalent to <target_var> += <expression>.

Parameters:

Name	Type	Description	Default
`expression`	`SymbolicExpr`	A classical or quantum arithmetic expression	required
`target_var`	`QScalar`	A scalar quantum variable	required

inplace_xor

inplace_xor(
    expression: SymbolicExpr, target_var: QScalar
) -> None

Bitwise-XOR a quantum variable with an arithmetic expression.

Equivalent to <target_var> ^= <expression>.

Parameters:

Name	Type	Description	Default
`expression`	`SymbolicExpr`	A classical or quantum arithmetic expression	required
`target_var`	`QScalar`	A scalar quantum variable	required

invert

invert(
    stmt_block: QCallable | Callable[[], Statements]
) -> None

Apply the inverse of a quantum gate.

This function allows inversion of a quantum gate. It is typically used within a quantum program to invert a sequence of operations.

Parameters:

Name	Type	Description	Default
`stmt_block`	`QCallable \| Callable[[], Statements]`	A callable that produces the quantum operation to be inverted.	required

Example

from classiq import qfunc, Output, QArray, QBit, allocate, qft, invert
from classiq.qmod.symbolic import pi


@qfunc
def main(x: Output[QArray[QBit]]):
    allocate(10, x)
    invert(qft(x))

lookup_table

lookup_table(
    func: RealFunction, targets: QNum | list[QNum]
) -> list[float]

Reduces a classical function into a lookup table over all the possible values of the quantum numbers.

Parameters:

Name	Type	Description	Default
`func`	`RealFunction`	A Python function	required
`targets`	`QNum \| list[QNum]`	One or more initialized quantum numbers	required

Returns:

Type	Description
`list[float]`	The function's lookup table

Notes

The QNum arguments must have generative attributes

phase

phase(
    phase_expr: SymbolicExpr | float | None = None,
    theta: SymbolicExpr | float = 1.0,
) -> None

Applies a state-dependent or fixed phase shift (Z rotation) to the quantum state.

This operation multiplies each computational-basis state \(|x_1,x_2,\ldots,x_n\rangle\) by a complex phase factor \(\theta * \text{phase_expr}(x_1,x_2,\ldots,x_n)\), where phase_expr is a symbolic expression that contains quantum variables \(x_1,x_2,\ldots,x_n\), and theta is a scalar multiplier. If phase_expr contains no quantum variables, all states are rotated by the same fixed angle.

Parameters:

Name	Type	Description	Default
`phase_expr`	`SymbolicExpr \| float \| None`	A symbolic expression that evaluates to an angle (in radians) as a function of the state of the quantum variables occurring in it, if any, or otherwise a fixed value. Execution parameters are only allowed if no quantum variables occur in the expression.	`None`
`theta`	`SymbolicExpr \| float`	(Optional, allowed only together with quantum expressions) A scalar multiplier for the evaluated expression, optionally containing execution parameters. Defaults to 1.0.	`1.0`

Note

The phase statement is a generalization of the PHASE() atomic function, and they are equivalent when the phase_expr is a single-qubit variable.

power

power(
    exponent: SymbolicExpr | int,
    stmt_block: QCallable | Callable[[], Statements],
) -> None

Apply a quantum operation raised to a symbolic or integer power.

This function enables exponentiation of a quantum gate, where the exponent can be a symbolic expression or an integer. It is typically used within a quantum program to repeat or scale quantum operations in a parameterized way.

Parameters:

Name	Type	Description	Default
`exponent`	`SymbolicExpr \| int`	The exponent value, either as an integer or a symbolic expression.	required
`stmt_block`	`QCallable \| Callable[[], Statements]`	A callable that produces the quantum operation to be exponentiated.	required

Example

from classiq import qfunc, Output, QArray, QBit, allocate, repeat, RX, power
from classiq.qmod.symbolic import pi


@qfunc
def my_RX(x: QArray[QBit], i: CInt):
    RX(2 * pi / x.len, x[i])


@qfunc
def main(x: Output[QArray[QBit]]):
    allocate(10, x)
    repeat(x.len, lambda i: power(i, lambda: my_RX(x, i)))

qmod_statement

qmod_statement(
    func: Callable[_Params, _RetType]
) -> Callable[_Params, _RetType]

repeat

repeat(
    count: SymbolicExpr | int,
    iteration: Callable[[int], Statements],
) -> None

Executes a quantum loop a specified number of times, applying a quantum operation on each iteration.

This operation provides quantum control flow similar to a classical for loop, enabling repeated application of quantum operations based on classical loop variables.

Parameters:

Name	Type	Description	Default
`count`	`SymbolicExpr \| int`	An integer or symbolic expression specifying the number of loop iterations.	required
`iteration`	`Callable[[int], Statements]`	A callable that takes a single integer index and returns the quantum operations to be performed at each iteration.	required

Example

from classiq import qfunc, Output, QArray, QBit, allocate, repeat, RX
from classiq.qmod.symbolic import pi


@qfunc
def main(x: Output[QArray[QBit]]):
    allocate(10, x)
    repeat(x.len, lambda i: RX(2 * pi * i / x.len, x[i]))

reset_bounds

reset_bounds(target_var: QNum) -> None

reset_bounds(
    target_var: QNum,
    lower_bound: float | SymbolicExpr,
    upper_bound: float | SymbolicExpr,
) -> None

reset_bounds(
    target_var: QNum,
    lower_bound: float | SymbolicExpr | None = None,
    upper_bound: float | SymbolicExpr | None = None,
) -> None

skip_control

skip_control(
    stmt_block: QCallable | Callable[[], Statements]
) -> None

Applies quantum statements unconditionally.

Parameters:

Name	Type	Description	Default
`stmt_block`	`QCallable \| Callable[[], Statements]`	A callable that produces a quantum operation.	required

For more details, see Qmod Reference.

within_apply

within_apply(
    within: Callable[[], Statements],
    apply: Callable[[], Statements],
) -> None

Given two operations \(U\) and \(V\), performs the sequence of operations \(U^{-1} V U\).

This operation is used to represent a sequence where the inverse gate U^{-1} is applied, followed by another operation V, and then U is applied to uncompute. This pattern is common in reversible computation and quantum subroutines.

Parameters:

Name	Type	Description	Default
`within`	`Callable[[], Statements]`	The unitary operation `U` to be computed and then uncomputed.	required
`apply`	`Callable[[], Statements]`	The operation `V` to be applied within the `U` block.	required

For more details, see Qmod Reference.