uniqc.algorithmics.state_preparation.thermal_state module#

Thermal state (Boltzmann distribution) preparation.

uniqc.algorithmics.state_preparation.thermal_state.thermal_state(circuit, beta, hamiltonian=None, qubits=None)[source]#

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().

Parameters:

  • 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.

Raises:

ValueError – beta is negative or hamiltonian shape is wrong.

Return type:

None

Example

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