Validation Module

Validation utilities for the quantum inaccessible game GENERIC decomposition.

This module provides tools for validating computational results throughout the GENERIC decomposition procedure, including: - Matrix property checks (Hermiticity, symmetry, tracelessness) - Cross-validation between different computational methods - Comparison against reference data - Comprehensive validation reporting

These utilities are used throughout all implementation phases to ensure correctness and numerical stability.

class qig.validation.ValidationCheck(name, passed, value, tolerance, message='')[source]

Bases: object

Represents a single validation check with its result.

Parameters:

name (str)
passed (bool)
value (float)
tolerance (float)
message (str)

name

Name of the validation check

Type:: str

passed

Whether the check passed

Type:: bool

value

Measured value (e.g., error norm)

Type:: float

tolerance

Tolerance threshold

Type:: float

message

Detailed message about the check

Type:: str

name: str

passed: bool

value: float

tolerance: float

message: str = ''

__init__(name, passed, value, tolerance, message='')

Parameters:

name (str)
passed (bool)
value (float)
tolerance (float)
message (str)

Return type:

None

class qig.validation.ValidationReport(title)[source]

Bases: object

Collects and reports validation results for a computation.

This class accumulates validation checks throughout a computation and provides methods to display results, identify failures, and generate summary statistics.

Examples

>>> report = ValidationReport("Structure Constants")
>>> report.add_check("Antisymmetry", error < tol, error, tol)
>>> report.add_check("Jacobi identity", violation < tol, violation, tol)
>>> report.print_summary()
>>> if not report.all_passed():
...     print(report.get_failures())

Parameters:: title (str)

__init__(title)[source]

Initialize validation report.

Parameters:: title (str) – Title for this validation report

checks: List[ValidationCheck]

add_check(name, passed, value, tolerance, message='')[source]

Add a validation check to the report.

Parameters:

name (str) – Name of the check
passed (bool) – Whether the check passed
value (float) – Measured value
tolerance (float) – Tolerance threshold
message (str, optional) – Additional message

all_passed()[source]

Check if all validation checks passed.

Return type:: bool

get_failures()[source]

Get list of failed checks.

Return type:: List[ValidationCheck]

get_passes()[source]

Get list of passed checks.

Return type:: List[ValidationCheck]

print_summary(verbose=True)[source]

Print summary of validation results.

Parameters:: verbose (bool) – If True, print all checks. If False, only print failures.

qig.validation.compare_matrices(A, B, tol, name='Matrix comparison')[source]

Compare two matrices with detailed diagnostics.

Computes various error norms and provides diagnostic information about differences between matrices.

Parameters:

A (np.ndarray) – First matrix
B (np.ndarray) – Second matrix
tol (float) – Tolerance threshold
name (str) – Name for this comparison

Return type:

Tuple[bool, float, str]

Returns:

passed (bool) – Whether comparison passed (max error < tol)
error (float) – Maximum absolute error
message (str) – Diagnostic message

qig.validation.check_hermitian(M, tol=1e-12)[source]

Check if a matrix is Hermitian (M = M†).

Parameters:

M (np.ndarray) – Matrix to check
tol (float) – Tolerance for Hermiticity

Return type:

Tuple[bool, float]

Returns:

passed (bool) – Whether matrix is Hermitian within tolerance
error (float) – ||M - M†||_max

qig.validation.check_symmetric(M, tol=1e-14)[source]

Check if a matrix is symmetric (M = M^T).

Parameters:

M (np.ndarray) – Matrix to check
tol (float) – Tolerance for symmetry

Return type:

Tuple[bool, float]

Returns:

passed (bool) – Whether matrix is symmetric within tolerance
error (float) – ||M - M^T||_max

qig.validation.check_antisymmetric(M, tol=1e-14)[source]

Check if a matrix is antisymmetric (M = -M^T).

Parameters:

M (np.ndarray) – Matrix to check
tol (float) – Tolerance for antisymmetry

Return type:

Tuple[bool, float]

Returns:

passed (bool) – Whether matrix is antisymmetric within tolerance
error (float) – ||M + M^T||_max

qig.validation.check_traceless(M, tol=1e-10)[source]

Check if a matrix is traceless (Tr(M) = 0).

Parameters:

M (np.ndarray) – Matrix to check
tol (float) – Tolerance for tracelessness

Return type:

Tuple[bool, float]

Returns:

passed (bool) – Whether matrix is traceless within tolerance
error (float) – |Tr(M)|

qig.validation.check_commutator(A, B, operators, f_abc, tol=1e-08)[source]

Verify commutator relation [A, B] = 2i Σ_c f_abc F_c.

Parameters:

A (np.ndarray) – First operator (index a)
B (np.ndarray) – Second operator (index b)
operators (List[np.ndarray]) – List of basis operators {F_c}
f_abc (np.ndarray, shape (n, n, n)) – Structure constants
tol (float) – Tolerance for commutator verification

Return type:

Tuple[bool, float, str]

Returns:

passed (bool) – Whether commutator relation holds
error (float) – Maximum error in reconstruction
message (str) – Diagnostic message

qig.validation.finite_difference_jacobian(func, x, eps=1e-05)[source]

Compute Jacobian using finite differences.

This provides an independent validation method for analytically computed Jacobians.

Parameters:

func (Callable) – Function mapping R^n -> R^m
x (np.ndarray, shape (n,)) – Point at which to compute Jacobian
eps (float) – Finite difference step size

Returns:

J – Jacobian matrix approximation

Return type:

np.ndarray, shape (m, n)

Notes

Uses central differences: f’(x) ≈ (f(x+h) - f(x-h))/(2h)

qig.validation.check_constraint_tangency(M, constraint_gradient, tol=1e-06)[source]

Check if flow is tangent to constraint manifold.

Verifies that M @ a ≈ 0 where a = ∇C is the constraint gradient.

Parameters:

M (np.ndarray) – Flow Jacobian
constraint_gradient (np.ndarray) – Gradient of constraint C
tol (float) – Tolerance for tangency

Return type:

Tuple[bool, float]

Returns:

passed (bool) – Whether flow is tangent within tolerance
error (float) – ||M @ a||

qig.validation.check_entropy_monotonicity(M, theta, tol=1e-12)[source]

Check if flow decreases entropy (or stays constant).

Verifies that θ^T M θ ≤ 0 (with small tolerance for numerical error).

Parameters:

M (np.ndarray) – Flow Jacobian
theta (np.ndarray) – Natural parameters
tol (float) – Tolerance for non-positivity (allows small numerical error)

Return type:

Tuple[bool, float]

Returns:

passed (bool) – Whether entropy is non-increasing
value (float) – θ^T M θ (should be ≤ 0)

qig.validation.check_positive_semidefinite(M, tol=1e-14)[source]

Check if a matrix is positive semidefinite.

Parameters:

M (np.ndarray) – Matrix to check
tol (float) – Tolerance for negative eigenvalues

Return type:

Tuple[bool, float]

Returns:

passed (bool) – Whether all eigenvalues are non-negative (within tolerance)
min_eigenvalue (float) – Smallest eigenvalue

See Validation Framework for detailed usage examples and the complete validation framework documentation.