Validation Framework

Overview

The validation framework provides comprehensive testing utilities for verifying the correctness of GENERIC decomposition computations. This infrastructure is used throughout all implementation phases to ensure numerical accuracy and mathematical consistency.

Components

1. Validation Utilities (qig/validation.py)

ValidationReport Class

Collects validation checks throughout a computation:

• Provides summary statistics and detailed reporting

• Identifies which checks passed and which failed

• Can print verbose or failure-only reports

Matrix Property Checks

• check_hermitian(): Verify M = M† (tol ~ 10⁻¹²)

• check_symmetric(): Verify M = Mᵀ (tol ~ 10⁻¹⁴)

• check_antisymmetric(): Verify M = -Mᵀ (tol ~ 10⁻¹⁴)

• check_traceless(): Verify Tr(M) = 0 (tol ~ 10⁻¹⁰)

Comparison Utilities

• compare_matrices(): Smart matrix comparison with multiple error norms

• Handles edge cases: NaN, Inf, near-zero values

• Reports Frobenius norm and relative error

Cross-Validation Tools

• finite_difference_jacobian(): Independent Jacobian computation

• Used to validate analytically computed Jacobians

• Central differences for accuracy

Physical Constraint Checks

• check_constraint_tangency(): Verify M @ ∇C ≈ 0

• check_entropy_monotonicity(): Verify θᵀMθ ≤ 0

• check_positive_semidefinite(): Verify all eigenvalues ≥ 0

2. Reference Data (qig/reference_data.py)

SU(2) Structure Constants

• 3 generators (Pauli matrices)

• Completely antisymmetric: f_abc = ε_ijk

• Verified: Antisymmetry 0.00e+00, Jacobi 0.00e+00

SU(3) Structure Constants

• 8 generators (Gell-Mann matrices)

• Reference: Gell-Mann (1962), Particle Data Group

• Verified: Antisymmetry 0.00e+00, Jacobi 1.11e-16

Verification Functions

• verify_structure_constant_properties(): Check antisymmetry and Jacobi identity

• get_reference_structure_constants(): Access by algebra name

3. Test Suite (tests/test_validation.py)

32 comprehensive tests covering:

• ValidationReport functionality (4 tests)

• Matrix comparison (5 tests)

• Matrix properties (7 tests)

• Finite differences (2 tests)

• Physical constraints (5 tests)

• Reference data (9 tests)

All tests passing ✓ (0.49s runtime)

Usage Examples

Basic Validation Report

from qig.validation import ValidationReport, check_hermitian

# Create report
report = ValidationReport("Hamiltonian Validation")

# Check properties
passed, error = check_hermitian(H_eff, tol=1e-12)
report.add_check("Hermiticity", passed, error, 1e-12)

passed, error = check_traceless(H_eff, tol=1e-10)
report.add_check("Traceless", passed, error, 1e-10)

# Print results
report.print_summary()

# Check if all passed
if not report.all_passed():
    failures = report.get_failures()
    for fail in failures:
        print(f"FAILED: {fail}")

Cross-Validation

from qig.validation import compare_matrices, finite_difference_jacobian

# Compute Jacobian analytically
J_analytic = exp_fam.jacobian(theta)

# Compute Jacobian numerically
flow = lambda th: exp_fam.flow_vector(th)
J_numeric = finite_difference_jacobian(flow, theta, eps=1e-5)

# Compare
passed, error, msg = compare_matrices(
    J_analytic, J_numeric, tol=1e-5,
    name="Jacobian cross-validation"
)
print(f"Cross-validation: {error:.2e} (tol: 1e-5)")

Using Reference Data

from qig.reference_data import get_reference_structure_constants

# Load reference structure constants
f_ref = get_reference_structure_constants("su3")

# Compare computed vs reference
passed, error, msg = compare_matrices(
    f_computed, f_ref, tol=1e-10,
    name="Structure constants"
)

Tolerance Hierarchy

Different quantities have different expected tolerances:

Check	Tolerance	Reason
Symmetry (S = Sᵀ)	~10⁻¹⁴	Machine precision
Hermiticity (H = H†)	~10⁻¹²	Direct computation
Tracelessness	~10⁻¹⁰	Numerical accumulation
Structure constants	~10⁻¹⁰	Reference comparison
Jacobi identity	~10⁻⁸	Triple sum
Commutator matching	~10⁻⁶	Transformation error
Finite difference	~10⁻⁵	FD approximation

Phase 0 Completion Status

✅ All Phase 0 Completion Criteria Met:

• ☑ All validation utilities implemented and tested (32 tests passing)

• ☑ ValidationReport class produces readable output

• ☑ Reference data for SU(2) verified (antisymmetry 0.00e+00, Jacobi 0.00e+00)

• ☑ Reference data for SU(3) verified (antisymmetry 0.00e+00, Jacobi 1.11e-16)

• ☑ All comparison functions handle edge cases (NaN, Inf tested)

• ☑ Documentation complete (this document)

Gate to Phase 1: OPEN ✓

The validation infrastructure is ready for use in all subsequent phases of the GENERIC decomposition implementation.

References

1. Gell-Mann, M. (1962). “Symmetries of Baryons and Mesons”. Physical Review.

2. Particle Data Group. Review of Particle Physics (structure constants tables).

3. CIP-0006: GENERIC Decomposition for Lie-Algebraic Bases (implementation plan).

API Reference

See API Reference for detailed API documentation of validation utilities.