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:
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 |
required | |
fraction_digits
|
The number of fraction digits in the allocated variable, valid only for |
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 |
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 |
required |
Notes
- After this operation,
source
qubits are unbound and considered uninitialized. source
anddestination
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 |
required |
stmt_block
|
Union[QCallable, Callable[[], Statements]]
|
The quantum operations to execute when the condition holds. This can be a |
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 |
required |
else_
|
Union[QCallable, Callable[[], Statements], int]
|
(Optional) A quantum operation executed when |
_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 |
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 |
required |
apply
|
Callable[[], Statements]
|
The operation |
required |
For more details, see Qmod Reference.