Skip to content

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

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.

phase

Applies a state-dependent phase shift 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
within_apply

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

allocate

allocate(
    num_qubits: Union[int, SymbolicExpr], out: Output[QVar]
) -> None
allocate(out: Output[QVar]) -> None
allocate(
    num_qubits: Union[int, SymbolicExpr],
    is_signed: Union[bool, SymbolicExpr],
    fraction_digits: Union[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 Type 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
  1. If the output variable has been declared with a specific number of qubits or numeric attributes, the passed values must match the declared values.
  2. 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

bind

bind(
    source: Union[Input[QVar], list[Input[QVar]]],
    destination: Union[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 Union[Input[QVar], list[Input[QVar]]]

A qubit or list of initialized qubits to reassign.

required
destination Union[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: Union[QCallable, Callable[[], Statements]]
) -> None

control

control(
    ctrl: Union[
        SymbolicExpr, QBit, QArray[QBit], list[QVar]
    ],
    stmt_block: Union[QCallable, Callable[[], Statements]],
    else_block: Union[
        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 Union[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 Union[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 Union[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: Union[SymbolicExpr, bool],
    then: Union[QCallable, Callable[[], Statements]],
    else_: Union[
        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 Union[SymbolicExpr, bool]

A symbolic or boolean expression evaluated at runtime to determine the execution path.

required
then Union[QCallable, Callable[[], Statements]]

A quantum operation executed when condition evaluates to True.

required
else_ Union[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: Union[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 Union[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))

phase

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

Applies a state-dependent phase shift to the quantum state.

This operation multiplies each basis state |x> by a complex phase factor theta * expr(x), where expr is a symbolic expression dependent on the state value x, and theta is a scalar multiplier.

Parameters:

Name Type Description Default
expr SymbolicExpr

A symbolic expression that evaluates to an angle (in radians) as a function of the quantum state value x.

required
theta float

(Optional) A scalar multiplier for the evaluated expression. Defaults to 1.0.

1.0
Note

The phase operation is equivalent to a Z-rotation up to a global phase. It is commonly used to apply relative phase shifts conditioned on the quantum state.

power

power(
    exponent: Union[SymbolicExpr, int],
    stmt_block: Union[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 Union[SymbolicExpr, int]

The exponent value, either as an integer or a symbolic expression.

required
stmt_block Union[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)))

repeat

repeat(
    count: Union[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 Union[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: Union[float, SymbolicExpr],
    upper_bound: Union[float, SymbolicExpr],
) -> None
reset_bounds(
    target_var: QNum,
    lower_bound: Optional[
        Union[float, SymbolicExpr]
    ] = None,
    upper_bound: Optional[
        Union[float, SymbolicExpr]
    ] = None,
) -> None

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.