Command-Line Interface#

The pyscf2mppt command runs a direct PySCF calculation, inspects direct-stage checkpoints, operates enabled downstream stages from an existing HDF5 file, or creates isolated managed single-point and sweep directories.

Options#

pyscf2mppt [input.yaml]
  -v, --version
  --checkpoint-dir DIR
  --resume-from DIR
  --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]
  [--selection-executable FILE]
  [--diagpt-executable FILE]
  [--heffso-executable FILE]

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

An input YAML is required except when --inspect-checkpoint is used. Only .yaml and .yml are accepted; legacy .inp input is rejected by this CLI. Direct orchestration exceptions are normally written to stderr as Error: ... without a Python traceback. Argparse uses its standard usage/error format; managed child stderr is merged into run.log/stdout, and sweep point failures use point-specific stderr summaries. run or sweep must be the first argument; otherwise the backward-compatible direct parser is used. Managed commands do not accept direct-only options such as --stop-after, --from-hdf5, --checkpoint-dir, or checkpoint inspection.

Direct Calculation#

pyscf2mppt input.yaml \
  --checkpoint-dir checkpoints/run1 \
  > run.log 2> run.err

The direct 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.

There is no --workdir option. The current directory is the work directory, and direct runs set PySCF scratch to <workdir>/tmp.

Direct Checkpoints#

A checkpoint directory can contain:

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

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 --resume-from checkpoints/run1

The supplied YAML must still exist and pass full parsing. The saved normalized input then replaces it for direct PySCF stage planning and execution, and resume restores the saved work directory and source path. Automatic downstream execution is different: it uses the newly supplied YAML’s mppt section. A changed prefix, output path, or downstream configuration can therefore affect the workflow after resumed PySCF work. Use a new checkpoint directory for changed inputs. If --checkpoint-dir and --resume-from are both supplied, they must resolve to the same directory. Direct checkpoints do not compare a scientific-input fingerprint, external basis/ECP/GRPP file contents, package version, executable identity, or runtime environment. Those external files are not copied into the checkpoint. The recorded package version is informational.

Dump completion is metadata-only. A checkpoint whose last completed stage is dump returns a completed result without checking that the configured HDF5 file still exists or is unchanged. With downstream stages disabled, the CLI can therefore return success for a missing dump. With stages enabled by the current YAML, downstream execution subsequently opens the current YAML’s HDF5 path and can fail. Relative HDF5 paths are resolved from the current process directory, even though scratch and workflow sidecars use the restored checkpoint work directory. Start a fresh direct run to recreate a missing dump. Managed runs add resource hashes and HDF5 input identity, but use the stricter resume rules in managed runs and sweeps.

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

pyscf2mppt --inspect-checkpoint checkpoints/run1

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

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

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. With all downstream stages disabled, workflow-only mode is a successful no-op and may not open the HDF5 file.

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#

pyscf2mppt run defaults 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. See managed runs and sweeps for the artifact and fallback rules.

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 revalidates completed points. --dry-run validates expanded inputs and resources but does not preflight executables.

Exit Status And Signals#

  • Direct and managed orchestration success 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; direct mode has no managed process-group guarantee.