State preparation
state_preparation
Functions:
Name | Description |
---|---|
allocate |
[Qmod core-library function] |
allocate_num |
[Qmod Classiq-library function] |
free |
[Qmod core-library function] |
prepare_state |
[Qmod core-library function] |
prepare_amplitudes |
[Qmod core-library function] |
inplace_prepare_state |
[Qmod core-library function] |
inplace_prepare_amplitudes |
[Qmod core-library function] |
prepare_uniform_trimmed_state |
[Qmod Classiq-library function] |
prepare_uniform_interval_state |
[Qmod Classiq-library function] |
prepare_ghz_state |
[Qmod Classiq-library function] |
prepare_exponential_state |
[Qmod Classiq-library function] |
prepare_bell_state |
[Qmod Classiq-library function] |
inplace_prepare_int |
[Qmod Classiq-library function] |
prepare_int |
[Qmod Classiq-library function] |
allocate
allocate(
num_qubits: CInt,
out: Output[QArray[QBit, Literal["num_qubits"]]],
) -> None
[Qmod core-library function]
Allocates the specified number of qubits to a given quantum variable and initializes them in the zero state:
Parameters:
Name | Type | Description | Default |
---|---|---|---|
num_qubits
|
CInt
|
The number of qubits to allocate. Must be a positive integer. |
required |
out
|
Output[QArray[QBit, Literal['num_qubits']]]
|
The quantum variable that will receive the allocated qubits. Must be uninitialized before allocation. |
required |
Notes
- If the output variable has been declared with a specific number of qubits, the number of qubits allocated must match the declared number.
- The synthesis engine automatically handles the allocation, either by drawing new qubits from the available pool or by reusing existing ones.
allocate_num
allocate_num(
num_qubits: CInt,
is_signed: CBool,
fraction_digits: CInt,
out: Output[
QNum[
Literal["num_qubits"],
Literal["is_signed"],
Literal["fraction_digits"],
]
],
) -> None
[Qmod Classiq-library function]
Initializes a quantum number with the given number of qubits, sign, and fractional digits.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
num_qubits
|
CInt
|
The number of qubits to allocate. |
required |
is_signed
|
CBool
|
Whether the number is signed or unsigned. |
required |
fraction_digits
|
CInt
|
The number of fractional digits. |
required |
free
free(in_: Input[QArray[QBit]]) -> None
[Qmod core-library function]
Releases the qubits allocated to a quantum variable, allowing them to be reused.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
in_
|
Input[QArray[QBit]]
|
The quantum variable that will be freed. Must be initialized before. |
required |
Note
This operation does not uncompute the qubits. It is the responsibility of the user to ensure that the qubits are at the zero state before freeing them.
prepare_state
prepare_state(
probabilities: CArray[CReal],
bound: CReal,
out: Output[
QArray[
QBit,
Literal[
"log(get_field(probabilities, 'len'), 2)"
],
]
],
) -> None
[Qmod core-library function]
Initializes a quantum variable in a state corresponding to a given probability distribution:
with \(i = 0, 1, 2, ..., \text{len(amplitudes)}-1\) corresponding to computational basis states.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
probabilities
|
CArray[CReal]
|
The probability distribution to initialize the quantum variable. Must be a valid probability distribution, i.e., a list of non-negative real numbers that sum to 1. Must have a valid length (a power of 2). |
required |
bound
|
CReal
|
An error bound, expressed as the \(L^{2}\) norm between the expected and actual distributions. A larger bound can reduce the circuit size at the expense of accuracy. Must be a positive real number. |
required |
out
|
Output[QArray[QBit, Literal["log(get_field(probabilities, 'len'), 2)"]]]
|
The quantum variable that will receive the initialized state. Must be uninitialized. |
required |
Notes
- If the output variable has been declared with a specific number of qubits, the number of qubits formed by the distribution must match the declared number.
- The synthesis engine automatically handles the allocation, either by drawing new qubits from the available pool or by reusing existing ones.
prepare_amplitudes
prepare_amplitudes(
amplitudes: CArray[CReal],
bound: CReal,
out: Output[
QArray[
QBit,
Literal["log(get_field(amplitudes, 'len'), 2)"],
]
],
) -> None
[Qmod core-library function]
Initializes a quantum variable in a state corresponding to the given amplitudes:
with \(i = 0, 1, 2, ..., \text{len(amplitudes)}-1\) corresponding to computational basis states.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
amplitudes
|
CArray[CReal]
|
The amplitudes to initialize the quantum variable. Must be a valid real quantum state vector, i.e., the sum of squares should be 1. Must have a valid length (a power of 2). |
required |
bound
|
CReal
|
An error bound, expressed as the \(L^{2}\) norm between the expected and actual distributions. A larger bound can reduce the circuit size at the expense of accuracy. Must be a positive real number. |
required |
out
|
Output[QArray[QBit, Literal["log(get_field(amplitudes, 'len'), 2)"]]]
|
The quantum variable that will receive the initialized state. Must be uninitialized. |
required |
Notes
- If the output variable has been declared with a specific number of qubits, the number of qubits formed by the distribution must match the declared number.
- The synthesis engine automatically handles the allocation, either by drawing new qubits from the available pool or by reusing existing ones.
inplace_prepare_state
inplace_prepare_state(
probabilities: CArray[CReal],
bound: CReal,
target: QArray[
QBit,
Literal["log(get_field(probabilities, 'len'), 2)"],
],
) -> None
[Qmod core-library function]
Transforms a given quantum variable in the state |0> to the state per the specified probability distribution
(similar to prepare_state
but preformed on an initialized variable).
Parameters:
Name | Type | Description | Default |
---|---|---|---|
probabilities
|
CArray[CReal]
|
The probability distribution corresponding to the quantum variable state. Must be a valid probability distribution, i.e., a list of non-negative real numbers that sum to 1. Must have a valid length (a power of 2). |
required |
bound
|
CReal
|
An error bound, expressed as the \(L^{2}\) norm between the expected and actual distributions. A larger bound can reduce the circuit size at the expense of accuracy. Must be a positive real number. |
required |
target
|
QArray[QBit, Literal["log(get_field(probabilities, 'len'), 2)"]]
|
The quantum variable to act upon. |
required |
This is useful as part of quantum building blocks like the Grover diffuser operator, \(\left|\psi\right\rangle\left\langle\psi\right| \left( 2\left|0\right\rangle\left\langle0\right| - \mathcal{I} \right)\), where the output state of the oracle is reflected about this state.
inplace_prepare_amplitudes
inplace_prepare_amplitudes(
amplitudes: CArray[CReal],
bound: CReal,
target: QArray[
QBit,
Literal["log(get_field(amplitudes, 'len'), 2)"],
],
) -> None
[Qmod core-library function]
Transforms a given quantum variable in the state |0> to the state per the specified amplitudes
(similar to prepare_amplitudes
but preformed on an initialized variable).
Parameters:
Name | Type | Description | Default |
---|---|---|---|
amplitudes
|
CArray[CReal]
|
The amplitudes to initialize the quantum variable. Must be a valid real quantum state vector, i.e., the sum of squares should be 1. Must have a valid length (a power of 2). |
required |
bound
|
CReal
|
An error bound, expressed as the \(L^{2}\) norm between the expected and actual distributions. A larger bound can reduce the circuit size at the expense of accuracy. Must be a positive real number. |
required |
target
|
QArray[QBit, Literal["log(get_field(amplitudes, 'len'), 2)"]]
|
The quantum variable to act upon. |
required |
This is useful as part of quantum building blocks like the Grover diffuser operator, \(\left|\psi\right\rangle\left\langle\psi\right| \left( 2\left|0\right\rangle\left\langle0\right| - \mathcal{I} \right)\), where the output state of the oracle is reflected about this state.
prepare_uniform_trimmed_state
prepare_uniform_trimmed_state(
m: CInt, q: QArray[QBit]
) -> None
[Qmod Classiq-library function]
Initializes a quantum variable in a uniform superposition of the first m
computational basis states:
The number of allocated qubits would be \(\left\lceil\log_2{m}\right\rceil\).
The function is especially useful when m
is not a power of 2.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
m
|
CInt
|
The number of states to load in the superposition. |
required |
q
|
QArray[QBit]
|
The quantum variable that will receive the initialized state. Must be uninitialized. |
required |
Notes
- If the output variable has been declared with a specific number of qubits, it must match the number of allocated qubits.
- The synthesis engine automatically handles the allocation, either by drawing new qubits from the available pool or by reusing existing ones.
prepare_uniform_interval_state
prepare_uniform_interval_state(
start: CInt, end: CInt, q: QArray[QBit]
) -> None
[Qmod Classiq-library function]
Initializes a quantum variable in a uniform superposition of the specified interval in the computational basis states:
The number of allocated qubits would be \(\left\lceil\log_2{\left(\text{end}\right)}\right\rceil\).
Parameters:
Name | Type | Description | Default |
---|---|---|---|
start
|
CInt
|
The lower bound of the interval to load (inclusive). |
required |
end
|
CInt
|
The upper bound of the interval to load (exclusive). |
required |
q
|
QArray[QBit]
|
The quantum variable that will receive the initialized state. Must be uninitialized. |
required |
Notes
- If the output variable has been declared with a specific number of qubits, it must match the number of allocated qubits.
- The synthesis engine automatically handles the allocation, either by drawing new qubits from the available pool or by reusing existing ones.
prepare_ghz_state
prepare_ghz_state(
size: CInt, q: Output[QArray[QBit]]
) -> None
[Qmod Classiq-library function]
Initializes a quantum variable in a Greenberger-Horne-Zeilinger (GHZ) state. i.e., a balanced superposition of all ones and all zeros, on an arbitrary number of qubits..
Parameters:
Name | Type | Description | Default |
---|---|---|---|
size
|
CInt
|
The number of qubits in the GHZ state. Must be a positive integer. |
required |
q
|
Output[QArray[QBit]]
|
The quantum variable that will receive the initialized state. Must be uninitialized. |
required |
Notes
The synthesis engine automatically handles the allocation, either by drawing new qubits from the available pool or by reusing existing ones.
prepare_exponential_state
prepare_exponential_state(
rate: CInt, q: QArray[QBit]
) -> None
[Qmod Classiq-library function]
Prepares a quantum state with exponentially decreasing amplitudes. The state is prepared in the computational basis, with the amplitudes of the states decreasing exponentially with the index of the state:
Parameters:
Name | Type | Description | Default |
---|---|---|---|
rate
|
CInt
|
The rate of the exponential decay. |
required |
q
|
QArray[QBit]
|
The quantum register to prepare. |
required |
prepare_bell_state
prepare_bell_state(
state_num: CInt, q: Output[QArray[QBit, Literal[2]]]
) -> None
[Qmod Classiq-library function]
Initializes a quantum array of size 2 in one of the four Bell states.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
state_num
|
CInt
|
The number of the Bell state to be prepared. Must be an integer between 0 and 3. |
required |
q
|
Output[QArray[QBit, Literal[2]]]
|
The quantum variable that will receive the initialized state. Must be uninitialized. |
required |
Bell States
The four Bell states are defined as follows (each state correlates to an integer between 0 and 3 as defined by the state_num
argument):
If state_num
= 0 the function prepares the Bell state:
If state_num
= 1 the function prepares the Bell state:
If state_num
= 2 the function prepares the Bell state:
If state_num
= 3 the function prepares the Bell state:
Notes
The synthesis engine automatically handles the allocation, either by drawing new qubits from the available pool or by reusing existing ones.
inplace_prepare_int
inplace_prepare_int(
value: CInt, target: QArray[QBit]
) -> None
[Qmod Classiq-library function]
Transitions a quantum variable in the zero state \(|0\rangle\) into the computational basis state \(|\text{value}\rangle\). In the general case, the function performs a bitwise-XOR, i.e. transitions the state \(|\psi\rangle\) into \(|\psi \oplus \text{value}\rangle\).
Parameters:
Name | Type | Description | Default |
---|---|---|---|
value
|
CInt
|
The value to assign to the quantum variable. |
required |
target
|
QArray[QBit]
|
The quantum variable to act upon. |
required |
Note
If the value cannot fit into the quantum variable, it is truncated, i.e. treated as the value modulo \(2^\text{target.size}\).
prepare_int
prepare_int(
value: CInt,
out: Output[QNum[Literal["floor(log(value, 2)) + 1"]]],
) -> None
[Qmod Classiq-library function]
Initializes a quantum variable to the computational basis state \(|\text{value}\rangle\). The number of allocated qubits is automatically computed from the value, and is the minimal number required for representation in the computational basis.
Parameters:
Name | Type | Description | Default |
---|---|---|---|
value
|
CInt
|
The value to assign to the quantum variable. |
required |
out
|
Output[QNum[Literal['floor(log(value, 2)) + 1']]]
|
The allocated quantum variable. Must be uninitialized. |
required |
Note
If the output variable has been declared with a specific number of qubits, it must match the number of allocated qubits.