Skip to content

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:

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

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
  1. If the output variable has been declared with a specific number of qubits, the number of qubits allocated must match the declared number.
  2. 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:

\[ \left|\text{out}\right\rangle = \sum_{i=0}^{\text{len(probabilities)}-1} \sqrt{\text{probabilities}[i]} \left|i\right\rangle \]

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
  1. 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.
  2. 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:

\[ \left|\text{out}\right\rangle = \sum_{i=0}^{\text{len(amplitudes)}-1} \text{amplitudes}[i] \left|i\right\rangle \]

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
  1. 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.
  2. 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:

\[ \left|\text{q}\right\rangle = \frac{1}{\sqrt{m}}\sum_{i=0}^{m-1}{|i\rangle} \]

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
  1. If the output variable has been declared with a specific number of qubits, it must match the number of allocated qubits.
  2. 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:

\[ \left|\text{q}\right\rangle = \frac{1}{\sqrt{\text{end} - \text{start}}}\sum_{i=\text{start}}^{\text{end}-1}{|i\rangle} \]

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
  1. If the output variable has been declared with a specific number of qubits, it must match the number of allocated qubits.
  2. 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:

\[ P(n) = \frac{1}{Z} e^{- \text{rate} \cdot n} \]

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:

\[ \left|\Phi^+\right\rangle = \frac{1}{\sqrt{2}} \left( \left| 00 \right\rangle + \left| 11 \right\rangle \right) \]

If state_num = 1 the function prepares the Bell state:

\[ \left|\Phi^-\right\rangle = \frac{1}{\sqrt{2}} \left( \left| 00 \right\rangle - \left| 11 \right\rangle \right) \]

If state_num = 2 the function prepares the Bell state:

\[ \left|\Psi^+\right\rangle = \frac{1}{\sqrt{2}} \left( \left| 01 \right\rangle + \left| 10 \right\rangle \right) \]

If state_num = 3 the function prepares the Bell state:

\[ \left|\Psi^-\right\rangle = \frac{1}{\sqrt{2}} \left( \left| 01 \right\rangle - \left| 10 \right\rangle \right) \]
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"],
            Literal[False],
            Literal[0],
        ]
    ],
) -> 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'], Literal[False], Literal[0]]]

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.