qrisp.QuantumVariable.init_state

QuantumVariable.init_state(params, method='auto')

Initialize an arbitrary quantum state on this quantum variable.

This method can be used in two ways:

1. Dictionary input

A dictionary of the form {value: amplitude} describing the (possibly non-normalized) wavefunction in the logical basis of the quantum variable. Any value not explicitly provided is assigned amplitude zero.

2. Explicit statevector input

A flat vector of complex amplitudes of length \(2^{n}\), where \(n\) is the size (in qubits) of the quantum variable. The vector is automatically normalized.

In both cases, the initialization algorithm requires all underlying qubits to be in the \(\ket{0}\) state (i.e. fresh).

The parameter method determines the backend used for state preparation:

• "auto" (default): Use the Qiskit-based initializer when not in Jasp mode, and fall back to the internal qswitch initializer during Jasp mode.

• "qiskit": Force the Qiskit state-preparation circuit. This cannot be used in Jasp mode.

• "qswitch": Use the state-preparation implementation based on qswitch, which is compatible with Jasp mode.

Parameters:

paramsdict or array-like

Either a dictionary {value: amplitude} or a length \(2^{n}\) complex statevector.

method{“auto”, “qiskit”, “qswitch”}, optional

Choice of state-preparation backend. Defaults to "auto".

Raises:

ValueError

If a statevector of incorrect length is provided.

ValueError

If the supplied statevector has zero norm.

ValueError

If the qubits are not fresh prior to initialization.

ValueError

If method="qiskit" is used in Jasp mode.

Note

When executing in Jasp mode, Python-based shape and normalization checks are disabled to avoid introducing tracing side effects.

Note

When using an array-like input, the ordering of amplitudes should correspond to the one retrieved with the statevector method.

Examples

Dictionary input

We create a QuantumFloat and encode the state

\[\ket{\psi} = \sqrt{\tfrac{1}{3}}\,\ket{0.5} + i\sqrt{\tfrac{2}{3}}\,\ket{2.0}\]

>>> from qrisp import QuantumFloat
>>> qf = QuantumFloat(3, -1)
>>> qf.init_state({0.5: (1/3)**0.5, 2.0: 1j*(2/3)**0.5})

or equivalently:

>>> qf[:] = {0.5: (1/3)**0.5, 2.0: 1j*(2/3)**0.5}

Explicit statevector input

>>> import numpy as np
>>> psi = np.zeros(2**3, dtype=complex)
>>> psi[4] = (1/3)**0.5
>>> psi[1] = 1j*(2/3)**0.5
>>> qf.init_state(psi)

Forcing a backend

We can also explicitly choose the state-preparation backend:

>>> qf.init_state(psi, method="qswitch")   # Always allowed
>>> qf.init_state(psi, method="qiskit")    # Only outside Jasp mode

After initialization, the amplitudes can be inspected via:

>>> sv_function = qf.qs.statevector("function")
>>> sv_function({qf: 2.0})
0.8164965809277261j  # i * sqrt(2/3)