qolumbina.utils.state_initialization module

qolumbina.utils.state_initialization module#

Input-state preparation circuit builders.

This module contains two independent preparation helpers:

  • PureStateInitialization builds circuits for pure input states, either from a single-qubit gate list or from a state-vector amplitude list.

  • MixedStateInitialization builds purification circuits for separable computational-basis mixed inputs by appending control/environment qubits.

Both helpers expose the generated preparation circuit through qc, so the caller can compose a tested circuit manually without running the full execution framework.

class InitStateType(value)[source]#

Bases: Enum

Supported encodings for pure-state initialization input.

GATE_LIST = 1#
STATE_VECTOR = 2#
class MixedStateInitialization(system_qubit_count, target_qubits='all', mixed_state_angles=None, predefined_clbit_count=None)[source]#

Bases: object

Build a separable mixed-state preparation circuit.

MixedStateInitialization creates a purification circuit for separable computational-basis mixed inputs. It appends one control/environment qubit per target system qubit. For one target qubit, the reduced state after tracing out the control qubit is \(\rho = \cos^2(\theta / 2)\lvert 0\rangle\langle 0\rvert + \sin^2(\theta / 2)\lvert 1\rangle\langle 1\rvert\), where theta is the matching entry in mixed_state_angles.

The generated circuit is available as qc. System qubits keep indices 0..system_qubit_count-1. Control qubits are appended after the maximum system-qubit index, so they occupy system_qubit_count..num_total_qubits-1.

Example

Build only the mixed-state preparation circuit and then compose a tested circuit manually:

init = MixedStateInitialization(
    system_qubit_count=3,
    target_qubits=[0, 2],
    mixed_state_angles=[theta_0, theta_2],
)

tested_qc = QuantumCircuit(3)
tested_qc.cx(0, 1)

qc = init.qc.copy()
qc.compose(tested_qc, qubits=range(init.num_system_qubits), inplace=True)
Parameters:

  • system_qubit_count (int) – Number of system qubits in the circuit under test. System qubits keep their original indices 0..n-1.

  • target_qubits (Literal['all'] | list[int]) – System qubits whose reduced input states are prepared as mixed states. If "all" and mixed_state_angles is None, all system qubits are targeted. If "all" and angles are provided, the targets default to low-index system qubits [0, 1, ..., m - 1] where m is the number of angles.

  • mixed_state_angles (list[float] | None) – Optional Ry angles for the appended control qubits. If None, each target uses pi / 2.

  • predefined_clbit_count (int | None) – Number of classical bits to allocate in the preparation circuit. If None, no classical bits are allocated.

qc#

The generated preparation circuit.

target_qubits#

Resolved target system-qubit indices.

control_qubits#

Appended control/environment qubit indices.

control_angles#

Resolved Ry angles, one per control qubit.

num_system_qubits#

Number of system qubits.

num_control_qubits#

Number of appended control qubits.

num_total_qubits#

Total number of qubits in qc.

class PureStateInitialization(init_state, init_qubits='all', predefined_qubit_count=None, predefined_clbit_count=None)[source]#

Bases: object

Build a pure-state preparation circuit.

PureStateInitialization creates a QuantumCircuit containing only input-state preparation operations. Callers can execute it directly or compose another circuit onto it. The resulting circuit is available as qc.

init_state supports two encodings:

  • Gate-list encoding, for example ["x", "i", "h"]. Each string is a non-parameterized single-qubit gate applied to the corresponding target.

  • State-vector encoding, for example [0, 0, 0, 1] for \(\lvert 11\rangle\).

Create a pure-state preparation circuit.

Parameters:

  • init_state (list[str] | list[float] | list[complex]) – Pure-state description. A list[str] is treated as a gate list; a numeric list is treated as a state vector.

  • init_qubits (Literal['all'] | list[int]) – Target qubits for the preparation. Use "all" to infer the circuit width from init_state. Use list[int] to prepare only selected qubits in a larger circuit.

  • predefined_qubit_count (int | None) – Total qubit count for the generated circuit. Required when init_qubits is a list. Ignored with a warning if init_qubits="all" and the count disagrees with init_state.

  • predefined_clbit_count (int | None) – Number of classical bits in the generated circuit. If None, it defaults to the total qubit count.

Raises:

  • ValueError – If gate-list length, state-vector dimension, or qubit count constraints are violated.

  • TypeError – If init_state or init_qubits has an unsupported type.

APPLY = {InitStateType.GATE_LIST: <function PureStateInitialization.<lambda>>, InitStateType.STATE_VECTOR: <function PureStateInitialization.<lambda>>}#
SINGLE_QUBIT_GATE_MAP = {'h': <function PureStateInitialization.<lambda>>, 'i': <function PureStateInitialization.<lambda>>, 's': <function PureStateInitialization.<lambda>>, 'sdg': <function PureStateInitialization.<lambda>>, 't': <function PureStateInitialization.<lambda>>, 'tdg': <function PureStateInitialization.<lambda>>, 'x': <function PureStateInitialization.<lambda>>, 'y': <function PureStateInitialization.<lambda>>, 'z': <function PureStateInitialization.<lambda>>}#
infer_init_state_type(init_state)[source]#

Infer how a pure initial state is encoded.

Supported types:

  • list[str]: single-qubit gate list, such as ["x", "i"].

  • list[int | float | complex]: state-vector amplitudes.

Parameters:

init_state (list) – User-provided pure-state initialization data.

Returns:

The inferred encoding type.

Raises:

  • TypeError – If init_state is not a list or contains unsupported element types.

  • ValueError – If init_state is an empty list.

Return type:

InitStateType

Contents