Command-Line Interface#

Every pyscf2mppt calculation owns an isolated directory and a complete run.log. The default is runs/<input-stem> below the current directory; use --output-dir to choose another location. pyscf2mppt run is an alias for the same calculation interface.

Options#

pyscf2mppt [input.yaml]
  -v, --version
  --output-dir DIR
  --resume
  --full-output
  --heffso-report
  --stop-after {input_normalized,scf,casscf,orbitals,dump}
  --inspect-checkpoint DIR
  --inspect-full
  --from-hdf5 FILE
  --force-workflow
  --selection-executable FILE
  --diagpt-executable FILE
  --heffso-executable FILE

pyscf2mppt run input.yaml
  [--output-dir DIR] [--resume] [--force-workflow]
  [--heffso-report]
  [--selection-executable FILE]
  [--diagpt-executable FILE]
  [--heffso-executable FILE]

pyscf2mppt sweep sweep.yaml
  [--output-dir DIR] [--resume] [--dry-run] [--force-workflow]
  [--heffso-report]
  [--selection-executable FILE]
  [--diagpt-executable FILE]
  [--heffso-executable FILE]

pyscf2mppt archive run.json --output-dir DIR [--diagnostics]

An input YAML is required except when --inspect-checkpoint is used. Input files must use the .yaml or .yml extension. The terminal shows stage transitions, elapsed times and selected progress lines. --full-output mirrors every process line. Both modes retain complete process output on disk, including stderr and worker tracebacks. YAML/argument failures before a run is created are printed to stderr; executable preflight failures after creation are recorded in the run directory.

run, sweep, or archive must be the first argument. The calculation and run interfaces accept the same options, including --stop-after and --from-hdf5. --heffso-report cannot be combined with --stop-after.

Calculation#

pyscf2mppt input.yaml --output-dir runs/run1

The PySCF stage plan always contains input_normalized and scf. It adds:

  • casscf when an active-space calculation is configured;

  • orbitals when projection or orbital analysis is requested;

  • dump unless mppt.no_dump: true.

The requested stop stage is not required to be in the plan. A non-CASSCF run with --stop-after casscf returns after SCF. In contrast, if orbital preparation is absent, --stop-after orbitals does not stop after SCF and the run proceeds to dump when dumping is enabled. --stop-after dump completes the dump but suppresses automatic downstream workflow execution.

The selected output directory is the work directory. Input resources resolve relative to the source YAML and are copied into input/resources/. PySCF scratch lives in <output-dir>/scratch. The shared HDF5 lives under data/.

Checkpoints And Resume#

The run-owned checkpoints/ directory contains the available Python restart files:

input.normalized.json
scf.npz
casscf.npz
orbitals.npz
stage.json

stage.json records the stage plan, completed/next stages, available artifacts, package version, saved work directory, and original source path. Dump completion is recorded in metadata; the HDF5 dump itself is not copied into the checkpoint.

Resume with:

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

Resume checks normalized input, copied resources, directory provenance and checkpoint payloads. A pre-dump checkpoint can continue into the dump. Reusing a dump-complete checkpoint additionally requires a valid HDF5 with the accepted managed-input identity. Each attempt preserves prior diagnostic logs and inputs under logs/attempts/, while run.log and logs/events.jsonl retain the history. See managed runs and sweeps for fallback rules.

Use a new output directory when changing the scientific input. The former public --checkpoint-dir and --resume-from flags are replaced by --output-dir and --resume; checkpoints always belong to the run.

Checkpoint inspection reconstructs available orbital state without rerunning SCF/CASSCF or the AO-to-MO transformation:

pyscf2mppt --inspect-checkpoint runs/run1/checkpoints

Despite its name, --inspect-full currently selects metadata-only inspection and reports that full inspection is not implemented.

Workflow-Only Mode#

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

The workflow YAML may contain only mppt; molecule, basis, and SCF sections are not required. --from-hdf5 cannot be combined with --stop-after.

The HDF5 path resolves from the caller’s directory and is an explicit writable reference: selection and workflow checkpoints update that file in place. No large-file copy is made when launching. run.json.external_hdf5 records the source; run.json.hdf5 is its logical path in an archive. Archiving explicitly copies and verifies the referenced file, making the bundle self-contained. Updating a file belonging to another run changes its recorded artifact identity.

Workflow-only parsing differs from full-calculation parsing: top-level keys other than mppt and unknown keys directly under mppt are currently ignored. Unknown keys inside cipsixx, diagpt, or heffso are rejected. Validate spelling carefully because a typo such as mppt.prefx falls back to the default prefix. The explicit --from-hdf5 argument selects the input file; mppt.output_hdf5 does not override it. Completion validates the referenced HDF5 even when all downstream stages are disabled.

Files referenced only by ignored PySCF settings (basis, ECP, GRPP, initial guess, auxiliary basis, or projection basis) are not read, copied, or included in the workflow-only resume identity. Existing workflow-only directories whose identities included these unused resources require a new --output-dir after upgrading; directories whose previous identities contained no producer resources are unaffected.

Downstream executables resolve in this order:

  1. Explicit --selection-executable, --diagpt-executable, or --heffso-executable path.

  2. CIPSIXX_SELECT_EXECUTABLE, DIAGPT_EXECUTABLE, or HEFFSO_EXECUTABLE environment variable.

  3. The executable name on PATH.

Matching completed stages are reused. --force-workflow reruns every enabled stage, with normal downstream invalidation. See outputs and restart state for fingerprints and success markers.

Managed Single Points#

Both calculation spellings default to runs/<input-stem>. A fresh run requires a nonexistent output directory. --resume requires the same normalized input, the original absolute run location, and an existing manifest. Each resume is a new recorded attempt; it does not guarantee direct PySCF checkpoint reuse. Managed paths are confined to the point directory, file-based basis/ECP/GRPP resources are copied and hashed, and a nonblocking lock prevents concurrent writers. --heffso-report requests the installed Caspy eight-file report and includes it in the schema-v2, layout-v2 terminal artifact inventory; it requires enabled HEFFSO properties, mppt.no_dump: false, and a regular non-editable Caspy installation. The output contract gives the supported install command. See managed runs and sweeps for the artifact and fallback rules.

Publish one complete, validator-backed manifest without following filesystem aliases:

pyscf2mppt archive runs/h2/run.json --output-dir archives/h2

The destination must be a new directory outside the source run. The command revalidates owning schemas, exact file bytes, executable identities, path containment, and the original run-directory provenance before copying only the declared bundle. Atomic no-replace publication currently requires Linux renameat2 support.

For a failed or interrupted run, publish an explicitly diagnostic bundle:

pyscf2mppt archive runs/h2/run.json --output-dir archives/h2-failed --diagnostics

Its manifest retains the failed/interrupted status and makes no scientific completion claim. Old-layout directories require their original release for resume/archive; start a new directory, optionally with --from-hdf5, to use the new layout.

Rebuild and install DIAGPT and HEFFSO together with the Python frontend when upgrading: the new layout uses their separate restart/report destinations.

Cartesian Sweeps#

pyscf2mppt sweep expands parameters from a sweep YAML into deterministic, sequential managed points below runs/<sweep-stem>/points. Ordinary point failures are recorded and later points continue. --resume requires an unchanged expanded definition and the same report policy, so repeat --heffso-report when resuming a reporting sweep. Completed points are revalidated. --dry-run validates expanded inputs and resources but does not preflight executables. --heffso-report requests and inventories the same report for every point. summary.csv lists statuses, SCF/CASSCF energies in Hartree and point log paths; sweep.log records aggregate progress. Each point uses the same run layout.

Exit Status And Signals#

  • Successful completion of the requested calculation returns 0.

  • Argparse usage errors return 2.

  • Managed single-point failure returns the child code when nonzero, otherwise 1.

  • A sweep with any incomplete point returns 1.

  • While a managed child is running, SIGINT or SIGTERM records interruption, terminates that process group, and returns 130. Signals before child launch or between sweep points are not guaranteed to update a manifest. Top-level SIGINT returns 130.