Outputs And Restart State#

The unified workflow stores scientific contracts and restart fingerprints in one HDF5 file, while generated namelists, logs, and solver-specific outputs remain ordinary files in the work directory.

PySCF Dump#

mppt.output_hdf5 defaults to pyscf_dump.h5. A new direct dump opens the file for replacement, so choose a new path when preserving an older calculation.

Important content includes:

  • root orbital, energy, electron, and integral metadata;

  • one-electron, spin-orbit, compact J/K, and two-electron integral datasets;

  • selected-route datasets when N_select > 0;

  • /cipsixx/config and /cipsixx/integrals for native selection;

  • optional downstream model space and workflow stage groups after selection.

When molecule.so: false, intso is still present and contains zeros.

Direct PySCF Checkpoints#

Direct-stage checkpoints are separate from the HDF5 workflow restart state:

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

They resume input normalization, SCF, CASSCF, and orbital preparation. The integral HDF5 file is not copied into this directory. Direct resume restores the saved normalized input for PySCF stages and the saved work directory without comparing a scientific input fingerprint, external basis/ECP/GRPP contents, package version, or runtime environment. The newly supplied YAML must still parse and its mppt section controls any automatic downstream execution. A checkpoint recorded as complete through dump is accepted without checking that the HDF5 dump still exists or is unchanged.

Managed Run State#

Managed points add effective-input.yaml, run.json, run.log, a persistent .pyscf2mppt.lock, copied file resources, and a managed-input hash in a successfully validated HDF5 output. run.json records one current attempt, including the exact child command, absolute run directory, timestamps, return code, error, and planned, running, complete, failed, or interrupted status. Resume increments the attempt and appends to run.log.

Sweep roots contain their own lock, sweep.json, and managed point directories. The sweep manifest records the definition hash, ordered overrides and input hashes, point statuses, return codes, errors, and the current number of points whose status is interrupted. This count is recomputed after attempts rather than retained as cumulative event history. These manifests are orchestration records; scientific energies remain in each point’s normal calculation outputs.

HDF5 Workflow Checkpoints#

Downstream state is stored at:

/mppt/workflow
/mppt/workflow/stages/selection
/mppt/workflow/stages/diagpt
/mppt/workflow/stages/heffso

Each stage can record running, complete, or failed, plus its normalized fingerprint, update time, command, log path, message, and output fingerprint. Input-contract or executable-resolution failures that occur before the stage is marked running can leave no stage record. A stage is reusable only when its configuration/executable/consumed-input fingerprint and its separate durable output_fingerprint both validate. Executable identity currently uses resolved path, byte size, and nanosecond modification time rather than a binary-content hash.

Rerunning selection invalidates DIAGPT and HEFFSO. Rerunning DIAGPT invalidates HEFFSO. Failed or interrupted stages are never treated as complete.

Workflow Sidecars#

The orchestrator writes:

.mppt-workflow/
  inputs/
    diagpt.inp
    heffso.inp
  logs/
    cipsixx_select.log
    diagpt.log
    heffso.log

Selection also writes cipsixx_iterations.csv and cipsixx_root_energies.csv by default. These reports are not durable reuse outputs. For DIAGPT, the validated HDF5 handoff is the reuse output.

Model Space#

The physical selector output is under /cipsixx/selected_determinants. The validated compatibility view consumed downstream is /mppt/model_space/quasi_restricted. It contains packed determinants, source ordering, dimensions, spin/electron metadata, and content hashes.

Current preflight limits include metat <= 1000, DIAGPT ncf <= 46340, and HEFFSO ncf <= 35000, plus excitation rank at most eight. HEFFSO packed slots must not exceed 280001; DIAGPT also requires 2*norb + 1 and its packed slot count to fit signed 32-bit integers. Exceeding a compiled capacity is a preflight error, not a request to truncate the model space.

DIAGPT Outputs#

mppt.prefix: Ce is normalized to the legacy file prefix Ce_:

Ce_h0.1
Ce_heffso.1.h5

h0.1 is the optional zero-order restart file. The H1/H2 matrices are written only to the HDF5 handoff; DIAGPT does not create separate H1/H2 sidecars.

The HDF5 handoff has schema mppt_heffso_handoff_v3. Its root attributes retain norb, noca, metat, and ncf; determinant datasets are det_ne, det_nd, det_trou, and det_part. The effective Hamiltonians remain pair-packed in h1_packed and h2_packed, with their dimensions and energy offsets recorded in the corresponding h1_* and h2_* attributes. Every handoff requires determinant_content_hash_fnv1a64; HEFFSO and Python preflight recompute it from the final ordered/remapped determinant payload before accepting the file. The required model_space_source attribute records the determinant source. For hdf5_quasi_restricted, model_space_content_hash_fnv1a64 is also required and must match a hash that HEFFSO recomputes from the shared model-space payload. The required scalar integer selected_remap attribute is 1 for a selected-route handoff and 0 for an unremapped handoff. When it is 1, the handoff also stores the normalized one-based signed-int64 selected_idx dataset and HEFFSO requires it to match the selected-orbital map in the shared HDF5 input. When it is 0, that dataset must be absent. Scalar root vector and energy datasets are not part of this handoff. The .1 suffix is a fixed compatibility convention, not a configurable pass number.

HEFFSO Outputs#

For the same prefix, HEFFSO writes:

Ce_sovec
HEFF.TMP
HMAT
Ce_heffso_effective_operators.h5  # only when effective operators are enabled

Workflow completion requires a nonempty Ce_sovec, fin heffso near the end of .mppt-workflow/logs/heffso.log, and a complete ordered bounded report. The state table must have contiguous IDs and internally consistent Hartree, eV, and wavenumber columns. Occupations must contain either every state in every displayed horizontal block or the explicit no-varying-orbitals status, and the configuration section must contain coefficient-consistent rows and a parsed summary for every state. A zero process exit without those durable markers is treated as failure. The workflow requires exactly the configured nvectw states; a HEFFSO run that emits fewer states is rejected rather than accepted as an automatic reduction. When mppt.heffso.effective_operators: true, completion also requires a valid mppt_heffso_effective_operators_v1 file with exactly nvectw states. Text state energies are cross-checked against its absolute Hartree energies. Every enabled HEFFSO stage fingerprint includes solver-relevant inherited environment variables. Effective-operator runs also include intdip, intang, and their conventions. The separate output fingerprint covers the console report, eigenvectors, and enabled effective-operator artifact. Disabled runs require the stale artifact to be absent.

The console log is a human-readable report whose lines are limited to 120 characters. It contains only these ordered sections:

  • SPIN-ORBIT STATES, with state, absolute Eh, dE / eV, and dE / cm-1;

  • ACTIVE-ORBITAL OCCUPATIONS;

  • DOMINANT CONFIGURATION WEIGHTS.

The configuration report prints every |c|^2 above the configured percentage and always prints at least the configured top-N coefficients. Effective-operator matrices are not printed in the human report.

The v1 HDF5 artifact stores one-based state IDs, absolute energies, and split-complex Cartesian matrices. For n = state_count, required datasets are:

Dataset

Shape

Meaning

state_id

(n,)

contiguous IDs 1..n

state_energy_hartree

(n,)

absolute electronic energies in Hartree

l_matrix_real, l_matrix_imag

(3,n,n)

orbital-angular-momentum matrices

s_matrix_real, s_matrix_imag

(3,n,n)

spin-angular-momentum matrices

j_matrix_real, j_matrix_imag

(3,n,n)

total-angular-momentum matrices, J = L + S

dipole_matrix_real, dipole_matrix_imag

(3,n,n)

bare length-gauge dipole matrices

The required attributes identify schema version 1, one-based indexing, state count, absolute Hartree energy semantics, vacuum energy, x,y,z component order, (component,bra_state,ket_state) matrix axes, HEFFSO eigenstate basis, V_dagger_Q_V projection, bare projected model-space semantics, dipole operator r, three-component dipole_origin_bohr, and final write_complete=1.

For each Cartesian operator Q, the stored matrix is V^dagger Q V in the HEFFSO eigenstate basis. Applying the bare one-body operator is restricted to the finite determinant catalog, so external daughters absent from that catalog are omitted by the model-space projector. These matrices have no wave-operator dressing and carry no exact Casimir, multiplet, parentage, certification, or exact E1 spectroscopy claim.

Install the optional Caspy helper and read the typed contract without keeping the HDF5 file open:

python -m pip install -e ./caspy

from caspy import read_heffso_effective_operators

result = read_heffso_effective_operators(
    "Ce_heffso_effective_operators.h5"
)
print(result.state_energy_hartree)
print(result.l_matrix.shape)
print(result.dipole_matrix[:, 0, 1])