Density-matrix input models and Gibbs states

oracq.algorithms.input_model.density

Density matrix (DM) input model and Gibbs state preparation.

The core abstraction of the DM input model is purification access: access to a density matrix ρ is defined as a quantum operation U that prepares its purified state, U |0> = |ψ_ρ⟩ acting on the two registers system and environment, with the partial trace over the environment giving Tr_env |ψ⟩⟨ψ| = ρ. This module provides three paradigm layers: abstract_purification open declarations, gate_purification explicit small-matrix witnesses (eigendecomposition followed by preparation via multiplexed rotations), and the PurificationAccess.from_state_preparation pure state adapter (a pure state is the trivial purification with the environment restored to zero). This view is the stable interface relied on by B2 (quantum SDP).

Gibbs state preparation follows the QSVT purification route (Chowdhury–Somma 2017, van Apeldoorn–Gilyén 2019, Gilyén et al. 2019, arXiv:1806.01838): first prepare the purification of the maximally mixed state on system and environment (n Bell pairs), then apply to system a QSVT block encoding whose zero-signal block is proportional to g(H/α), where g(x) = exp(−βα(x+1)/2) takes values in (0,1] on [−1,1]. g decomposes by parity into the two branches e^{−c}·cosh(cx) and −e^{−c}·sinh(cx) (c = βα/2), each approximated by a modified Bessel truncation, with phases synthesized via imaginary completion, the real part extracted by (U_Φ + U_{−Φ})/2, and the branches finally summed by LCU. After post-selecting signal == 0, the reduced density matrix of system is proportional to g(H/α)² = e^{−βH} (up to normalization).

class oracq.algorithms.input_model.density.ApproximatePurification(operation)

Bases: OracleView

Post-selected approximate purification: on the signal == 0 branch, system and environment carry the approximate purified state.

It differs from PurificationAccess by having a signal register and a controllable approximation error; algorithm parameters (such as beta and error for Gibbs preparation) are stored in module attributes and read via attributes.

oracle_kind = 'approximate_purification'

operation

approximate_purification()

Structured protocol accessor for approximate purification, returning self.

A host object implementing a method of the same name returning ApproximatePurification can be adapted by protocol, isomorphic to accessors such as state_preparation and block_encoding.

Returns:

This view itself.

Return type:

ApproximatePurification

property width

Bit width of the system register, per the RIR register signature.

property environment_width

Bit width of the environment register, per the RIR register signature.

property signal_qubits

Bit width of the signal register; post-selection requires its readout to be all zeros.

property attributes

Copy of the module attribute dictionary; stores algorithm parameters such as beta and error.

property beta

Inverse temperature β read from the module attributes; None when not recorded.

property error

Polynomial uniform approximation error parameter read from the module attributes; None when not recorded.

describe()

Return the OracleSpec snapshot with type approximate_purification.

The system width is recorded in main_qubit, and the sum of the environment and signal widths in anc_qubit.

Returns:

The snapshot, with type approximate_purification.

Return type:

OracleSpec

class oracq.algorithms.input_model.density.PurificationAccess(operation)

Bases: OracleView

Purification access view of a density matrix: prepares |ψ_ρ⟩ with Tr_env |ψ⟩⟨ψ| = ρ.

The operation starts from the all-zero state and prepares the purification of ρ on the two registers system and environment; the environment width is at least the bits needed by the rank of system (taking it equal to the system width is usually fine).

oracle_kind = 'purification_access'

operation

purification_access()

Structured protocol accessor for purification access, returning self.

A host object implementing a method of the same name returning PurificationAccess can be adapted by protocol, isomorphic to accessors such as state_preparation and block_encoding.

Returns:

This view itself.

Return type:

PurificationAccess

property width

Bit width of the system register, per the RIR register signature.

property environment_width

Bit width of the environment register, per the RIR register signature.

describe()

Return the OracleSpec snapshot with type purification_access.

The system width is recorded in main_qubit and the environment width in anc_qubit.

Returns:

The snapshot, with type purification_access.

Return type:

OracleSpec

classmethod from_state_preparation(preparation)

A pure state is the trivial purification: adapt a work-restored StatePreparation into PurificationAccess.

The work register plays the role of environment; the preparation contract promises that work is restored to zero, so after tracing out the environment the state on system is still the original pure state.

Parameters:

preparation – Pure state preparation view with work restored to zero; when the work width is greater than 0, the clean_work promise is required.

Returns:

The trivial purification view whose environment is the original work register.

Return type:

PurificationAccess

as_state_preparation()

Treat the purification operation as a whole as a StatePreparation on system⊕environment (for B2 composition).

Returns:

Preparation view whose target state is the purified state and whose work width is 0.

Return type:

StatePreparation

oracq.algorithms.input_model.density.abstract_purification(name, width, environment_width=None, *, reversible=True)

Open declaration of the DM input model: a purification access slot preparing |ψ_ρ⟩, for batched binding.

environment_width defaults to width (every density matrix has a purification with an equal-width environment); the declaration is closed by binding a witness implementation such as gate_purification via linking.bind.

Parameters:

• name – Slot name, referenced when binding a witness implementation via linking.bind.

• width – Bit width of the system register, range 1..63.

• environment_width – Bit width of the environment register, range 0..63; defaults to width.

• reversible – Whether the declaration slot also promises adjoint and controlled capabilities.

Returns:

The open declaration slot awaiting a witness implementation.

Return type:

PurificationAccess

oracq.algorithms.input_model.density.gate_purification(rho, *, name=None)

Purification witness for an explicit small density matrix: eigendecomposition ρ = Σ_j p_j |v_j⟩⟨v_j| followed by controlled preparation.

The purified state is |ψ_ρ⟩ = Σ_j √p_j |v_j⟩_s |j⟩_e; its amplitude vector is prepared on the concatenated register of system and environment by the multiplexed rotation tree of gate_state_prep; taking the partial trace over the environment returns exactly ρ.

Parameters:

• rho – Explicit density matrix, which must be a positive semidefinite

• 16. (power-of-two square matrix of trace 1 and dimension at most)

• name – Name of the generated operation; derived from the matrix content by default.

Returns:

Purification access view implemented by the eigendecomposition witness.

Return type:

PurificationAccess

oracq.algorithms.input_model.density.gibbs_purification(hamiltonian, beta, *, error=0.01, synthesizer=None)

Approximate purification preparation of the Gibbs state ρ = e^{−βH}/Z (QSVT purification route).

hamiltonian is the BlockEncoding of H, with the convention that the spectrum lies in [−α,α] (α = be_alpha); the target function on the spectral variable x = λ/α ∈ [−1,1] is g(x) = exp(−βα(x+1)/2) ∈ (0,1]. The construction has two steps: (a) prepare n Bell pairs on system and environment (the purification |Φ⟩ of the maximally mixed state); (b) apply to system a QSVT block encoding whose zero-signal block is g(H/α)/(2s). Since the even branch e^{−c}cosh(cx) and the odd branch −e^{−c}sinh(cx) of g are both convex, the endpoint-matched imaginary completion always satisfies the unit-disk constraint (f²(x) does not exceed the chord between the endpoints), so the phase synthesis is always feasible. After post-selecting signal == 0, the state is proportional to (g(H/α) ⊗ I)``|Φ⟩``, and the reduced density matrix of system is exactly e^{−βH}/Z; the normalization factor 2s is unrelated to the partition function and does not affect the reduced state.

error controls the polynomial uniform approximation error (each branch’s truncation tail ≤ error/8); returns an ApproximatePurification whose module attributes include algorithm=”gibbs_purification”, beta, error, qsp_degree, and gibbs_scale = 2s. β = 0 degenerates to the maximally mixed purification.

Parameters:

• hamiltonian – Block encoding of H, with spectrum contained in [−α,α] (α = be_alpha).

• beta – Inverse temperature, a nonnegative finite real number; 0 degenerates to the maximally mixed purification.

• error – Polynomial uniform approximation error, with range (0,1).

• synthesizer – Optional replacement for the bundled QSP phase synthesis route; when given, the bundled route’s truncation degree cap does not apply.

Returns:

The approximate purification view whose reduced

Return type:

ApproximatePurification

state on system after post-selecting signal == 0 is e^{−βH}/Z.

oracq.algorithms.input_model.density.gibbs_state(hamiltonian, beta)

Classical reference Gibbs state e^{−βH}/Tr(e^{−βH}); used only as a classical witness for small matrices.

Parameters:

• hamiltonian – Small Hermitian matrix given as a nested sequence of complex elements.

• beta – Inverse temperature, a finite real number in the same units as the spectrum of H.

Returns:

Normalized Gibbs state matrix as a row-major nested tuple.

Return type:

tuple[tuple[complex, …], …]

oracq.algorithms.input_model.density.maximally_mixed_purification(width, *, name=None)

Purification generator of the maximally mixed state I/2^n: the tensor product of n Bell pairs |Φ+⟩.

Parameters:

• width – Bit width of each of the system and environment registers, range 1..32.

• name – Name of the generated operation; bell_purification_{width} by default.

Returns:

Purification view preparing the tensor product of n Bell pairs.

Return type:

PurificationAccess

oracq.algorithms.input_model.density.partial_trace(amplitudes, system_width, environment_width)

Take the partial trace over environment, returning the reduced density matrix on system as a row-major nested tuple.

amplitudes is the dense state vector of length 2^(system_width + environment_width), with the basis state index convention system | (environment << system_width).

Parameters:

• amplitudes – Pure state amplitude sequence satisfying the length convention above.

• system_width – Bit width of the system register, range 0..20.

• environment_width – Bit width of the environment register to be partially traced, range 0..20.

Returns:

The 2^system_width-dimensional reduced

Return type:

tuple[tuple[complex, …], …]

density matrix as a row-major nested tuple.

oracq.algorithms.input_model.density.trace_distance(rho, sigma)

Trace distance T(ρ,σ) = ‖ρ−σ‖₁/2, computed via the Hermitian eigendecomposition of the difference matrix.

Parameters:

• rho – First Hermitian matrix, usually a density matrix.

• sigma – Second Hermitian matrix, dimension must match rho.

Returns:

Trace distance, with range [0,1].

Return type:

float