qig.generic

GENERIC Decomposition Components

This module provides functions for extracting effective Hamiltonian and diffusion operators from the GENERIC decomposition of quantum inaccessible game dynamics.

The GENERIC (General Equation for Non-Equilibrium Reversible-Irreversible Coupling) framework decomposes dynamics into:

Reversible (Hamiltonian) part: \(-i[H_{\text{eff}}, \rho]\)
Irreversible (dissipative) part: \(\mathcal{D}[\rho]\)

Effective Hamiltonian Extraction

qig.generic.effective_hamiltonian_coefficients(A, theta, f_abc, regularization=1e-10)[source]

Extract effective Hamiltonian coefficients from antisymmetric flow.

Solves for η such that the adjoint-action formula holds approximately:

(A⋅θ)_r  ≈  Σ_{b,c} f_{rbc} θ_b η_c  =  (F⋅η)_r

where F[r, c] = Σ_b f[r, b, c] θ_b is the adjoint action of θ on the basis, and f_abc are the structure constants defined by [F_a, F_b] = i Σ_c f_{abc} F_c.

The extracted Hamiltonian is:

H_eff = Σ_c η_c F_c

BCH approximation — known limitation (see CIP-0009): The formula (A⋅θ)_r = (F⋅η)_r holds only in the limit θ → 0. For finite θ the Kubo-Mori kernel K_ρ (which defines ∂ρ/∂θ and thus A) differs from a pure commutator by the operator-ordered BCH integral structure, contributing an irreducible residual of order O(‖θ‖²).

Because F is built from adjoint-action contractions, it is also typically rank-deficient for small θ (the system has a three-dimensional null space for the n_pairs=1, d=2 system), so the system F⋅η = v is inconsistent: v = A⋅θ has a non-zero component outside col(F) of magnitude ~0.1·‖θ‖². No choice of η can reduce the residual below this floor.

Parameters:

A (np.ndarray, shape (n, n)) – Antisymmetric part of flow Jacobian.
theta (np.ndarray, shape (n,)) – Natural parameters.
f_abc (np.ndarray, shape (n, n, n)) – Structure constants; f_abc[a, b, c] = f_{abc}.
regularization (float) – Tikhonov regularisation added to F^T F when the condition number of F exceeds 1e12.

Return type:

Tuple[ndarray, dict]

Returns:

eta (np.ndarray, shape (n,)) – Coefficients of effective Hamiltonian.
diagnostics (dict) –
- 'condition_number': condition number of F.
- 'residual': ‖F⋅η − v‖; bounded below by the BCH residual ~0.1·‖θ‖² and above by the regularisation error.
- 'method': 'linear_solver'.
- 'regularization': value used.

Notes

The extracted H_eff is always Hermitian and traceless regardless of the residual magnitude — those properties follow from the operator basis, not from the accuracy of the formula.

qig.generic.effective_hamiltonian_coefficients_lstsq(A, theta, operators, rho)[source]

Extract effective Hamiltonian coefficients using least-squares fitting.

This provides an alternative method (Method B) that directly minimizes the difference between the commutator evolution and the antisymmetric flow.

Minimizes: ||i[H_eff, ρ] - ρ_dot_reversible||

where ρ_dot_reversible is the density matrix flow from the antisymmetric part.

Parameters:

A (np.ndarray, shape (n, n)) – Antisymmetric part of flow Jacobian
theta (np.ndarray, shape (n,)) – Natural parameters
operators (List[np.ndarray]) – List of operator basis {F_a}
rho (np.ndarray) – Density matrix at current state

Return type:

Tuple[ndarray, dict]

Returns:

eta (np.ndarray, shape (n,)) – Coefficients of effective Hamiltonian
diagnostics (dict) – Diagnostic information: - ‘residual’: Final residual - ‘success’: Whether optimization succeeded - ‘method’: ‘least_squares’

Notes

Method B: Least-squares fitting approach

This method provides cross-validation for Method A (linear solver). They should agree within tolerance (~1e-6) if the GENERIC structure is correctly implemented.

qig.generic.effective_hamiltonian_operator(eta, operators)[source]

Construct effective Hamiltonian operator from coefficients.

H_eff = Σ_a η_a F_a

Parameters:

eta (np.ndarray, shape (n,)) – Hamiltonian coefficients
operators (List[np.ndarray]) – Operator basis {F_a}

Returns:

H_eff – Effective Hamiltonian operator

Return type:

np.ndarray

Notes

The effective Hamiltonian should be: - Hermitian: H_eff = H_eff† - Traceless: Tr(H_eff) ≈ 0 (for Lie algebra generators)

These properties should be verified after construction.

qig.generic.cross_validate_hamiltonian_coefficients(A, theta, f_abc, operators, rho, tol=1e-06)[source]

Cross-validate Hamiltonian coefficients between two methods.

Compares: - Method A: Linear solver (structure constants) - Method B: Least-squares fitting (direct optimization)

Parameters:

A (np.ndarray) – Antisymmetric part
theta (np.ndarray) – Natural parameters
f_abc (np.ndarray) – Structure constants
operators (List[np.ndarray]) – Operator basis
rho (np.ndarray) – Density matrix
tol (float) – Tolerance for agreement

Returns:

report – Cross-validation report

Return type:

ValidationReport

Diffusion Operator Construction

qig.generic.kubo_mori_derivatives(theta, operators, exp_fam)[source]

Compute Kubo-Mori derivatives ∂ρ/∂θ_a for all parameters.

The Kubo-Mori derivative is:: ∂ρ/∂θ_a = ∫_0^1 ρ^s F_a ρ^{1-s} ds

where ρ = exp(K - ψ) and K = Σ θ_b F_b.

This uses the Duhamel formula from qig.duhamel for high precision.

Parameters:

theta (np.ndarray) – Natural parameters
operators (List[np.ndarray]) – Operator basis {F_a}
exp_fam (MatrixExponentialFamily) – Exponential family instance (for using duhamel method)

Returns:

drho_dtheta – List of ∂ρ/∂θ_a matrices, one for each parameter

Return type:

List[np.ndarray]

Notes

The Kubo-Mori derivative is the “quantum derivative” that maintains Hermiticity and provides the correct mapping from parameter space to density matrix space.

For machine precision, we use the Duhamel integral from qig.duhamel.

qig.generic.diffusion_operator(S, theta, exp_fam, method='duhamel')[source]

Construct diffusion operator D[ρ] from symmetric flow.

The diffusion operator generates the irreversible (dissipative) dynamics:: D[ρ] = Σ_a (S⋅q)_a ∂ρ/∂θ_a

where S is the symmetric part, q are mean parameters (tangent to constraint), and ∂ρ/∂θ_a are Kubo-Mori derivatives.

Parameters:

S (np.ndarray, shape (n, n)) – Symmetric part of flow Jacobian
theta (np.ndarray, shape (n,)) – Natural parameters
exp_fam (MatrixExponentialFamily) – Exponential family instance
method (str) – Method for computing Kubo-Mori derivatives

Returns:

D_rho – Diffusion operator D[ρ] acting on density matrix

Return type:

np.ndarray

Notes

The dissipative flow is:: ρ̇_dissipative = D[ρ]

Key properties that should be verified: - D[ρ] is Hermitian - Tr(D[ρ]) = 0 (trace preservation) - Entropy production: -Tr(ρ log ρ D[ρ]) ≥ 0

The flow is in the tangent space to the constraint manifold, so we need the mean parameters q = ∇ψ.

qig.generic.milburn_approximation(H_eff, rho, gamma=1.0)[source]

Compute Milburn approximation to diffusion operator.

Near equilibrium, the diffusion operator can be approximated as:: D[ρ] ≈ -γ/2 [H_eff, [H_eff, ρ]]

where γ is an effective decoherence rate.

Parameters:

H_eff (np.ndarray) – Effective Hamiltonian
rho (np.ndarray) – Density matrix
gamma (float) – Decoherence rate (typically ~ 1)

Returns:

D_rho_milburn – Milburn approximation to D[ρ]

Return type:

np.ndarray

Notes

This is a useful approximation near equilibrium and provides a simple form for comparison with the full Kubo-Mori construction.

The double commutator -[H, [H, ρ]] is a standard form in quantum master equations (Lindblad form with H as the Lindblad operator).

For comparison with the full diffusion operator: - Near equilibrium: Should agree within ~10^-4 - Far from equilibrium: May differ significantly

Examples

Extracting Effective Hamiltonian

import numpy as np
from qig.exponential_family import MatrixExponentialFamily
from qig.structure_constants import compute_structure_constants
from qig.generic import effective_hamiltonian_coefficients, effective_hamiltonian_operator

# Initialize system
exp_fam = MatrixExponentialFamily(n_pairs=1, d=2, pair_basis=True)
theta = 0.1 * np.random.randn(exp_fam.n_params)

# Compute structure constants
f_abc = compute_structure_constants(exp_fam.operators)

# Get antisymmetric part of Jacobian
A = exp_fam.antisymmetric_part(theta)

# Extract Hamiltonian coefficients
eta, info = effective_hamiltonian_coefficients(A, theta, f_abc)

# Construct Hamiltonian operator
H_eff = effective_hamiltonian_operator(eta, exp_fam.operators)

print(f"Effective Hamiltonian: {H_eff.shape}")
print(f"Hermitian: {np.allclose(H_eff, H_eff.conj().T)}")

Computing Diffusion Operator

from qig.generic import diffusion_operator

# Get symmetric part of Jacobian
S = exp_fam.symmetric_part(theta)

# Compute diffusion operator (expensive!)
D_rho = diffusion_operator(S, theta, exp_fam, method='duhamel')

print(f"Diffusion operator: {D_rho.shape}")
print(f"Hermitian: {np.allclose(D_rho, D_rho.conj().T)}")
print(f"Traceless: {abs(np.trace(D_rho)) < 1e-10}")

qig.generic

GENERIC Decomposition Components

Effective Hamiltonian Extraction

Diffusion Operator Construction

Examples

Extracting Effective Hamiltonian

Computing Diffusion Operator

See Also