Development And Testing#

Repository Layout#

Path	Responsibility
`pyscf2mppt/`	YAML parsing, PySCF calculations, integral export, and workflow orchestration
`external/cipsixx/`	Pinned selected-CI implementation
`diagpt/`	Scalar effective-Hamiltonian construction and diagonalization
`heffso/`	Spin-orbit effective Hamiltonian and eigensolvers
`hdf5_util/`	Shared HDF5 readers and handoff schema helpers
`test_suite/`	CTest-discovered integration and shell tests
`docs/`	Hosted Sphinx documentation

Build out of source in build/ and use a serial build:

cmake --build build --parallel 1

Test Levels#

# Python package
python -m pytest -q pyscf2mppt/tests

# Compiled units
cmake --build build --target test-unit

# Unit and light integration coverage
cmake --build build --target test-light

# Unit, light, and selected heavy coverage
cmake --build build --target test-main

# Every registered test
cmake --build build --target test-manual

test-light is broader than one SCF smoke test. It covers compiled units and multiple Python/PySCF paths. CTest injects exact paths for cipsixx_select, DIAGPT, and HEFFSO from the current build. Direct workflow scripts default to build/bin and accept MPPT_BIN_DIR for another build tree.

Run focused tests with CTest:

ctest --test-dir build -R '^heffso_unit_' --output-on-failure
ctest --test-dir build -L DIAGPT --output-on-failure
ctest --test-dir build -R '^pyscf2mppt_hf_h2$' --output-on-failure

Quality Checks#

After Python changes, run the repository fixer twice, then type checking:

./ruff_autofix.sh pyscf2mppt
./ruff_autofix.sh pyscf2mppt
pyright

For diagpt/ Fortran changes:

fortitude check
ffmt --check .

Apply formatting in small reviewed batches. The current Fortitude/ffmt policy is scoped to diagpt; do not apply it wholesale to fixed-form legacy code.

HEFFSO production targets retain the legacy -fno-automatic flag. New reentrant routines must explicitly release local allocatable work buffers, and their repeated-call tests must use the same flag so static-local lifetime bugs are visible before an end-to-end run.

Numerical Acceptance#

Eigenvectors are not unique up to sign or complex phase. Degenerate eigenspaces may also rotate between valid bases. Validate eigenvalues, projected subspaces, energies, and downstream observables rather than requiring byte-identical eigenvector output.

Documentation In Changes#

Public behavior, configuration, file formats, outputs, or build/test commands must update their owning documentation in the same change. Follow the documentation guide.