Troubleshooting#

Configure And Build#

If no Conda-compatible manager is available, or the latest Miniconda installer fails on an old server, start with the Miniforge and Micromamba setup guide.

Installer reports Permission denied or GLIBC_2.28 is missing#

Run shell installers explicitly with bash from $HOME; an executable bit is not required, and this avoids direct installer execution from a noexec filesystem. The final installation prefix must still permit executable files. The latest Miniconda Linux installers require glibc 2.28, while current Miniforge supports glibc 2.17. Follow the old-server decision table instead of changing the host glibc.

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.

CMake reports no known C++ features#

cipsixx requires C++20 and sets that standard itself. GCC 14 and newer are not rejected by the project. This diagnostic means that CMake did not populate its feature data for the selected compiler; stale compiler cache data and incomplete compiler wrappers are common causes. Activate the intended environment and re-export the compiler wrappers, then repeat the complete supported configuration with a fresh cache:

export CC="$CONDA_PREFIX/bin/x86_64-conda-linux-gnu-gcc"
export CXX="$CONDA_PREFIX/bin/x86_64-conda-linux-gnu-g++"
export FC="$CONDA_PREFIX/bin/x86_64-conda-linux-gnu-gfortran"

cmake --fresh -S . -B build \
  -UBLAS_LIBRARIES \
  -ULAPACK_LIBRARIES \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_PREFIX_PATH="$CONDA_PREFIX" \
  -DCMAKE_INSTALL_PREFIX="$CONDA_PREFIX" \
  -DCMAKE_INSTALL_LIBDIR=lib \
  -DHDF5_ROOT="$CONDA_PREFIX" \
  -DOpenMP_gomp_LIBRARY="$CONDA_PREFIX/lib/libgomp.so.1" \
  -DMPPT_ENABLE_CIPSIXX=ON \
  -DMPPT_COPY_TO_HOME_BIN=ON \
  -DMPPT_HOME_BIN_DIR="$CONDA_PREFIX/bin" \
  -DINSTALL_PYSCF2MPPT=ON \
  -DWITH_LIBGRPP=ON

Do not work around the diagnostic with -DCMAKE_CXX_STANDARD=17; it is below the cipsixx language requirement and can hide a mixed-toolchain configuration.

HDF5 is not found#

For an existing configured build/ tree, reconfigure with 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.

LIBGRPP shared library is not found#

Install MPPT into the active mppt environment so the native library and Python bindings share one location:

cmake -S . -B build \
  -DCMAKE_INSTALL_PREFIX="$CONDA_PREFIX" \
  -DCMAKE_INSTALL_LIBDIR=lib \
  -DINSTALL_PYSCF2MPPT=ON \
  -DWITH_LIBGRPP=ON
cmake --build build --parallel 1
cmake --install build

The installed bindings discover $CONDA_PREFIX/lib/liblibgrpp.so automatically. Set LIBGRPP_ROOT only to override this path with another libgrpp installation.

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#

Release Fortran tests fail with undefined references#

Keep MPPT_ENABLE_FORTUNO_TESTS=ON. MPPT enables DIAGPT LTO through CMake’s IPO support so static libraries use the compiler-aware archiver. Do not inject -flto through CMAKE_Fortran_FLAGS; a plain ar may then discard the LTO symbol table. For an unsupported custom toolchain, CMake reports that IPO is unavailable and continues without it. -DMPPT_ENABLE_DIAGPT_IPO=OFF is also an explicit diagnostic fallback and does not disable 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 Calculations#

Symmetry is rejected#

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

PySCF RHF And MKL On Sandy Bridge#

A Ce:YPO4 RHF calculation on Intel Xeon E5-1650 (Sandy Bridge, AVX without AVX2) failed to converge with PySCF 2.14.0, SciPy 1.18.0 and MKL 2026.1.0 at ten threads. CASSCF had not started.

The affected installation used a PySCF fork with canonical overlap orthogonalization. On the saved 1470-by-1470 overlap matrix, both SciPy evr and direct LAPACKE_dsyevr returned nonorthogonal eigenvectors despite success status. This reproduced a numerical backend defect, not merely a slow SCF cycle. It does not establish that every PySCF/MKL combination has the same problem.

  • Reinstalling with OpenBLAS restored RHF convergence for this case.

  • MKL_NUM_THREADS=1 passed the bounded eigensolver controls while PySCF/OpenMP retained ten threads. A complete RHF run was not validated with this workaround.

  • evd also passed the matrix controls, but changing the solver is a separate code-level choice, not an MPPT YAML setting.

If using the MKL workaround, set it before launching a fresh calculation:

MKL_NUM_THREADS=1 pyscf2mppt input.yaml --output-dir runs/mkl-single-thread

Do not reuse the unconverged orbitals from the failing run. Check convergence and MO orthonormality, and keep the original logs when investigating a similar failure. Prefer the supported OpenBLAS installation if the defect reproduces.

CASSCF input is incomplete#

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

Resume rejects YAML edits#

CLI resume requires the same normalized input and resource contents. Choose a new --output-dir after changing scientific input or external resources. The low-level Python checkpoint API has weaker guarantees and restores saved input; it is not the managed CLI resume interface.

Resume recreates a missing HDF5 dump#

The CLI validates HDF5 presence and accepted identity before reusing a dump-complete checkpoint. Missing or invalid output can force SCF/CASSCF and dump to run again. Inspect the attempt history in run.log and logs/attempts/.

Scratch or integral dump runs out of space#

CLI runs use <output-dir>/scratch. Choose an output directory on 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 dump-complete checkpoint, 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. All four pair-packed ERI blocks are required.

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, the fin heffso marker, a complete bounded primary report, both prefix-qualified occupation and configuration analysis logs, and exactly the configured nvectw state rows in all three text artifacts. Properties runs additionally require all angular, magnetic, validation, and summary sections plus a complete mppt_heffso_properties_v4 artifact. Every run also requires the bounded SOLVER DIAGNOSTICS section; properties artifacts must contain matching solver evidence and exact final determinant identity. The state count, energies, oscillator strengths, angular values, and independently validated line strengths must agree. Inspect logs/heffso.log, reports/heffso/<prefix>heffso_occupancy_analysis.log, reports/heffso/<prefix>heffso_configuration_analysis.log, and run.log; process exit status alone is not a completion contract.

Reporting A Problem#

Include the configure command, compiler/CMake versions, input YAML, relevant stage attributes, summary.md and the relevant raw file under logs/. Use pyscf2mppt archive RUN/run.json --output-dir diagnostics --diagnostics for a failed/interrupted diagnostic bundle. Do not attach an entire large HDF5 file unless a minimal reproducer cannot be made.