Quick Start

This example runs a small H2 SCF calculation and writes the HDF5 file used by the downstream MPPT workflow. Complete the installation first.

Prepare A Working Directory

pyscf2mppt uses the current directory as its work directory and creates a tmp/ scratch directory there. Choose a filesystem with enough space before starting a large integral transformation.

mkdir -p runs/h2
cd runs/h2

Create h2.yaml:

molecule:
  symmetry: false
  charge: 0
  units: angstrom
  so: false
  atoms:
    - [H, 0.0, 0.0, 0.0]
    - [H, 0.0, 0.0, 0.74]

basis:
  H: [library, sto-3g]

scf:
  spin: singlet
  type: rhf
  conv_tol: 1.0e-10
  omp_num_threads: 2

mppt:
  prefix: h2
  output_hdf5: h2.h5

Run with direct-calculation checkpoints:

pyscf2mppt h2.yaml --checkpoint-dir checkpoints > h2.log 2> h2.err

The run should print an SCF energy and create h2.h5. The three downstream stages are disabled unless their YAML sections contain enabled: true.

For an isolated artifact directory that captures file resources, manifests, logs, locks, and managed resume state, run the same input from its parent directory with:

cd ..
pyscf2mppt run h2/h2.yaml --output-dir h2-managed
cd h2

See managed runs and sweeps before relying on resume: a managed retry can rerun SCF/CASSCF when the managed HDF5 identity is not yet complete.

Inspect the top-level HDF5 content without loading integral arrays:

python - <<'PY'
import h5py

with h5py.File("h2.h5", "r") as h5f:
    print("attributes:", sorted(h5f.attrs))
    print("objects:", sorted(h5f.keys()))
PY

Stop And Resume PySCF Work

Stop after SCF and resume later:

pyscf2mppt h2.yaml \
  --checkpoint-dir checkpoints-scf \
  --stop-after scf

pyscf2mppt h2.yaml --resume-from checkpoints-scf

The current h2.yaml must still exist and parse. Resume uses the saved input.normalized.json for PySCF stages, so edits do not change those stages, but the current YAML’s mppt section controls automatic downstream execution. Start a new checkpoint directory whenever scientific input, external basis/ECP/GRPP resources, package/runtime versions, or environment changes. Direct checkpoints do not fingerprint those values. They also do not own the HDF5 dump: a checkpoint recorded through dump can report completion without checking that the dump still exists.

Inspect a checkpoint without rerunning SCF:

pyscf2mppt --inspect-checkpoint checkpoints-scf

--inspect-full currently prints checkpoint metadata only; additional full inspection is not implemented.

Run Downstream Stages From HDF5

The workflow-only mode accepts a YAML file containing only mppt. This compact example is a template, not a production model-space recommendation:

mppt:
  prefix: h2

  cipsixx:
    enabled: true
    initial_space: hf
    max_selected: 10

  diagpt:
    enabled: true
    integral_space: auto

  heffso:
    enabled: true
    nvectw: 1
    iorder: 2
    print_level: 1

Workflow-only parsing currently ignores top-level keys other than mppt and unknown keys directly under mppt; nested stage sections remain strict. The explicit --from-hdf5 argument selects the file. If every stage remains disabled, the command is a successful no-op and may not open that file.

Run only those enabled stages:

pyscf2mppt workflow.yaml \
  --from-hdf5 h2.h5 \
  --selection-executable "$MPPT_ROOT/build/bin/cipsixx_select" \
  --diagpt-executable "$MPPT_ROOT/build/bin/diagpt" \
  --heffso-executable "$MPPT_ROOT/build/bin/heffso"

Set MPPT_ROOT to the repository root, or pass absolute executable paths. Selection thresholds, active orbitals, root counts, and state weights must be chosen for the scientific problem; do not copy production values from another system.

The shared file records restart state under /mppt/workflow/stages. Generated inputs and logs are under .mppt-workflow/. See the unified workflow, CLI reference, and output contract before running larger calculations.

Use the benchmarks and scaling guidance to choose thread counts and size scratch resources. Results are workload- and host-specific, and a skipped target is not a measured performance result.