MPPT v0.2.0

Release date: 2026-09-23. Changes since v0.2.0-rc.7.

At a glance

• One directory per calculation: logs, results and restart state.

• External PySCF reference examples, including LIBGRPP and DMRG-CASSCF.

• YAML selection of SCF initial guesses, atom-specific auxiliary bases and AVAS reference bases.

• Integral export: memory planning, blocked exact transformations and DF-expanded export.

• DIAGPT/HEFFSO: 3000-MO capacity and measured workload sizes.

Migration required: CLI checkpoint options and output paths changed. See Action required below.

Runs and logs

pyscf2mppt input.yaml --output-dir runs/example
pyscf2mppt input.yaml --output-dir runs/example --resume

The default directory is runs/<input-stem>/. pyscf2mppt run and sweep points use the same layout:

runs/example/
├── summary.md       — status, energies, errors and diagnostic links
├── run.log          — complete output across stages and attempts
├── run.json         — run metadata and artifact locations
├── input/           — inputs and copied resources
├── logs/            — original stage logs
│   └── attempts/    — diagnostics from previous attempts
├── data/            — HDF5, native handoffs and numerical results
├── reports/         — scientific tables, analysis and Caspy reports
├── checkpoints/     — restart files
└── scratch/         — temporary files

--full-output also prints the full stream in the terminal.

Collect diagnostics from a failed or interrupted run:

pyscf2mppt archive runs/example/run.json \
  --output-dir archives/example-diagnostics --diagnostics

The destination must be new. The bundle retains the failed/interrupted status.

See outputs, resume and archives.

External PySCF examples

These examples start in external Python code and export a PySCF reference. LIBGRPP was already available through YAML; the new example demonstrates its external-reference route.

Under test_suite/workflows/external_reference/:

• h2_scf: PySCF RHF → HDF5 → CIPSIXX → DIAGPT → HEFFSO, all launched from Python. Includes an independent FCI comparison.

• h2_casscf: PySCF RHF → CASSCF → HDF5 in Python; downstream CIPSIXX → DIAGPT → HEFFSO through the Python API or the workflow-YAML CLI shown in test.sh.

• h4_dmrg_casscf: PySCF RHF → Block DMRG-CASSCF → HDF5 → CIPSIXX → DIAGPT → HEFFSO, launched from Python.

• ce_ypo4_grpp: PySCF RHF + LIBGRPP → HDF5, including spin-orbit integrals → CIPSIXX → DIAGPT → HEFFSO, launched from Python; 150 AOs and 40 selected MOs.

Each run.py reads downstream settings from workflow.yaml. --dump-only stops after export; pyscf2mppt --from-hdf5 can run the downstream YAML later. DMRG exports orbitals and the Hamiltonian; CIPSIXX performs its own selection.

See examples and continuation modes and DMRG setup.

SCF and auxiliary bases

Initial guess

RHF/ROHF example:

scf:
  initial_guess:
    method: hcore

• Methods: minao, atom, hcore (1e), huckel, mod_huckel, sap, chkfile.

• chkfile: starting density from a native PySCF checkpoint, with optional basis projection. Starts a new SCF calculation; it is not pyscf2mppt --resume.

• sap: library or file fits, including atom-specific sources.

• Omitted initial_guess: previous initialization behavior.

• Changing the guess does not guarantee convergence.

Start with PySCF’s initial-guess methods. For MPPT YAML, see supported settings and the checkpoint example.

Atom-specific auxiliary bases

Both scf.auxbasis and casscf.auxbasis accept maps of library or file sources:

scf:
  density_fit: true
  auxbasis:
    O: [file, aux/O.nwchem]
    O1: [file, aux/O1.nwchem]
    H: [library, def2-universal-jkfit]

The example requires the named atoms and basis files relative to the YAML. O and O1 are distinct. Managed runs copy and hash explicit files. Existing string and null settings remain supported.

See auxiliary-basis input. SCF/CASSCF density fitting and integral-export mode are selected separately.

AVAS and orbital placement

Projection bases can differ from the working orbital basis:

• casscf.avas_basis: CASSCF initial-guess AVAS.

• mppt.avas_basis_occupied: occupied generation, placement and analysis.

• mppt.avas_basis_virtual: virtual generation and analysis.

• Choose a library basis or a file for each element/atom label.

• Unspecified atoms keep the working basis. The reference AO count may differ.

• Enable AVAS/orbital generation separately; a basis setting does not activate it.

• Inspect the saved reference bases and projection weights in HDF5.

Occupied-orbital fix: placement no longer remixes the projected block through whole-window Fock canonicalization. Final-order Fock expectations are logged.

See the complete example, basis settings and placement.

Integral export

Memory planning

Set the available calculation memory with molecule.max_memory (MB). The exporter accounts for memory already in use and chooses work batches and RAM/disk storage. Leave mppt.max_mem_bytes unset or null for automatic planning.

See memory settings and external-reference export.

Blocked exact transformations

For selected-route exact integrals, mppt.exact_half_block_size reduces the largest intermediate file. Smaller blocks can make export slower.

Its size scales as min(b, C+A)/(C+A) relative to an unblocked half-transform: b is the block width, C the core count and A the selected count. For 1000 AOs, 500 MOs, C=100, A=20, choosing b=32 reduces that file’s estimated payload from 192.19 GB to 51.25 GB. These are storage estimates, not timings.

See settings and storage scaling.

DF-expanded export

mppt:
  integral_mode: df

• Transforms three-centre AO DF factors to MO factors, then reconstructs the four-index MO integrals used by MPPT.

• Avoids the exact four-centre AO-to-MO transformation. Factor storage scales as Q*M*(M+1)/2 values for auxiliary rank Q and M MOs, reducing intermediate memory and often transformation time.

• Writes the usual MPPT/CIPSIXX integral datasets. Consumers do not read factors.

• Uses a DF approximation; accuracy depends on the auxiliary basis. exact remains the default, independently of SCF/CASSCF density fitting.

See DF export and auxiliary-source selection.

Orbital capacity and tested sizes

DIAGPT and HEFFSO accept up to 3000 physical spatial orbitals. Completed workload examples:

Reference/system	Retained MOs	DIAGPT model rows (ncf)	Host
Ce:YPO4, RHF-based selection	750	1142	Xeon E5-1650, Sandy Bridge
Ce:YPO4, RHF-based selection	1052	1236	Xeon E5-1650, Sandy Bridge
Ce:YPO4, 1470-AO SA-CASSCF reference	1300	12	Xeon E5-1650, Sandy Bridge
Ce3+ atomic selected-space benchmark	232	10701	Xeon E5-2680 v4, Broadwell

ncf includes the adapted model space; it can exceed the physical determinant count. The 1470-AO reference was exported with 1300 MOs, not 1470 MOs and 1000 determinants.

At fixed orbital data, a useful planning model is linear in ncf for diagonal PT2 and quadratic in ncf for off-diagonal Heff pairs. In the 750→1052-MO selection comparison, off-diagonal time grew 2.86×; the integral-count × pair-count model gives 2.78×. These runs also differ in roots and build settings, so they do not determine a universal scaling exponent.

DIAGPT’s off-diagonal Heff build uses one thread when ncf - 1 < 4*T, where T is the requested OpenMP thread count. This condition applies to that stage, not to the whole workflow.

See measurements and scaling and capacity limits.

Caspy reports — WIP

Caspy provides state/occupation tables, orbital-character and configuration analysis, energy-level diagrams, and stick/broadened transition spectra. Its interaction interface is work in progress and will change.

See the new Caspy guide for installation, commands, output files and plot examples.

Action required

If you are migrating an existing calculation

Keep the old directory: use its original MPPT release for resume/archive. There is no automatic directory conversion.

Reuse its HDF5 in the new release: PySCF and integral export are not repeated.

pyscf2mppt workflow.yaml --from-hdf5 existing.h5 --output-dir runs/downstream

The HDF5 must be writable. Compatible downstream checkpoints inside it are reused when their configuration, executables and outputs still match. Missing/moved native outputs can require DIAGPT/HEFFSO to run again. To consume an already selected model space without reselection, set mppt.cipsixx.enabled: false and enable the required downstream stages.

Update your launch scripts:

• --checkpoint-dir / --resume-from → --output-dir / --resume.

• Read results from data/, logs from logs/, reports from reports/.

• Use a new directory after changing scientific input; --resume validates it.

See HDF5 continuation and migration/reuse rules.

Component versions

Component	Version
MPPT	v0.2.0
pyscf2mppt	0.6.0
libgrpppy	0.1.2
Caspy	0.5.0
Managed-run schema / directory layout	2 / 2
HEFFSO properties schema	3
PRIMME	3.2.3

Known limitations

• DMRG-CASSCF is currently available through external PySCF references.

• CIPSIXX can spend most of its time rebuilding/merging parent-excitation candidates in wide, highly unfrozen spaces. Iterative selection may become impractical; one or a few growth steps can be the feasible starting point. This is not a two-iteration program limit. See selection costs.

• Integral storage remains a memory/disk limit for large systems.

• Small-system timings do not predict large-system runtime.

• On Xeon E5-1650 (Sandy Bridge), a PySCF RHF run failed to converge with MKL 2026.1; multithreaded dsyevr returned nonorthogonal eigenvectors. OpenBLAS restored convergence. See affected stack and workarounds.

Other fixes

• Export: always save intdip/intang; ignore an out-of-range delete_from with a warning instead of dropping orbitals. Old files are not changed.

• Native stages: fixed the odd-electron selected-route infinity-index crash; HEFFSO/PRIMME automatic blocks respect the search basis.

• GRPP uses supported shell-pair calls instead of unavailable matrix entry points.

• Exact-export J/K reuses screening setup between batches; no new setting.

• Reports/restart: Caspy accepts 1 <= metat <= ncf; corrected prefix/path validation, duplicate log capture and attempt/archive diagnostics.