Development And Testing#
Complete the environment-manager setup and
MPPT installation first. Commands on this page run from the
repository root with the mppt environment active and the build/ tree already
configured unless a section says otherwise.
Repository Layout#
Path |
Responsibility |
|---|---|
|
YAML parsing, PySCF calculations, integral export, and workflow orchestration |
|
Pinned selected-CI implementation |
|
Scalar effective-Hamiltonian construction and diagonalization |
|
Spin-orbit effective Hamiltonian and eigensolvers |
|
Shared HDF5 readers and handoff schema helpers |
|
CTest-discovered integration and shell tests |
|
Hosted Sphinx documentation |
Build out of source in build/ and use a serial build:
cmake --build build --parallel 1
Test Levels#
The maintained case catalog is test_suite/README.md. Cases are grouped by
purpose: pyscf2mppt/ for frontend stages, workflows/yaml/ and
workflows/external_reference/ for end-to-end entry routes, solvers/ for
numerical consistency, and benchmarks/ for tooling. Each category and case
owns its launch instructions. Runtime labels are independent of folder names.
CTest identifiers follow relative paths with slashes replaced by underscores.
For example, the complete H2O case is workflows_yaml_hf_H2O_no_symm.
# 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,
multiple Python/PySCF paths, and a compact HF calculation using the installed
native libgrpp and libgrpppy bindings. Run cmake --install build before this
suite. 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.
CTest provides those paths as MPPT_CIPSIXX, MPPT_DIAGPT, and MPPT_HEFFSO.
CLI test launchers must pass them through the executable options or export
CIPSIXX_SELECT_EXECUTABLE, DIAGPT_EXECUTABLE, and HEFFSO_EXECUTABLE.
Do not rely on installed native programs being present on PATH in CI.
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
Python Source And Editable Tests#
Use one thread for the small frontend suite. From the repository root, with the Python dependencies and native reorder extension already available:
export OMP_NUM_THREADS=1 OPENBLAS_NUM_THREADS=1 MKL_NUM_THREADS=1
python -m pytest -q pyscf2mppt/tests
Also verify the CI-style editable install from the package directory. To avoid
reinstalling into a shared environment, create a private environment from the
prepared mppt interpreter:
export CMAKE_BUILD_PARALLEL_LEVEL=1
python -m venv --system-site-packages .venv-frontend-tests
.venv-frontend-tests/bin/python -m pip install --no-deps --no-build-isolation \
-e './pyscf2mppt[test]'
(cd pyscf2mppt && ../.venv-frontend-tests/bin/python -m pytest -q tests)
The private install requires the existing runtime/test dependencies plus
scikit-build-core, pybind11, CMake and a C++ compiler. The extension build is
serial. These commands cover the frontend suite, not the compiled Fortran or
full release validation suites.
Tests and their helpers live in the source checkout, not the installed
pyscf2mppt package. Import a sibling helper as, for example,
from auxiliary_basis_fixtures import auxiliary_input, matching the existing
workflow_fixtures convention. Use normal pyscf2mppt... imports for production
code. Pytest’s default import mode supplies the test directory; do not add a
sys.path workaround or ship test helpers as production modules.
An editable import finder can select the installed production package before
normal source-path lookup. Therefore from pyscf2mppt.tests... can fail even
though pytest already configures pythonpath = [".."]. A source-only pass is
not evidence that editable collection works. After production Python edits,
repeat the private install before testing: this build configuration can resolve
Python modules to installed copies rather than live source files.
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 sources.
HEFFSO production targets use the -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#
Apply the MPPT symmetry and convergence rules before assigning a degeneracy oracle. Rebuilding MPPT after an input-basis change need not preserve energies. Check S and applicable L/J completeness and selection convergence; multiplet splitting may increase or decrease as the space grows. Kramers protection requires time-reversal closure and symmetry of the approximate Hamiltonian. These conditions are distinct from angular completeness.
The following equivalence requirement applies to the same constructed operator and space, including a consistent passive transformation of all matrices.
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.