diffpes.tightb tests

Validation and regression tests for diffpes.tightb.

Validate differentiable diagonalization and the VASP adapter.

Extended Summary

The tests validate the single-k solver, the multi-k solver, and the VASP adapter. They cover eigensystem properties, gradients, output shapes, and the policy for phase loss.

class tests.test_diffpes.test_tightb.test_diagonalize.TestDiagonalizeSingleK

Bases: object

Validate diagonalize_single_k.

The tests verify the real eigenvalues and the orthonormal eigenvectors of a Hermitian matrix.

See:

diagonalize_single_k()

test_eigenvalues_real() → None

Verify the Hermitian solver returns real eigenvalues.

The Hermitian eigensolver produces a float64 eigenvalue array from a complex128 input matrix.

Notes

The test diagonalizes a 2x2 matrix with complex off-diagonal entries. It compares the eigenvalue dtype with jnp.float64.

Return type:

None

test_eigenvectors_orthogonal() → None

Verify the Hermitian solver returns orthonormal eigenvectors.

The eigenvectors of the Hermitian matrix form a unitary transformation.

Notes

The test diagonalizes a real-symmetric 2x2 matrix. It compares U^dag U with the identity at an absolute tolerance of 1e-10.

Return type:

None

class tests.test_diffpes.test_tightb.test_diagonalize.TestDiagonalizeTB

Bases: object

Validate diagonalize_tb.

The tests use graphene and 1D chain models. They cover output shapes, eigenvalue order, hopping gradients, and eigenvector indexing.

See:

diagonalize_tb()

test_output_shapes() → None

Verify output shapes match (K, B) eigenvalues and (K, B, O) eigenvectors.

The solver retains both k-points and both orbitals in the DiagonalizedBands fields.

Notes

The test diagonalizes a two-orbital graphene model at two k-points. It compares all three output shapes with their specified values.

Return type:

None

test_eigenvalues_sorted() → None

Verify eigenvalues have ascending order at each k-point.

The lower band precedes the upper band at every k-point. Downstream band analysis depends on this energy order.

Notes

The test diagonalizes the graphene model at three k-points. It compares the first eigenvalue with the second eigenvalue at each point.

Return type:

None

test_differentiable() → None

Verify JAX differentiates the eigenvalue sum with respect to hopping parameters.

The eigenspectrum carries hopping sensitivity through the Hamiltonian and the eigendecomposition.

Notes

The test differentiates the eigenvalue sum for a 1D chain with jax.grad. It checks every hopping gradient for a finite value.

Return type:

None

test_eigenvectors_shape_convention() → None

Verify eigenvector indexing: eigenvectors[k, band, orbital].

The last eigenvector axis contains the orbital coefficients. Each vector has unit norm across this axis.

Notes

The test diagonalizes graphene at one k-point. It checks shape (1, 2, 2) and compares each norm with 1.0 at a tolerance of 1e-10.

Return type:

None

class tests.test_diffpes.test_tightb.test_diagonalize.TestVaspToDiagonalized

Bases: object

Validate vasp_to_diagonalized.

The adapter uses VASP eigenvalues and approximates eigenvectors from orbital projections. The tests cover shapes, normalization, and the policy for phase loss.

See:

vasp_to_diagonalized()

test_output_shapes() → None

Verify output shapes match the input band structure dimensions.

The adapter retains five k-points and three bands. Its eigenvector result also contains the three selected orbitals.

Notes

The test supplies projections for two atoms and nine channels. It checks eigenvalue shape (5, 3) and eigenvector shape (5, 3, 3).

Return type:

None

test_eigenvectors_normalized() → None

Verify the VASP projection adapter normalizes approximate eigenvectors.

The adapter produces unit eigenvector norms from approximate orbital weights. This property holds when the raw weights do not sum to one.

Notes

The test supplies s and pz weights of 0.3 and 0.7. It compares every squared norm with 1.0 at an absolute tolerance of 1e-10.

Return type:

None

test_warns_by_default() → None

Verify the default phase_loss policy emits a RuntimeWarning.

The default policy warns the user because real VASP projections do not contain complex eigenvector phases.

Notes

The test calls the adapter with a minimal input and no policy argument. It expects a RuntimeWarning that contains cannot recover complex.

Return type:

None

test_phase_loss_error_mode_raises() → None

Verify phase_loss=”error” raises ValueError instead of warning.

The error policy rejects approximate eigenvectors that lack complex phase information.

Notes

The test calls the adapter with a minimal input and the error policy. It expects a ValueError that contains cannot recover complex.

Return type:

None

test_invalid_phase_loss_raises() → None

Verify an unrecognized phase_loss value raises an error.

The type contract permits only warn, ignore, and error.

Notes

The test passes phase_loss="bad" to the adapter with a minimal input. It expects the runtime type checker to raise an exception.

Return type:

None

test_f_orbital_raises() → None

Verify an f-orbital (l=3) in the basis raises ValueError.

The VASP PROCAR format contains only s, p, and d channels. The adapter rejects an f-orbital outside this set.

Notes

The test supplies an orbital with l=3 and m=0. It expects a ValueError that contains not in VASP 9-orbital set.

Return type:

None

Validate the tight-binding Hamiltonian builder.

Extended Summary

The tests validate build_hamiltonian_k and the two model factories. They cover Hermiticity, the matrix shape, JIT, analytic dispersions, and gradients with respect to hopping parameters.

class tests.test_diffpes.test_tightb.test_hamiltonian.TestBuildHamiltonianK

Bases: object

Validate build_hamiltonian_k.

The tests cover the Bloch Hamiltonian H(k) from hopping parameters and lattice vectors. They verify Hermiticity, the matrix shape, and JIT.

See:

build_hamiltonian_k()

test_hermitian() → None

Verify H(k) satisfies Hermiticity at the specified k-point.

The graphene Hamiltonian satisfies H = H^dag. This property permits a real eigenspectrum.

Notes

The test computes H at k=(0.3, 0.2, 0.0). It compares H with its conjugate transpose at an absolute tolerance of 1e-12.

Return type:

None

test_correct_shape() → None

Verify H(k) has shape (n_orbitals, n_orbitals).

The Hamiltonian has one row and one column for each model orbital.

Notes

The test computes the two-orbital graphene Hamiltonian at one k-point. It compares the output shape with (2, 2).

Return type:

None

test_jit_compatible() → None

Verify JAX compiles build_hamiltonian_k.

The compiled builder accepts a traced k-point and produces finite matrix elements.

Notes

The test compiles the builder for the 1D chain model with jax.jit. It checks the result at k=(0.25, 0, 0) for finite values.

Return type:

None

class tests.test_diffpes.test_tightb.test_hamiltonian.TestMake1DChainModel

Bases: object

Validate the 1D chain tight-binding model factory.

The tests compare the model with its analytic cosine dispersion. They also verify the eigenvalue interval [-2|t|, 2|t|].

See:

make_1d_chain_model()

test_cosine_dispersion() → None

Verify E(k) = 2t*cos(2*pi*k) for the 1D chain.

The single-band model with t=-1.0 has the dispersion E(k) = -2*cos(2*pi*k).

Notes

The test diagonalizes 101 k-points in the Brillouin zone [-0.5, 0.5]. It compares all eigenvalues at an absolute tolerance of 1e-10.

Return type:

None

test_eigenvalue_range() → None

Verify eigenvalue bandwidth spans [-2|t|, 2|t|].

A chain with t=-1.5 has eigenvalue limits of -3.0 and 3.0 eV. The corresponding bandwidth is 6.0 eV.

Notes

The test diagonalizes 201 k-points across the Brillouin zone. It compares both extrema at an absolute tolerance of 0.05 eV.

Return type:

None

class tests.test_diffpes.test_tightb.test_hamiltonian.TestMakeGrapheneModel

Bases: object

Validate the graphene tight-binding model factory.

The tests use analytic properties of the graphene pi-band structure. They cover the Gamma point, the Dirac point, and hopping gradients.

See:

make_graphene_model()

test_gamma_point() → None

Verify graphene has Gamma-point eigenvalues of +/-3|t|.

The two-orbital model with t=-2.7 eV has eigenvalues of -8.1 and 8.1 eV at the Gamma point.

Notes

The test diagonalizes the model at Gamma=(0, 0, 0). It compares both eigenvalues at an absolute tolerance of 0.01 eV.

Return type:

None

test_k_point_dirac() → None

Verify the Dirac point at K=(2/3, 1/3, 0) has zero-energy eigenvalues.

The off-diagonal Bloch sum vanishes at this k-point. Both eigenvalues consequently equal zero.

Notes

The test diagonalizes the model with t=-2.7 eV at the Dirac point. It compares both eigenvalues with zero at a tolerance of 1e-10 eV.

Return type:

None

test_gradient_wrt_hopping() → None

Verify JAX produces a finite hopping gradient for sum(E**2).

The graphene eigenspectrum carries sensitivity to the hopping parameters through the Hamiltonian and the eigendecomposition.

Notes

The test differentiates sum(E**2) with jax.grad at k=(0.1, 0.2, 0). It checks every hopping gradient for a finite value.

Return type:

None

Validate differentiable k-space conversion and fixed-shape mesh builders.

The tests cover the graphene reciprocal-lattice truth, Cartesian round trips, first-zone geometry, path distance, ARPES raster rotation, gradients, and JIT trace counts.

class tests.test_diffpes.test_tightb.test_kspace.TestKpointsFracToCart

Bases: object

Validate kpoints_frac_to_cart().

The cases use the analytic graphene reciprocal basis and its lattice-scale derivative.

See:

kpoints_frac_to_cart()

test_matches_the_graphene_reciprocal_closed_form() → None

Match the magnitude and direction of the graphene K point.

The fractional point (1/3, 1/3, 0) must have magnitude \(4\pi/(3a)\) and azimuth 60 degrees within 1e-12.

Notes

The test constructs the hexagonal real-space basis and compares the reciprocal rows with their independent closed forms.

Return type:

None

test_matches_the_analytic_graphene_scale_derivative() → None

Match \(d|K|/da=-4\pi/(3a^2)\) for graphene.

The automatic derivative must match the independent closed form within a relative tolerance of 1e-10.

Notes

The test differentiates lattice construction and reciprocal conversion together at a=2.46 Angstrom.

Return type:

None

test_preserves_all_generic_lattice_sensitivities() → None

Preserve finite nonzero gradients through all nine lattice entries.

Automatic derivatives must match central differences for a generic non-orthogonal cell.

Notes

A weighted Cartesian reduction makes every reciprocal-lattice entry relevant. The shared gate checks reverse mode and each gradient leaf.

Return type:

None

class tests.test_diffpes.test_tightb.test_kspace.TestKpointsCartToFrac

Bases: object

Validate kpoints_cart_to_frac().

The case checks the exact inverse contract across random non-orthogonal lattices.

See:

kpoints_cart_to_frac()

test_round_trips_random_nonorthogonal_lattices() → None

Recover fractional points after Cartesian conversion.

The round trip must agree within 1e-12 for each generated right-handed lattice.

Notes

Hypothesis supplies positive diagonal values and bounded shear values. The resulting upper-triangular lattice cannot be singular.

Return type:

None

class tests.test_diffpes.test_tightb.test_kspace.TestBuildKpath

Bases: object

Validate build_kpath().

The cases cover endpoint duplication, label indices, and absolute anchor conversion.

See:

build_kpath()

test_repeats_junctions_and_places_each_label() → None

Repeat shared anchors and place labels at Chinook-compatible indices.

Two three-point segments must produce six points with the middle anchor at indices two and three.

Notes

The test compares the generated fractional path with a direct linear interpolation table.

Return type:

None

test_converts_absolute_anchors_once() → None

Convert Cartesian anchors to the fractional path convention.

A cubic cell with unit real-space length maps pi to one-half on the matching fractional axis.

Notes

The test supplies two Cartesian anchors and compares both generated endpoints with the analytic fractional coordinates.

Return type:

None

test_rejects_each_invalid_path_setting() → None

Reject invalid anchor counts, segment sizes, labels, and units.

Static validation must reject every setting before interpolation.

Notes

The shared helper checks the four static branches and one traced finite-value branch in eager and compiled execution.

Return type:

None

class tests.test_diffpes.test_tightb.test_kspace.TestKpathArcLength

Bases: object

Validate kpath_arc_length().

The cases cover a closed-form cubic path and lattice gradients across a repeated junction.

See:

kpath_arc_length()

test_matches_a_cubic_two_segment_path() → None

Match cumulative distance for a cubic path with one repeated point.

The path must have total length pi in 1/Angstrom for a two Angstrom cubic lattice.

Notes

The test builds two perpendicular half-reciprocal segments and compares all six cumulative positions with a closed form.

Return type:

None

test_matches_finite_differences_through_a_repeated_junction() → None

Match lattice gradients with a repeated path junction.

The zero-length junction must not produce a NaN or an incorrect derivative.

Notes

The shared gradient harness compares reverse mode with central finite differences for a weighted cumulative path distance.

Return type:

None

class tests.test_diffpes.test_tightb.test_kspace.TestFirstBzMask

Bases: object

Validate first_bz_mask().

The case uses the exact first-zone cube for a simple cubic lattice.

See:

first_bz_mask()

test_matches_exact_cubic_membership() → None

Include exactly the cubic points with each magnitude at most pi.

Boundary points must remain inside, while points beyond one face must remain outside.

Notes

The test uses a one Angstrom cubic cell and compares the Boolean mask with a hand-classified point table.

Return type:

None

test_matches_the_pinned_chinook_mesh_reduction() → None

Match the pinned Chinook reduction for a skew lattice.

The mask must select the same indices and Cartesian points within the artifact tolerance.

Notes

The test validates the gate and source metadata. It reconstructs the geometry and compares its reciprocal basis and retained mesh points.

Return type:

None

test_handles_an_unreduced_basis_beyond_the_nearest_shell() → None

Reject a point whose closest competitor has coefficient minus two.

The nearest 3 by 3 by 3 coefficient shell gives a false positive for this well-conditioned, right-handed lattice. The default static shell must include the missed reciprocal vector and return exact membership.

Notes

Use a fixed regression from a larger-shell independent search. Check the public result and the insufficient-radius diagnostic under JIT.

Return type:

None

class tests.test_diffpes.test_tightb.test_kspace.TestBuildBzMesh

Bases: object

Validate build_bz_mesh().

The cases cover fixed output shapes and the reciprocal-cell volume identity.

See:

build_bz_mesh()

test_preserves_all_mesh_points_and_estimates_the_zone_volume() → None

Keep the full mesh and estimate the cubic first-zone volume.

The weighted volume error must decrease at the expected order of the axis spacing.

Notes

The test samples a 33-point fractional axis. It multiplies the mask fraction by the volume of the sampled reciprocal cube.

Return type:

None

test_rejects_an_axis_with_fewer_than_two_samples() → None

Reject a reciprocal axis that cannot span the sampled cube.

The static sample count must contain at least both cube endpoints.

Notes

The shared helper passes n_per_axis=1 through eager and compiled execution and matches the sample-count diagnostic.

Return type:

None

test_rejects_a_basis_without_proven_cube_coverage() → None

Reject an unreduced basis whose first zone can leave the cube.

The fixed fractional cube is valid only when reciprocal-basis inequalities bound every first-zone coordinate by one.

Notes

Use the unreduced regression lattice. Require the coverage diagnostic in eager and compiled execution instead of accepting a partial zone.

Return type:

None

class tests.test_diffpes.test_tightb.test_kspace.TestBuildArpesKmesh

Bases: object

Validate build_arpes_kmesh().

The cases cover sample rotation, fractional conversion, azimuth derivatives, and fixed-shape JIT reuse.

See:

build_arpes_kmesh()

test_rotates_the_laboratory_raster_into_the_sample() → None

Rotate a positive laboratory x point to negative sample y.

A positive 90-degree sample azimuth must apply a negative 90-degree coordinate rotation.

Notes

The test converts the generated fractional grid back to Cartesian coordinates and compares one row with the rotated closed form.

Return type:

None

test_matches_finite_differences_for_sample_azimuth() → None

Match the nonzero azimuth derivative with central differences.

The registered raster must retain sensitivity to sample alignment.

Notes

The shared gradient gate differentiates a weighted fractional raster at a generic nonzero azimuth.

Return type:

None

test_reuses_one_trace_for_traced_mesh_values() → None

Reuse one trace across fixed-shape kz, azimuth, and energy sweeps.

Changes to traced values must not cause a second compilation when all axis lengths stay fixed.

Notes

A Python counter records traces around both ARPES mesh builders. Two calls change every traced scalar and the photon-energy values.

Return type:

None

class tests.test_diffpes.test_tightb.test_kspace.TestBuildKmeshHv

Bases: object

Validate build_kmesh_hv().

The case checks direct free-electron composition and photon-axis metadata.

See:

build_kmesh_hv()

test_composes_the_free_electron_kz_rows() → None

Match every out-of-plane row with the kinematics primitive.

The Cartesian third coordinate must equal the real propagating momentum for each photon energy and parallel momentum.

Notes

The test computes the expected rows by direct vectorization of diffpes.simul.kz_from_inner_potential().

Return type:

None

Validate the eigenvector projection utilities.

Extended Summary

The tests validate eigenvector_orbital_weights and orbital_coefficients from diffpes.tightb.projections. They cover complex orbital weights and the identity operation for orbital coefficients.

class tests.test_diffpes.test_tightb.test_projections.TestEigenvectorOrbitalWeights

Bases: object

Validate diffpes.tightb.projections.eigenvector_orbital_weights().

The tests verify the squared magnitude of each complex coefficient. They also verify the shape and the real dtype of the result.

See:

eigenvector_orbital_weights()

test_real_eigenvectors_give_squared_values() → None

Verify real eigenvectors produce their squared magnitudes.

For a real coefficient, |c|^2 = c^2. The expected weights have values 0.36 and 0.64.

Notes

The test uses one k-point, two bands, and two orbitals. It compares the weights with the squared input at an absolute tolerance of 1e-12.

Return type:

None

test_complex_eigenvectors_give_modulus_squared() → None

Verify complex eigenvectors produce |c|^2 per coefficient.

The coefficient (3+4j)/5 has a squared magnitude of 1.0. The expected result distinguishes the squared magnitude from the squared real part.

Notes

The test fills a two-band array with the complex coefficient. It compares every weight with 1.0 at an absolute tolerance of 1e-12.

Return type:

None

test_output_shape_matches_input() → None

Verify the output shape equals the input shape (K, B, O).

The weight function preserves every axis of the eigenvector array.

Notes

The test supplies an array with shape (3, 4, 5). It compares the output shape with the input shape.

Return type:

None

test_output_is_real() → None

Verify squared magnitudes have a float64 dtype.

Squared magnitudes of complex coefficients have a real dtype.

Notes

The test supplies a complex128 array. It checks that the result has a floating-point dtype.

Return type:

None

class tests.test_diffpes.test_tightb.test_projections.TestOrbitalCoefficients

Bases: object

Validate diffpes.tightb.projections.orbital_coefficients().

The tests verify that the identity function preserves the complex values, shape, and dtype of its input.

See:

orbital_coefficients()

test_identity_preserves_values() → None

Verify orbital_coefficients returns its input unchanged.

The function preserves each complex orbital coefficient.

Notes

The test supplies a complex128 eigenvector array. It compares the output and input at an absolute tolerance of 1e-15.

Return type:

None

test_identity_preserves_shape_and_dtype() → None

Verify orbital_coefficients preserves the shape and complex128 dtype.

The function retains all eigenvector axes and the complex dtype.

Notes

The test supplies a complex128 array with shape (2, 3, 4). It compares the output shape and dtype with the input properties.

Return type:

None