Gradient harness tests

Cross-cutting gradient and differentiability checks for the diffpes forward pipeline.

Validate the shared gradient harness against external analytic truths.

Extended Summary

Exercises scale-aware finite differences, JAX’s complex-to-real convention, complex-step differentiation, and planted wrong and zero gradients. These self-tests establish gates 01.G3 and 01.G4 before physics code relies on the shared harness.

class tests.test_diffpes.test_gradients_harness.TestGradientHarness(*args, **kwargs) → None

Bases: TestCase

Validate the shared gradient harness and gates 01.G3 and 01.G4.

Covers analytic real and complex derivatives, scale-aware steps, planted tangent defects, zero-gradient tripwires, and complex-step restrictions.

See:

assert_grad_matches_fd()

See:

assert_nonzero_grad()

See:

central_fd_grad()

See:

complex_step_derivative()

See:

fd_step()

See:

gradient_gate()

test_closed_form_truths() → None

Verify analytic smooth gradients pass at relative tolerance 1e-6.

The shared gate must accept closed-form derivatives across smooth and stiff regimes and across parameter scales from 1e-3 to 5.

Notes

The test checks sine, a Gaussian sum, and the two-dimensional Rosenbrock function. It also checks a mixed-unit rational monomial. Each check uses both autodiff modes and elementwise finite differences for gate 01.G3.

Return type:

None

test_fd_step_scales_per_element() → None

Verify finite-difference steps scale with each parameter magnitude.

The step policy must retain numerical resolution for small parameters without applying one global perturbation to mixed-unit inputs.

Notes

The test compares a mixed-unit vector against the exact eps**(1/3) * max(abs(theta), 1e-3) prescription (01.G3).

Return type:

None

test_wirtinger_convention() → None

Pin JAX’s C-to-R gradient as d/dRe minus i times d/dIm.

The finite-difference harness must reproduce JAX’s complex gradient convention for a real-valued modulus-squared loss.

Notes

The test checks the exact gradient 2-2j at 1+1j. It also checks generic asymmetric complex data at relative tolerance 1e-8 for gate 01.G3.

Return type:

None

test_planted_wrong_gradient() → None

Verify a ten-percent tangent defect fails every tolerance rung.

No configured smooth, stiff, or singular tolerance may accept the deliberately corrupted derivative of an otherwise correct primal.

Notes

A custom_jvp retains the correct sine primal. It scales the derivative by 1.1. The shared gate must raise for gate 01.G4.

Return type:

None

test_detection_floor() → None

Verify a one-part-in-100000 defect fails the smooth tolerance.

The strict smooth regime must detect an error at its sensitivity floor. The forward values remain exact.

Notes

The test uses a planted 1.00001*cos(x) tangent and demands detection at the strictest 1e-6 relative rung, documenting gate 01.G4’s floor.

Return type:

None

test_planted_zero_gradient() → None

Verify finite-but-zero stopped gradients fail both tripwires.

A finite primal and finite automatic derivative are insufficient when the physical loss retains nonzero finite-difference sensitivity.

Notes

The primal remains sum(x**2) while stop_gradient removes all autodiff sensitivity. Finite differences and the independent norm check must each raise for gate 01.G4.

Return type:

None

test_in_tree_zero_gradient() → None

Verify the known heuristic photon-energy dead gradient is caught.

The nonzero-gradient gate must expose the constant interpolation plateau in the heuristic cross-section path at 30 eV.

Notes

The test differentiates the sum of heuristic orbital weights at 30 eV. The piecewise lookup has exactly zero sensitivity at this energy. The test requires the zero-gradient check to raise for gate 01.G4.

Return type:

None

test_complex_step_derivative() → None

Verify complex-step sine accuracy and reject modulus-squared.

Complex-step differentiation must retain machine precision for a holomorphic function and reject a non-holomorphic operation.

Notes

The test compares the holomorphic sine derivative with cosine at relative tolerance 1e-15, then confirms conjugation in abs(x)**2 triggers the zero-imaginary guard (01.G3).

Return type:

None

test_check_grads_semantics_anchor() → None

Pin JAX check_grads behavior on truth and a planted tangent defect.

The upstream JAX checker must accept the analytical sine derivative. It must reject the corrupted tangent from the harness test.

Notes

The test calls the JAX directional-gradient checker on sine and the scaled custom_jvp. This direct check establishes the independent semantic reference for gate 01.G3.

Return type:

None