uniqc.algorithms.core.circuits.thermal_state module

Thermal state preparation circuit fragment.

uniqc.algorithms.core.circuits.thermal_state.thermal_state_circuit(first_arg=None, beta=1.0, qubits=None)

Build (or apply) a thermal-state preparation fragment for \(H=\sum_i Z_i\).

Two calling conventions:

# Fragment style (recommended):
c = thermal_state_circuit(3, beta=1.0)         # returns Circuit

# Legacy in-place style (deprecated):
c = Circuit(3)
thermal_state_circuit(c, beta=1.0)             # mutates c in place

Each qubit is prepared in \(\sqrt{p_0}|0\rangle + \sqrt{p_1}|1\rangle\) with \(p_0 = e^\beta / (e^\beta + e^{-\beta})\).

Parameters:

• first_arg – Either n_qubits: int (fragment) or circuit: Circuit (deprecated).

• beta (float) – Inverse temperature (must be non-negative).

• qubits (list[int] | None) – Qubit indices to use.

Returns:

Fresh Circuit in fragment mode; None in legacy mode.

Return type:

Circuit | None

uniqc.algorithms.core.circuits.thermal_state.thermal_state_example()

Return a 3-qubit thermal-state circuit at \(\beta=1\) for tests/docs.

Return type:

Circuit