Allocation

allocation

Functions:

Name	Description
`allocate`	[Qmod core-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]

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

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.

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

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:

\[ \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

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.