Gibbs-Lock Frame

Gibbs-locked frame API for the quantum inaccessible game.

A Gibbs-locked frame is a background state K_0 = beta * H that is a fixed point of the linearised reversible dynamics: because [K_0, H] = 0 by construction, the commutator term i[delta_K, K_0] generates pure phase rotation in the eigenbasis of H without displacing K_0.

This module provides: - GibbsLockedFrame: encapsulates K_0 = beta * H with its spectral geometry. - infer_mu0: fits the uniform decay rate mu_0 from an off-diagonal trajectory.

These objects are the primary API for the analysis in:

the-inaccessible-game-hamiltonian.tex

References

  • Lawrence (2026), “Gibbs-Lock and the Emergence of Hamiltonian Structure in the Inaccessible Game”.

  • qig.core.loewner_kernel: the divided-difference kernel applied at rho0.

class qig.gibbs_lock.GibbsLockedFrame(H, beta, dims=None)[source]

Bases: object

Encapsulate a Gibbs-locked background K_0 = beta * H.

Parameters:

  • H (array, shape (D, D)) – Traceless Hermitian generator. Its eigenbasis defines the preferred spectral decomposition; Bohr gaps are eigenvalue differences of H.

  • beta (float) – Inverse temperature / coupling strength (real, nonzero).

  • dims (list of int, optional) – Subsystem dimensions for partial-trace operations (e.g. [3, 3] for a qutrit pair). Required for is_iso_marginal.

H
Type:

array

beta
Type:

float

dims
Type:

list or None

D

Hilbert-space dimension.

Type:

int

__init__(H, beta, dims=None)[source]
Parameters:
Return type:

None

property rho0: ndarray

Gibbs state rho0 = exp(-beta * H) / tr(exp(-beta * H)).

Computed via eigendecomposition for numerical stability.

bohr_gaps()[source]

Return eigenvalues of H and the matrix of Bohr gaps.

Return type:

Tuple[ndarray, ndarray]

Returns:

  • eps (array, shape (D,)) – Eigenvalues of H sorted ascending.

  • gaps (array, shape (D, D)) – gaps[i, j] = eps[i] - eps[j]. Diagonal is zero.

loewner_kernel(tol=1e-12)[source]

Loewner divided-difference kernel at rho0.

Thin wrapper around qig.core.loewner_kernel(self.rho0).

Return type:

Tuple[ndarray, ndarray, ndarray]

Returns:

  • C (array, shape (D, D)) – Kernel matrix C[i, j] = c(lambda_i, lambda_j) in the eigenbasis of rho0 (= eigenbasis of H for a Gibbs-locked frame).

  • vals (array, shape (D,)) – Eigenvalues of rho0 (ascending, clipped to >= 1e-14).

  • vecs (array, shape (D, D)) – Eigenvectors of rho0 as columns.

Parameters:

tol (float)

loewner_map(X)[source]

Apply the Loewner map J_{rho0}(X) to a matrix X.

In the eigenbasis of rho0:

(J_{rho0}(X))_{ij} = C[i, j] * X_{ij}
Parameters:

X (array, shape (D, D)) – Input matrix (same basis as H and rho0).

Returns:

JX

Return type:

array, shape (D, D)

is_iso_marginal(delta_K, tol=1e-10)[source]

True if delta_K is iso-marginal to first order.

A perturbation delta_K is iso-marginal if the induced first-order change in every marginal density matrix vanishes:

tr_{!=k}(J_{rho0}(delta_K)) approx 0   for all k.

Requires dims to be set.

Parameters:

  • delta_K (array, shape (D, D)) – Perturbation of the modular generator in the same basis as H.

  • tol (float) – Threshold for the Frobenius norm of each marginal perturbation.

Return type:

bool

linearised_flow(delta_K, mu0, t)[source]

Analytical element-wise solution of the linearised GENERIC equation.

In the eigenbasis of H the equation decouples element-by-element:

d/dt (delta_K)_{ij} = (i * beta * Delta_eps_{ij} - mu0) * (delta_K)_{ij}

with solution:

(delta_K(t))_{ij} = exp((i * beta * Delta_eps_{ij} - mu0) * t)
                      * (delta_K(0))_{ij}.
Parameters:

  • delta_K (array, shape (D, D)) – Initial perturbation in the same basis as H.

  • mu0 (float) – Uniform decay rate (>= 0).

  • t (float) – Evolution time.

Returns:

delta_K_t – Evolved perturbation at time t (in the same basis as H).

Return type:

array, shape (D, D)

gibbs_lock_residual()[source]

Return ||[K0, H]||_F as a check of the Gibbs-lock condition.

Should be zero (< 1e-12) by construction when H is the same matrix used to define K0 = beta * H.

Return type:

float

qig.gibbs_lock.infer_mu0(times, rho_trajectory, frame, tol=0.001)[source]

Estimate the uniform decay rate mu_0 from an off-diagonal trajectory.

Fits exp(-mu0 * t) to the phase-stripped magnitude of off-diagonal elements of delta_rho(t) = rho(t) - rho0, averaged over all (i,j) pairs whose magnitude at t=0 exceeds tol.

The Gibbs-lock picture predicts that each off-diagonal coherence decays as:

|delta_rho_{ij}(t)| = |delta_rho_{ij}(0)| * exp(-mu0 * t)

independently of the Bohr gap Delta_eps_{ij}, so a single exponential fit to the mean magnitude extracts mu_0.

Parameters:

  • times (array, shape (T,)) – Time points corresponding to the trajectory.

  • rho_trajectory (array, shape (T, D, D)) – Density matrices at each time step.

  • frame (GibbsLockedFrame) – The background Gibbs-locked frame defining rho0 and the eigenbasis.

  • tol (float) – Minimum |delta_rho_{ij}(0)| for a mode to be included in the fit.

Returns:

mu0 – Fitted uniform decay rate (>= 0).

Return type:

float

Raises:

  • ValueError – If no off-diagonal modes have initial magnitude above tol.

  • RuntimeError – If the exponential fit fails to converge.