qpandalite.algorithmics.state_preparation package#

Submodules#

qpandalite.algorithmics.state_preparation.basis_state module#

Computational basis-state preparation.

qpandalite.algorithmics.state_preparation.basis_state.basis_state(circuit, state, qubits=None)[源代码]

Prepare a computational basis state |state> on the given qubits.

Applies X gates to the qubits whose corresponding bit in the binary representation of state is 1. All other qubits are left in |0>.

参数:

  • circuit (Circuit) -- Quantum circuit to operate on (mutated in-place).

  • state (int) -- Non-negative integer whose binary representation specifies the target basis state. Qubit 0 corresponds to the least-significant bit.

  • qubits (List[int] | None) -- Qubit indices to use. None means list(range(n_bits)) where n_bits is the number of bits needed.

抛出:

ValueError -- state is negative.

返回类型:

None

示例

>>> from qpandalite.circuit_builder import Circuit
>>> from qpandalite.algorithmics.state_preparation import basis_state
>>> c = Circuit()
>>> basis_state(c, state=5, qubits=[0, 1, 2])  # ``|101>``

qpandalite.algorithmics.state_preparation.dicke_state module#

Dicke state preparation.

Prepares the symmetric Dicke state |D(n,k)> — the equal superposition of all n-qubit basis states with exactly k excitations (ones).

qpandalite.algorithmics.state_preparation.dicke_state.dicke_state(circuit, qubits=None, k=1)[源代码]

Prepare the symmetric Dicke state |D(n,k)>.

The Dicke state is the equal superposition of all weight-k computational basis states on n qubits:

\[\begin{split}|D(n,k)\\rangle = \\frac{1}{\\sqrt{\\binom{n}{k}}} \\sum_{\\substack{x \\in \\{0,1\\}^n \\\\ |x|=k}} |x\\rangle\end{split}\]

The target state vector is constructed directly and prepared using rotation_prepare().

参数:

  • circuit (Circuit) -- Quantum circuit (mutated in-place).

  • qubits (List[int] | None) -- Qubit indices to use. None → all circuit qubits.

  • k (int) -- Number of excitations (0 ≤ k ≤ n).

抛出:

ValueError -- k is negative or exceeds the number of qubits.

返回类型:

None

示例

>>> from qpandalite.circuit_builder import Circuit
>>> from qpandalite.algorithmics.state_preparation import dicke_state
>>> c = Circuit()
>>> dicke_state(c, qubits=[0, 1, 2], k=1)  # ``|D(3,1)>``

qpandalite.algorithmics.state_preparation.hadamard_superposition module#

Hadamard superposition preparation.

Creates a uniform superposition over the specified qubits.

qpandalite.algorithmics.state_preparation.hadamard_superposition.hadamard_superposition(circuit, qubits=None)[源代码]

Create a uniform Hadamard superposition on the given qubits.

Applies an H gate to every qubit in qubits, transforming |0...0> into an equal superposition of all 2^n basis states:

\[|0\rangle^{\otimes n} \xrightarrow{H^{\otimes n}} \frac{1}{\sqrt{2^n}} \sum_{k=0}^{2^n-1} |k\rangle\]
参数:

  • circuit (Circuit) -- Quantum circuit to operate on (mutated in-place).

  • qubits (List[int] | None) -- Qubit indices to apply H to. None means all qubits (list(range(circuit.max_qubit + 1))).

返回类型:

None

示例

>>> from qpandalite.circuit_builder import Circuit
>>> from qpandalite.algorithmics.state_preparation import hadamard_superposition
>>> c = Circuit()
>>> c.allocate_qubits(3)
[0, 1, 2]
>>> hadamard_superposition(c)       # (|0>+|1>)/√2 ⊗ 3

qpandalite.algorithmics.state_preparation.rotation_prepare module#

Arbitrary state preparation via rotation method.

Uses the Shende–Bullock–Markov (SBM) decomposition: disentangles qubits one at a time, then reverses the gate sequence.

qpandalite.algorithmics.state_preparation.rotation_prepare.rotation_prepare(circuit, target_vector, qubits=None)[源代码]

Prepare an arbitrary quantum state from a complex amplitude vector.

Uses the Shende–Bullock–Markov state-preparation algorithm. The method works by computing the circuit that would disentangle the target state back to |00...0>, collecting the gates, then applying them in reverse order.

Gate count: O(2^n) for n qubits.

The vector is automatically normalised.

参数:

  • circuit (Circuit) -- Quantum circuit to operate on (mutated in-place).

  • target_vector (ndarray) -- 1-D complex array of length 2**n specifying the target state amplitudes.

  • qubits (List[int] | None) -- Qubit indices to use. None → first n qubits.

抛出:

  • ValueError -- target_vector length is not a power of 2.

  • ValueError -- target_vector is the zero vector.

返回类型:

None

示例

>>> import numpy as np
>>> from qpandalite.circuit_builder import Circuit
>>> from qpandalite.algorithmics.state_preparation import rotation_prepare
>>> target = np.array([1, 0, 0, 1]) / np.sqrt(2)  # Bell state
>>> c = Circuit()
>>> rotation_prepare(c, target)

qpandalite.algorithmics.state_preparation.thermal_state module#

Thermal state (Boltzmann distribution) preparation.

qpandalite.algorithmics.state_preparation.thermal_state.thermal_state(circuit, beta, hamiltonian=None, qubits=None)[源代码]

Prepare a thermal (Gibbs) state for a given inverse temperature β.

For the default Hamiltonian H = Σ Z_i, each qubit independently receives a Ry(θ) gate where θ = 2·arccos(√p₀) with p₀ = e^β/(e^β + e^{-β}).

For a custom Hamiltonian, the function diagonalises H, computes Boltzmann weights, and uses rotation_prepare().

参数:

  • circuit (Circuit) -- Quantum circuit (mutated in-place).

  • beta (float) -- Inverse temperature. 0 → maximally mixed; ∞ → ground state.

  • hamiltonian (ndarray | None) -- 2^n × 2^n Hermitian matrix, or None for H = Σ Z_i.

  • qubits (List[int] | None) -- Qubit indices. None → all circuit qubits.

抛出:

ValueError -- beta is negative or hamiltonian shape is wrong.

返回类型:

None

示例

>>> from qpandalite.circuit_builder import Circuit
>>> from qpandalite.algorithmics.state_preparation import thermal_state
>>> c = Circuit()
>>> thermal_state(c, beta=1.0, qubits=[0])

Module contents#

State preparation module — routines to initialise quantum registers into specific quantum states.

qpandalite.algorithmics.state_preparation.basis_state(circuit, state, qubits=None)[源代码]

Prepare a computational basis state |state> on the given qubits.

Applies X gates to the qubits whose corresponding bit in the binary representation of state is 1. All other qubits are left in |0>.

参数:

  • circuit (Circuit) -- Quantum circuit to operate on (mutated in-place).

  • state (int) -- Non-negative integer whose binary representation specifies the target basis state. Qubit 0 corresponds to the least-significant bit.

  • qubits (List[int] | None) -- Qubit indices to use. None means list(range(n_bits)) where n_bits is the number of bits needed.

抛出:

ValueError -- state is negative.

返回类型:

None

示例

>>> from qpandalite.circuit_builder import Circuit
>>> from qpandalite.algorithmics.state_preparation import basis_state
>>> c = Circuit()
>>> basis_state(c, state=5, qubits=[0, 1, 2])  # ``|101>``
qpandalite.algorithmics.state_preparation.dicke_state(circuit, qubits=None, k=1)[源代码]

Prepare the symmetric Dicke state |D(n,k)>.

The Dicke state is the equal superposition of all weight-k computational basis states on n qubits:

\[\begin{split}|D(n,k)\\rangle = \\frac{1}{\\sqrt{\\binom{n}{k}}} \\sum_{\\substack{x \\in \\{0,1\\}^n \\\\ |x|=k}} |x\\rangle\end{split}\]

The target state vector is constructed directly and prepared using rotation_prepare().

参数:

  • circuit (Circuit) -- Quantum circuit (mutated in-place).

  • qubits (List[int] | None) -- Qubit indices to use. None → all circuit qubits.

  • k (int) -- Number of excitations (0 ≤ k ≤ n).

抛出:

ValueError -- k is negative or exceeds the number of qubits.

返回类型:

None

示例

>>> from qpandalite.circuit_builder import Circuit
>>> from qpandalite.algorithmics.state_preparation import dicke_state
>>> c = Circuit()
>>> dicke_state(c, qubits=[0, 1, 2], k=1)  # ``|D(3,1)>``
qpandalite.algorithmics.state_preparation.hadamard_superposition(circuit, qubits=None)[源代码]

Create a uniform Hadamard superposition on the given qubits.

Applies an H gate to every qubit in qubits, transforming |0...0> into an equal superposition of all 2^n basis states:

\[|0\rangle^{\otimes n} \xrightarrow{H^{\otimes n}} \frac{1}{\sqrt{2^n}} \sum_{k=0}^{2^n-1} |k\rangle\]
参数:

  • circuit (Circuit) -- Quantum circuit to operate on (mutated in-place).

  • qubits (List[int] | None) -- Qubit indices to apply H to. None means all qubits (list(range(circuit.max_qubit + 1))).

返回类型:

None

示例

>>> from qpandalite.circuit_builder import Circuit
>>> from qpandalite.algorithmics.state_preparation import hadamard_superposition
>>> c = Circuit()
>>> c.allocate_qubits(3)
[0, 1, 2]
>>> hadamard_superposition(c)       # (|0>+|1>)/√2 ⊗ 3
qpandalite.algorithmics.state_preparation.rotation_prepare(circuit, target_vector, qubits=None)[源代码]

Prepare an arbitrary quantum state from a complex amplitude vector.

Uses the Shende–Bullock–Markov state-preparation algorithm. The method works by computing the circuit that would disentangle the target state back to |00...0>, collecting the gates, then applying them in reverse order.

Gate count: O(2^n) for n qubits.

The vector is automatically normalised.

参数:

  • circuit (Circuit) -- Quantum circuit to operate on (mutated in-place).

  • target_vector (ndarray) -- 1-D complex array of length 2**n specifying the target state amplitudes.

  • qubits (List[int] | None) -- Qubit indices to use. None → first n qubits.

抛出:

  • ValueError -- target_vector length is not a power of 2.

  • ValueError -- target_vector is the zero vector.

返回类型:

None

示例

>>> import numpy as np
>>> from qpandalite.circuit_builder import Circuit
>>> from qpandalite.algorithmics.state_preparation import rotation_prepare
>>> target = np.array([1, 0, 0, 1]) / np.sqrt(2)  # Bell state
>>> c = Circuit()
>>> rotation_prepare(c, target)
qpandalite.algorithmics.state_preparation.thermal_state(circuit, beta, hamiltonian=None, qubits=None)[源代码]

Prepare a thermal (Gibbs) state for a given inverse temperature β.

For the default Hamiltonian H = Σ Z_i, each qubit independently receives a Ry(θ) gate where θ = 2·arccos(√p₀) with p₀ = e^β/(e^β + e^{-β}).

For a custom Hamiltonian, the function diagonalises H, computes Boltzmann weights, and uses rotation_prepare().

参数:

  • circuit (Circuit) -- Quantum circuit (mutated in-place).

  • beta (float) -- Inverse temperature. 0 → maximally mixed; ∞ → ground state.

  • hamiltonian (ndarray | None) -- 2^n × 2^n Hermitian matrix, or None for H = Σ Z_i.

  • qubits (List[int] | None) -- Qubit indices. None → all circuit qubits.

抛出:

ValueError -- beta is negative or hamiltonian shape is wrong.

返回类型:

None

示例

>>> from qpandalite.circuit_builder import Circuit
>>> from qpandalite.algorithmics.state_preparation import thermal_state
>>> c = Circuit()
>>> thermal_state(c, beta=1.0, qubits=[0])