diffpes.inout tests

Validation and regression tests for diffpes.inout.

Validate portable forward-certificate persistence.

The tests cover public behavior, differentiability, validation, and stable scientific identity in the supported certification regime.

tests.test_diffpes.test_inout.test_certificate.sample_certificate(*, execution_id: str = 'run-001', started_at_utc: str = '2026-07-21T12:00:00Z', model_version: str = '1.0.0', environment_checksum: str = 'crc32:canonical-1:environment:89abcdef', extensions_json: str = '{"project":"demo","unicode":"Å"}') → ForwardCertificate

Return one small, fully populated certificate test fixture.

Return type:

ForwardCertificate

class tests.test_diffpes.test_inout.test_certificate.TestSaveCertificateJson

Bases: object

Verify save_certificate_json().

The cases cover the public behavior in the supported certification regime.

See:

save_certificate_json()

test_json_preserves_model_identity(tmp_path: Path) → None

Verify JSON round-trip preserves exact scientific model identity.

The case uses explicit inputs in the supported certification regime. It checks the public result or the documented failure state.

Notes

The test writes the shared complete certificate fixture and reloads it before comparing the permanent model identity.

Return type:

None

test_json_round_trip_is_byte_stable_and_lossless(tmp_path: Any) → None

Verify json round trip is byte stable and lossless.

The case uses explicit inputs in the supported certification regime. It checks the public result or the documented failure state.

Notes

The test compares the result with explicit numerical or structural assertions.

Return type:

None

test_json_write_failure_keeps_previous_file(tmp_path: Any, monkeypatch: Any) → None

Verify json write failure keeps previous file.

The case uses explicit inputs in the supported certification regime. It checks the public result or the documented failure state.

Notes

The test compares the result with explicit numerical or structural assertions.

Return type:

None

class tests.test_diffpes.test_inout.test_certificate.TestCertificateIdentity

Bases: object

Verify certificate_identity().

The cases separate scientific identity from audit execution fields.

See:

certificate_identity()

test_audit_fields_do_not_change_scientific_identity() → None

Keep one identity across distinct execution IDs and timestamps.

The scientific identity must exclude both declared audit fields.

Notes

The test changes only the two fields classified as audit metadata.

Return type:

None

class tests.test_diffpes.test_inout.test_certificate.TestFinalizeCertificate

Bases: object

Verify finalize_certificate().

The case replaces the compiled placeholder at the canonical I/O boundary.

See:

finalize_certificate()

test_final_identity_matches_canonical_record() → None

Replace an arbitrary checksum with the computed scientific identity.

The stored identity must equal a new computation from the result.

Notes

The test finalizes the complete shared certificate fixture once.

Return type:

None

class tests.test_diffpes.test_inout.test_certificate.TestLoadCertificateJson

Bases: object

Verify load_certificate_json().

The cases cover the public behavior in the supported certification regime.

See:

load_certificate_json()

test_json_corruption_fails_consistency_check(tmp_path: Any) → None

Verify json corruption fails consistency check.

The case uses explicit inputs in the supported certification regime. It checks the public result or the documented failure state.

Notes

The test compares the result with explicit numerical or structural assertions.

Return type:

None

test_internal_identity_mismatch_is_rejected(tmp_path: Path) → None

Reject an internal identity mismatch after storage CRC recalculation.

The reader must validate the internal identity independently.

Notes

The test changes only the identity field and updates the outer CRC32.

Return type:

None

test_unknown_schema_major_is_rejected_before_interpretation(tmp_path: Any) → None

Verify rejection of an unknown schema major before interpretation.

The case uses explicit inputs in the supported certification regime. It checks the public result or the documented failure state.

Notes

The test compares the result with explicit numerical or structural assertions.

Return type:

None

test_unknown_minor_extensions_survive_round_trip(tmp_path: Any) → None

Verify unknown minor extensions survive round trip.

The case uses explicit inputs in the supported certification regime. It checks the public result or the documented failure state.

Notes

The test compares the result with explicit numerical or structural assertions.

Return type:

None

test_current_minor_rejects_unknown_structural_field(tmp_path: Any) → None

Verify current minor rejects unknown structural field.

The case uses explicit inputs in the supported certification regime. It checks the public result or the documented failure state.

Notes

The test compares the result with explicit numerical or structural assertions.

Return type:

None

class tests.test_diffpes.test_inout.test_certificate.TestAttachCertificateH5

Bases: object

Verify attach_certificate_h5().

The cases cover the public behavior in the supported certification regime.

See:

attach_certificate_h5()

test_hdf5_attach_preserves_results_and_round_trips(tmp_path: Any) → None

Verify hdf5 attach preserves results and round trips.

The case uses explicit inputs in the supported certification regime. It checks the public result or the documented failure state.

Notes

The test compares the result with explicit numerical or structural assertions.

Return type:

None

test_hdf5_write_failure_keeps_previous_file(tmp_path: Any, monkeypatch: Any) → None

Verify hdf5 write failure keeps previous file.

The case uses explicit inputs in the supported certification regime. It checks the public result or the documented failure state.

Notes

The test compares the result with explicit numerical or structural assertions.

Return type:

None

test_hdf5_name_rejects_path_components(tmp_path: Any, name: Any) → None

Verify hdf5 name rejects path components.

The case uses explicit inputs in the supported certification regime. It checks the public result or the documented failure state.

Notes

The test compares the result with explicit numerical or structural assertions.

Return type:

None

class tests.test_diffpes.test_inout.test_certificate.TestLoadCertificateH5

Bases: object

Verify load_certificate_h5().

The cases cover the public behavior in the supported certification regime.

See:

load_certificate_h5()

test_hdf5_replace_and_missing_name(tmp_path: Any) → None

Verify hdf5 replace and missing name.

The case uses explicit inputs in the supported certification regime. It checks the public result or the documented failure state.

Notes

The test compares the result with explicit numerical or structural assertions.

Return type:

None

test_hdf5_corruption_and_index_disagreement_fail_closed(tmp_path: Any) → None

Verify hdf5 corruption and index disagreement fail closed.

The case uses explicit inputs in the supported certification regime. It checks the public result or the documented failure state.

Notes

The test compares the result with explicit numerical or structural assertions.

Return type:

None

test_hdf5_corrupt_authoritative_json_fails_closed(tmp_path: Any) → None

Verify hdf5 corrupt authoritative json fails closed.

The case uses explicit inputs in the supported certification regime. It checks the public result or the documented failure state.

Notes

The test compares the result with explicit numerical or structural assertions.

Return type:

None

Validate HDF5 PyTree save/load.

Extended Summary

The tests exercise save_to_h5 and load_from_h5 for all registered PyTree types. They cover spin and OAM variants and files with multiple PyTrees. Round-trip tests compare numerical values within tolerance. Error tests cover unknown types, missing groups, and invalid options. The tests also verify applicable compression and data set options.

class tests.test_diffpes.test_inout.test_hdf5.TestDensityOfStates(*args, **kwargs) → None

Bases: TestCase

Round-trip tests for DensityOfStates HDF5 serialization.

Verifies that energy, total DOS, and Fermi energy arrays survive a save-then-load cycle with exact numerical fidelity.

See:

save_to_h5()

See:

load_from_h5()

test_round_trip() → None

Verify DensityOfStates survives HDF5 round-trip.

The test establishes the round trip contract for density of states with the concrete values and array shapes described below.

Notes

1. Create a DensityOfStates with 100-point energy axis and uniform DOS.

2. Save to a temporary HDF5 file.

3. Load back by group name.

Expected assertions

All three array fields match to within 1e-12.

Return type:

None

class tests.test_diffpes.test_inout.test_hdf5.TestBandStructure(*args, **kwargs) → None

Bases: TestCase

Round-trip tests for BandStructure HDF5 serialization.

The tests verify preservation of the eigenvalues, k-points, weights, and Fermi energy through save and load operations.

See:

save_to_h5()

See:

load_from_h5()

test_round_trip() → None

Verify BandStructure survives HDF5 round-trip.

The test establishes the round trip contract for band structure with the concrete values and array shapes described below.

Notes

1. Create a BandStructure with 10 k-points, 4 bands.

2. Save and load via HDF5.

Expected assertions

All four array fields match to within 1e-12.

Return type:

None

class tests.test_diffpes.test_inout.test_hdf5.TestArpesSpectrum(*args, **kwargs) → None

Bases: TestCase

Round-trip tests for ArpesSpectrum HDF5 serialization.

Verifies intensity map and energy axis survive the save/load cycle.

See:

save_to_h5()

See:

load_from_h5()

test_round_trip() → None

Verify ArpesSpectrum survives HDF5 round-trip.

The test establishes the round trip contract for arpes spectrum with the concrete values and array shapes described below.

Notes

1. Create an ArpesSpectrum with shape (20, 100).

2. Save and load via HDF5.

Expected assertions

Both array fields match to within 1e-12.

Return type:

None

class tests.test_diffpes.test_inout.test_hdf5.TestOrbitalProjection(*args, **kwargs) → None

Bases: TestCase

Round-trip tests for OrbitalProjection HDF5 serialization.

Verifies projections array and Optional spin/oam fields (both None and non-None) survive the cycle.

See:

save_to_h5()

See:

load_from_h5()

test_round_trip_none_optionals() → None

Verify OrbitalProjection with None spin/oam.

The test establishes the round trip none optionals contract for orbital projection with the concrete values and array shapes described below.

Notes

1. Create with only projections (spin=None, oam=None).

2. Save and load via HDF5.

Expected assertions

Projections match; spin and oam are None.

Return type:

None

test_round_trip_with_spin() → None

Verify OrbitalProjection with non-None spin.

The test establishes the round trip with spin contract for orbital projection with the concrete values and array shapes described below.

Notes

1. Create with both projections and spin arrays.

2. Save and load via HDF5.

Expected assertions

Projections and spin match; oam is None.

Return type:

None

test_round_trip_with_all() → None

Verify OrbitalProjection with spin and oam.

The test establishes the round trip with all contract for orbital projection with the concrete values and array shapes described below.

Notes

1. Create with projections, spin, and oam.

2. Save and load via HDF5.

Expected assertions

All three array fields match.

Return type:

None

class tests.test_diffpes.test_inout.test_hdf5.TestSimulationParams(*args, **kwargs) → None

Bases: TestCase

Round-trip tests for SimulationParams HDF5 serialization.

Verifies that all six float children and the integer fidelity aux_data survive the cycle.

See:

save_to_h5()

See:

load_from_h5()

test_round_trip() → None

Verify SimulationParams survives HDF5 round-trip.

The test establishes the round trip contract for simulation params with the concrete values and array shapes described below.

Notes

1. Create with non-default values for all fields.

2. Save and load via HDF5.

Expected assertions

All float fields match, and the integer fidelity matches.

Return type:

None

class tests.test_diffpes.test_inout.test_hdf5.TestPolarizationConfig(*args, **kwargs) → None

Bases: TestCase

Round-trip tests for PolarizationConfig serialization.

Verifies that float angles and the string polarization_type aux_data survive the cycle.

See:

save_to_h5()

See:

load_from_h5()

test_round_trip() → None

Verify PolarizationConfig survives HDF5 round-trip.

The test establishes the round trip contract for polarization config with the concrete values and array shapes described below.

Notes

1. Create an LHP config with custom angles.

2. Save and load via HDF5.

Expected assertions

The float angles and the polarization_type string match.

Return type:

None

class tests.test_diffpes.test_inout.test_hdf5.TestKPathInfo(*args, **kwargs) → None

Bases: TestCase

Round-trip tests for KPathInfo HDF5 serialization.

Verifies that integer arrays and the (mode, labels) tuple aux_data survive the cycle.

See:

save_to_h5()

See:

load_from_h5()

test_round_trip() → None

Verify KPathInfo survives HDF5 round-trip.

The test establishes the round trip contract for k path info with the concrete values and array shapes described below.

Notes

1. Create with 3 symmetry labels.

2. Save and load via HDF5.

Expected assertions

The integer arrays, mode, and label strings match.

Return type:

None

test_loads_pre_migration_aux_format() → None

Load K-path metadata written by the NamedTuple-era codec.

The test establishes the loads pre migration aux format contract for k path info 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_inout.test_hdf5.TestCrystalGeometry(*args, **kwargs) → None

Bases: TestCase

Round-trip tests for CrystalGeometry HDF5 serialization.

Verifies that lattice, reciprocal lattice, coords, atom_counts arrays and the symbols tuple aux_data survive the cycle.

See:

save_to_h5()

See:

load_from_h5()

test_round_trip() → None

Verify CrystalGeometry survives HDF5 round-trip.

The test establishes the round trip contract for crystal geometry with the concrete values and array shapes described below.

Notes

1. Create a cubic Si structure with 2 atoms.

2. Save and load via HDF5.

Expected assertions

All four arrays and the symbols tuple match.

Return type:

None

class tests.test_diffpes.test_inout.test_hdf5.TestSaveToH5(*args, **kwargs) → None

Bases: TestCase

Validate saving/loading multiple PyTrees in one file.

Verifies multi-group HDF5 files and both loading modes (by name, load all).

See:

save_to_h5()

test_save_load_multiple() → None

Verify two PyTrees coexist in one HDF5 file.

The test establishes the save load multiple contract for multi py tree with the concrete values and array shapes described below.

Notes

1. Create a BandStructure and an OrbitalProjection.

2. Save both to one file under different names.

3. Load each by name.

Expected assertions

Both round-trip correctly and independently.

Return type:

None

test_load_all_returns_dict() → None

Verify load_from_h5 without name returns dict.

The test establishes the load all returns dict contract for multi py tree with the concrete values and array shapes described below.

Notes

1. Save two PyTrees to one file.

2. Load without specifying a name.

Expected assertions

Result is a dict with both group names as keys.

Return type:

None

class tests.test_diffpes.test_inout.test_hdf5.TestLoadFromH5(*args, **kwargs) → None

Bases: TestCase

Validate load_from_h5().

Covers named-group recovery of a concrete Equinox carrier from a file produced by the public HDF5 writer.

See:

load_from_h5()

test_load_named_band_structure() → None

Recover a named band structure without changing its arrays.

The loaded carrier must preserve the eigenvalue and k-point arrays at exact float64 precision for this deterministic fixture.

Notes

Saves one two-k-point BandStructure, loads the bands group by name, narrows its runtime type, and compares both array fields exactly.

Return type:

None

class tests.test_diffpes.test_inout.test_hdf5.TestErrorHandling(*args, **kwargs) → None

Bases: TestCase

Validate error conditions in save/load functions.

The tests verify the applicable exceptions for invalid inputs and missing data.

See:

save_to_h5()

See:

load_from_h5()

test_no_pytrees_raises() → None

Verify save_to_h5 with no kwargs raises ValueError.

The test establishes the no pytrees raises contract for error handling with the concrete values and array shapes described below.

Notes

1. Call save_to_h5 with only a path, no PyTrees.

Expected assertions

The function raises ValueError.

Return type:

None

test_unsupported_type_raises() → None

Verify unregistered type raises TypeError.

The test establishes the unsupported type raises contract for error handling with the concrete values and array shapes described below.

Notes

1. Call save_to_h5 with a plain tuple (not a registered PyTree).

Expected assertions

The function raises TypeError.

Return type:

None

test_missing_group_raises() → None

Verify load with nonexistent name raises KeyError.

The test establishes the missing group raises contract for error handling with the concrete values and array shapes described below.

Notes

1. Save a PyTree under name "a".

2. Load with name "b".

Expected assertions

The function raises KeyError.

Return type:

None

test_load_unknown_pytree_type_raises() → None

Verify loading a group with unknown _pytree_type raises TypeError.

The test establishes the load unknown pytree type raises contract for error handling with the concrete values and array shapes described below.

Notes

1. Create an HDF5 file with a group that has _pytree_type = “UnknownType” (not in _PYTREE_REGISTRY).

2. Load that group with load_from_h5(path, name=”bad”).

Expected assertions

The function raises TypeError with the unknown type in its message.

Return type:

None

class tests.test_diffpes.test_inout.test_hdf5.TestDatasetFlags(*args, **kwargs) → None

Bases: TestCase

Validate HDF5 dataset storage flags in save_to_h5.

See:

save_to_h5()

test_compression_flags_applied_to_arrays() → None

Verify application of storage flags to non-scalar data sets.

The test establishes the compression flags applied to arrays contract for dataset flags with the concrete values and array shapes described below.

Notes

1. Create an ArpesSpectrum (array datasets) and SimulationParams (scalar datasets).

2. Save both with compression/chunk/checksum flags.

3. Inspect HDF5 dataset properties directly.

4. Round-trip load to verify numerical integrity.

Expected assertions

• Array dataset has requested filter/chunk settings.

• Scalar dataset remains uncompressed (safe handling).

• Loaded spectrum matches original data.

Return type:

None

test_compression_opts_without_compression_raises() → None

Verify invalid compression flag combination raises ValueError.

The test establishes the compression opts without compression raises contract for dataset flags with the concrete values and array shapes described below.

Notes

1. Create a simple DensityOfStates PyTree.

2. Call save_to_h5 with compression_opts only.

Expected assertions

The function raises ValueError with an explanatory message.

Return type:

None

class tests.test_diffpes.test_inout.test_hdf5.TestStaticMetadataEncoding

Bases: object

Validate generic static Equinox metadata encoding.

See:

save_to_h5()

See:

load_from_h5()

test_encode_and_decode_round_trip() → None

Preserve nested tuple types through the generic JSON codec.

The test establishes the encode and decode round trip contract for static metadata encoding 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_encode_returns_tagged_json_mapping() → None

Encode tuples as JSON-compatible tagged mappings.

The test establishes the encode returns tagged json mapping contract for static metadata encoding 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

Verify HDF5 round trips for every types-owned Equinox carrier.

Extended Summary

Exercises the introspected recursive codec over all twenty-two carrier classes, including nested modules, static tuple metadata, complex arrays, and absent optional leaves.

tests.test_diffpes.test_inout.test_hdf5_all_carriers.test_all_carriers_round_trip_bitwise() → None

Round-trip every carrier with exact leaves and static metadata.

Return type:

None

Extended Summary

Saves all twenty-two deterministic carriers into one HDF5 file and reloads them together. Each reconstructed module must retain its exact class, numerical leaves, nested modules, optional None leaves, and static metadata.

Notes

Uses equinox.tree_equal() for an exact recursive comparison after a single multi-group save/load cycle.

Validate parser-adjacent workflow helpers.

Extended Summary

The tests validate atom selection, atom aggregation, shell reduction, and dimension checks across files. They use synthetic projection carriers.

class tests.test_diffpes.test_inout.test_helpers.TestSelectAtoms(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.inout.select_atoms().

The tests validate atom-axis slicing of both projection carriers. They cover one atom and multiple atoms while preserving values. They also verify the SpinOrbitalProjection type and both sliced arrays.

See:

select_atoms()

test_select_single_atom() → None

Select a single atom by index and verify output shape and s-orbital value.

The fixture has three atoms with distinct s-orbital weights. The test selects atom 1 and checks the reduced atom axis. It compares the selected s-orbital value with 2.0 by using atol=1e-12.

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_select_multiple_atoms() → None

Select two non-contiguous atoms and verify shape and ordering.

The test selects atoms 0 and 2 from the three-atom fixture. It checks the output shape and selection order. Output indices 0 and 1 contain s-orbital values 1.0 and 3.0. The comparisons use atol=1e-12.

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_preserves_spin_orbital_projection_type() → None

Verify that selecting atoms from a SpinOrbitalProjection returns SpinOrbitalProjection.

The test constructs a SpinOrbitalProjection with projections shape (2, 2, 3, 9) and spin shape (2, 2, 3, 6), then selects atoms 0 and 2. The test verifies the SpinOrbitalProjection result type. It also verifies the two-atom shapes of both arrays. This test checks dispatch for the input subtype.

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_inout.test_helpers.TestAggregateAtoms(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.inout.aggregate_atoms().

The tests validate the sum of orbital projections over the atom axis. They cover all atoms and an explicit subset. They verify the output shape and the summed s-orbital values.

See:

aggregate_atoms()

test_aggregate_all() → None

Sum projections over all atoms and verify collapsed shape and total.

The test calls aggregate_atoms without atom indices. It checks the output shape after removal of the atom axis. It compares the summed s-orbital value with 6.0 by using atol=1e-12.

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_aggregate_subset() → None

Sum projections over a specified subset of atoms.

The test calls aggregate_atoms with atom indices 0 and 1. It checks the output shape and compares the s-orbital value with 3.0. The comparison uses atol=1e-12. This input covers explicit atom selection before the sum.

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_inout.test_helpers.TestReduceOrbitals(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.inout.reduce_orbitals().

The tests reduce nine orbital channels to aggregate s, p, and d channels. Each aggregate channel sums the applicable input channels.

See:

reduce_orbitals()

test_reduces_to_spd() → None

Reduce 9-channel orbital projections to s/p/d totals and verify sums.

The test applies reduce_orbitals to the fixture’s raw projections array. The test asserts the output shape is (2, 2, 3, 3) – 9 orbital channels collapsed to 3 – and checks atom 0’s reduced values analytically:

The expected s, p, and d totals are 1.0, 0.6, and 0.15.

All comparisons use atol=1e-12.

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_inout.test_helpers.TestCheckConsistency(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.inout.check_consistency().

Validates the dimension-compatibility checker that ensures BandStructure, OrbitalProjection, and (optionally) KPathInfo agree on k-point and band counts. Covers the happy path (all dimensions match), k-point mismatch, band mismatch, and the optional KPathInfo consistency check.

See:

check_consistency()

test_consistent_inputs() → None

Verify successful checks for matching band and projection carriers.

The test constructs a BandStructure with 2 k-points and 3 bands, and an OrbitalProjection with matching leading dimensions (2, 3, 1, 9). The test calls check_consistency and asserts it returns without raising, confirming the positive validation 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_kpoint_mismatch() → None

Verify ValueError for different k-point counts.

The test constructs a BandStructure with 2 k-points but an OrbitalProjection with 4 k-points. Asserts that check_consistency raises ValueError matching "K-point count mismatch", exercising the first dimension check.

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_band_mismatch() → None

Verify ValueError for different band counts.

The test constructs a BandStructure with 3 bands but an OrbitalProjection with 5 bands (k-points match at 2). Asserts that check_consistency raises ValueError matching "Band count mismatch", exercising the second dimension check independently from the k-point check.

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_with_kpath() → None

Verify consistency with an optional KPathInfo.

The test constructs matching band, projection, and k-path carriers. The carriers have ten k-points and three bands. The test calls check_consistency and expects no error. This result confirms that all three dimensions agree.

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_kpath_line_mode_mismatch_raises() → None

Verify ValueError when Line-mode KPathInfo has a different k-point count.

The test constructs a BandStructure with 10 k-points and an OrbitalProjection with matching dimensions, but a KPathInfo with num_kpoints=5 in "Line-mode". Asserts that check_consistency raises ValueError matching "K-point count mismatch", covering the kpath.mode == "Line-mode" branch at helpers.py lines 283-287.

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_inout.test_helpers.TestSelectAtomsWithOAM(*args, **kwargs) → None

Bases: TestCase

Test that select_atoms correctly propagates the OAM field.

See:

select_atoms()

test_select_atoms_preserves_oam() → None

Verify OAM slicing along the atom axis during selection.

The test constructs an OrbitalProjection with OAM shape (2, 2, 3, 3) and selects atoms 0 and 2. The test checks the resulting OAM shape. This input covers the path where orb.oam is not None.

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 plotting utilities.

Extended Summary

The tests exercise the public plotting functions. They cover default and custom rendering, shape validation, and existing axes. They also cover color limits, color bars, and empty k-path labels.

class tests.test_diffpes.test_inout.test_plotting.TestPlotArpesSpectrum(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.inout.plot_arpes_spectrum().

Covers default plotting, optional color limits and colorbar, validation of spectrum array dimensions and shape compatibility, and reuse of a user-provided matplotlib axis.

See:

plot_arpes_spectrum()

test_returns_expected_objects() → None

Plot with default options returns figure, axis, and image with correct shape and labels.

The test builds a spectrum and calls plot_arpes_spectrum with colorbar=False. The test checks the transposed image shape (120, 20). It also checks the default axis labels and title. The test closes the figure.

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_with_clim_and_colorbar() → None

Verify color limits and a color bar with custom options.

The test calls plot_arpes_spectrum with colorbar=True and clim=(0.0, 0.5). The test compares the image color limits with (0.0, 0.5) through get_clim. This input covers the limits and color bar paths.

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_validation_rejects_wrong_intensity_ndim() → None

_prepare_plot_arrays raises ValueError when intensity is not 2D.

The test constructs an ArpesSpectrum with 1D intensity (bypassing the factory’s type checks) and calls plot_arpes_spectrum. Expects a ValueError whose message indicates that spectrum.intensity must have shape (K, E). This validates the dimension check inside the plotting pipeline.

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_validation_rejects_wrong_energy_axis_ndim() → None

_prepare_plot_arrays raises ValueError when energy_axis is not 1D.

The test constructs an ArpesSpectrum with 2D energy_axis and calls plot_arpes_spectrum. Expects a ValueError whose message indicates that spectrum.energy_axis must have shape (E,).

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_validation_rejects_shape_mismatch() → None

_prepare_plot_arrays raises ValueError when intensity and energy_axis lengths disagree.

The test uses intensity of shape (5, 10) and energy_axis of length 7, so intensity.shape[1] != energy_axis.shape[0]. Expects a ValueError with a message about incompatible shapes.

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_uses_existing_axis() → None

Verify reuse of a given figure and axis.

The test creates a figure and axis with plt.subplots(), then passes ax to plot_arpes_spectrum. The test verifies the identities of the returned figure and axis. It also verifies the image on the given axis.

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_inout.test_plotting.TestApplyKpathTicks(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.inout.apply_kpath_ticks().

The tests apply symmetry-point ticks and labels to an axis. They cover fewer labels than indices and the path without labels.

See:

apply_kpath_ticks()

test_sets_ticks_and_labels() → None

apply_kpath_ticks sets x-axis ticks and labels from KPathInfo.

The test builds a KPathInfo with four label indices and four labels (G, M, K, G). The test applies apply_kpath_ticks to a new axis. It compares the x-axis labels with the expected ordered labels.

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_handles_label_index_mismatch() → None

Verify truncation when labels are fewer than label indices.

The fixture provides four label indices but only two labels. The test expects exactly the two available labels. This input covers the truncation logic without an index error.

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_empty_labels_returns_ax_unchanged() → None

Verify the unchanged axis when the k-path has no labels.

The test builds a KPathInfo with empty label_indices and empty labels so that n_labels is zero. The test verifies the identity of the returned axis. It also verifies the return path without tick changes.

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_inout.test_plotting.TestPlotArpesWithKpath(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.inout.plot_arpes_with_kpath().

Covers the combined workflow of plotting an ARPES spectrum and annotating the k-axis with symmetry labels from KPathInfo.

See:

plot_arpes_with_kpath()

test_combined_plot() → None

plot_arpes_with_kpath produces a spectrum image and applies k-path ticks and labels.

The test builds a spectrum and a KPathInfo with three symmetry points. The test calls plot_arpes_with_kpath and checks the image shape. It also compares the tick labels and the x-axis label. These checks verify the spectrum plot and its k-path annotation.

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_inout.test_plotting.TestListBandScatterPresets(*args, **kwargs) → None

Bases: TestCase

Validate list_band_scatter_presets().

Covers the stable public names for orbital, spin, and orbital-angular- momentum scatter modes.

See:

list_band_scatter_presets()

test_returns_each_preset_family() → None

Return at least one name from each supported preset family.

The result must expose orbital, signed-spin, and OAM choices so callers can build selection controls without reading private tables.

Notes

The test calls the listing function once and checks representative public names in the returned immutable tuple.

Return type:

None

class tests.test_diffpes.test_inout.test_plotting.TestPlotBandScatterPreset(*args, **kwargs) → None

Bases: TestCase

Validate projected-band scatter plotting presets.

See:

plot_band_scatter_preset()

test_lists_presets() → None

list_band_scatter_presets returns known keys.

The test establishes the lists presets contract for plot band scatter 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_orbital_preset_plot() → None

Verify the orbital preset scatter for each k-point and band.

The test establishes the orbital preset plot contract for plot band scatter 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_signed_spin_preset_with_colorbar() → None

Verify a signed-spin preset with a color bar.

The test establishes the signed spin preset with colorbar contract for plot band scatter 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_spin_preset_requires_spin_data() → None

Verify that spin presets require a spin field.

The test establishes the spin preset requires spin data contract for plot band scatter 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_band_scatter_with_kpath() → None

Verify symmetry labels on the projected-band scatter.

The test establishes the band scatter with kpath contract for plot band scatter 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_inout.test_plotting.TestPlotBandScatterWithKpath(*args, **kwargs) → None

Bases: TestCase

Validate plot_band_scatter_with_kpath().

Covers composition of projected-band marker weights with line-mode symmetry labels on the shared momentum axis.

See:

plot_band_scatter_with_kpath()

test_applies_labels_to_projected_bands() → None

Apply all supplied symmetry labels to the scatter axis.

A ten-point, three-band fixture must produce thirty offsets and retain the three requested high-symmetry labels in order.

Notes

The test builds deterministic band and projection carriers, applies a three-label KPathInfo, and checks the collection size and rendered tick text.

Return type:

None

class tests.test_diffpes.test_inout.test_plotting.TestPlotBandScatterEdgeCases(*args, **kwargs) → None

Bases: TestCase

Validate additional paths in the band-scatter plotting helpers.

The tests cover invalid array ranks and incompatible weight shapes. They cover selections by atom, orbital, spin, and OAM. They also cover unknown presets, missing OAM data, and an existing axis.

See:

plot_band_scatter_preset()

test_prepare_band_arrays_wrong_ndim_raises() → None

_prepare_band_arrays with 1D eigenvalues raises ValueError (lines 449-450).

The test constructs a BandStructure with 1D eigenvalues (bypassing the factory), then calls plot_band_scatter_preset. Asserts a ValueError matching "shape (K, B)".

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_subset_atom_axis_with_indices() → None

Verify atom-axis selection with explicit atom indices.

The test plots the p preset with atom_indices=[0]. Thus, _subset_atom_axis receives an index array. The test asserts the scatter point count equals nk * nb.

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_s_orbital_preset() → None

Verify the s-orbital preset branch.

The test calls plot_band_scatter_preset with preset='s'. Asserts that the scatter renders without error and the point count is correct (exercises the ORBITAL_INDEX[key] branch).

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_total_preset() → None

Verify that the total preset sums all orbital channels.

The test calls plot_band_scatter_preset with preset='total'. The test asserts the scatter renders and the point count is correct (exercises the elif key == 'total' branch at line 501-502).

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_spin_channel_preset() → None

Verify the spin-channel preset branch.

The test calls plot_band_scatter_preset with preset='spin_z_up'. This exercises the if key in spin_channel branch (line 527-528). The test asserts the scatter renders without error.

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_oam_preset_with_oam_data() → None

Verify OAM selection and the component branch.

The test calls plot_band_scatter_preset with preset='oam_total' and an OrbitalProjection that has oam data. This exercises line 541 (oam_arr = _subset_atom_axis(...)) and lines 554-556 (if key in oam_component: weights = ...).

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_oam_abs_total_preset() → None

Verify the absolute-total OAM preset.

The test calls plot_band_scatter_preset with preset='oam_abs_total' and an OrbitalProjection with OAM data present. This exercises the elif key == 'oam_abs_total' branch at lines 557-559, which computes np.sum(np.abs(oam_arr[..., 2]), axis=2) and sets signed = False. Asserts the scatter renders without error.

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_oam_preset_without_oam_data_raises() → None

Verify that an OAM preset requires OAM data.

The test calls plot_band_scatter_preset with preset='oam_p' but provides an OrbitalProjection with oam=None. Asserts ValueError matching "requires OAM data".

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_unknown_preset_raises() → None

Verify that an unknown preset raises ValueError.

The test calls plot_band_scatter_preset with an unrecognized preset name. Asserts ValueError matching "Unknown preset".

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_weight_shape_mismatch_raises() → None

Verify rejection of weights with an incompatible shape.

The test creates incompatible band and projection shapes. The "p" preset produces weights with shape (4, 3) instead of (4, 2). The test expects a ValueError that matches "Preset weights must have shape".

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_uses_provided_ax() → None

Verify reuse of a given axis for a band scatter.

The test creates a figure and passes its axis to the plotting function. It verifies the identity of the returned figure. This check covers the existing-axis path instead of the new-figure 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

Validate VASP CHGCAR parsing.

Covers scalar, spin-polarized, and SOC volumetric grids together with malformed headers, grid blocks, and coordinate data.

class tests.test_diffpes.test_inout.test_chgcar.TestReadChgcar(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.inout.read_chgcar().

The tests validate charge-only, ISPIN=2, and SOC CHGCAR files. These files have one, two, and four data blocks, respectively. The tests check the lattice, coordinate, and grid shapes, type discrimination, and numerical values of the volumetric data grids.

See:

read_chgcar()

test_charge_only() → None

Read charge-only CHGCAR and verify VolumetricData output with no magnetization.

The test parses CHGCAR_charge, which has one data block. It checks the result type, the array shapes, and grid_shape. It also checks the symbols, atom counts, and absent magnetization. These checks validate the CHGCAR path for one block.

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_charge_with_magnetization() → None

Read ISPIN=2 CHGCAR and verify VolumetricData includes scalar magnetization.

The test parses CHGCAR_spin, which has two data blocks. It checks the result type, grid_shape, and both array shapes. It also verifies that the magnetization exists. These checks validate the ISPIN=2 path, where magnetization equals rho_up-rho_down.

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_soc_chgcar() → None

Read SOC CHGCAR and verify SOCVolumetricData with 3-component magnetization.

Parses CHGCAR_soc (four data blocks: charge, mx, my, mz). The test checks the result type, grid_shape, and all array shapes. It verifies that the scalar magnetization equals the z-component. It compares the first x-component with its volume-normalized value by using atol=1e-12. These checks validate the four-block SOC 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

class tests.test_diffpes.test_inout.test_chgcar.TestReadChgcarErrors(*args, **kwargs) → None

Bases: TestCase

Validate error paths in read_chgcar().

See:

read_chgcar()

test_zero_volume_lattice_raises() → None

Verify that a zero-volume lattice raises ValueError.

The test writes a CHGCAR where the lattice vectors are all zero, making the unit cell volume = 0. Asserts ValueError matching "volume is zero".

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_no_grid_dimensions_raises() → None

Verify that a missing grid dimension line raises ValueError.

The test writes a CHGCAR with a valid POSCAR header but no grid dimension line after the coordinates. Asserts ValueError matching "Could not locate".

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_invalid_lattice_line_raises() → None

Verify that a short lattice line raises ValueError.

The test writes a CHGCAR where the first lattice row has only 2 values. The test asserts ValueError matching "Invalid CHGCAR lattice".

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_selective_dynamics_line_consumed() → None

Verify consumption of the selective-dynamics line before coordinates.

The test writes a CHGCAR with a ‘Selective dynamics’ line before the coordinate-mode line. The test checks successful parsing and the Direct coordinate mode.

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_invalid_coordinate_line_raises() → None

Verify that a short atomic-coordinate line raises ValueError.

The test writes a CHGCAR where the atomic coordinate line has only 2 values. Asserts ValueError matching "Invalid CHGCAR coordinate".

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_cartesian_coordinates_transform() → None

Verify conversion from Cartesian coordinates to fractional coordinates.

The test writes a CHGCAR with Cartesian coordinate mode. One atom has coordinate [3.0, 0.0, 0.0] in a cubic lattice. Its expected fractional coordinate is [1.0, 0.0, 0.0]. The comparison uses atol=1e-10.

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_find_next_grid_skips_non_matching_lines() → None

_find_next_grid_line skips lines with != 3 parts and non-int 3-part lines.

The test writes a CHGCAR with nonmatching lines before the grid shape. One line has the three floats 1.5 2.5 3.5. The parser skips these lines before it reads the grid shape.

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_parse_float_block_skips_blank_lines() → None

_parse_float_block skips blank lines in data (chgcar.py lines 449-450).

The test writes a CHGCAR where the data block has a blank line after the first row of values. The test checks the parsed grid.

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_parse_float_block_stops_on_non_float_token() → None

Verify that a non-float token sets row_valid=False.

The test writes a CHGCAR with a header between two float rows. The non-float token sets row_valid=False and stops the inner loop. The parser does not append that row. The outer loop advances, and later valid rows complete the eight-value collection.

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_parse_float_block_truncated_raises() → None

Verify that a truncated data block raises ValueError.

The test writes a CHGCAR where the grid is 2x2x2 (needs 8 values) but only 4 values are present. Asserts ValueError matching "Unexpected end of CHGCAR data block".

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 VASP DOSCAR parsing.

Covers legacy and full density-of-states carriers, spin channels, projected blocks, and malformed or truncated input.

class tests.test_diffpes.test_inout.test_doscar.TestReadDoscar(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.inout.read_doscar().

Verifies that the DOSCAR parser produces a valid DensityOfStates PyTree with correct array shapes and expected numeric values from the minimal fixture.

See:

read_doscar()

test_parses_minimal_doscar() → None

Read minimal DOSCAR fixture and assert shape and key values of DensityOfStates.

The test loads the fixtures/DOSCAR file. It checks the array shapes and the scalar Fermi energy. It compares selected elements with the known fixture values. These checks verify the DOSCAR header and data block.

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_inout.test_doscar.TestReadDoscarFull(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.inout.read_doscar() with return_mode='full'.

Validates the full-mode DOSCAR parser that returns FullDensityOfStates objects containing spin-resolved total DOS, integrated DOS, and optionally per-atom projected DOS (PDOS). Covers spin-polarized files (both channels), non-spin files (spin-down fields are None), PDOS-containing files, and the legacy fallback for spin-polarized data.

See:

read_doscar()

test_spin_doscar_full() → None

Read spin-polarized DOSCAR in full mode and verify both spin channels.

Parses the DOSCAR_spin fixture with return_mode="full". The test checks the result type and the shape of each DOS array. It checks that both spin-down arrays exist. It compares the Fermi energy and the first value of each spin channel with fixture values. The comparisons use atol=1e-12.

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_nonspin_doscar_full() → None

Read non-spin-polarized DOSCAR in full mode and verify spin-down fields are None.

Parses the standard DOSCAR fixture (non-spin-polarized) with return_mode="full". The test checks the result type and the three spin-up array shapes. It verifies that both spin-down arrays are None. These checks confirm detection of non-spin data.

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_pdos_doscar_full() → None

Read DOSCAR containing per-atom PDOS blocks in full mode.

Parses the DOSCAR_pdos fixture with return_mode="full". The test checks the result type and verifies that pdos exists. The PDOS shape represents two atoms, three energies, and ten columns. The test also verifies natoms=2. These checks validate the PDOS block after the total DOS header.

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_spin_doscar_legacy() → None

Read a legacy spin-polarized DOSCAR and verify the spin-up result.

Parses the DOSCAR_spin fixture with return_mode="legacy". The test verifies a plain DensityOfStates result and both array shapes. It compares the first total DOS value with the spin-up value. The comparison uses atol=1e-12. This test covers the compatible path that discards spin-down data.

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_inout.test_doscar.TestReadDoscarPdosHeader(*args, **kwargs) → None

Bases: TestCase

Validate read_doscar() PDOS parsing with per-atom header lines.

See:

read_doscar()

test_pdos_with_header_line() → None

Exercise DOSCAR parsing with a header for each atom.

The test uses the DOSCAR_pdos_header fixture where each atom’s PDOS block starts with a 4-value header line (EMIN EMAX NEDOS EFERMI). The four values satisfy the column-count condition. Therefore, the parser executes the applicable header path. The test checks the PDOS shape for one atom, three energies, and nine orbital columns.

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_pdos_early_break_on_empty_line() → None

Exercise PDOS parsing with fewer rows than NEDOS.

The test writes a DOSCAR where natoms=1, NEDOS=3 but the PDOS block has only 1 data row followed by an empty line. This causes the for j in range(1, nedos): loop to hit an empty row_line and execute the break on line 230. Asserts the result is a FullDensityOfStates (parse continues with truncated data).

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_pdos_header_then_empty_line_breaks() → None

Exercise PDOS parsing with an empty line after the header.

The test writes a DOSCAR with natoms=1 and NEDOS=3. Its PDOS block has a four-value header followed by an empty line. The parser reads the header (line 204), then reads the empty line as pdos_ncols_check and hits if not pdos_ncols_check.strip(): break on line 205-206. The test asserts the result is a FullDensityOfStates with pdos=None (no PDOS data collected before the break).

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_pdos_header_inner_loop_empty_row_breaks() → None

Exercise the PDOS header loop with an empty data row.

The test writes a DOSCAR with natoms=1 and NEDOS=3. The PDOS block has a header, one valid row, and one empty row. The inner loop reads the empty row_line and hits if not row_line.strip(): break on line 217-218. Asserts the result is a FullDensityOfStates.

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 VASP EIGENVAL parsing.

Covers scalar and spin-resolved band carriers, multiple k-points, Fermi-level shifts, and malformed or truncated input.

class tests.test_diffpes.test_inout.test_eigenval.TestReadEigenval(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.inout.read_eigenval().

Covers single- and multi-k-point EIGENVAL parsing, including the loop branch for multiple k-points, and asserts BandStructure shapes and eigenvalue/k-point values.

See:

read_eigenval()

test_parses_minimal_eigenval() → None

Read minimal EIGENVAL (1 k-point, 1 band) and assert BandStructure shape and values.

The test uses the minimal EIGENVAL fixture and fermi_energy=-0.5. The test asserts eigenvalues shape (1, 1), kpoints (1, 3), kpoint_weights (1,), k-point [0,0,0], fermi -0.5, and eigenvalue -1.5. Validates header and per-k-point block parsing.

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_parses_eigenval_two_kpoints() → None

Read EIGENVAL with 2 k-points and assert both k-points and eigenvalues.

The test uses EIGENVAL_two_kp fixture to exercise the parser’s loop over multiple k-points (including the branch between k-point blocks). Asserts eigenvalues shape (2, 1), k-points at [0,0,0] and [0.5,0,0], and eigenvalues -1.0 and -0.5.

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_spin_polarized_legacy() → None

Read spin-polarized EIGENVAL in legacy mode and verify only spin-up eigenvalues.

Parses the EIGENVAL_spin fixture with return_mode="legacy", which should discard spin-down data and return a plain BandStructure. The test checks the result type and the (2, 2) eigenvalue shape. It compares both spin-up eigenvalues at k=0 with fixture values by using atol=1e-12. This exercises the legacy backward-compatibility 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_spin_polarized_full() → None

Read spin-polarized EIGENVAL in full mode and verify both spin channels.

Parses the EIGENVAL_spin fixture with return_mode="full", which returns a SpinBandStructure containing separate eigenvalues_up and eigenvalues_down arrays. Asserts the result type and both (2, 2) array shapes. It compares both spin channels at k=0 with fixture values by using atol=1e-12.

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_nonspin_full_returns_bandstructure() → None

Verify that full mode with a non-spin-polarized file returns plain BandStructure.

Parses the standard EIGENVAL fixture (ISPIN=1) with return_mode="full". Asserts the result is a plain BandStructure rather than SpinBandStructure. This result confirms that the full mode detects single-spin data.

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_inout.test_eigenval.TestReadEigenvalErrors(*args, **kwargs) → None

Bases: TestCase

Validate error paths in read_eigenval().

See:

read_eigenval()

test_eof_on_kpoint_line_raises() → None

Verify that EOF in a k-point block raises ValueError.

The test writes an EIGENVAL with a valid 6-line header followed by a blank separator but no k-point data line. _read_next_nonempty_line returns "" at EOF (line 255), then line 169 detects the empty string and raises ValueError.

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_invalid_kpoint_line_raises() → None

Verify that a short k-point line raises ValueError.

The test writes an EIGENVAL where the first k-point line has only 2 values. The test asserts ValueError matching "Invalid EIGENVAL k-point line".

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_eof_on_band_line_raises() → None

Verify that EOF in a band line raises ValueError.

The test writes an EIGENVAL with a valid k-point line but no band data. _read_next_nonempty_line returns "" at EOF (line 255), then line 179 detects it and raises ValueError.

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_invalid_band_line_raises() → None

Verify that a band line without numbers raises ValueError.

The test writes an EIGENVAL with a valid k-point line but an empty-looking band line that has no parseable eigenvalue. Asserts ValueError matching "Invalid EIGENVAL band line".

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_spin_polarized_band_missing_spin_down_raises() → None

Verify that a short spin-polarized band line raises ValueError.

The test writes an ISPIN=2 EIGENVAL with a value of 2 in its header. The band line has a spin-up energy but no spin-down energy. The test expects a ValueError that matches "Invalid spin-polarized".

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 VASP KPOINTS parsing.

Covers line-mode, automatic, and explicit sampling together with labels, weights, shifts, and malformed coordinate records.

class tests.test_diffpes.test_inout.test_kpoints.TestReadKpoints(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.inout.read_kpoints().

Covers Line-mode (with and without label fallback), Automatic, and Explicit KPOINTS formats. Asserts both legacy plotting fields (mode, labels, label_indices) and richer mode-specific metadata (grid/shift, explicit k-points/weights, line-mode endpoints).

See:

read_kpoints()

test_line_mode() → None

Read Line-mode KPOINTS and assert mode, num_kpoints, and symmetry labels.

The test parses the KPOINTS_line fixture. It verifies the mode, point count, and labels. It also verifies all metadata for line mode.

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_automatic_mode() → None

Read Automatic (Monkhorst-Pack) KPOINTS and assert mode and zero k-point count.

The test parses KPOINTS_auto. It checks the mode, zero point count, grid, and shift.

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_line_mode_label_fallback() → None

Read Line-mode KPOINTS using fallback label extraction (no “!” prefix).

The test uses KPOINTS_line_fallback where one line has five tokens (coordinates plus weight and label “G”) and another has three (no label). The test verifies the mode and both label outcomes. This input covers both label extraction branches.

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_mode() → None

Read Explicit KPOINTS and assert mode and k-point count.

The test parses KPOINTS_explicit. It checks the mode, point count, k-points, and weights.

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_mode_with_mode_header() → None

Read Explicit KPOINTS with an explicit mode header line and separate coordinate line.

The test parses KPOINTS_explicit_mode_header. A separate header line declares the mode before the coordinate system. The test checks the mode, point count, array shapes, first point, weights, and coordinate mode. This input covers the alternative KPOINTS layout.

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_inout.test_kpoints.TestReadKpointsErrors(*args, **kwargs) → None

Bases: TestCase

Validate additional paths in read_kpoints().

See:

read_kpoints()

test_explicit_break_when_excess_lines() → None

Verify that explicit KPOINTS ignores excess point lines.

The test writes a 3-kpoint Explicit KPOINTS file with 4 coordinate lines. The test checks the Explicit mode and exactly three returned k-points. The parser ignores the fourth line.

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_invalid_float_raises() → None

Verify that a nonnumeric KPOINTS token raises ValueError.

The test writes an Explicit KPOINTS with “abc 0.0 0.0” as a k-point line. The test asserts ValueError matching "Invalid explicit KPOINTS".

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_too_few_coords_raises() → None

Verify that a short KPOINTS coordinate raises ValueError.

The test writes an Explicit KPOINTS where a k-point line has only 2 values. The test asserts ValueError matching "at least 3 coordinates".

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_no_weight_column_defaults_to_one() → None

Verify the default KPOINTS weight without a weight column.

The test writes an Explicit KPOINTS where k-point lines have only 3 columns (no weight). Asserts that all weights equal 1.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_looks_like_kpoint_line_value_error_branch() → None

Verify rejection of a nonnumeric three-token k-point line.

The test uses an Explicit KPOINTS with an unrecognized mode_line. The first remaining line has three tokens and a nonnumeric first token. The test checks consumption of the mode header as coord_mode.

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_looks_like_kpoint_line_returns_true() → None

Verify acceptance of a numeric k-point line.

The test uses an Explicit KPOINTS with an unrecognized mode_line. The first remaining line contains numeric tokens. All float calls succeed (lines 272-273 executed), so the function reaches return True (line 276). This means remaining_lines.pop(0) is NOT called and coord_mode stays as scheme_or_mode (“Explicit”).

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_automatic_grid_too_few_values_raises() → None

Verify that a short automatic-grid line raises ValueError.

The test writes an Automatic KPOINTS where the grid line has only 2 integers. Asserts ValueError matching "3 values".

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_automatic_shift_too_few_values_raises() → None

Verify that a short automatic-shift line raises ValueError.

The test writes an Automatic KPOINTS where the shift line has only 2 values. Asserts ValueError matching "3 values".

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_line_mode_bad_coord_line_raises() → None

Verify that an invalid line-mode coordinate raises ValueError.

The test writes a Line-mode KPOINTS where a coordinate line has fewer than 3 float tokens. Asserts ValueError matching "Could not parse k-point coordinates".

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 VASP POSCAR parsing.

Covers VASP 4 and VASP 5 headers, direct and Cartesian coordinates, and selective-dynamics records.

class tests.test_diffpes.test_inout.test_poscar.TestReadPoscar(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.inout.read_poscar().

Covers VASP5 (species + Direct), VASP4 (Cartesian), and selective-dynamics POSCAR formats. Asserts lattice, coords, symbols, and atom_counts as appropriate.

See:

read_poscar()

test_parses_vasp5_direct() → None

Read VASP-5 POSCAR with species and Direct coordinates and assert geometry.

Parses the default POSCAR fixture. Asserts lattice (3,3), positions (6,3), and the expanded per-atom species tuple. The test validates species line parsing and direct-coordinate scaling.

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_parses_vasp4_cartesian() → None

Read VASP-4 POSCAR with Cartesian coordinates and assert geometry.

Parses POSCAR_cartesian (no species line). Asserts positions shape (2, 3) and empty species. Validates Cartesian path and single-species fallback.

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_parses_selective_dynamics() → None

Read POSCAR with Selective dynamics line and assert coordinates.

Parses POSCAR_selective. Asserts positions shape (1, 3) and first coordinate [0, 0, 0]. The test verifies consumption of the selective-dynamics line. It also checks the parsed coordinates.

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_negative_scale_sets_the_target_cell_volume() → None

Use a negative POSCAR scale as a positive target volume.

A raw cubic cell with volume eight and a requested volume of 64 needs a linear scale of two. Cartesian coordinates must use the same scale before conversion to fractional coordinates.

Notes

Write one Cartesian site in a synthetic POSCAR. Check the positive lattice, target volume, and resulting fractional position.

Return type:

None

Validate VASP PROCAR parsing.

Covers non-spin, spin-polarized, and SOC projections together with orbital ordering and malformed or truncated blocks.

class tests.test_diffpes.test_inout.test_procar.TestReadProcar(*args, **kwargs) → None

Bases: TestCase

Validate diffpes.inout.read_procar().

Verifies that the PROCAR parser produces an OrbitalProjection with correct projection array shape and optional spin/oam absent when not present in the file.

See:

read_procar()

test_parses_minimal_procar() → None

Read minimal PROCAR and assert OrbitalProjection shape and sample values.

The test loads the minimal PROCAR fixture. Asserts projections shape (2, 2, 1, 9), selected projection values (0.1 and 0.18), and that spin and oam are None. Validates k-point/band/ion block parsing and orbital channel ordering.

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_spin_procar_legacy() → None

Read spin-polarized PROCAR in legacy mode and verify only first spin block.

Parses the PROCAR_spin fixture with return_mode="legacy", which extracts only the first spin-up block. The test checks the projection shape and the selected s-orbital value. It also verifies that spin is None in legacy mode. This exercises the backward-compatible single-block extraction.

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_spin_procar_full() → None

Read spin-polarized PROCAR in full mode and verify SpinOrbitalProjection output.

Parses the PROCAR_spin fixture with return_mode="full", returning a SpinOrbitalProjection with both projections and spin arrays. The test checks the result type and both shapes. It compares the averaged s-orbital value with 0.09. This value is the mean of the two spin values. The comparison uses atol=1e-12.

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_inout.test_procar.TestReadProcarErrors(*args, **kwargs) → None

Bases: TestCase

Validate error handling in read_procar().

See:

read_procar()

test_empty_procar_raises() → None

Verify that an empty PROCAR file raises ValueError.

The test writes a file with no valid k-points block and calls read_procar. Asserts a ValueError matching "No valid PROCAR blocks found".

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_inout.test_procar.TestReadProcarSOC(*args, **kwargs) → None

Bases: TestCase

Validate SOC PROCAR parsing (procar.py lines 191-210, 282-283, 307).

See:

read_procar()

test_soc_procar_full() → None

Read SOC PROCAR (4 blocks) in full mode and verify spin components.

The test uses the PROCAR_soc fixture. It has a title before the first k-point block and a blank line before the band header. The fixture contains four blocks. The test checks a SpinOrbitalProjection with projections shape (1, 1, 1, 9) and spin shape (1, 1, 1, 6).

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