qig.generic_decomposition

High-Level GENERIC Decomposition Interface

This module provides a user-friendly interface for executing the complete 12-step GENERIC decomposition procedure systematically.

The GenericDecomposition class orchestrates all steps from initial state to final diagnostics, providing comprehensive results with validation checks.

Classes

class qig.generic_decomposition.GenericDecomposition(exp_fam, method='duhamel', compute_diffusion=False)[source]

Bases: object

Complete GENERIC decomposition with diagnostics.

This class orchestrates the full 12-step procedure for computing the GENERIC decomposition of quantum inaccessible game dynamics:

1. Initial state and density matrix 2-8. Information geometry (ψ, μ, G, h_i, a, ν, ∇ν, M) 9. Symmetric/antisymmetric decomposition (S, A) 10. Effective Hamiltonian extraction (η, H_eff) 11. Diffusion operator construction (D[ρ]) 12. Comprehensive diagnostics and validation

Examples

>>> exp_fam = QuantumExponentialFamily(n_pairs=1, d=2, pair_basis=True)
>>> decomp = GenericDecomposition(exp_fam)
>>> theta = np.random.randn(exp_fam.n_params) * 0.1
>>> results = decomp.compute_all(theta)
>>> decomp.print_summary()
Parameters:
__init__(exp_fam, method='duhamel', compute_diffusion=False)[source]

Initialize GENERIC decomposition.

Parameters:

  • exp_fam (QuantumExponentialFamily) – The exponential family

  • method (str, optional) – Method for derivatives: ‘duhamel’ (accurate) or ‘sld’ (fast)

  • compute_diffusion (bool, optional) – Whether to compute diffusion operator (expensive!) Default: False

compute_all(theta, verbose=False)[source]

Execute complete 12-step GENERIC decomposition.

Parameters:

  • theta (np.ndarray) – Natural parameters

  • verbose (bool) – Print progress messages

Returns:

results – Complete results with all intermediate computations

Return type:

dict

print_summary(detailed=False)[source]

Print human-readable summary of results.

Parameters:

detailed (bool) – Print detailed diagnostics

Functions

qig.generic_decomposition.run_generic_decomposition(theta, exp_fam, method='duhamel', compute_diffusion=False, verbose=True, print_summary=True)[source]

Convenience function for complete GENERIC decomposition.

Parameters:

  • theta (np.ndarray) – Natural parameters

  • exp_fam (QuantumExponentialFamily) – Exponential family

  • method (str, optional) – Derivative method: ‘duhamel’ or ‘sld’

  • compute_diffusion (bool, optional) – Whether to compute diffusion operator (expensive!)

  • verbose (bool, optional) – Print progress during computation

  • print_summary (bool, optional) – Print summary at end

Returns:

results – Complete GENERIC decomposition results

Return type:

dict

Examples

>>> exp_fam = QuantumExponentialFamily(n_pairs=1, d=2, pair_basis=True)
>>> theta = np.zeros(exp_fam.n_params)
>>> results = run_generic_decomposition(theta, exp_fam)

The 12-Step Procedure

The complete GENERIC decomposition executes these steps systematically:

  1. Initial State: Density matrix \(\rho(\theta)\) from parameters

  2. Cumulant Function: \(\psi(\theta) = \log \text{Tr}[e^{\sum_a \theta_a F_a}]\)

  3. Mean Parameters: \(\mu = \nabla\psi(\theta)\)

  4. Fisher Information: \(G(\theta)\) (BKM metric)

  5. Marginal Entropies: \(h_i\) for each subsystem

  6. Constraint Gradient: \(a = \nabla C\) where \(C = \sum_i h_i\)

  7. Lagrange Multiplier: \(\nu(\theta)\) for constraint enforcement

  8. Lagrange Multiplier Gradient: \(\nabla\nu(\theta)\)

  9. Flow Jacobian: \(M = \partial F/\partial\theta\)

  10. GENERIC Decomposition: \(M = S + A\) (symmetric + antisymmetric)

  11. Effective Hamiltonian: \(H_{\text{eff}} = \sum_a \eta_a F_a\) from \(A\)

  12. Diffusion Operator: \(\mathcal{D}[\rho]\) from \(S\) (optional)

  13. Diagnostics: Comprehensive validation of all properties

Examples

Basic Usage

import numpy as np
from qig.exponential_family import QuantumExponentialFamily
from qig.generic_decomposition import run_generic_decomposition

# Initialize 2-qubit system
exp_fam = QuantumExponentialFamily(n_pairs=1, d=2, pair_basis=True)

# Choose state near LME origin
theta = 0.1 * np.random.randn(exp_fam.n_params)

# Run complete decomposition
results = run_generic_decomposition(
    theta, exp_fam,
    compute_diffusion=False,  # Skip expensive D[ρ] computation
    verbose=True,              # Print progress
    print_summary=True         # Show results summary
)

# Access results
print(f"Effective Hamiltonian: {results['H_eff']}")
print(f"All checks passed: {results['diagnostics']['all_checks_pass']}")

Using the Class Directly

from qig.generic_decomposition import GenericDecomposition

# Create decomposition object
decomp = GenericDecomposition(
    exp_fam,
    method='duhamel',          # High-precision derivatives
    compute_diffusion=False
)

# Execute all steps
results = decomp.compute_all(theta, verbose=False)

# Print summary
decomp.print_summary(detailed=True)

# Access specific results
H_eff = results['H_eff']
S = results['S']
A = results['A']
diagnostics = results['diagnostics']

Diagnostics and Validation

The diagnostics include automatic validation of all mathematical properties:

# Check which properties pass
checks = results['diagnostics']['checks']

for property_name, passed in checks.items():
    status = "✓" if passed else "✗"
    print(f"{status} {property_name}")

# Get detailed error metrics
diag = results['diagnostics']
print(f"S symmetry error: {diag['S_symmetry_error']:.2e}")
print(f"H_eff Hermiticity error: {diag['H_eff_hermiticity_error']:.2e}")
print(f"Degeneracy condition (S): {diag['degeneracy_S_condition']:.2e}")

See Also