Troubleshooting

Configure And Build

cipsixx source is missing

Release snapshots include the pinned source under external/cipsixx. Confirm that the checkout is complete, or configure another compatible pinned source with -DMPPT_CIPSIXX_SOURCE_DIR=/path/to/cipsixx.

If selection is not needed, configure with -DMPPT_ENABLE_CIPSIXX=OFF.

HDF5 is not found

Use one consistent prefix for CMake and runtime libraries:

cmake -S . -B build \
  -DCMAKE_PREFIX_PATH="$CONDA_PREFIX" \
  -DHDF5_ROOT="$CONDA_PREFIX"

HDF5 is required for every supported build. Do not combine an HDF5-enabled Python environment with unrelated system HDF5 libraries in the same build.

OpenMP configure failure

OpenMP C++ and Fortran support are required. Install the host compiler runtime or point CMake to the active environment’s libgomp.so.1.

PRIMME cannot be fetched or built

PRIMME 3.2.3 is a mandatory pinned build dependency. The first configuration requires access to its upstream Git repository plus a C compiler and make. Fix the fetch or compiler error and rerun CMake; DIAGPT and HEFFSO have no alternate eigensolver path.

Tests

A workflow test cannot find an executable

Run repository suites through cmake --build build --target test-light so CTest injects exact target paths. A workflow test.sh run directly defaults to the repository’s build/bin; set MPPT_BIN_DIR to select another build tree.

YAML And Direct Runs

Symmetry is rejected

The current YAML runtime supports C1 only. Omit molecule.symmetry, set it to false, or use C1.

CASSCF input is incomplete

A CASSCF run requires both active_orbitals and n_active_electrons. An unconverged SCF is rejected before CASSCF.

Resume ignores YAML edits

The current YAML must still exist and parse. Resume then restores input.normalized.json for direct PySCF stages, but any automatic downstream workflow uses the current YAML’s mppt section. Start a fresh checkpoint after changing scientific input, external basis/ECP/GRPP files, package/runtime versions, or execution environment. Direct checkpoints do not fingerprint those inputs.

Resume reports completion but the HDF5 dump is missing

A direct checkpoint records dump completion in stage.json but does not own or validate the HDF5 file. Resuming a completed dump checkpoint can therefore return success after the dump was moved, deleted, or replaced when downstream stages are disabled. If the current YAML enables downstream stages, they can fail when they subsequently open the current YAML’s HDF5 path. Start a fresh direct run to recreate it. Use a managed run when resource hashing and HDF5 input identity are required.

Scratch or integral dump runs out of space

Direct CLI runs use <workdir>/tmp. Run from a filesystem with enough scratch and destination capacity. Selected-route dumps omit int2e_full, but still store full J/K slices and the required pair-packed ERI blocks. The block-size formulas and remaining limits are documented in the selected-route contract. mppt.max_mem_bytes controls transformation and J/K batching, not final dataset volume.

Managed Runs And Sweeps

A fresh managed run says the directory already exists

Fresh managed runs and sweeps require a nonexistent output directory; they do not adopt arbitrary existing files. Use --resume only for the original managed directory with a matching manifest and normalized input. Otherwise choose a new nonexistent path.

A copied or moved managed directory cannot resume

This is expected for a point: run.json stores its original absolute directory, and point resume rejects a different location. A moved sweep root has no global location check, but every existing point fails its individual location check; missing point directories can start fresh and later points continue. Keep the moved tree as an archive, choose a new nonexistent output path, and start a new run or sweep from the source YAML.

A managed resume reruns SCF or CASSCF

Direct checkpoint resume is enabled only when all checkpoint payloads are valid and, for a dumping run, the HDF5 output has the matching managed-input hash. That hash is written after a successful managed attempt. An interrupted or downstream-failed attempt can therefore restart the direct calculation even when some checkpoint files exist. Inspect the new command and attempt number in run.json and the separators in run.log.

The managed directory is locked

Managed roots are single-writer resources. Another active run or sweep holds .pyscf2mppt.lock. Do not delete the lock while a process is active. After an abnormal host failure, confirm no process is using the directory and rerun with --resume; the lock is advisory and is released when the owning process exits. If termination happened after directory creation but before run.json or sweep.json was written, neither fresh run nor resume can adopt that partial directory. Preserve it for diagnosis if needed, then choose a new nonexistent output path.

Sweep dry-run did not find a missing executable

--dry-run validates the sweep schema, Cartesian expansion, normalized inputs, and file resources, but returns before executable preflight. Run the non-dry command to validate enabled selector, DIAGPT, and HEFFSO executables before the sweep root is created.

One sweep point failed

Ordinary point failures are recorded and later points continue. Inspect sweep.json, then the point’s run.json and run.log when present. A failure before child launch can have no run.log. Resume the unchanged sweep to attempt failed, interrupted, and completed points through the same revalidation path.

Downstream Workflow

An executable is not found

Pass an explicit CLI path, set the corresponding environment variable, or put the executable on PATH. Resolution order is documented in the CLI reference.

Selected DIAGPT contract is incomplete

Compare the file against the selected-route dataset list. The current loader requires all four pair-packed ERI blocks; older 4D selected blocks are not a substitute.

A stage reruns unexpectedly

Each stage fingerprint covers normalized configuration, executable identity, and consumed inputs. A separate output_fingerprint covers durable outputs. A changed input or missing/changed output invalidates reuse. Inspect /mppt/workflow/stages/<stage>, both fingerprints, and its log_path attribute.

Print stage metadata without reading large arrays:

python - <<'PY'
import h5py

with h5py.File("calculation.h5", "r") as h5f:
    stages = h5f.get("/mppt/workflow/stages")
    if stages is None:
        print("No workflow checkpoints")
    else:
        for name, group in stages.items():
            print(name, dict(group.attrs))
PY

HEFFSO exits but the workflow reports failure

The orchestrator requires a nonempty <prefix>_sovec file and the fin heffso log marker, a complete bounded report, and exactly the configured nvectw state rows. Effective-operator runs additionally require a complete mppt_heffso_effective_operators_v1 artifact with the same state count and absolute Hartree energies. Inspect .mppt-workflow/logs/heffso.log and stderr; process exit status alone is not a completion contract.

Reporting A Problem

Include the configure command, compiler/CMake versions, input YAML, relevant stage attributes, and the bounded .mppt-workflow log. Do not attach an entire large HDF5 file unless a minimal reproducer cannot be made.