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.

The antisymmetric part A encodes the reversible (Hamiltonian) dynamics through the relation:

A_ab θ_b = Σ_c f_abc η_c

where η_c are the coefficients of the effective Hamiltonian:

H_eff = Σ_c η_c F_c

This function solves the linear system F⋅η = v, where:

F_rc = Σ_b f_rbc θ_b
v_r = (A⋅θ)_r
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

  • regularization (float) – Regularization parameter for nearly singular systems

Return type:

Tuple[ndarray, dict]

Returns:

  • eta (np.ndarray, shape (n,)) – Coefficients of effective Hamiltonian

  • diagnostics (dict) – Diagnostic information: - ‘condition_number’: Condition number of F matrix - ‘residual’: ||F⋅η - v|| - ‘method’: ‘linear_solver’

Notes

Method A: Direct linear solver approach

The structure constants f_abc appear in the matrix F that relates the Hamiltonian coefficients to the antisymmetric flow.

For nearly singular systems (near degeneracies), regularization helps stabilize the solution.

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 (QuantumExponentialFamily) – 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 (QuantumExponentialFamily) – 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 QuantumExponentialFamily
from qig.structure_constants import compute_structure_constants
from qig.generic import effective_hamiltonian_coefficients, effective_hamiltonian_operator

# Initialize system
exp_fam = QuantumExponentialFamily(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}")

See Also