diffpes.simul tests

Validation and regression tests for diffpes.simul.

Validate ARPES broadening functions.

Extended Summary

The tests exercise Gaussian, Voigt, and Fermi-Dirac functions. chex.variants runs applicable tests with and without JIT. The tests cover normalization, peak position, symmetry, limiting profiles, and Fermi-Dirac values.

class tests.test_diffpes.test_simul.test_broadening.TestGaussian(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.simul.broadening.gaussian().

Verifies the normalized Gaussian broadening profile, including normalization (unit integral), peak position accuracy, and symmetry about the center energy.

See:

gaussian()

test_normalization__with_jit() → None

Verify that the Gaussian profile integrates to unity.

The test establishes the normalization contract for gaussian with the concrete values and array shapes described below.

Notes

1. Create dense energy grid: Use 100,000 points across [-10, 10] eV for accurate integration.

2. Evaluate Gaussian: Computes the profile centered at 0.0 eV with sigma = 0.5 eV.

3. Numerical integration: Sums profile values multiplied by the energy step size to approximate the integral.

Expected assertions

The numerical integral is within 1e-3 of 1.0, confirming proper normalization of the Gaussian density.

Return type:

None

test_normalization__without_jit() → None

Verify that the Gaussian profile integrates to unity.

The test establishes the normalization contract for gaussian with the concrete values and array shapes described below.

Notes

1. Create dense energy grid: Use 100,000 points across [-10, 10] eV for accurate integration.

2. Evaluate Gaussian: Computes the profile centered at 0.0 eV with sigma = 0.5 eV.

3. Numerical integration: Sums profile values multiplied by the energy step size to approximate the integral.

Expected assertions

The numerical integral is within 1e-3 of 1.0, confirming proper normalization of the Gaussian density.

Return type:

None

test_peak_position__with_jit() → None

Verify that the Gaussian peak occurs at the specified center energy.

The test establishes the peak position contract for gaussian with the concrete values and array shapes described below.

Notes

1. Create energy grid: Use 10,001 points across [-5, 5] eV for precise peak location.

2. Evaluate Gaussian: Computes the profile centered at 1.5 eV with sigma = 0.3 eV.

3. Locate peak: Finds the energy corresponding to the maximum profile value using jnp.argmax.

Expected assertions

The peak energy is within 0.01 eV of the requested center (1.5 eV), confirming the centering parameter works correctly.

Return type:

None

test_peak_position__without_jit() → None

Verify that the Gaussian peak occurs at the specified center energy.

The test establishes the peak position contract for gaussian with the concrete values and array shapes described below.

Notes

1. Create energy grid: Use 10,001 points across [-5, 5] eV for precise peak location.

2. Evaluate Gaussian: Computes the profile centered at 1.5 eV with sigma = 0.3 eV.

3. Locate peak: Finds the energy corresponding to the maximum profile value using jnp.argmax.

Expected assertions

The peak energy is within 0.01 eV of the requested center (1.5 eV), confirming the centering parameter works correctly.

Return type:

None

test_symmetry__with_jit() → None

Verify that the Gaussian profile is symmetric about its center.

The test establishes the symmetry contract for gaussian with the concrete values and array shapes described below.

Notes

1. Create symmetric energy grid: Use 1001 symmetric points so one point lies exactly at 0.0 eV.

2. Evaluate Gaussian: Computes the profile centered at 0.0 eV with sigma = 0.5 eV.

3. Compare with reversed profile: Check that the profile array equals its reverse.

Expected assertions

Each element matches its mirror element to within 1e-10, confirming the even-function symmetry G(-E) = G(E).

Return type:

None

test_symmetry__without_jit() → None

Verify that the Gaussian profile is symmetric about its center.

The test establishes the symmetry contract for gaussian with the concrete values and array shapes described below.

Notes

1. Create symmetric energy grid: Use 1001 symmetric points so one point lies exactly at 0.0 eV.

2. Evaluate Gaussian: Computes the profile centered at 0.0 eV with sigma = 0.5 eV.

3. Compare with reversed profile: Check that the profile array equals its reverse.

Expected assertions

Each element matches its mirror element to within 1e-10, confirming the even-function symmetry G(-E) = G(E).

Return type:

None

class tests.test_diffpes.test_simul.test_broadening.TestVoigt(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.simul.broadening.voigt().

Verifies the pseudo-Voigt broadening profile, including its limiting behavior (reduction to Gaussian when gamma approaches zero), peak position accuracy, and output finiteness.

See:

voigt()

test_simultaneous_zero_width_is_rejected() → None

Reject the singular zero-width point eagerly and under JIT.

Return type:

None

Extended Summary

The test verifies rejection of sigma = gamma = 0. It does not accept a pointwise value with a fabricated derivative.

Notes

The test uses the shared rejection helper on a finite energy grid, exercising both direct execution and equinox.filter_jit.

test_boundary_gradients_match_fd_plateau__with_jit() → None

Match both boundary-ray gradients to a multistep FD plateau.

Return type:

None

Extended Summary

The test verifies sensitivities on the pure-Gaussian and pure-Lorentzian rays remain finite, nonzero, and central-FD-correct to the stiff rtol=1e-5 gate.

Notes

The test applies the shared program-wide gradient harness at three step scales to both width vectors, for eager and JIT-transformed scalar losses.

test_boundary_gradients_match_fd_plateau__without_jit() → None

Match both boundary-ray gradients to a multistep FD plateau.

Return type:

None

Extended Summary

The test verifies sensitivities on the pure-Gaussian and pure-Lorentzian rays remain finite, nonzero, and central-FD-correct to the stiff rtol=1e-5 gate.

Notes

The test applies the shared program-wide gradient harness at three step scales to both width vectors, for eager and JIT-transformed scalar losses.

test_exact_boundary_profiles_match_scipy__with_jit() → None

Match the Gaussian and Lorentzian endpoint rays to SciPy.

Return type:

None

Extended Summary

The test verifies the exact Gaussian and Cauchy limits of the mixing law. Both comparisons use rtol=1e-12.

Notes

The test evaluates both rays eagerly and under JIT on an asymmetric energy grid, then compares against scipy.stats.norm.pdf and scipy.stats.cauchy.pdf as independent external truths.

test_exact_boundary_profiles_match_scipy__without_jit() → None

Match the Gaussian and Lorentzian endpoint rays to SciPy.

Return type:

None

Extended Summary

The test verifies the exact Gaussian and Cauchy limits of the mixing law. Both comparisons use rtol=1e-12.

Notes

The test evaluates both rays eagerly and under JIT on an asymmetric energy grid, then compares against scipy.stats.norm.pdf and scipy.stats.cauchy.pdf as independent external truths.

test_peak_position__with_jit() → None

Verify that the Voigt profile peaks at the specified center energy.

The test establishes the peak position contract for voigt with the concrete values and array shapes described below.

Notes

1. Create energy grid: A range [-5, 5] eV with 10,001 points for sub-meV resolution.

2. Evaluate Voigt profile: Compute a profile centered at -1.0 eV with both broadening terms.

3. Locate peak: Finds the energy corresponding to the maximum profile value.

Expected assertions

The peak is within 0.01 eV of the requested center. Both profile components share this center.

Return type:

None

test_peak_position__without_jit() → None

Verify that the Voigt profile peaks at the specified center energy.

The test establishes the peak position contract for voigt with the concrete values and array shapes described below.

Notes

1. Create energy grid: A range [-5, 5] eV with 10,001 points for sub-meV resolution.

2. Evaluate Voigt profile: Compute a profile centered at -1.0 eV with both broadening terms.

3. Locate peak: Finds the energy corresponding to the maximum profile value.

Expected assertions

The peak is within 0.01 eV of the requested center. Both profile components share this center.

Return type:

None

test_positive_values__with_jit() → None

Verify that the Voigt profile produces finite values everywhere.

The test establishes the positive values contract for voigt with the concrete values and array shapes described below.

Notes

1. Evaluate Voigt profile: Compute a profile on [-5, 5] eV with both broadening terms.

2. Check finiteness: Check that the output contains no NaN or infinity values.

Expected assertions

All profile values are finite (no NaN or Inf), confirming numerical stability of the pseudo-Voigt implementation.

Return type:

None

test_positive_values__without_jit() → None

Verify that the Voigt profile produces finite values everywhere.

The test establishes the positive values contract for voigt with the concrete values and array shapes described below.

Notes

1. Evaluate Voigt profile: Compute a profile on [-5, 5] eV with both broadening terms.

2. Check finiteness: Check that the output contains no NaN or infinity values.

Expected assertions

All profile values are finite (no NaN or Inf), confirming numerical stability of the pseudo-Voigt implementation.

Return type:

None

test_reduces_to_gaussian__with_jit() → None

Verify that the Voigt profile reduces to a Gaussian when gamma is negligible.

The test establishes the reduces to gaussian contract for voigt with the concrete values and array shapes described below.

Notes

1. Set near-zero Lorentzian width: Uses gamma = 1e-10 eV so the Lorentzian contribution vanishes, leaving only the Gaussian component.

2. Evaluate both profiles: Computes the Voigt profile and a pure Gaussian with the same sigma on the same energy grid.

3. Compare element-wise: Checks that the Voigt output matches the pure Gaussian.

Expected assertions

All values agree to within 1e-3, confirming the correct Gaussian limiting behavior of the pseudo-Voigt approximation.

Return type:

None

test_reduces_to_gaussian__without_jit() → None

Verify that the Voigt profile reduces to a Gaussian when gamma is negligible.

The test establishes the reduces to gaussian contract for voigt with the concrete values and array shapes described below.

Notes

1. Set near-zero Lorentzian width: Uses gamma = 1e-10 eV so the Lorentzian contribution vanishes, leaving only the Gaussian component.

2. Evaluate both profiles: Computes the Voigt profile and a pure Gaussian with the same sigma on the same energy grid.

3. Compare element-wise: Checks that the Voigt output matches the pure Gaussian.

Expected assertions

All values agree to within 1e-3, confirming the correct Gaussian limiting behavior of the pseudo-Voigt approximation.

Return type:

None

class tests.test_diffpes.test_simul.test_broadening.TestFermiDirac(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.simul.broadening.fermi_dirac().

The tests verify the value at the Fermi level and both asymptotic limits. They also verify the bounded output range [0, 1].

See:

fermi_dirac()

test_at_fermi_level__with_jit() → None

Verify that the Fermi-Dirac function equals 0.5 at the Fermi energy.

The test establishes the at fermi level contract for fermi dirac with the concrete values and array shapes described below.

Notes

1. Evaluate at E = Ef: Call fermi_dirac(0.0, 0.0, 300.0) at the Fermi level.

2. Check analytic result: Check the analytical value 0.5 for a zero exponent.

Expected assertions

The result is within 1e-5 of 0.5, confirming the fundamental property f(Ef) = 0.5 at finite temperature.

Return type:

None

test_at_fermi_level__without_jit() → None

Verify that the Fermi-Dirac function equals 0.5 at the Fermi energy.

The test establishes the at fermi level contract for fermi dirac with the concrete values and array shapes described below.

Notes

1. Evaluate at E = Ef: Call fermi_dirac(0.0, 0.0, 300.0) at the Fermi level.

2. Check analytic result: Check the analytical value 0.5 for a zero exponent.

Expected assertions

The result is within 1e-5 of 0.5, confirming the fundamental property f(Ef) = 0.5 at finite temperature.

Return type:

None

test_deep_below_fermi__with_jit() → None

Verify full occupation deep below the Fermi level.

The test establishes the deep below fermi contract for fermi dirac with the concrete values and array shapes described below.

Notes

1. Evaluate far below Ef: Call fermi_dirac at -5.0 eV and 15 K.

2. Check saturation: For large negative exponents, exp(x) approaches 0 and the occupation approaches 1/(1+0) = 1.

Expected assertions

The result is within 1e-5 of 1.0, confirming full occupation of deeply bound states.

Return type:

None

test_deep_below_fermi__without_jit() → None

Verify full occupation deep below the Fermi level.

The test establishes the deep below fermi contract for fermi dirac with the concrete values and array shapes described below.

Notes

1. Evaluate far below Ef: Call fermi_dirac at -5.0 eV and 15 K.

2. Check saturation: For large negative exponents, exp(x) approaches 0 and the occupation approaches 1/(1+0) = 1.

Expected assertions

The result is within 1e-5 of 1.0, confirming full occupation of deeply bound states.

Return type:

None

test_extreme_arguments_have_finite_zero_gradients__with_jit() → None

Keep the audit probe and extreme tails free of NaN gradients.

Return type:

None

Extended Summary

The test verifies finite values and derivatives at the former failure point and extreme tails. Saturated derivatives equal zero exactly.

Notes

The test evaluates the occupation and all three gradients eagerly and under JIT, then checks the positive audit/tail values and every saturated derivative exactly.

test_extreme_arguments_have_finite_zero_gradients__without_jit() → None

Keep the audit probe and extreme tails free of NaN gradients.

Return type:

None

Extended Summary

The test verifies finite values and derivatives at the former failure point and extreme tails. Saturated derivatives equal zero exactly.

Notes

The test evaluates the occupation and all three gradients eagerly and under JIT, then checks the positive audit/tail values and every saturated derivative exactly.

test_gradients_match_central_finite_differences__with_jit() → None

Match all three smooth derivatives to central differences.

Return type:

None

Extended Summary

The test verifies energy, Fermi-energy, and temperature sensitivities are finite, nonzero, and central-FD-correct at x = 1 and 15 K to the smooth rtol=1e-6 gate.

Notes

The test runs the shared gradient harness against eager and JIT-transformed scalar functions on the three-parameter vector.

test_gradients_match_central_finite_differences__without_jit() → None

Match all three smooth derivatives to central differences.

Return type:

None

Extended Summary

The test verifies energy, Fermi-energy, and temperature sensitivities are finite, nonzero, and central-FD-correct at x = 1 and 15 K to the smooth rtol=1e-6 gate.

Notes

The test runs the shared gradient harness against eager and JIT-transformed scalar functions on the three-parameter vector.

test_high_above_fermi__with_jit() → None

Verify zero occupation far above the Fermi level.

The test establishes the high above fermi contract for fermi dirac with the concrete values and array shapes described below.

Notes

1. Evaluate far above Ef: Calls fermi_dirac(5.0, 0.0, 15.0) where E - Ef = +5.0 eV at T = 15 K, making the exponent ~ +3900.

2. Check vanishing occupation: For large positive exponents, exp(x) dominates and the occupation approaches 1/(1+inf) = 0.

Expected assertions

The result is within 1e-5 of 0.0, confirming that states well above the Fermi energy are effectively empty.

Return type:

None

test_high_above_fermi__without_jit() → None

Verify zero occupation far above the Fermi level.

The test establishes the high above fermi contract for fermi dirac with the concrete values and array shapes described below.

Notes

1. Evaluate far above Ef: Calls fermi_dirac(5.0, 0.0, 15.0) where E - Ef = +5.0 eV at T = 15 K, making the exponent ~ +3900.

2. Check vanishing occupation: For large positive exponents, exp(x) dominates and the occupation approaches 1/(1+inf) = 0.

Expected assertions

The result is within 1e-5 of 0.0, confirming that states well above the Fermi energy are effectively empty.

Return type:

None

test_range_0_to_1__with_jit() → None

Verify that the Fermi-Dirac output lies within [0, 1].

The test establishes the range 0 to 1 contract for fermi dirac with the concrete values and array shapes described below.

Notes

1. Evaluate at a typical energy: Call fermi_dirac at -0.5 eV and 300 K.

2. Bound checks: Asserts the scalar result is non-negative and does not exceed unity using plain Python comparisons.

Expected assertions

The occupation value satisfies 0 <= f(E) <= 1, which must hold for any valid probability/occupation function.

Return type:

None

test_range_0_to_1__without_jit() → None

Verify that the Fermi-Dirac output lies within [0, 1].

The test establishes the range 0 to 1 contract for fermi dirac with the concrete values and array shapes described below.

Notes

1. Evaluate at a typical energy: Call fermi_dirac at -0.5 eV and 300 K.

2. Bound checks: Asserts the scalar result is non-negative and does not exceed unity using plain Python comparisons.

Expected assertions

The occupation value satisfies 0 <= f(E) <= 1, which must hold for any valid probability/occupation function.

Return type:

None

test_value_and_gradients_match_closed_forms__with_jit() → None

Match occupations and all derivatives across the f64 ladder.

Return type:

None

Extended Summary

The test compares values with a high-precision mpmath logistic. It compares three derivatives with analytical formulas at rtol=1e-12.

Notes

The test evaluates x in {0, ±1, ±10, ±100, ±700} at 5, 15, and 300 K, both eagerly and under JIT. The test evaluates closed forms from the independent occupation after f64 rounding, including the representable saturation convention.

test_value_and_gradients_match_closed_forms__without_jit() → None

Match occupations and all derivatives across the f64 ladder.

Return type:

None

Extended Summary

The test compares values with a high-precision mpmath logistic. It compares three derivatives with analytical formulas at rtol=1e-12.

Notes

The test evaluates x in {0, ±1, ±10, ±100, ±700} at 5, 15, and 300 K, both eagerly and under JIT. The test evaluates closed forms from the independent occupation after f64 rounding, including the representable saturation convention.

Validate ARPES cross-section weight functions.

Extended Summary

Exercises heuristic_weights and yeh_lindau_weights. Heuristic tests verify the two-regime model (p-enhanced below 50 eV, d-enhanced above), output shape (9,), and JIT compatibility. Yeh-Lindau tests verify interpolation at a fixed photon energy, output shape, and non-negative weights. Each class and method docstring documents its test logic.

class tests.test_diffpes.test_simul.test_crosssections.TestHeuristicWeights(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.simul.crosssections.heuristic_weights().

The tests verify p-orbital enhancement below 50 eV and d-orbital enhancement above 50 eV. They check the output shape and JIT compatibility.

See:

heuristic_weights()

test_high_energy_d_enhanced__with_jit() → None

Verify enhanced d-orbital weights in the high-energy regime.

The test establishes the high energy d enhanced contract for heuristic weights with the concrete values and array shapes described below.

Notes

1. Compute weights at 60 eV: Call heuristic_weights(60.0) above the 50 eV threshold.

2. Check p- and d-orbital values: Verify weight 1.0 for a p orbital and 2.0 for two d orbitals.

Expected assertions

p-orbital (index 1) equals 1.0, and d-orbitals (indices 4, 8) equal 2.0.

Return type:

None

test_high_energy_d_enhanced__without_jit() → None

Verify enhanced d-orbital weights in the high-energy regime.

The test establishes the high energy d enhanced contract for heuristic weights with the concrete values and array shapes described below.

Notes

1. Compute weights at 60 eV: Call heuristic_weights(60.0) above the 50 eV threshold.

2. Check p- and d-orbital values: Verify weight 1.0 for a p orbital and 2.0 for two d orbitals.

Expected assertions

p-orbital (index 1) equals 1.0, and d-orbitals (indices 4, 8) equal 2.0.

Return type:

None

test_low_energy_p_enhanced__with_jit() → None

Verify enhanced p-orbital weights in the low-energy regime.

The test establishes the low energy p enhanced contract for heuristic weights with the concrete values and array shapes described below.

Notes

1. Compute weights at 30 eV: Call heuristic_weights(30.0) below the 50 eV threshold.

2. Check output shape: Confirms the result has shape (9,) matching the 9-orbital basis.

3. Check p-orbital enhancement: Verify weights 2.0 for p orbitals and 1.0 for the first d orbital.

Expected assertions

Output shape is (9,), p-orbitals (indices 1-3) equal 2.0, and d-orbital (index 4) equals 1.0.

Return type:

None

test_low_energy_p_enhanced__without_jit() → None

Verify enhanced p-orbital weights in the low-energy regime.

The test establishes the low energy p enhanced contract for heuristic weights with the concrete values and array shapes described below.

Notes

1. Compute weights at 30 eV: Call heuristic_weights(30.0) below the 50 eV threshold.

2. Check output shape: Confirms the result has shape (9,) matching the 9-orbital basis.

3. Check p-orbital enhancement: Verify weights 2.0 for p orbitals and 1.0 for the first d orbital.

Expected assertions

Output shape is (9,), p-orbitals (indices 1-3) equal 2.0, and d-orbital (index 4) equals 1.0.

Return type:

None

class tests.test_diffpes.test_simul.test_crosssections.TestYehLindauWeights(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.simul.crosssections.yeh_lindau_weights().

Verifies the interpolated Yeh-Lindau cross-section weights including exact values at tabulation points, correct interpolation at intermediate energies, positivity of all weights, and JIT compatibility.

See:

yeh_lindau_weights()

test_all_positive__with_jit() → None

Verify that all 9 orbital weights are strictly positive at 40 eV.

The test establishes the all positive contract for yeh lindau weights with the concrete values and array shapes described below.

Notes

1. Compute weights at 40 eV: Calls yeh_lindau_weights(40.0) at a tabulation point.

2. Check positivity of every element: Iterates over all 9 orbital weight entries and asserts each is strictly positive using chex.assert_scalar_positive.

Expected assertions

Every element of the 9-element weight vector is strictly positive, ensuring no orbital receives a zero or negative cross-section.

Return type:

None

test_all_positive__without_jit() → None

Verify that all 9 orbital weights are strictly positive at 40 eV.

The test establishes the all positive contract for yeh lindau weights with the concrete values and array shapes described below.

Notes

1. Compute weights at 40 eV: Calls yeh_lindau_weights(40.0) at a tabulation point.

2. Check positivity of every element: Iterates over all 9 orbital weight entries and asserts each is strictly positive using chex.assert_scalar_positive.

Expected assertions

Every element of the 9-element weight vector is strictly positive, ensuring no orbital receives a zero or negative cross-section.

Return type:

None

test_at_20_eV__with_jit() → None

Verify exact cross-section values at the 20 eV tabulation point.

The test establishes the at 20 eV contract for yeh lindau weights with the concrete values and array shapes described below.

Notes

1. Compute weights at 20 eV: Call yeh_lindau_weights(20.0) at the lowest table energy.

2. Check output shape: Confirms the result has shape (9,).

3. Check known tabulated values: Compare selected s, p, and d weights with their table values.

Expected assertions

Output shape is (9,) and weights at indices 0, 1, 4 match the tabulated values within tolerance 1e-5.

Return type:

None

test_at_20_eV__without_jit() → None

Verify exact cross-section values at the 20 eV tabulation point.

The test establishes the at 20 eV contract for yeh lindau weights with the concrete values and array shapes described below.

Notes

1. Compute weights at 20 eV: Call yeh_lindau_weights(20.0) at the lowest table energy.

2. Check output shape: Confirms the result has shape (9,).

3. Check known tabulated values: Compare selected s, p, and d weights with their table values.

Expected assertions

Output shape is (9,) and weights at indices 0, 1, 4 match the tabulated values within tolerance 1e-5.

Return type:

None

test_interpolated__with_jit() → None

Verify that interpolation at 30 eV produces positive s and p weights.

The test establishes the interpolated contract for yeh lindau weights with the concrete values and array shapes described below.

Notes

1. Compute weights at 30 eV: Calls yeh_lindau_weights(30.0), an energy between the 20 eV and 40 eV tabulation points, requiring interpolation.

2. Check output shape: Confirms the result has shape (9,).

3. Check s- and p-orbital weights are positive: Verify positive interpolated s-orbital and p-orbital weights.

Expected assertions

Output shape is (9,) and weights at indices 0 and 1 are strictly positive.

Return type:

None

test_interpolated__without_jit() → None

Verify that interpolation at 30 eV produces positive s and p weights.

The test establishes the interpolated contract for yeh lindau weights with the concrete values and array shapes described below.

Notes

1. Compute weights at 30 eV: Calls yeh_lindau_weights(30.0), an energy between the 20 eV and 40 eV tabulation points, requiring interpolation.

2. Check output shape: Confirms the result has shape (9,).

3. Check s- and p-orbital weights are positive: Verify positive interpolated s-orbital and p-orbital weights.

Expected assertions

Output shape is (9,) and weights at indices 0 and 1 are strictly positive.

Return type:

None

Validate expanded-input simulation wrappers.

Extended Summary

The tests validate expanded wrappers that accept arrays and scalars. They compare each wrapper with its corresponding core simulation. They verify energy-window construction and dispatch for every level. They also verify that the SOC level requires spin data.

class tests.test_diffpes.test_simul.test_expanded.TestExpandedParams(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.simul.expanded.make_expanded_simulation_params().

The tests verify the energy window from eigenband extrema and default padding. They also verify all forwarded scalar parameters.

See:

make_expanded_simulation_params()

test_energy_window_matches_expanded_default() → None

Verify derivation of the energy bounds from eigenbands.

The test establishes the energy window matches expanded default contract for expanded params with the concrete values and array shapes described below.

Notes

1. Setup: Create a small eigenband array with known extrema: min = -2.0, max = 1.0. Use the default energy padding of 1.0.

2. Build params: Call make_expanded_simulation_params with fidelity=100.

3. Check energy bounds: Assert that energy_min equals min(eigenbands) - 1.0 = -3.0 and energy_max equals max(eigenbands) + 1.0 = 2.0, each within a tolerance of 1e-12.

4. Check fidelity: Check that the fidelity parameter equals 100.

Expected assertions

The derived energy window matches [min - padding, max + padding]. The fidelity value remains exactly 100.

Return type:

None

class tests.test_diffpes.test_simul.test_expanded.TestSimulateNoviceExpanded(*args, **kwargs) → None

Bases: TestCase

Validate simulate_novice_expanded().

Covers the plain-array novice wrapper at a reduced energy-grid fidelity while retaining all required Voigt parameters.

See:

simulate_novice_expanded()

test_returns_requested_energy_grid() → None

Return one intensity row per k-point on the requested energy grid.

The twelve-point synthetic band path and fidelity of 48 must produce a finite (12, 48) intensity array.

Notes

The test passes the raw synthetic arrays and explicit novice parameters to the wrapper, then checks its shape and finite values with Chex.

Return type:

None

class tests.test_diffpes.test_simul.test_expanded.TestSimulateBasicExpanded(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.simul.expanded.simulate_basic_expanded().

Verifies that the expanded basic wrapper produces results identical to manually constructing PyTree inputs and calling the core simulate_basic() function directly.

See:

simulate_basic_expanded()

test_matches_core_basic_simulation() → None

Verify that the expanded wrapper matches the core basic simulation.

The test establishes the matches core basic simulation contract for expanded basic wrapper with the concrete values and array shapes described below.

Notes

1. Build reference manually: Construct equivalent PyTrees from the raw inputs.

2. Run core simulation: Call simulate_basic directly with the PyTree inputs to obtain the expected spectrum.

3. Run expanded wrapper: Call the expanded wrapper with equivalent inputs.

4. Compare: Assert that both intensity arrays and energy axes match to within 1e-12 absolute tolerance.

Expected assertions

The expanded and core results have identical intensity and energy axes. This agreement verifies construction of all intermediate PyTrees.

Return type:

None

class tests.test_diffpes.test_simul.test_expanded.TestSimulateBasicplusExpanded(*args, **kwargs) → None

Bases: TestCase

Validate simulate_basicplus_expanded().

Covers the Yeh-Lindau weighted wrapper for raw arrays at a representative ultraviolet photon energy.

See:

simulate_basicplus_expanded()

test_returns_finite_cross_section_weighted_spectrum() → None

Return finite intensity at the requested basicplus fidelity.

The wrapper must retain twelve k-points and construct forty-eight energy samples without non-finite cross-section weights.

Notes

The test evaluates the raw synthetic arrays at 21.2 eV and checks the output intensity shape and finiteness with Chex.

Return type:

None

class tests.test_diffpes.test_simul.test_expanded.TestSimulateAdvancedExpanded(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.simul.expanded.simulate_advanced_expanded().

The tests verify conversion of incident angles from degrees to radians. They compare the wrapper result with a core call that uses radians.

See:

simulate_advanced_expanded()

test_degree_conversion_matches_core_advanced() → None

Verify that degree-input angles produce the same result as radian-input.

The test establishes the degree conversion matches core advanced contract for expanded advanced wrapper with the concrete values and array shapes described below.

Notes

1. Build reference manually: Construct equivalent PyTrees from the raw inputs.

2. Run core simulation: Call simulate_advanced directly with the manually built PyTrees and polarization config to obtain the expected spectrum.

3. Run expanded wrapper: Call the expanded wrapper with equivalent inputs.

4. Compare: Assert that both intensity arrays match to within 1e-12 absolute tolerance.

Expected assertions

The expanded and core intensities are identical. This agreement verifies conversion of both incident angles.

Return type:

None

class tests.test_diffpes.test_simul.test_expanded.TestSimulateExpertExpanded(*args, **kwargs) → None

Bases: TestCase

Validate simulate_expert_expanded().

Covers the full dipole and Voigt wrapper for raw arrays under unpolarized illumination at a reduced test fidelity.

See:

simulate_expert_expanded()

test_returns_finite_unpolarized_spectrum() → None

Return finite expert intensity for unpolarized illumination.

The expert wrapper must preserve twelve k-points and form forty-eight energy samples after its polarization and matrix-element stages.

Notes

The test evaluates the synthetic raw arrays with explicit Voigt and incidence parameters, then checks the output shape and finite values with Chex.

Return type:

None

class tests.test_diffpes.test_simul.test_expanded.TestSimulateExpanded(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.simul.expanded.simulate_expanded().

Verifies that the level-based dispatch function correctly routes to the appropriate expanded wrapper and produces identical results.

See:

simulate_expanded()

test_dispatch_expert_matches_direct_wrapper() → None

Verify that dispatching with level=”Expert” matches the direct wrapper.

The test establishes the dispatch expert matches direct wrapper contract for expanded dispatch with the concrete values and array shapes described below.

Notes

1. Run direct wrapper: Call the direct wrapper with explicit parameters.

2. Run dispatcher: Call simulate_expanded with level="Expert" and the same parameters. Note the capitalized level string, which tests case-insensitive dispatch.

3. Compare: Assert that both intensity arrays match to within 1e-12 absolute tolerance.

Expected assertions

The dispatched intensity is numerically identical to the direct expert wrapper, confirming that simulate_expanded correctly routes to simulate_expert_expanded and that level matching is case-insensitive.

Return type:

None

test_dispatch_novice_matches_direct_wrapper() → None

Verify that dispatching with level=’novice’ matches the direct wrapper.

The test establishes the dispatch novice matches direct wrapper contract for expanded dispatch with the concrete values and array shapes described below.

Notes

1. Run direct wrapper: Call the direct wrapper with explicit parameters.

2. Run dispatcher: Call simulate_expanded with level="novice" and the same parameters.

3. Compare: Assert that both intensity arrays match to within 1e-12 absolute tolerance.

Expected assertions

The dispatched intensity is numerically identical to the direct novice wrapper, confirming that simulate_expanded correctly routes to simulate_novice_expanded.

Return type:

None

test_dispatch_basic_matches_direct_wrapper() → None

Verify that dispatching with level=’basic’ matches the direct wrapper.

The test establishes the dispatch basic matches direct wrapper contract for expanded dispatch with the concrete values and array shapes described below.

Notes

1. Run direct wrapper: Call the direct wrapper with explicit parameters.

2. Run dispatcher: Call simulate_expanded with level="basic" and the same parameters.

3. Compare: Assert that both intensity arrays match to within 1e-12 absolute tolerance.

Expected assertions

The dispatched intensity is numerically identical to the direct basic wrapper, confirming that simulate_expanded correctly routes to simulate_basic_expanded.

Return type:

None

test_dispatch_basicplus_matches_direct_wrapper() → None

Verify that dispatching with level=’basicplus’ matches the direct wrapper.

The test establishes the dispatch basicplus matches direct wrapper contract for expanded dispatch with the concrete values and array shapes described below.

Notes

1. Run direct wrapper: Call the direct wrapper with explicit parameters.

2. Run dispatcher: Call simulate_expanded with level="basicplus" and the same parameters.

3. Compare: Assert that both intensity arrays match to within 1e-12 absolute tolerance.

Expected assertions

The dispatched intensity is numerically identical to the direct basicplus wrapper, confirming that simulate_expanded correctly routes to simulate_basicplus_expanded.

Return type:

None

test_dispatch_advanced_matches_direct_wrapper() → None

Verify that dispatching with level=’advanced’ matches the direct wrapper.

The test establishes the dispatch advanced matches direct wrapper contract for expanded dispatch with the concrete values and array shapes described below.

Notes

1. Run direct wrapper: Call the direct wrapper with explicit parameters.

2. Run dispatcher: Call simulate_expanded with level="advanced" and the same parameters.

3. Compare: Assert that both intensity arrays match to within 1e-12 absolute tolerance.

Expected assertions

The dispatched intensity is numerically identical to the direct advanced wrapper, confirming that simulate_expanded correctly routes to simulate_advanced_expanded.

Return type:

None

test_dispatch_unknown_level_raises() → None

Verify that an unknown level raises ValueError with expected message.

The test establishes the dispatch unknown level raises contract for expanded dispatch with the concrete values and array shapes described below.

Notes

1. Call dispatcher with invalid level: Call simulate_expanded(level="invalid", ...) with minimal required arguments (eigenbands, surface_orb, ef).

2. Check exception type: Expect a ValueError.

3. Check error message: Verify the error description and one supported level in the message.

Expected assertions

The function raises ValueError with an error description and valid level names.

Return type:

None

test_dispatch_soc_requires_surface_spin() → None

Verify that level=’soc’ without surface_spin raises ValueError.

The test establishes the dispatch soc requires surface spin contract for expanded dispatch with the concrete values and array shapes described below.

Notes

1. Setup: Synthetic eigenbands and surface_orb (no surface_spin passed).

2. Call: Invoke simulate_expanded(level="soc", ...) with only the required array args and ef.

3. Check: Expect ValueError and "surface_spin" in its message.

Expected assertions

Dispatching to the SOC level without providing spin data raises ValueError with a clear requirement for surface_spin.

Return type:

None

test_dispatch_soc_matches_direct_wrapper() → None

Verify that level=’soc’ with surface_spin matches simulate_soc_expanded.

The test establishes the dispatch soc matches direct wrapper contract for expanded dispatch with the concrete values and array shapes described below.

Notes

1. Setup: Synthetic eigenbands and surface_orb; build a surface_spin array of shape (K, B, A, 6) with non-zero z components.

2. Run direct: Call simulate_soc_expanded with the same scalar parameters to get the expected spectrum.

3. Run dispatcher: Call simulate_expanded(level="soc", ..., surface_spin=surface_spin, ls_scale=0.01).

4. Compare: Assert dispatched and expected intensities match to within 1e-12.

Expected assertions

The level-based dispatcher with level="soc" and surface_spin produces the same result as calling simulate_soc_expanded directly.

Return type:

None

class tests.test_diffpes.test_simul.test_expanded.TestSimulateSocExpanded(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.simul.expanded.simulate_soc_expanded().

The tests compare manually built PyTrees with the wrapper PyTrees. They also compare the wrapper result with simulate_soc().

See:

simulate_soc_expanded()

test_matches_core_soc_simulation() → None

Verify that the expanded SOC wrapper matches the core simulate_soc.

The test establishes the matches core soc simulation contract for expanded soc wrapper with the concrete values and array shapes described below.

Notes

1. Build reference manually: Use _build_inputs() with surface_spin to get bands and orb_proj; build params via make_expanded_simulation_params() (fidelity=180, sigma=0.05, gamma=0.08, etc.); build pol via _build_polarization() (unpolarized, 45°, 0°). Call simulate_soc(bands, orb_proj, params, pol, ls_scale=0.02) to get the expected spectrum.

2. Run expanded wrapper: Call simulate_soc_expanded with the same raw arrays and scalar parameters (including ls_scale=0.02).

3. Compare: Assert that wrapped and expected intensity and energy_axis match to within 1e-12.

Expected assertions

The expanded SOC wrapper produces numerically identical output to the core SOC simulation when given the same physical parameters.

Return type:

None

Validate the end-to-end differentiable forward model.

Extended Summary

Validates diffpes.simul.forward.simulate_tb_radial(), the Chinook-style tight-binding forward model that combines tight-binding diagonalization, Slater radial wavefunctions, dipole matrix elements, and Voigt broadening into a single differentiable pipeline. The tests cover shapes, value constraints, polarization modes, and optional broadening. They verify work function sensitivity and derivatives for Slater exponents and hopping parameters. The graphene model test verifies a multi-orbital, multi-atom system runs end-to-end without error.

tests.test_diffpes.test_simul.test_forward.chain_setup() → tuple[DiagonalizedBands, SlaterParams, SimulationParams, PolarizationConfig]

Provide a 1D chain tight-binding model with a single Slater s-orbital.

The fixture constructs a 1D chain with -1.0 eV nearest-neighbor hopping. It diagonalizes the model at ten k-points along the x-axis. The orbital basis is a single hydrogen-like 1s orbital (n=1, l=0, m=0) with Slater exponent zeta = 1.0. The simulation uses a [-3, 3] eV energy window, fidelity 500, Voigt broadening, 30 K, and 21.2 eV photons. The fixture uses LHP polarization.

Most tests in TestSimulateTBRadial share this fixture. The analytical cosine band keeps diagonalization fast while exercising the complete forward pipeline.

Return type:

tuple[DiagonalizedBands, SlaterParams, SimulationParams, PolarizationConfig]

Returns:

• diag (TBDiagonalization) – Diagonalized tight-binding model at 10 k-points.

• slater (SlaterParams) – Slater radial parameters with zeta=1.0 for a single 1s orbital.

• params (SimulationParams) – Simulation parameters (energy window, broadening, temperature, photon energy).

• pol (PolarizationConfig) – LHP polarization configuration.

class tests.test_diffpes.test_simul.test_forward.TestSimulateTBRadial

Bases: object

Validate diffpes.simul.forward.simulate_tb_radial().

Validates the Chinook-style differentiable forward model that computes ARPES spectra from tight-binding Hamiltonians and Slater radial wavefunctions. The tests cover shapes, finite nonnegative values, and polarization modes. They cover optional broadening and work-function sensitivity. They also verify derivatives for Slater exponents and tight-binding hopping parameters. A graphene test confirms multi-orbital, multi-atom generality.

See:

simulate_tb_radial()

test_output_shape(chain_setup) → None

Verify that the spectrum intensity and energy axis have expected shapes.

The test establishes the output shape contract for simulate t b radial with the concrete values and array shapes described below.

Notes

1. Setup: Use the chain_setup fixture (10 k-points, fidelity=500, 1D chain with one s-orbital, LHP polarization).

2. Simulate: Call simulate_tb_radial with the fixture inputs to produce an ArpesSpectrum.

3. Check shapes: Assert intensity shape is (10, 500) (n_kpoints x fidelity) and energy_axis shape is (500,).

Expected assertions

The intensity has shape (n_kpoints, fidelity) and the energy axis has length fidelity, confirming that the forward model correctly maps k-points and energy grid dimensions.

Return type:

None

test_output_finite(chain_setup) → None

Verify that all intensity and energy axis values are finite.

The test establishes the output finite contract for simulate t b radial with the concrete values and array shapes described below.

Notes

1. Setup: Use the chain_setup fixture (1D chain, LHP).

2. Simulate: Call simulate_tb_radial to produce a spectrum.

3. Check finiteness: Check every intensity and energy-axis value.

Expected assertions

All elements of intensity and energy_axis are finite, confirming numerical stability of the radial integration, dipole matrix element computation, and broadening stages.

Return type:

None

test_output_non_negative(chain_setup) → None

Verify that the simulated ARPES intensity is non-negative.

The test establishes the output non negative contract for simulate t b radial with the concrete values and array shapes described below.

Notes

1. Setup: Use the chain_setup fixture (1D chain, LHP).

2. Simulate: Call simulate_tb_radial to produce a spectrum.

3. Check non-negativity: Assert all intensity values are >= -1e-15 (allowing negligible floating-point undershoot).

Expected assertions

All intensity values are effectively non-negative, consistent with the physical interpretation of ARPES intensity as a squared matrix element weighted by spectral function and occupation.

Return type:

None

test_unpolarized(chain_setup) → None

Verify that unpolarized light mode produces finite intensity.

The test establishes the unpolarized contract for simulate t b radial with the concrete values and array shapes described below.

Notes

1. Setup: Use the chain_setup fixture but override the polarization config to "unpolarized", which averages contributions from orthogonal s- and p-polarization vectors.

2. Simulate: Call simulate_tb_radial with the unpolarized configuration.

3. Check finiteness: Assert all intensity values are finite.

Expected assertions

The unpolarized path produces finite intensity values. This result verifies stable averaging of the polarization contributions.

Return type:

None

test_with_self_energy(chain_setup) → None

Verify that the optional self-energy extension produces finite output.

The test establishes the with self energy contract for simulate t b radial with the concrete values and array shapes described below.

Notes

1. Setup: Use the fixture and a constant 0.15 eV self-energy.

2. Simulate: Call simulate_tb_radial with the self_energy keyword argument.

3. Check finiteness: Assert all intensity values are finite.

Expected assertions

A constant self-energy produces finite intensity values. This result verifies its integration with the forward model.

Return type:

None

test_with_momentum_broadening(chain_setup) → None

Verify that the optional momentum-broadening extension produces finite output.

The test establishes the with momentum broadening contract for simulate t b radial with the concrete values and array shapes described below.

Notes

1. Setup: Use the fixture and dk=0.05 inverse Angstrom.

2. Simulate: Call simulate_tb_radial with the dk keyword argument.

3. Check finiteness: Assert all intensity values are finite.

Expected assertions

Momentum broadening produces finite intensity values. This result verifies its integration with the forward model.

Return type:

None

test_work_function_effect(chain_setup) → None

Verify that different work function values produce different spectra.

The test establishes the work function effect contract for simulate t b radial with the concrete values and array shapes described below.

Notes

1. Setup: Use the chain_setup fixture and run the simulation twice with work_function=4.0 eV and work_function=6.0 eV. The work function enters the photoelectron kinetic energy calculation (Ek = hv - phi - |Eb|), which affects the Slater radial matrix element via the outgoing plane-wave momentum.

2. Simulate both: Call simulate_tb_radial twice with different work functions.

3. Compare: Assert the two intensity arrays are not element-wise close (jnp.allclose returns False).

Expected assertions

Different work functions produce different intensity maps. This result verifies propagation through the radial matrix element.

Return type:

None

test_gradient_wrt_zeta(chain_setup) → None

Verify that the gradient of total intensity w.r.t. Slater exponent is finite.

The test establishes the gradient wrt zeta contract for simulate t b radial with the concrete values and array shapes described below.

Notes

1. Setup: Use the fixture without its Slater parameters. Define a scalar loss with new parameters and an explicit radial grid.

2. Differentiate: Call jax.grad(loss)(1.0) to compute the gradient of the loss with respect to the Slater exponent.

3. Check finiteness: Assert the gradient is finite.

Expected assertions

The Slater-exponent gradient is finite. This result verifies JAX differentiation through the radial integration without singularities.

Return type:

None

test_gradient_wrt_hopping() → None

Verify end-to-end gradient through TB diagonalization and simulation.

The test establishes the gradient wrt hopping contract for simulate t b radial with the concrete values and array shapes described below.

Notes

1. Setup: Build a five-point chain with one 1s orbital. Define a scalar loss that replaces the hopping parameters. Diagonalize the model and simulate with an explicit radial grid.

2. Differentiate: Call jax.grad(loss)(model.hopping_params) to compute the gradient of the total intensity with respect to the tight-binding hopping parameter(s).

3. Check finiteness: Assert all gradient components are finite.

Expected assertions

All hopping gradients are finite. This result verifies JAX differentiation through the complete forward model.

Return type:

None

test_graphene_runs() → None

Verify that a graphene model with two pz orbitals runs end-to-end.

The test establishes the graphene runs contract for simulate t b radial with the concrete values and array shapes described below.

Notes

1. Setup: Build a graphene tight-binding model with nearest-neighbour hopping t=-2.7 eV (standard graphene value). Use three high-symmetry k-points and two carbon pz orbitals. Use a wide energy window and an explicit radial grid.

2. Simulate: Call simulate_tb_radial with LHP polarization.

3. Check shape and finiteness: Assert intensity shape is (3, 300) and all values are finite.

Expected assertions

The intensity has the expected shape and finite values. This result verifies the forward model for a graphene system with multiple atoms.

Return type:

None

Validate free-electron photoemission kinematics.

Extended Summary

The tests cover energy floors, momentum values, complex out-of-plane roots, emission angles, detector maps, JAX transforms, and certified gradients.

class tests.test_diffpes.test_simul.test_kinematics.TestKineticEnergyEv(*args, **kwargs) → None

Bases: TestCase

Validate kinetic_energy_ev().

The tests cover energy conservation, the physical floor, JIT, and the selected gradient on each side of the floor.

See:

kinetic_energy_ev()

test_energy_conservation_and_floor_under_jit() → None

Match energy conservation and apply the physical floor under JIT.

The first three values remain above the floor. The last value cannot produce a photoelectron and therefore maps to EKIN_FLOOR_EV.

Notes

Use 21.2 eV photons and a 4.3 eV work function. Compare four binding energies with the closed-form values.

Return type:

None

test_floor_selects_zero_gradient() → None

Verify exact gradients above and below the kinetic-energy floor.

Photon energy has unit sensitivity above the floor. The floor selects zero sensitivity outside the physical validity domain.

Notes

Differentiate one allowed point, one boundary point, and one rejected point. Check all gradients and their finiteness.

Return type:

None

class tests.test_diffpes.test_simul.test_kinematics.TestFinalStateKInvAng(*args, **kwargs) → None

Bases: TestCase

Validate final_state_k_inv_ang().

The tests compare the free-electron formula with closed-form values. They also verify the floor guard and the momentum gradient.

See:

final_state_k_inv_ang()

test_values_and_shape_match_free_electron_formula() → None

Match the free-electron momentum formula and preserve shape.

The expected values use the Plan 03 CODATA-derived prefactor. The function must return one float64 momentum for each energy.

Notes

Evaluate energies of 1, 16, and 100 eV under JIT. Compare at rtol=1e-14.

Return type:

None

test_gradient_matches_formula_and_floor_guard() → None

Match the analytic derivative and verify the floor subgradient.

The derivative above the floor equals C/(2*sqrt(E)). A negative direct input uses the floor and has zero sensitivity.

Notes

Apply the shared finite-difference harness at 24 eV. Differentiate a negative input and the exact floor separately.

Return type:

None

class tests.test_diffpes.test_simul.test_kinematics.TestKzFromInnerPotential(*args, **kwargs) → None

Bases: TestCase

Validate kz_from_inner_potential().

The tests cover Damascelli values, evanescent channels, analytic and finite-difference gradients, vmap consistency, and a large JIT raster.

See:

kz_from_inner_potential()

test_matches_damascelli_grid() → None

Match the Damascelli closed form on a photon-energy grid.

The detector map supplies the parallel momentum. The expected out-of-plane momentum uses the independent angle formula.

Notes

Use horizontal-slit angles (theta, 0). Compare the composed result with C*sqrt(Ekin*cos(theta)^2+V0) at rtol=1e-10.

Return type:

None

test_matches_pinned_chinook_reference() → None

Match the pinned Chinook kinematics table and its constant mapping.

The injected Chinook constants must reproduce all 168 source values. The production constants must reproduce the separately recorded accuracy-improved values and retain the measured constant delta.

Notes

Read the committed offline artifact for Plan 03 gate 03.G3. Vmap the production function across its rows and compare both formulations at the artifact tolerance.

Return type:

None

test_preserves_evanescent_channels() → None

Verify principal complex roots and the propagation mask.

Small parallel momentum gives a positive real root. Large parallel momentum gives a positive imaginary root and a false mask value.

Notes

Evaluate parallel momenta 0 and 3 in 1/Angstrom. Compare both values with the direct complex square root.

Return type:

None

test_gradients_match_fd_at_twelve_registered_points() → None

Match three parameter gradients at twelve propagating points.

The points span ultraviolet through soft-X-ray photon energies. Each parameter leaf retains a nonzero gradient norm.

Notes

Vmap the scalar kinematics over twelve tuples. The shared harness checks both autodiff modes and central finite differences.

Return type:

None

test_inner_potential_gradient_matches_closed_form() → None

Match the inner-potential derivative with its analytic value.

For a real channel, the derivative equals TWO_ME_OVER_HBAR_SQ_INV_EV_ANG2 / (2*kz).

Notes

Differentiate at 50 eV photon energy and 0.7 1/Angstrom. Compare at rtol=1e-10 and require nonzero sensitivity.

Return type:

None

test_real_kz_increases_with_inner_potential() → None

Verify monotonic out-of-plane momentum in the inner potential.

The free-electron radicand increases linearly with the inner potential. Thus, each positive real root must increase.

Notes

Hypothesis generates twenty photon energies and ordered potentials. Compare real roots at fixed work function and parallel momentum.

Return type:

None

test_vmap_gradient_matches_elementwise_gradients() → None

Match vmapped and elementwise photon-energy gradients.

Vmap must not change the gradient of the out-of-plane momentum. The comparison uses four photon energies and relative tolerance 1e-14.

Notes

Differentiate one scalar real root. Apply JIT and vmap to the gradient and compare with an eager stack.

Return type:

None

test_large_photon_energy_vmap_has_static_shape() → None

Verify a large JIT-vmap raster has the required static shape.

The raster contains 64 photon energies and 256 squared parallel momenta. The operation must not construct a quadratic point matrix.

Notes

JIT one vmap over photon energy. Check the two output shapes and all finite complex values.

Return type:

None

class tests.test_diffpes.test_simul.test_kinematics.TestEmissionAngles(*args, **kwargs) → None

Bases: TestCase

Validate emission_angles().

The tests cover Cartesian directions, the normal-emission gauge, batched JIT execution, and finite-difference gradients away from the pole.

See:

emission_angles()

test_cardinal_directions_and_normal_emission() → None

Match cardinal angles and the normal-emission gauge convention.

Positive x has polar angle pi/2 and zero azimuth. Positive y has azimuth pi/2. Positive z selects two zero angles.

Notes

Pass all three directions as one batch through JIT. Compare each angle at absolute tolerance 1e-14.

Return type:

None

test_generic_gradients_match_finite_differences() → None

Match angle gradients with central finite differences.

The generic vector stays outside the punctured normal-emission neighborhood. A weighted angle sum depends on all vector components.

Notes

Use [0.7, -0.4, 1.2] in 1/Angstrom. Apply the shared gradient harness in both autodiff modes.

Return type:

None

test_normal_emission_selects_zero_angle_gradients() → None

Verify finite zero angle gradients at normal emission.

Azimuth has no physical value at the pole. The safe coordinate primitives assign no derivative to either angle there.

Notes

Compute the Jacobian of both angles at the positive z direction. Compare it with a zero matrix exactly.

Return type:

None

class tests.test_diffpes.test_simul.test_kinematics.TestDetectorAnglesToKpar(*args, **kwargs) → None

Bases: TestCase

Validate detector_angles_to_kpar().

The tests cover both slit conventions, the Rodrigues frame, JIT, and gradients in both angles and kinetic energy.

See:

detector_angles_to_kpar()

test_matches_closed_form_rotation() → None

Match the closed-form detector rotation for both slits.

The expected components follow the Plan 03 matrix products. The test also verifies static-slit JIT compilation.

Notes

Use angles 0.23 and -0.17 radians with 35 eV kinetic energy. Compare at rtol=1e-14.

Return type:

None

test_gradients_match_finite_differences() → None

Match angle and energy gradients with finite differences.

A generic weighted momentum sum depends on all three traced inputs. Both slit branches must retain this sensitivity.

Notes

Use nonzero angles and 42 eV kinetic energy. Apply the shared harness in forward and reverse autodiff modes.

Return type:

None

test_normal_emission_jacobian_matches_frame() → None

Match the Cartesian detector Jacobian at normal emission.

The direction vector remains smooth when both detector angles vanish. Each slit gives a different signed permutation of the tangent axes.

Notes

Differentiate the two parallel components with respect to both angles. Compare each Jacobian with its closed form exactly.

Return type:

None

test_rejects_unknown_slit() → None

Verify that the detector map rejects an unknown slit.

The slit controls a static Python branch. Only horizontal and vertical orientations define a detector convention.

Notes

Pass the value "bad" with scalar arrays. Require ValueError with the slit validation message.

Return type:

None

class tests.test_diffpes.test_simul.test_kinematics.TestKparToDetectorAngles(*args, **kwargs) → None

Bases: TestCase

Validate kpar_to_detector_angles().

Property tests cover both exact detector-map compositions. Additional checks cover JIT, vmap, and static slit validation.

See:

kpar_to_detector_angles()

test_angle_round_trip() → None

Round-trip random detector angles for both slit conventions.

The generated angles stay on the positive-normal branch. Their parallel momenta therefore have magnitude below 0.95*k_f.

Notes

Compose the forward and inverse maps for each slit. Compare both angles at absolute tolerance 1e-12.

Return type:

None

test_parallel_momentum_round_trip() → None

Round-trip random parallel momenta for both slit conventions.

The generated normalized magnitude stays below 0.85. This bound lies inside the open physical domain required by the inverse.

Notes

Scale the normalized components by k_f at 40 eV. Compose inverse and forward maps at absolute tolerance 1e-12.

Return type:

None

test_jit_and_vmap_preserve_round_trip() → None

Verify batched round trips under static-slit JIT compilation.

Five detector-angle pairs exercise the broadcast and vmap paths. The recovered angles must equal their inputs.

Notes

Vmap both public maps over scalar angle pairs. JIT each vmap and compare at rtol=1e-13.

Return type:

None

test_inverse_gradients_match_finite_differences() → None

Match inverse-map gradients with central finite differences.

A generic weighted angle sum depends on parallel momentum and kinetic energy. Both slit branches must retain these sensitivities.

Notes

Use an interior parallel momentum at 38 eV. Apply the shared harness in forward and reverse autodiff modes.

Return type:

None

test_rejects_unknown_slit() → None

Verify that the inverse map rejects an unknown slit.

The inverse shares the static slit contract with the forward detector map. An unsupported string must fail before numerical work.

Notes

Pass the value "bad" with one parallel vector. Require ValueError with the slit validation message.

Return type:

None

Validate orbital angular momentum calculation.

Extended Summary

The tests exercise diffpes.simul.compute_oam(). They verify the (K, B, A, 3) output shape and finite values. They also verify that the total channel equals the sum of the p and d channels.

class tests.test_diffpes.test_simul.test_oam.TestComputeOam(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.simul.oam.compute_oam().

The tests verify the output shape and finite p, d, and total contributions.

See:

compute_oam()

test_output_shape() → None

Verify OAM array has shape (K, B, A, 3).

The test establishes the output shape contract for compute oam with the concrete values and array shapes described below.

Notes

1. Setup: Create projections of shape (4, 3, 2, 9) (K=4, B=3, A=2) with uniform values.

2. Call: compute_oam(projections).

3. Check: Assert output shape (4, 3, 2, 3) and all finite.

Expected assertions

OAM shape is (K, B, A, 3) with [p_oam, d_oam, total_oam].

Return type:

None

test_total_is_p_plus_d() → None

Verify that the total OAM channel equals the sum of p and d channels.

The test establishes the total is p plus d contract for compute oam with the concrete values and array shapes described below.

Notes

1. Setup: Create projections of shape (2, 2, 1, 9) with uniform value 0.2.

2. Call: compute_oam(projections) yields oam with shape (2, 2, 1, 3).

3. Check: The third channel (index 2) should equal the sum of the first (p) and second (d) channels.

Expected assertions

oam[…, 0] + oam[…, 1] equals oam[…, 2] to within 1e-12, confirming the total OAM is the sum of p and d contributions.

Return type:

None

Exercise Plan 02 cross-cutting differentiability and scalability gates.

Extended Summary

Validates the migrated carrier seams of the novice forward chain, JIT cache behavior across dynamic and static fields, and vectorization over a batched simulation-parameter leaf.

class tests.test_diffpes.test_simul.test_plan02_gates.TestNoviceCarrierGradients

Bases: object

Validate autodiff across each migrated novice-chain carrier seam.

See:

diffpes.simul.simulate_novice()

test_gradients_match_finite_differences() → None

Match central differences for bands, projections, and parameters.

Return type:

None

Extended Summary

The test differentiates summed spectral intensity through each complete carrier on the pinned [-1, +1] eV two-band fixture. Automatic reverse-mode derivatives must agree with the shared central-FD gate.

Notes

The test uses a sixteen-point energy grid to keep the full leafwise FD census small while retaining both occupied and underflowed unoccupied bands.

class tests.test_diffpes.test_simul.test_plan02_gates.TestNoviceScalability

Bases: object

Validate Plan 02 JIT-cache and batched-leaf scalability floors.

See:

diffpes.simul.simulate_novice()

test_compile_count_tracks_only_static_changes() → None

Compile once for data changes and once per fidelity change.

Return type:

None

Extended Summary

Same-shaped carrier leaf changes reuse one trace. Changing the static SimulationParams.fidelity field triggers exactly one additional trace because it changes the output energy-axis shape.

Notes

A Python counter records traces around the JIT simulation. The test blocks completed outputs so asynchronous dispatch cannot hide additional traces.

test_vmap_over_sigma_leaf() → None

Vectorize a parameter leaf into (P, K, E) intensity.

Return type:

None

Extended Summary

The test maps three Gaussian widths over shared carriers. The output retains the parameter, k-point, and energy axes.

Notes

The test builds each mapped parameter carrier with equinox.tree_at() and evaluates the production forward function under jax.vmap().

Validate ARPES polarization and detector-frame functions.

Extended Summary

Exercise build_polarization_vectors, build_efield, and dipole_matrix_elements. Verify the polarization basis and each field mode. Check dipole matrix element shape and sign. Compare the detector frame with an offline table from the pinned Chinook source.

class tests.test_diffpes.test_simul.test_polarization.TestBuildPolarizationVectors(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.simul.polarization.build_polarization_vectors().

Verifies the geometric properties of the s- and p-polarization basis vectors, including mutual orthogonality, unit norm, and correct output shape for various incidence angle combinations.

See:

build_polarization_vectors()

test_orthogonality() → None

Verify that e_s and e_p are mutually orthogonal.

The test establishes the orthogonality contract for build polarization vectors with the concrete values and array shapes described below.

Notes

1. Build polarization vectors: Calls build_polarization_vectors with theta=pi/4, phi=0 to produce s- and p-polarization unit vectors.

2. Compute dot product: Takes the inner product of e_s and e_p.

Expected assertions

The dot product of e_s and e_p is zero (within tolerance 1e-10), confirming the two vectors are perpendicular.

Return type:

None

test_unit_vectors() → None

Verify that both e_s and e_p have unit norm.

The test establishes the unit vectors contract for build polarization vectors with the concrete values and array shapes described below.

Notes

1. Build polarization vectors: Call build_polarization_vectors with theta=pi/3 and phi=pi/6.

2. Compute norms: Calculates the Euclidean norm of each vector.

Expected assertions

Both vectors have unit norm within tolerance 1e-10.

Return type:

None

test_shape() → None

Verify that the output vectors have the correct 3D shape.

The test establishes the shape contract for build polarization vectors with the concrete values and array shapes described below.

Notes

1. Build polarization vectors: Calls build_polarization_vectors with theta=0.5, phi=0.0.

2. Check shapes: Confirms both returned arrays have shape (3,).

Expected assertions

Both e_s and e_p have shape (3,), matching the 3D Cartesian coordinate system.

Return type:

None

test_is_smooth_across_the_old_collinearity_threshold() → None

Keep one transverse frame across near-normal incidence angles.

The basis must not jump when the photon direction crosses the former reference-axis threshold. Its angle Jacobian must match the analytic trigonometric basis on both sides.

Notes

Evaluate two angles around arccos(0.99) at a fixed azimuth. Compare both bases and both theta derivatives with their closed forms.

Return type:

None

class tests.test_diffpes.test_simul.test_polarization.TestPhotonWavevector(*args, **kwargs) → None

Bases: TestCase

Validate photon_wavevector().

Covers the spherical-angle convention and unit normalization for photon propagation along the surface normal and in the surface plane.

See:

photon_wavevector()

test_matches_cardinal_incidence_directions() → None

Match normal and grazing incidence to Cartesian unit vectors.

Map zero polar angle to positive z. Map a right-angle polar angle at zero azimuth to positive x within float64 tolerance.

Notes

Evaluate two scalar angle pairs. Compare both vectors with analytic Cartesian directions at atol=1e-12. Check their unit norms.

Return type:

None

class tests.test_diffpes.test_simul.test_polarization.TestBuildEfield(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.simul.polarization.build_efield().

Verify the electric field for each polarization type. Check the LVP, LHP, RCP, and LCP relations.

See:

build_efield()

test_lvp_equals_s() → None

Verify that LVP (linear vertical polarization) yields the s-polarization vector.

The test establishes the lvp equals s contract for build efield with the concrete values and array shapes described below.

Notes

1. Build E-field with LVP config: Create an LVP configuration at theta=pi/4 and phi=0. Compute its electric field vector.

2. Build reference s-polarization vector: Independently computes e_s using build_polarization_vectors with the same angles.

3. Compare real parts: Checks that the real part of the E-field matches e_s.

Expected assertions

The real part of the LVP E-field equals the s-polarization vector within tolerance 1e-10.

Return type:

None

test_lhp_equals_p() → None

Verify that LHP (linear horizontal polarization) yields the p-polarization vector.

The test establishes the lhp equals p contract for build efield with the concrete values and array shapes described below.

Notes

1. Build E-field with LHP config: Create an LHP configuration at theta=pi/4 and phi=0. Compute its electric field vector.

2. Build reference p-polarization vector: Independently computes e_p using build_polarization_vectors with the same angles.

3. Compare real parts: Checks that the real part of the E-field matches e_p.

Expected assertions

The real part of the LHP E-field equals the p-polarization vector within tolerance 1e-10.

Return type:

None

test_rcp_lcp_conjugate() → None

Verify that RCP and LCP E-fields share the same real part.

The test establishes the rcp lcp conjugate contract for build efield with the concrete values and array shapes described below.

Notes

1. Build RCP and LCP E-fields: Create RCP and LCP configurations at theta=pi/4 and phi=0. Compute both E-field vectors.

2. Compare real parts: Use the circular-polarization definitions. Compare their common real part, e_s/sqrt(2).

Expected assertions

The real parts of the RCP and LCP E-fields are equal within tolerance 1e-10, confirming the conjugate symmetry relationship.

Return type:

None

test_lap_linear_combination() → None

Verify that LAP (linear arbitrary) yields cos(angle)*e_s + sin(angle)*e_p.

The test establishes the lap linear combination contract for build efield with the concrete values and array shapes described below.

Notes

1. Build E-field with LAP config: Create an LAP configuration with polarization_angle=0.3. Compute its electric field.

2. Build e_s and e_p with the same angles. Form the expected combination cos(0.3)*e_s + sin(0.3)*e_p.

3. Compare: E-field matches the expected combination.

Expected assertions

LAP E-field equals the linear combination of s- and p-vectors at the given polarization angle.

Return type:

None

test_unknown_pol_type_fallback_to_s() → None

Verify that unknown polarization type falls back to e_s.

The test establishes the unknown pol type fallback to s contract for build efield with the concrete values and array shapes described below.

Notes

1. Build E-field with an unsupported type (e.g. “unpolarized”): build_efield treats it as the default branch and returns e_s.

2. Compare real part of E-field to e_s from build_polarization_vectors.

Expected assertions

The default/else branch returns the s-polarization vector.

Return type:

None

class tests.test_diffpes.test_simul.test_polarization.TestDipoleMatrixElements(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.simul.polarization.dipole_matrix_elements().

Verify the output shape and the zero s-orbital element. Check px coupling and non-negative elements for arbitrary polarization.

See:

dipole_matrix_elements()

test_shape() → None

Verify that the output has shape (9,) for the 9-orbital basis.

The test establishes the shape contract for dipole matrix elements with the concrete values and array shapes described below.

Notes

1. Create x-polarized E-field: Constructs a complex E-field vector along the x-axis.

2. Compute matrix elements: Calls dipole_matrix_elements and checks the output shape.

Expected assertions

The output array has shape (9,), one element per orbital in the [s, py, pz, px, dxy, dyz, dz2, dxz, dx2-y2] basis.

Return type:

None

test_s_orbital_zero() → None

Verify that the s-orbital dipole matrix element is always zero.

The test establishes the s orbital zero contract for dipole matrix elements with the concrete values and array shapes described below.

Notes

1. Create x-polarized E-field: Constructs a complex E-field vector along the x-axis.

2. Compute matrix elements: Calls dipole_matrix_elements and inspects the s-orbital entry (index 0).

Expected assertions

The s-orbital direction vector is [0, 0, 0]. Its matrix element is zero within tolerance 1e-10 for any electric field.

Return type:

None

test_px_with_x_field() → None

Verify that an x-polarized field produces a positive px matrix element.

The test establishes the px with x field contract for dipole matrix elements with the concrete values and array shapes described below.

Notes

1. Create x-polarized E-field: Constructs a complex E-field vector purely along the x-axis.

2. Compute matrix elements: Calls dipole_matrix_elements and inspects the px-orbital entry (index 3), whose direction vector is [1, 0, 0].

Expected assertions

The px-orbital matrix element (index 3) is strictly positive, confirming that the x-polarized field couples to the px-orbital via the dipole selection rule.

Return type:

None

test_all_nonnegative() → None

Verify that all dipole matrix elements are non-negative for arbitrary polarization.

The test establishes the all nonnegative contract for dipole matrix elements with the concrete values and array shapes described below.

Notes

1. Create arbitrary normalized E-field: Create a complex field with components [0.5, 0.3, 0.8]. Normalize it to unit length.

2. Compute matrix elements: Calls dipole_matrix_elements on the normalized field.

3. Check non-negativity of all elements: Iterates over all 9 entries and asserts each is >= 0.

Expected assertions

Every element of the 9-element matrix element vector is non-negative, as expected from the squared-modulus definition |e . d|^2 >= 0.

Return type:

None

class tests.test_diffpes.test_simul.test_polarization.TestPolarizationFromAngles(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.simul.polarization.polarization_from_angles().

The tests verify each static polarization selector and the traced linear angle against the transverse basis.

See:

polarization_from_angles()

test_constructs_standard_states() → None

Verify standard states against the transverse basis.

The test constructs all static states at one incidence geometry and compares each vector with its closed-form basis combination.

Notes

Evaluate one generic incidence geometry. Compare four polarization kinds with the analytic transverse-basis combinations at 1e-14.

Return type:

None

test_rejects_unknown_kind() → None

Verify rejection of an unknown polarization kind.

The test calls the constructor with an unregistered static selector and checks the specific validation error.

Notes

Pass "unknown" as the static selector. Require ValueError with the polarization-kind message.

Return type:

None

class tests.test_diffpes.test_simul.test_polarization.TestPolarizationToSpherical(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.simul.polarization.polarization_to_spherical().

The tests pin the Condon-Shortley convention, norm preservation, and the complex-linear derivative.

See:

polarization_to_spherical()

test_matches_closed_form_states() → None

Verify circular and linear closed-form states.

The test transforms both helicities and Cartesian x polarization and compares their spherical components with analytic values.

Notes

Build two circular states and one linear state. Compare their ordered spherical components with the Condon-Shortley values at 1e-15.

Return type:

None

test_preserves_norm_and_jvp() → None

Verify norm preservation and the complex-linear JVP.

The test transforms a generic complex vector and tangent, then checks the norm identity and the exact transformed tangent.

Notes

Apply a JAX JVP to a generic complex vector. Compare the norm and tangent identities at 1e-14.

Return type:

None

class tests.test_diffpes.test_simul.test_polarization.TestDetectorRotation(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.simul.polarization.detector_rotation().

The tests compare both slit conventions with closed forms and exercise their traced angle derivatives.

See:

detector_rotation()

test_rotates_reference_direction_for_both_slits() → None

Verify both slit conventions against closed forms.

The test rotates the reference z direction and compares both results with their analytic trigonometric expressions.

Notes

Use two nonzero detector angles. Compare the horizontal and vertical directions with their closed forms at 1e-14.

Return type:

None

test_is_proper_and_differentiable() → None

Verify proper rotation and a nonzero angle derivative.

The test checks orthogonality, determinant, and the derivative of one emitted-direction component with respect to the first angle.

Notes

Compute one horizontal rotation. Differentiate its x direction and compare the result with the analytic cosine at 1e-14.

Return type:

None

test_matches_pinned_chinook_artifact() → None

Match the pinned Chinook direction and polarization table.

The artifact records both declared coordinate remaps. It contains the full rotation, direction, and three complex polarization states.

Notes

Load gate 03.G4 without a Chinook import. Compare all points on the two 5 by 5 angle grids at the recorded relative tolerance.

Return type:

None

test_rejects_unknown_slit() → None

Verify rejection of an unknown slit orientation.

The test calls the frame constructor with an unsupported static slit value and checks the validation error.

Notes

Pass "X" as the slit. Require ValueError with the slit validation message.

Return type:

None

class tests.test_diffpes.test_simul.test_polarization.TestRotateFrameVectors(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.simul.polarization.rotate_frame_vectors().

The test checks the detector-grid shape, vector norms, and mapped frame values for a real vector.

See:

rotate_frame_vectors()

test_maps_real_vector_over_grid() → None

Verify mapped real-vector values and shape.

The test rotates one normalized vector over two angle axes and checks each result against direct detector-frame multiplication.

Notes

Use a 2 by 3 horizontal angle grid. Check its shape, norms, and one direct matrix product at 1e-14.

Return type:

None

class tests.test_diffpes.test_simul.test_polarization.TestRotatePolarizationGrid(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.simul.polarization.rotate_polarization_grid().

The test checks complex phase preservation, detector-grid shape, and differentiation through the mapped detector angles.

See:

rotate_polarization_grid()

test_maps_complex_polarization_and_gradients() → None

Verify complex grid values and angle gradients.

The test rotates a generic complex vector and compares one cell with direct multiplication. It also checks a nonzero mapped derivative.

Notes

Use a 2 by 2 vertical angle grid. Compare one cell and differentiate one real component with respect to the first angle.

Return type:

None

Validate momentum resolution broadening.

Extended Summary

Apply diffpes.simul.resolution.apply_momentum_broadening() to a 2D ARPES intensity map. Test the identity limit, smoothing, conservation, shape, and gradients.

class tests.test_diffpes.test_simul.test_resolution.TestApplyMomentumBroadening

Bases: object

Validate diffpes.simul.resolution.apply_momentum_broadening().

Validate Gaussian momentum broadening along the k-axis. Verify the identity limit, smoothing, conservation, shape, and JAX gradients.

See:

apply_momentum_broadening()

test_identity_with_zero_dk() → None

Verify that vanishing dk returns approximately the original intensity.

The test establishes the identity with zero dk contract for apply momentum broadening with the concrete values and array shapes described below.

Notes

1. Setup: Create a uniform intensity map of shape (20, 50) and a linearly spaced k_distances array from 0 to 1. Set dk = 1e-15 so that the kernel approaches a delta function.

2. Apply broadening: Call apply_momentum_broadening with the near-zero dk.

3. Compare: Assert the result is element-wise close to the original intensity within atol=1e-3.

Expected assertions

The broadened intensity equals the input to within 1e-3, confirming the correct identity limit when the broadening width vanishes.

Return type:

None

test_smoothing_effect() → None

Verify that finite dk smooths a delta-like peak along the k-axis.

The test establishes the smoothing effect contract for apply momentum broadening with the concrete values and array shapes described below.

Notes

1. Setup: Create a zero intensity map of shape (50, 10). Set k-index 25 to 1.0 across all energy channels.

2. Apply broadening: Call apply_momentum_broadening with dk=0.1, which should spread the peak to neighbouring k-points via the Gaussian kernel.

3. Check peak reduction: Assert that the peak value at index 25 falls below 1.0.

4. Check neighbour activation: Assert that indices 24 and 26 have positive intensity.

Expected assertions

The peak decreases and its neighbours gain intensity. Thus, the Gaussian convolution smooths sharp k-space features.

Return type:

None

test_conservation() → None

Verify approximate conservation of intensity under broadening.

The test establishes the conservation contract for apply momentum broadening with the concrete values and array shapes described below.

Notes

1. Setup: Create a 2D intensity map (30 x 20) with a spatially varying (sinusoidal) k-profile broadcast across all energy channels. Use dk=0.05 for moderate broadening.

2. Apply broadening: Call apply_momentum_broadening.

3. Compare totals: Assert the summed intensity before and after broadening agree within 10% relative tolerance.

Expected assertions

The total intensity changes by less than 10%. Grid boundaries truncate the Gaussian kernel and prevent exact conservation.

Return type:

None

test_output_shape() → None

Verify that the output shape matches the input shape.

The test establishes the output shape contract for apply momentum broadening with the concrete values and array shapes described below.

Notes

1. Setup: Create a uniform intensity map of shape (15, 25) and apply momentum broadening with dk=0.1.

2. Check shape: Assert the output shape is (15, 25), identical to the input.

Expected assertions

The output shape equals the input shape (K, E), confirming that the convolution does not alter the grid dimensions.

Return type:

None

test_gradient_wrt_dk() → None

Verify that the gradient of total intensity w.r.t. dk is finite.

The test establishes the gradient wrt dk contract for apply momentum broadening with the concrete values and array shapes described below.

Notes

1. Setup: Create a uniform intensity map of shape (10, 5). Define a loss that sums the broadened intensity.

2. Differentiate: Call jax.grad(loss)(0.1) to compute the gradient of the loss with respect to dk.

3. Check finiteness: Assert the gradient is finite.

Expected assertions

The gradient with respect to dk is finite. This result supports inverse fitting with dk as a learnable instrument parameter.

Return type:

None

Validate energy-dependent self-energy evaluation.

Extended Summary

Validates diffpes.simul.self_energy.evaluate_self_energy(), which computes lifetime broadening as a function of binding energy. Exercise constant, polynomial, and tabulated modes. Verify their values and JAX gradients.

class tests.test_diffpes.test_simul.test_self_energy.TestEvaluateSelfEnergy

Bases: object

Validate diffpes.simul.self_energy.evaluate_self_energy().

Validates the three self-energy evaluation modes – constant, polynomial, and tabulated – by checking exact functional values at known energy points. Also verifies JAX differentiability of the constant and polynomial modes by asserting that jax.grad produces finite gradients with respect to the self-energy coefficients.

See:

evaluate_self_energy()

test_constant_mode() → None

Verify that constant mode returns the same gamma at every energy.

The test establishes the constant mode contract for evaluate self energy with the concrete values and array shapes described below.

Notes

1. Setup: Create a self-energy config with mode=”constant” and gamma=0.15 eV. Evaluate at 100 energy points spanning [-3, 1] eV.

2. Check: Assert all 100 returned gamma values equal 0.15.

Expected assertions

Every output element equals 0.15. Thus, constant mode returns a uniform broadening width.

Return type:

None

test_polynomial_mode() → None

Verify that polynomial mode evaluates gamma(E) = c0 + c1*E correctly.

The test establishes the polynomial mode contract for evaluate self energy with the concrete values and array shapes described below.

Notes

1. Setup: Create a polynomial configuration with coefficients [0.05, 0.1]. Evaluate gamma(E) = 0.05*E + 0.1 at three points.

2. Check: Assert the returned values match the analytically expected [0.1, 0.15, 0.05] to within atol=1e-10.

Expected assertions

The results match the analytic values at three energies. The coefficient order follows jnp.polyval semantics.

Return type:

None

test_tabulated_mode() → None

Verify that tabulated mode interpolates gamma between energy nodes.

The test establishes the tabulated mode contract for evaluate self energy with the concrete values and array shapes described below.

Notes

1. Setup: Create a self-energy config with mode=”tabulated”, energy_nodes=[-3.0, 0.0, 1.0] and coefficients=[0.05, 0.1, 0.2]. Evaluate at E = [0.0, 0.5]. The first point is a node, and the second point is midway between two nodes.

2. Check exact node: Assert gamma(0.0) = 0.1 (direct lookup).

3. Check interpolated point: Assert gamma(0.5) = 0.15, the linear interpolation midpoint between 0.1 and 0.2.

Expected assertions

The function returns exact node values and correct interpolated values between nodes.

Return type:

None

test_constant_gradient() → None

Verify that the gradient w.r.t. constant self-energy coefficient is finite.

The test establishes the constant gradient contract for evaluate self energy with the concrete values and array shapes described below.

Notes

1. Setup: Define a loss from one constant coefficient. Evaluate two energies and sum their gamma values.

2. Differentiate: Call jax.grad(loss)(0.1) to compute the gradient w.r.t. the constant coefficient.

3. Check finiteness: Assert the gradient is finite.

Expected assertions

The gradient w.r.t. the constant self-energy coefficient is finite, confirming that the constant evaluation path is differentiable through JAX and suitable for inverse fitting.

Return type:

None

test_polynomial_gradient() → None

Verify that gradients w.r.t. polynomial coefficients are finite.

The test establishes the polynomial gradient contract for evaluate self energy with the concrete values and array shapes described below.

Notes

1. Setup: Define a polynomial loss from coefficients [c1, c0]. Evaluate 50 energies and sum their gamma values.

2. Differentiate: Call jax.grad(loss) with initial coefficients [0.01, 0.1] to compute the gradient vector.

3. Check finiteness: Assert all gradient components are finite.

Expected assertions

All gradient components w.r.t. the polynomial coefficients are finite, confirming that the polynomial evaluation via jnp.polyval is differentiable through JAX. This enables fitting energy-dependent self-energy models to experimental linewidths.

Return type:

None

class tests.test_diffpes.test_simul.test_self_energy.TestSelfEnergyErrors

Bases: object

Validate invalid mode handling in evaluate_self_energy.

Validates that evaluate_self_energy raises ValueError when given a SelfEnergyConfig with an unsupported mode string.

See:

evaluate_self_energy()

test_unknown_mode_raises() → None

Verify that an unknown self-energy mode raises ValueError.

Construct a SelfEnergyConfig with mode=”bad_mode”. Call evaluate_self_energy and require ValueError with the expected message.

Notes

The test builds the inputs in the test body and checks the stated property with the documented numerical or structural assertions.

Return type:

None

Validate ARPES simulation spectrum functions.

Extended Summary

Validate all simulation levels in diffpes.simul.spectrum. Check shapes, value constraints, and sensitivity to physical parameters. Generate synthetic data for the tests. Require spin data for SOC tests.

class tests.test_diffpes.test_simul.test_spectrum.TestSimulateNovice(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.simul.spectrum.simulate_novice().

Verifies the novice-level simulation (Voigt broadening with uniform orbital weights) including output tensor shapes and non-negativity of the intensity map.

See:

simulate_novice()

test_output_shape() → None

Verify that intensity and energy axis have the expected shapes.

The test establishes the output shape contract for simulate novice with the concrete values and array shapes described below.

Notes

1. Setup: Generate synthetic data with 20 k-points and 5 bands, and create simulation parameters with fidelity=500 energy points.

2. Simulate: Run simulate_novice to produce an ArpesSpectrum.

3. Check shapes: Assert that intensity is (20, 500) (k-points by energy) and energy_axis is (500,).

Expected assertions

The intensity shape matches (n_kpoints, fidelity) and the energy axis length matches fidelity.

Return type:

None

test_nonnegative_intensity() → None

Verify that all intensity values are non-negative.

The test establishes the nonnegative intensity contract for simulate novice with the concrete values and array shapes described below.

Notes

1. Setup: Generate synthetic data and simulation parameters with fidelity=200.

2. Simulate: Run simulate_novice to produce an ArpesSpectrum.

3. Check non-negativity: Assert that the minimum intensity value is at least -1e-10 (allowing for negligible floating-point undershoot).

Expected assertions

The minimum intensity is effectively non-negative, confirming that the Voigt convolution with Fermi-Dirac occupation does not produce physically impossible negative spectral weight.

Return type:

None

class tests.test_diffpes.test_simul.test_spectrum.TestSimulateBasic(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.simul.spectrum.simulate_basic().

Verifies the basic-level simulation (Gaussian broadening with heuristic orbital weights) including output tensor shape and finiteness of all intensity values.

See:

simulate_basic()

test_output_shape() → None

Verify that the intensity array has the expected shape.

The test establishes the output shape contract for simulate basic with the concrete values and array shapes described below.

Notes

1. Setup: Generate synthetic data with 20 k-points and 5 bands, and create simulation parameters with fidelity=500.

2. Simulate: Run simulate_basic to produce an ArpesSpectrum.

3. Check shape: Assert that intensity is (20, 500).

Expected assertions

The intensity shape matches (n_kpoints, fidelity).

Return type:

None

test_finite_values() → None

Verify that all intensity values are finite (no NaN or Inf).

The test establishes the finite values contract for simulate basic with the concrete values and array shapes described below.

Notes

1. Setup: Generate synthetic data and simulation parameters with fidelity=200.

2. Simulate: Run simulate_basic to produce an ArpesSpectrum.

3. Check finiteness: Use chex.assert_tree_all_finite to confirm that no element of the intensity array is NaN or infinite.

Expected assertions

Every element of the intensity array is finite, confirming that the Gaussian convolution and heuristic weighting do not produce numerical overflow or undefined values.

Return type:

None

class tests.test_diffpes.test_simul.test_spectrum.TestSimulateBasicplus(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.simul.spectrum.simulate_basicplus().

Verifies the basicplus-level simulation (Gaussian broadening with Yeh-Lindau photoionization cross-sections) including output tensor shape and sensitivity of the spectrum to changes in photon energy.

See:

simulate_basicplus()

test_output_shape() → None

Verify that the intensity array has the expected shape.

The test establishes the output shape contract for simulate basicplus with the concrete values and array shapes described below.

Notes

1. Setup: Generate synthetic data with 20 k-points and 5 bands, and create simulation parameters with fidelity=500.

2. Simulate: Run simulate_basicplus to produce an ArpesSpectrum.

3. Check shape: Assert that intensity is (20, 500).

Expected assertions

The intensity shape matches (n_kpoints, fidelity).

Return type:

None

test_yeh_lindau_affects_weights() → None

Verify that different photon energies produce different spectra.

The test establishes the yeh lindau affects weights contract for simulate basicplus with the concrete values and array shapes described below.

Notes

1. Setup: Generate synthetic data and create two sets of simulation parameters that differ only in photon energy (20 eV vs 60 eV).

2. Simulate both: Run simulate_basicplus with each parameter set to produce two spectra.

3. Compare: Compute the total absolute difference between the two intensity arrays.

Expected assertions

The summed absolute intensity difference is positive. Thus, photon energy changes the Yeh-Lindau orbital weights.

Return type:

None

class tests.test_diffpes.test_simul.test_spectrum.TestSimulateAdvanced(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.simul.spectrum.simulate_advanced().

Verifies the advanced-level simulation (Gaussian broadening with Yeh-Lindau cross-sections and polarization selection rules) including output tensor shape and finiteness under unpolarized light conditions.

See:

simulate_advanced()

test_output_shape() → None

Verify that intensity has the expected shape under LVP polarization.

The test establishes the output shape contract for simulate advanced with the concrete values and array shapes described below.

Notes

1. Setup: Generate synthetic data with 20 k-points and 5 bands, create simulation parameters with fidelity=500, and configure linear vertical polarization (LVP).

2. Simulate: Run simulate_advanced with the polarization config to produce an ArpesSpectrum.

3. Check shape: Assert that intensity is (20, 500).

Expected assertions

The intensity shape matches (n_kpoints, fidelity), confirming that the polarization pathway produces correctly shaped output.

Return type:

None

test_unpolarized() → None

Verify that unpolarized light produces finite intensity values.

The test establishes the unpolarized contract for simulate advanced with the concrete values and array shapes described below.

Notes

1. Setup: Generate synthetic data, create simulation parameters with fidelity=200, and configure unpolarized light.

2. Simulate: Run simulate_advanced with unpolarized configuration, which averages s- and p-polarization contributions.

3. Check finiteness: Use chex.assert_tree_all_finite to confirm no NaN or Inf values in the intensity.

Expected assertions

All intensity values are finite, verifying that the unpolarized code path (averaging over orthogonal polarization vectors) does not introduce numerical instabilities.

Return type:

None

class tests.test_diffpes.test_simul.test_spectrum.TestSimulateExpert(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.simul.spectrum.simulate_expert().

Verify the expert simulation shape. Check finite results for unpolarized and circular light.

See:

simulate_expert()

test_output_shape() → None

Verify that intensity has the expected shape under LHP polarization.

The test establishes the output shape contract for simulate expert with the concrete values and array shapes described below.

Notes

1. Setup: Generate synthetic data with 20 k-points and 5 bands, create simulation parameters with fidelity=500, and configure linear horizontal polarization (LHP).

2. Simulate: Run simulate_expert with the polarization config to produce an ArpesSpectrum.

3. Check shape: Assert that intensity is (20, 500).

Expected assertions

The intensity shape matches (n_kpoints, fidelity), confirming that the expert-level polarization and Voigt broadening pathway produces correctly shaped output.

Return type:

None

test_unpolarized() → None

Verify that unpolarized light produces finite intensity values.

The test establishes the unpolarized contract for simulate expert with the concrete values and array shapes described below.

Notes

1. Setup: Generate synthetic data, create simulation parameters with fidelity=200, and configure unpolarized light.

2. Simulate: Run simulate_expert with unpolarized configuration, which averages s- and p-polarization dipole contributions.

3. Check finiteness: Use chex.assert_tree_all_finite to confirm no NaN or Inf values in the intensity.

Expected assertions

All intensity values are finite, verifying that the unpolarized code path with Voigt broadening and dipole matrix elements does not introduce numerical instabilities.

Return type:

None

test_circular_polarization() → None

Verify that right circular polarization (RCP) produces finite values.

The test establishes the circular polarization contract for simulate expert with the concrete values and array shapes described below.

Notes

1. Setup: Generate synthetic data, create simulation parameters with fidelity=200, and configure right circular polarization (RCP).

2. Simulate: Run simulate_expert with RCP configuration, which builds a complex electric-field vector and evaluates dipole matrix elements with Voigt broadening.

3. Check finiteness: Use chex.assert_tree_all_finite to confirm no NaN or Inf values in the intensity.

Expected assertions

All intensity values are finite. The complex electric field does not cause overflow or undefined values.

Return type:

None

class tests.test_diffpes.test_simul.test_spectrum.TestSimulateSoc(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.simul.spectrum.simulate_soc().

Verify that SOC requires spin data and produces the expected shapes. Compare zero and nonzero ls_scale values with expert results.

See:

simulate_soc()

test_output_shape() → None

Verify SOC spectrum has intensity (K, E) and energy_axis (E).

The test establishes the output shape contract for simulate soc with the concrete values and array shapes described below.

Notes

1. Setup: Build bands and orb_proj with spin via _make_synthetic_data_with_spin(); params with fidelity=100; unpolarized polarization config.

2. Simulate: Run simulate_soc with ls_scale=0.01.

3. Check shapes: Assert intensity shape (n_kpoints, 100) and energy_axis shape (100,); assert all intensity values are finite.

Expected assertions

Output shapes match the expert convention and the spectrum contains no NaN or Inf.

Return type:

None

test_soc_ls_scale_zero_matches_expert() → None

Verify that zero ls_scale reproduces the expert intensity.

The test establishes the soc ls scale zero matches expert contract for simulate soc with the concrete values and array shapes described below.

Notes

1. Setup: Synthetic data with spin; params and unpolarized pol_config.

2. Run both: Call simulate_expert and simulate_soc(..., ls_scale=0.0).

3. Compare: Assert intensity and energy_axis from both match to within 1e-12 absolute tolerance.

Expected assertions

With ls_scale=0, the SOC simulation reproduces the expert result.

Return type:

None

test_soc_nonzero_ls_scale_differs_from_expert() → None

Verify that nonzero ls_scale can change the SOC intensity.

The test establishes the soc nonzero ls scale differs from expert contract for simulate soc with the concrete values and array shapes described below.

Notes

1. Setup: Synthetic data with spin; params and unpolarized pol_config.

2. Run both: Call simulate_expert and simulate_soc(..., ls_scale=0.1).

3. Compare: Compute the maximum absolute difference between the two intensity arrays; assert it is greater than 1e-10.

Expected assertions

A nonzero ls_scale changes the intensity map. Thus, the spin correction affects the result.

Return type:

None

test_soc_polarized_light() → None

Verify that SOC simulation runs with polarized light (LHP).

The test establishes the soc polarized light contract for simulate soc with the concrete values and array shapes described below.

Notes

1. Setup: Build bands and spin-orbital projections. Create parameters with fidelity=100 and an LHP configuration. Use an explicit electric field for the dipole matrix elements.

2. Simulate: Run simulate_soc with ls_scale=0.02.

3. Check shape and finiteness: Assert intensity shape is (n_kpoints, 100) and all values are finite.

Expected assertions

The SOC simulation returns finite output with the expected shape. The polarized branch includes spin-orbit and dipole effects.

Return type:

None

Exercise the tight-binding radial differentiability smoke chain.

Extended Summary

Validates finite-difference-correct gradients through the diagonalized-band, Slater-radial, polarization, and simulation-parameter carrier seams. The eigenvector probe uses generic complex coefficients so conjugation errors cannot hide behind real or symmetric test data.

class tests.test_diffpes.test_simul.test_tb_radial_gradients.TestTBRadialCarrierGradients

Bases: object

Validate the carrier seams of the tight-binding radial forward.

See:

diffpes.simul.simulate_tb_radial()

test_carrier_gradient_smoke_chain() → None

Match FD through every requested radial-chain carrier seam.

Return type:

None

Extended Summary

The test differentiates one scalar spectrum observable. It covers eigenvalues, eigenvectors, Slater exponents, polarization angles, and continuous simulation parameters. Every selected leaf must retain finite, nonzero, FD-correct sensitivity.

Notes

The test builds the inputs in the test body and checks the stated property with the documented numerical or structural assertions.

class tests.test_diffpes.test_simul.test_tb_radial_gradients.TestTBRadialBaselineGradient

Bases: object

Pin the fully specified pre-migration graphene gradient baseline.

See:

diffpes.simul.simulate_tb_radial()

test_common_zeta_gradient_matches_v01_fixture() → None

Reproduce the tagged-v0.1 graphene/LHP common-zeta gradient.

Return type:

None

Extended Summary

The test uses the v0.1 graphene fixture. It contains three Gamma/K/M points, carbon 2p orbitals, 300 energies, and 2,000 radial points. An independent run against tag v0.1 supplies the expected derivative.

Notes

The test builds the inputs in the test body and checks the stated property with the documented numerical or structural assertions.

Validate high-level workflow helpers in diffpes.simul.workflow.

Extended Summary

Validates VASP context loading, projection preparation, simulation dispatch, and the combined file-to-spectrum workflow with controlled temporary inputs.

class tests.test_diffpes.test_simul.test_workflow.TestLoadVaspContextEdgeCases(*args, **kwargs) → None

Bases: TestCase

Validate additional paths in diffpes.simul.load_vasp_context().

See:

load_vasp_context()

test_no_doscar_fermi_defaults_to_zero() → None

Verify Fermi energy is 0.0 when doscar_file=None and fermi_energy=None.

The test passes doscar_file=None and fermi_energy=None, exercising workflow.py line 142 (resolved_fermi = 0.0). Asserts the returned band structure has fermi_energy == 0.0.

Notes

The test builds the inputs in the test body and checks the stated property with the documented numerical or structural assertions.

Return type:

None

test_missing_doscar_raises() → None

Verify that a missing required DOSCAR raises FileNotFoundError.

The test passes a non-existent doscar_file with fermi_energy=None, exercising workflow.py lines 146-150 (FileNotFoundError path).

Notes

The test builds the inputs in the test body and checks the stated property with the documented numerical or structural assertions.

Return type:

None

test_explicit_fermi_reads_doscar_optionally() → None

Verify optional DOSCAR loading with an explicit Fermi energy.

The test passes fermi_energy=1.5 and a valid doscar_file, exercising workflow.py lines 154-158 (optional DOSCAR read). The explicit Fermi energy controls the bands, and the file supplies dos.

Notes

The test builds the inputs in the test body and checks the stated property with the documented numerical or structural assertions.

Return type:

None

class tests.test_diffpes.test_simul.test_workflow.TestLoadVaspContext(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.simul.load_vasp_context().

See:

load_vasp_context()

test_loads_context_with_optional_dos_and_kpath() → None

Verify context loading with inferred Fermi level and checks.

The test establishes the loads context with optional dos and kpath contract for load vasp context with the concrete values and array shapes described below.

Notes

The test builds the inputs in the test body and checks the stated property with the documented numerical or structural assertions.

Return type:

None

class tests.test_diffpes.test_simul.test_workflow.TestPrepareProjection(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.simul.prepare_projection().

See:

prepare_projection()

test_spin_orbital_projection_attaches_oam() → None

Verify OAM attachment works for SpinOrbitalProjection input.

The test constructs a SpinOrbitalProjection and calls prepare_projection with attach_oam=True. Asserts the returned object is still a SpinOrbitalProjection with OAM attached, covering workflow.py line 224 (make_spin_orbital_projection with oam).

Notes

The test builds the inputs in the test body and checks the stated property with the documented numerical or structural assertions.

Return type:

None

test_selects_atoms_and_attaches_oam() → None

Verify atom sub-selection and OAM attachment in one call.

The test establishes the selects atoms and attaches oam contract for prepare projection with the concrete values and array shapes described below.

Notes

The test builds the inputs in the test body and checks the stated property with the documented numerical or structural assertions.

Return type:

None

class tests.test_diffpes.test_simul.test_workflow.TestSimulateContext(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.simul.simulate_context().

See:

simulate_context()

test_momentum_broadening_changes_output() → None

Verify nonzero dk changes simulated intensity.

The test establishes the momentum broadening changes output contract for simulate context with the concrete values and array shapes described below.

Notes

The test builds the inputs in the test body and checks the stated property with the documented numerical or structural assertions.

Return type:

None

test_loaded_fermi_energy_gradient_matches_fd() → None

Propagate the loaded Fermi energy through the workflow gradient.

Return type:

None

Extended Summary

The test traces an explicit scalar Fermi energy through load_vasp_context and simulate_context. Its finite, nonzero derivative matches central differences at rtol=1e-5.

Notes

The test loads two-k-point spin fixtures inside the traced loss. It simulates the basic level at 300 K and checks the summed intensity with the shared gradient harness.

class tests.test_diffpes.test_simul.test_workflow.TestRunVaspWorkflow(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.simul.run_vasp_workflow().

See:

run_vasp_workflow()

test_runs_end_to_end_with_normalization() → None

Verify one-call workflow runs and returns normalized spectrum.

The test establishes the runs end to end with normalization contract for run vasp workflow with the concrete values and array shapes described below.

Notes

The test builds the inputs in the test body and checks the stated property with the documented numerical or structural assertions.

Return type:

None