YAML Input

pyscf2mppt reads .yaml and .yml files, runs the PySCF calculation, and optionally writes an HDF5 integral dump for the downstream MPPT tools. mppt.output_hdf5 defaults to pyscf_dump.h5.

For orbital setup, use CASSCF AVAS initial guess to prepare the starting active-space orbitals, or orbital generation and analysis to prepare the orbitals used for export after SCF/CASSCF. The two operations can be combined.

General notes:

• Keys are case-sensitive.

• Booleans must be YAML booleans (true/false), not quoted strings.

• Use YAML numbers rather than quoted numeric strings. Strict numeric fields reject coercion; several cipsixx/DIAGPT threshold and weight fields currently use coercive floats, but portable inputs should not rely on that exception.

• Strict floating-point fields such as SCF/CASSCF max_memory and HEFFSO tolerances require floating-point YAML values (8000.0, not 8000).

• molecule.atoms and basis are required; other sections are optional and defaulted.

• Section examples are illustrative and mix defaults with nondefault values. Do not infer a default from an example unless the surrounding text identifies it explicitly.

• Full-calculation YAML rejects unknown top-level and nested keys. Workflow-only parsing with --from-hdf5 is an exception: top-level keys other than mppt and unknown keys directly under mppt are currently ignored; unknown keys inside cipsixx, diagpt, and heffso are rejected.

• A mapping-form casscf.states_to_average item requires spin and nroots. Its only optional key is spin_penalty_shift; other keys are rejected.

• Only C1/no symmetry is supported. Use molecule.symmetry: false, omit the key, or use molecule.symmetry: C1, which is normalized to false internally.

---

Minimal example

molecule:
  symmetry: false
  charge: 0
  units: bohr
  so: true
  atoms:
    - [O, 0.0, 0.0, 0.11779]
    - [H, 0.0, 0.75545, -0.47116]
    - [H, 0.0, -0.75545, -0.47116]

basis:
  H: [library, sto-3g]
  O: [library, sto-3g]

scf:
  spin: singlet
  type: rhf

mppt:
  prefix: h2o

---

Section: molecule

molecule:
  symmetry: false   # only false or C1 allowed; defaults to false
  charge: 0
  units: bohr       # or angstrom / A
  so: true          # dump spin-orbit integrals when supported by the setup
  max_memory: 32000 # MB; can also be "32GB"
  atoms:
    - [H, 0.0, 0.0, 0.0]
    - [H, 0.0, 0.0, 0.74]

• symmetry: must be false or C1. Other symmetries are rejected.

• units: use A/angstrom or B/bohr. The current normalizer also accepts strings beginning with a or b; counterintuitively, a.u. maps to Angstrom. Avoid ambiguous spellings and write bohr explicitly for atomic units.

• so: include spin-orbit integrals in the dump when supported by the setup. This does not run a spin-orbit electronic-structure calculation in PySCF. The schema default is true; set it explicitly for reproducible inputs.

• max_memory: global PySCF memory hint, not a hard process cap. Accepts numeric MB or strings like "32GB". Numeric 50000 is 50,000,000,000 bytes for the integral planner; this is decimal PySCF MB, not MiB. Prefer numeric MB for unambiguous budgets: the legacy molecule string "32GB" resolves to 32768 PySCF MB. See shared export memory for the separate temporary-buffer cap and insufficient-budget behavior.

• atoms: list of [Element, x, y, z].

• charge: total molecular charge.

---

Section: point_charges (optional)

point_charges:
  - [1.0, 0.0, 0.0, -0.5]
  - [-1.0, 0.0, 0.0, 0.5]

Each entry is [x, y, z, charge]. Coordinates use the same units as molecule.units.

---

Section: basis

basis:
  H: [library, sto-3g]
  Ce: [file, ./Ce_expt.dat]

• Each element maps to [library, name] or [file, path]. Only the case-insensitive token file selects file loading. Any other first token, including a misspelling of library, is currently treated as a library specification, so use the exact documented tokens.

---

Section: ecp (optional)

ecp:
  Ce: [library, stuttgart]
  Pr: [file, ./Pr_ecp.dat]

---

Section: grpp (optional)

The supported CMake installation places native libgrpp and libgrpppy in the active Python prefix. Set LIBGRPP_ROOT only when loading a custom libgrpp installation from another directory.

grpp:
  Pr: ./Pr_grpp.dat

---

Section: scf (optional)

scf:
  spin: singlet   # or integer multiplicity, not N_alpha - N_beta
  type: rhf
  conv: 1.0e-10
  max_cycle: 100
  max_memory: 8000.0
  density_fit: false
  auxbasis: null
  omp_num_threads: 8
  verbose: 3

Notes:

• spin accepts names (singlet, doublet, triplet, …) or a positive integer multiplicity.

• type accepts rhf, rohf, and closed-shell rks with explicit XC and DF. For an open-shell molecule, PySCF’s native RHF factory may return ROHF even when type: rhf is requested.

• omp_num_threads controls PySCF/OpenMP thread setup for the SCF stage. It is applied before the first PySCF import in the normal runtime path.

• density_fit: true enables PySCF density fitting. auxbasis selects an auxiliary basis when the PySCF default is not appropriate.

• Aliases are accepted:

  • conv -> conv_tol

  • threads, omp, omp_threads, num_threads, cores, num_cores -> omp_num_threads

  • maxiter, iter, num_iter, numiter -> max_cycle

  • memory, mem, maxmem, max_mem -> max_memory

  • df, density_fitting, with_df -> density_fit

  • aux_basis, auxiliary_basis, df_auxbasis -> auxbasis

Restricted DFT Orbitals

Use explicit RKS + DF for a closed-shell reference:

scf:
  type: rks
  spin: singlet
  xc: PBE0
  density_fit: true
  grids:
    level: 4

xc is required; no implicit LDA fallback is used. grids.level accepts 0–9 (default 3), with native PySCF pruning. HF inputs reject XC/grid options instead of silently ignoring them. ROKS, UKS, nonlocal correlation, dispersion suffixes, double hybrids and Laplacian-dependent functionals are not supported here. Ordinary Libxc LDA/GGA, supported meta-GGA and hybrid expressions are resolved by PySCF. Numerical accuracy and grid convergence remain calculation-specific.

RKS shares the existing initial-guess, embedding, DF and checkpoint path. Completed direct resume restores the saved effective XC/grid input without a kernel. To change XC, start a new run and optionally use a native checkpoint as initial_guess; managed reuse rejects changed scientific input.

With mppt.integral_mode: df, MPPT receives physical hcore and full Coulomb DF integrals on the KS orbitals. It does not receive Vxc, DFT total energy as a scalar constant, or exchange scaled by the hybrid coefficient. KS orbital energies are provenance, not MPPT denominators. DFT identity is reported and included in SCF-reference provenance. RKS orbitals may initialize CASCI/CASSCF; the active stage uses the physical Hamiltonian and its own exact/DF setting. Small-system acceptance compares exact/DF CASCI and DF CASSCF with a native FCI oracle on the same final orbitals; this does not certify large-system convergence.

Auxiliary Basis For Density Fitting

scf.auxbasis, casscf.auxbasis and casci.auxbasis accept a string or null, or a nonempty atom-label map of explicit [library, name] / [file, path] pairs:

scf:
  density_fit: true
  auxbasis:
    O: [file, aux/O.nwchem]
    O1: [file, aux/O1.nwchem]
    H: [library, def2-universal-jkfit]

O and O1 remain distinct keys. Each file contains a normal basis for its chemical element: both oxygen files use O element headers, but are loaded separately before the label map is passed to PySCF. Specify separate entries where labels require different functions; native PySCF label/element lookup otherwise applies. Unsupported source kinds and malformed map entries fail validation. Bare library names remain the legacy whole-setting string form.

Direct runs resolve explicit file entries from the effective runtime workdir; checkpoint reconstruction uses the restored workdir. Auxiliary files are still needed when rebuilding a density-fitted mean-field object from saved SCF arrays, even though the SCF kernel and initial guess are not rerun.

Managed runs capture and hash explicit auxiliary files, including the accepted aux_basis, auxiliary_basis and df_auxbasis aliases. See auxiliary resources and identity. Library entries and legacy strings are passed through without file capture; use explicit file pairs for portable managed resources. Omission/null retains native automatic selection and does not change legacy normalized input identity. These settings configure each stage’s DF object. The selected reference’s actual exact/DF mode and auxiliary provider are inherited by integral export, without rerunning the source stage.

SCF Initial Guess

Set scf.initial_guess to a mapping with a required method to choose the starting density for a fresh RHF or ROHF calculation:

scf:
  initial_guess:
    method: hcore

Omitting initial_guess, or setting it to null, preserves the existing native initialization path. Normalization removes the omitted/null field rather than adding a new default key, so unchanged old inputs retain their normalized data and managed identity. An explicit method, including minao, remains explicit and participates in managed input identity.

Canonical method	Method-specific fields	Starting density
minao	None	Projected minimal atomic density.
atom	None	Superposition of atomic Hartree-Fock densities.
hcore	None	One-electron guess using the final mean-field object’s get_hcore() and eigensolver; 1e is an alias.
huckel	None	Native on-the-fly Huckel guess.
mod_huckel	None	Native modified Huckel guess with the updated GWH rule.
sap	Optional sap_basis	Gaussian-fitted superposition of atomic potentials.
chkfile	Required path; optional project	Density from a native PySCF checkpoint.

Method names are stripped of surrounding whitespace, lowercased, and validated against InitialGuessMethod, a fixed Enum; 1e normalizes to hcore. vsap is unsupported on the RHF/ROHF runtime. Unknown methods, arbitrary chk-prefixed names, scalar shorthand such as initial_guess: atom, empty mappings, unknown fields, and fields belonging to another method are rejected. For example, project is only valid for chkfile, and sap_basis only for sap. Arbitrary inline density or fit arrays are not supported. If the requested native capability is unavailable on the installed mean-field object, execution fails before the SCF kernel rather than choosing another method.

SAP Fit Sources

sap_basis supplies potential-fit data, not the orbital basis or the density-fitting auxbasis. Omit it, or set it to null, to inherit the native mean-field object’s configured SAP fit. A string default is resolved as a bundled library fit, using the same lookup as an explicit library source below. To select a different library fit:

scf:
  initial_guess:
    method: sap
    sap_basis: [library, sapgraspsmall]

Library names resolve through PySCF’s ALIAS registry to bundled NWChem files under its basis-data directory. The permissive basis.load current-directory and pathname fallback is not used. Arbitrary paths in [library, name] are rejected: declare [file, path] for custom SAP fits. A same-named file in the current directory cannot shadow either an explicit library fit or an inherited library default.

An explicit source is either [library, name], [file, path], or a nonempty atom-label mapping whose values have those same two-item forms. Use the exact lowercase source tokens and nonblank names/paths. A common source applies to all atoms; for example, sap_basis: [file, fits/sap.dat] loads each required element from that file. A per-label choice can mix files and library fits:

scf:
  initial_guess:
    method: sap
    sap_basis:
      H1: [file, fits/hydrogen-sap.dat]
      H: [library, sapgraspsmall]

Lookup tries the exact molecular atom label first, then its pure element. In this example, H1 uses the file and other hydrogen labels use the H entry. Every atom must be covered; an incomplete map is an error, not a request to fill missing entries with the native default. The selected source is loaded for the pure element, so a file selected for H1 must contain the H fit.

File sources use the NWChem basis-format loader, not arbitrary format autodetection. Each loaded element fit must contain exactly one S shell with one or more exponent/coefficient pairs. Exponents must be finite and strictly positive; coefficients must be finite and may be signed. Extra coefficient columns, other angular momenta, empty data, and malformed fits are rejected. Library fits are subject to the same loaded-data checks. File contents and map completeness are checked at runtime before the molecular SCF kernel, not by schema validation alone. Resolved fits are assigned to mf.sap_basis before native SAP dispatch; invalid sources are not silently substituted.

If the native mean-field object already holds an in-memory default fit dictionary, its fit data are accepted unchanged after the same label and data checks. This native-object case does not enable arbitrary inline fit arrays in YAML.

Native Checkpoint Guess

Use chkfile to start a new SCF calculation from native PySCF checkpoint orbitals, not to resume an MPPT stage:

scf:
  initial_guess:
    method: chkfile
    path: references/start.chk
    project: true

path is required and must be nonblank. project accepts only YAML true, false, or null (StrictBool or null); strings and numbers are rejected.

project	Native behavior
Omitted or null	Let PySCF decide from its basis-set comparison.
true	Request projection of checkpoint orbitals into the target basis.
false	Reuse checkpoint coefficients without projection.

The automatic decision is not a general geometry or atom-order compatibility check. Large geometry changes can yield a poor guess, and checkpoint occupations can differ from the requested charge or spin.

The checkpoint is a read-only input resource, separate from the output mf.chkfile. Its path is passed directly to the native checkpoint reader, not assigned as the output filename. Input/output collisions are rejected before loading, whether they use the same path, a symlink, or distinct hard links to the same file. A missing or unreadable file, missing SCF records, or an unusable density is fatal before the kernel, with no silent MINAO fallback. MPPT’s scf.npz stage payload is not a native PySCF checkpoint and cannot be used here.

A native UHF checkpoint with different alpha/beta orbitals can produce inconsistent upstream orbital tags when read into ROHF. Such a density is rejected with an Inconsistent initial density orbital tags error before the kernel, rather than silently stripping or repairing the tags or normalizing the density.

Density And Hamiltonian Semantics

Explicit guesses are prepared on the existing final mean-field object after embedding, density-fitting wrapping, and overlap linear-dependency handling. Shape validation and population logging use the actual mean-field family, not just the requested scf.type. This includes native promotion of an open-shell RHF request to ROHF. An actual RHF object uses an AO density of shape (nao, nao); an actual ROHF object uses alpha/beta densities of shape (2, nao, nao). Invalid shape, nonnumeric or nonfinite data, and non-Hermitian densities are rejected.

When orbital tags are present, the helper checks that mo_coeff and mo_occ reconstruct the density array using PySCF’s density-fitting spin interpretation. For shared ROHF orbitals, positive occupations define alpha occupancy and occupations equal to two define beta occupancy. Tags describing a different state are rejected before tag-sensitive exchange can use them. An accepted native starting density D0 is passed to mf.kernel(dm0=D0) without MPPT rescaling, occupation rewriting, or tag stripping or repair.

For explicit requests, the log reports the chosen method and actual Tr(DS) against the target electron count, where S is the AO overlap. When the actual object is ROHF, it also reports actual alpha/beta traces against the target spin-resolved counts, including factory-promoted cases. A population mismatch produces a warning, not automatic normalization or spin correction. Native MINAO/atomic guesses and ROHF guesses need not have the target initial counts; selecting a method does not certify those counts or SCF convergence.

hcore uses the final instance’s patched Hamiltonian, including its embedding contribution. Native Gaussian SAP instead constructs its guess with the module-level bare pyscf.scf.hf.get_hcore(mol) and does not incorporate an instance-level embedding override. This does not replace the Hamiltonian of the subsequent SCF: the configured final get_hcore() and ECP/GRPP, embedding, and DF setup remain intact. Initial-guess selection adds no DIIS, damping, or level-shift controls.

Relative SAP and native-checkpoint paths in CLI calculations resolve against the source YAML directory. The runner captures and copies the files into input/resources/ and rewrites the effective input; see initial-guess resources and identity.

---

Sections: casscf Or casci (optional)

Choose casscf for orbital optimization or casci for fixed-orbital CI. Both default to solver: fci; set solver: block2 for the optional DMRG backend. The solver guide gives a complete YAML example, installation commands, sweep controls, saved files and restart limits. Specify one active-space section only; CASCI accepts the same stage-local DF, resource, AVAS and state-average settings. Orbital-optimizer controls apply only to CASSCF. Both retain casscf as their internal checkpoint stage name.

Use AVAS initial guess below for label-driven starting orbitals. For rotations and ordering after CASSCF, see orbital generation.

casscf:
  solver: fci
  active_orbitals: 8
  n_active_electrons: 10
  conv_tol: 1.0e-7
  conv_tol_grad: 1.0e-4
  max_cycle_micro: 5
  max_cycle_macro: 100
  ah_max_cycle: 30
  ah_start_tol: 2.5
  ah_lindep: 1.0e-14
  ah_conv_tol: 1.0e-12
  ah_level_shift: 1.0e-8
  omp_num_threads: 8
  max_memory: 8000.0
  density_fit: false
  auxbasis: null
  charge: 0
  spin: triplet
  verbose: 6
  avas_labels: ["Pr 4f", ["O 2p", "Pr 5d"]]
  avas_basis: null
  spin_penalty_shift: 1.0
  # Optional observation only; does not prepare or rotate orbitals.
  runtime_projections:
    labels: ["Pr 4f", "Pr 5d"]
    min_weight: 0.01
  states_to_average:
    - [singlet, 2]
    - {spin: triplet, nroots: 1, spin_penalty_shift: 0.5}

Notes:

• The runtime schedules CASSCF only when active_orbitals is supplied. Convergence, memory, density-fitting, charge, or spin settings alone do not add a CASSCF stage. Supplying n_active_electrons, avas_labels, or states_to_average or spin_penalty_shift without active_orbitals is treated as an incomplete active-space request and raises an error. A requested stage requires positive active_orbitals and n_active_electrons.

• states_to_average entries can be [spin, nroots] or {spin: <spin>, nroots: <nroots>, spin_penalty_shift: <shift|null>}. All requested roots receive uniform weights; there is no CASSCF state-weight input. Every multiplicity and root count must be positive.

• spin_penalty_shift optionally targets total spin with PySCF fix_spin. Set a positive finite shift in Eh. Without state averaging it applies to the single FCI solver. With state averaging it is the default: an omitted block key inherits it, a block value replaces it, and block null disables it. Omitting all settings preserves native PySCF behavior. Block2 rejects both forms.

• conv_tol_grad defaults to sqrt(conv_tol) when omitted.

• density_fit and auxbasis control density fitting for the CASSCF setup. Completed SCF arrays are still required before AVAS or active-space work.

• charge or spin overrides rebuild the molecule and create a new ROHF reference object, but do not run a new SCF kernel for that overridden reference before CASSCF.

Accepted CASSCF aliases:

Alias	Canonical key
n_active_orbitals	active_orbitals
avas_label	avas_labels
state_averaged	states_to_average
threads, omp, omp_threads, num_threads, cores, num_cores	omp_num_threads
memory, mem, maxmem, max_mem	max_memory
df, density_fitting, with_df	density_fit
aux_basis, auxiliary_basis, df_auxbasis	auxbasis

AVAS Initial Guess For CASSCF

Set casscf.avas_labels to build a starting orbital ordering with the desired atomic-orbital character. AVAS runs on the converged SCF reference, before the CASSCF optimization. Omitting the labels, or using null or [], starts CASSCF from the SCF orbitals directly.

This is a CASSCF orbital guess. For the starting SCF density, use SCF initial guess. For occupied/virtual preparation of the converged orbitals before MPPT export, use orbital generation. None of these settings selects CIPSIXX determinants; that has its own mppt.cipsixx configuration.

For example, the following fragment requests a chosen five-electron, five-orbital active space and uses Fe 3d character for its initial ordering:

casscf:
  active_orbitals: 5
  n_active_electrons: 5
  avas_labels: ["Fe 3d"]
  avas_basis:
    Fe: [library, def2-svp]

Supply the molecule, charge, spin and working basis appropriate to your system. The reference-basis override is optional. A complete small input is provided in the combined H2 example.

Setting	Default	Meaning
active_orbitals	Required for a CASSCF stage	Actual number of active spatial orbitals used by CASSCF.
n_active_electrons	Required for a CASSCF stage	Actual active electron count; it must be compatible with the molecule and spin.
avas_labels	null	YAML list of AO search labels or compound label lists. A nonempty list requests AVAS initialization.
avas_basis	null	Optional reference AO basis overrides; omitted atoms inherit the working basis. It does not enable AVAS by itself.
runtime_projections	omitted (off)	Optional labels, inclusive raw min_weight (default 0.01) and independent basis. Prints per-label MO-by-step percentage tables and writes unique raw JSONL histories. Available under casci too. See the Runtime Orbital Projections section of the active-space solver guide.

The labels follow the shared AO-label rules. CASSCF AVAS uses the union of all matched AOs as its target space. The working orbital basis remains basis; the optional reference basis follows the library/file and atom-label rules.

How The Starting Orbitals Are Built

1. Complete SCF and check that its MO coefficients, occupations and energies are available. An unconverged SCF result is rejected before CASSCF starts.

2. Build the metric-correct projector onto the requested reference AO subspace, then diagonalize its occupied and virtual MO blocks separately.

3. Use the projection eigenvalues to partition and reorder the starting MOs; canonicalize the resulting inactive, active and remaining virtual blocks.

4. Pass that ordering to CASSCF, using the explicitly requested active orbital/electron counts. CASSCF then optimizes the orbitals.

The current YAML runner uses these fixed AVAS algorithm settings:

Internal control	Current value	Consequence
Projection threshold	0.2	Directions with projector eigenvalues at or above this threshold enter the AVAS-inferred active space.
Open-shell treatment	openshell_option=2	Uses occupied/virtual projection partitioning; it is not the alternative mode that explicitly preserves every open-shell orbital.
Canonicalization	true	Canonicalizes the initial blocks using the SCF energy information.
Excluded leading MOs	ncore=0	No leading columns are removed from the AVAS projector calculation. This is not a global frozen-core setting.

These internal controls are not additional YAML keys. Changing avas_basis changes the projector, so the same 0.2 threshold can yield different inferred AVAS dimensions. For open-shell systems, inspect the resulting character and electron count rather than assuming every singly occupied orbital is automatically retained.

Requested CAS Size, Diagnostics And Errors

AVAS reports its inferred ncas and nelecas. They do not replace active_orbitals and n_active_electrons: if the counts differ, the runner prints a warning and uses the AVAS orbitals as an ordered guess for the requested CASSCF space. Review that warning and adjust the target labels, reference basis or requested CAS deliberately.

Look for CASSCF AVAS projection basis, the occupied/virtual projector eigenvalues, and AVAS guess built before the CASSCF iterations. Those eigenvalues describe the AVAS selection step; they are not per-orbital weights of the subsequently optimized CASSCF MOs. To inspect final character, use orbital diagnostics.

casscf.avas_basis does not automatically set a final-analysis reference. To compare final MOs using the same projector, repeat the desired labels/basis under an MPPT group such as avas_labels_virtual/avas_basis_virtual and leave generate_projected_virtuals: false. That diagnostic group evaluates all MOs in the table; it is not restricted to virtual rows.

With a nonempty explicit avas_basis, basis-loading, label-resolution and AVAS errors propagate instead of silently using SCF MOs. In the default working-basis mode, an AVAS failure is logged as a warning and falls back to SCF orbitals. In either case, verify the log before attributing a result to the intended AVAS guess. A successful guess does not certify CASSCF convergence.

CASSCF charge/spin overrides do not run a second SCF for AVAS: the guess still uses the completed original SCF reference. Keep the requested CAS and spin consistent with the CASSCF system.

--stop-after casscf saves the orbitals returned by the CASSCF kernel, not an intermediate AVAS-only guess; check the CASSCF convergence status. Resuming a completed CASSCF checkpoint restores its orbitals without rebuilding AVAS. To try different labels or a different reference basis, use a fresh calculation/checkpoint; see preview and restart rules.

---

Section: mppt (optional)

Export inherits the selected reference’s exact/DF approximation. Keep delete_from: 0 to retain all reference MOs, and use N_select > 0 for a selected window inside that full space. N_select: 0 is the full-ERI route, including int2e_full; it is not required just to keep every MO. Memory controls do not automatically truncate orbitals or enable DF export, even if SCF/CASSCF used density fitting.

For avas_labels_*, occupied/virtual construction, reference bases and orbital ordering, go to orbital generation and analysis. The CASSCF starting-orbital settings are in CASSCF AVAS initial guess.

integral_mode	N_select	Output and applicable controls
exact source	Positive	Ordinary selected families; optional exact_half_block_size bounds only the exact half-transform scratch
exact	0	Full ERIs including int2e_full; the public API’s force_transform_outcore controls the exact full transform, not final dataset size
df	Positive	Ordinary selected families from one DF approximation; automatic RAM/HDF5 MO factors, no force-storage flag or exact slabs
df	0	Full DF ERIs including int2e_full; large native and packed/reorder arrays remain materialized regardless of factor storage

Both approximations retain the ordinary float64 integral payload and HDF5 contract. DF factors are internal, not a new consumer format. See DF-expanded export for supported sources and short reference fragments; this section is not a standalone calculation recipe.

mppt:
  orbitals: auto         # auto | scf | casscf; casci with a casci section
  prefix: pyscf
  output_hdf5: pyscf_dump.h5
  so_source: auto        # auto | scalar | relativistic
  no_dump: false
  N_select: 0
  N_start: 1
  delete_from: 0
  avas_labels_analysis: ["Pr 4f"]   # labels for tables and HDF5 weights
  max_mem_bytes: null               # automatic workspace from molecule.max_memory
  exact_half_block_size: null        # positive integer; exact selected route only
  downstream_nocc: null              # optional downstream occupied-prefix override

Notes:

• orbitals chooses the reference used for projection and dump: auto uses the configured CASCI/CASSCF stage, otherwise SCF; scf always uses SCF, even after an active-space stage. casci is accepted with a casci section and normalized to the shared casscf checkpoint label.

• output_hdf5 chooses the integral-dump name below the CLI run’s data/ directory. Already data/-qualified paths are not prefixed twice.

• Omit integral_mode to inherit the selected reference’s actual exact/DF mode and auxiliary provider. Legacy explicit exact/df values only assert a match; a conflict is rejected. Explicit null also inherits. Both YAML and Python use the shared ExportConfig model and inherit DF for a DF source. See DF-expanded export for storage and resource limits.

• prefix and output_hdf5 must remain nonempty after surrounding whitespace is removed when the downstream workflow configuration is built.

• so_source accepts auto, scalar, or relativistic. auto constructs the GRPP molecule when a nonempty grpp section exists; scalar suppresses that construction even when GRPP paths are present; relativistic requires a nonempty grpp section. This is separate from molecule.so: setting molecule.so: false still writes intso, but fills it with zeros.

• no_dump: true runs through calculation/orbital preparation but skips final pyscf_dump.h5 generation. Because automatic downstream continuation occurs only after dump, it also prevents enabled cipsixx, DIAGPT, and HEFFSO stages from running in that command.

• N_select > 0 chooses that many consecutive MOs, starting exactly at N_start in the prepared orbital ordering. Full-space compact J/K and required ERI families still use every retained MO; only the selected window is passed to CIPSIXX. 0 requests full-space ERIs. Both YAML and Python reject negative values; use 0 for the full route.

• N_start is a positive one-based first selected MO; it defaults to 1. For example, N_start: 1, N_select: 25 selects MO 1–25, and N_start: 4, N_select: 25 selects MO 4–28. The window must contain a downstream occupied orbital and fit inside the retained MO space. Nonpositive starts and out-of-range endpoints are rejected before integral transformation.

• delete_from is a one-based inclusive trim point applied before integral transformation. For example, delete_from: 320 keeps orbitals 1 through 319. 0 disables trimming. Negative values and 1 are rejected. Any value above the available MO count, including count plus one, is ignored with a [WARN] message and behaves as delete_from: 0: orbital analysis and export retain every available MO. The YAML runtime checks the AO count immediately after building the molecule, before SCF, and disables an oversized cutoff for all later stages. Export and checkpoint orbital inspection also check the actual MO count, which can be smaller than the AO count. A cutoff equal to the MO count still removes the last MO. N_select and N_start keep their usual meanings when deletion is disabled.

• max_mem_bytes defaults to null (automatic); omission and null pass through the runtime and public exporter without an injected 2-GiB cap. An explicit positive integer byte count or unit string (GB, MB, KB) retains its temporary-buffer meaning, not total RSS. Historical parsing is unchanged: these legacy suffixes use powers of 1024, so "2GB" is 2,147,483,648 bytes.

• exact_half_block_size is an optional strict positive integer, not a boolean or fractional value. It limits the first MO side of the exact half-transform for selected blocks. Omitted or null keeps the monolithic strategy and existing numerical output. Setting it with N_select <= 0 is an early error, not a silently ignored full-route option. It is also rejected with integral_mode: df.

• avas_labels_analysis controls which AO subspaces are shown in analysis tables and persisted as raw final-orbital weights under /mppt/orbital_analysis. Analysis, occupied, and virtual label sets are merged and deduplicated by label and reference basis in their declared order. Compound labels are stored as JSON arrays. These are weighted character diagnostics, not categorical shell or correlated-state assignments.

• downstream_nocc overrides the closed-shell occupied-orbital prefix used by downstream compatibility metadata. When omitted, the producer uses the physical reference electron count: ceil(nelec/2), equivalently inactive orbitals plus ceil(active_electrons/2) for CASSCF. Fractional populations do not increase this count by the number of nonzero active orbitals. An explicit value must be between zero and the post-trim orbital count.

For an input with a valid five-orbital selected window, this optional fragment retains all reference MOs and uses half slabs without changing the exact integral approximation or ordinary HDF5 output contract:

mppt:
  integral_mode: exact
  delete_from: 0
  N_select: 5
  exact_half_block_size: 4

Only the exact half-transform scratch is bounded by exact_half_block_size. Dense CV-CV staging, other ERI arrays, J/K and final HDF5 storage remain. Smaller slabs can repeat AO integral passes and slow the dump; they do not bound all peak disk usage. The width stays explicit, not automatically resized by the RAM planner. Preflight scratch and destination capacity separately. The option is incompatible with DF; DF storage is automatic, not selected by an outcore flag.

For memory, normally set a realistic molecule.max_memory and leave mppt.max_mem_bytes: null. scf.max_memory and casscf.max_memory override their respective stages and otherwise fall back to the molecule/global value; they do not replace the dump’s molecule total hint. An explicit buffer cap is intersected with the remaining automatic workspace. Small caps such as 16 MiB keep their type and meaning but can be rejected at runtime if they cannot admit the minimum work. None of these settings enforces process RSS or limits final dataset size, and caller-owned SCF/DF caches still consume RAM.

An insufficient budget raises ValueError before the affected allocation. Remove an optional cap only when the remaining total has room; raise the total hint only when RAM is genuinely available under the host/worker limits. Admission rejects a 1-MB total already exceeded by the resident process on either route. Exact full-route automatic transform/reorder choices honor the checked remaining workspace and explicit cap. The HOCl routing regression uses a feasible 512-MB total with max_mem_bytes: 16KB, not force flags; native/packing buffer floors mean this is not a strict 16-KiB allocation limit. See shared memory units and failure guidance for diagnostics and Exact Export Internals for formulas, screening, lifetimes and validation limits. DF’s separate phase admission and automatic RAM/HDF5 selection are described in DF Export Internals, not additional user settings.

Changing memory or slab controls preserves the retained MO space, complete Hamiltonian, requested SO/property data and ordinary HDF5 contract. Consumer limits still apply; a successful export is not downstream or production certification. The selected-route contract lists the required outputs and indexing rules. Matched-DF checks establish assembly agreement, not the error of DF relative to exact Coulomb integrals.

CLI --resume validates the saved normalized input and resources. Use a new --output-dir for changed scientific inputs; resume is not an approximation switch or a request to repeat a completed export. For a separate export of an existing completed reference, use the reference API with an explicit ExportConfig and a new output path.

Accepted MPPT aliases are normalized before strict schema validation:

• so_from, so_provider, so -> so_source;

• ao2mo_max_mem_bytes, ao2mo_max_memory_bytes -> max_mem_bytes;

• generate_projected_occupied, generate_occupieds, project_occupieds -> generate_projected_occupieds;

• generate_occupied_from, occupied_from, occupied_start -> generate_occupieds_from;

• generate_occupied_to, occupied_to, occupied_end -> generate_occupieds_to;

• occupied_map, occupied_mapping, orbital_map_occupied -> occupied_orbital_map.

Do not provide an alias together with its canonical key. Use canonical keys for deterministic validation.

Optional cipsixx initialization and selection metadata is shown below. The example mixes defaults and nondefault values; the tables after it are the authoritative field summary. See the CIPSIXX selection algorithm for equations, iteration flow, scoring, stopping, and model-space export.

mppt:
  cipsixx:
    enabled: true
    initial_space: cas       # hf | cas | determinants
    selection_method: mp2_coefficient
    max_selected: 4000
    batch_size: 250
    max_iterations: 20
    max_candidates: null
    denominator_tolerance: 1.0e-12
    n_roots: 8
    selected_root: 0
    multi_state: true
    selection_growth: topk   # topk | threshold
    selection_metric: coefficient
    state_weighting: uniform # uniform | legacy-taum | inverse-participation | custom
    root_weights: null        # required only for custom weighting
    spin_adaptation_closure: spin-projection # spin-projection | spin-complement | none
    final_diagonalization: always            # always | never
    adaptive_threshold: false
    threshold_multiplier: 0.75
    threshold_floor: 1.0e-7
    min_new_determinants: 100
    min_abs_coefficient: 1.0e-5
    min_abs_energy: 0.0
    cas_orbitals: [14, 15, 16, 17]  # human-facing 1-based labels
    core_orbitals: [1, 2, 3, 4]
    frozen_orbitals: []
    cas_alpha_electrons: 1
    cas_beta_electrons: 0
    cas_electrons: null
    determinants_group: /cipsixx/initial_determinants
    omp_num_threads: 8
    iteration_report: cipsixx_iterations.csv
    root_energy_report: cipsixx_root_energies.csv

Stage And Initial Space

Key	Default and accepted values	Runtime effect and interactions
enabled	false; Boolean	Enables the selection stage. The HDF5 dump still records cipsixx metadata when selection is disabled.
initial_space	hf; hf, cas, determinants	Chooses one HF determinant, an enumerated CAS reference, or an HDF5 determinant list.
selection_method	mp2_coefficient; no other value	Fixed compatibility identifier. It does not select an alternative algorithm; selection_metric controls ranking.
cas_orbitals	null; one-based integer list	Required and nonempty for CAS initialization. Defines the active occupation combinations.
core_orbitals	null; one-based integer list	Doubly occupied in every CAS determinant. Also becomes the frozen-orbital fallback when frozen_orbitals is omitted. It cannot overlap cas_orbitals.
frozen_orbitals	null; one-based integer list	Prevents listed orbitals from acting as excitation holes or particles. null uses core_orbitals. In managed runs, [] emits --frozen-orbitals none; direct cipsixx_select use must pass that option because the HDF5 contract cannot distinguish omitted from explicitly empty lists.
cas_electrons	null; nonnegative integer	Total active CAS electrons. The selector splits an odd total as one more alpha than beta.
cas_alpha_electrons	null; nonnegative integer	Active alpha count. Spin-resolved counts must always be provided together. With a total, provide either neither spin count or both.
cas_beta_electrons	null; nonnegative integer	Active beta count. If all three count fields are present, total must equal alpha plus beta.
determinants_group	/cipsixx/initial_determinants; absolute HDF5 path	Source group for initial_space: determinants. Point it at /cipsixx/selected_determinants to restart from an earlier physical selection.

Orbital lists must be positive and duplicate-free. Their upper bounds are checked against the effective selected/full cipsixx orbital space during HDF5 dumping and native selection.

Candidate Generation And Growth

Key	Default and accepted values	Runtime effect and interactions
max_selected	null; positive integer	Closure-expanded stopping target, not a hard maximum. A null target disables target stopping.
batch_size	250; positive integer	Caps additions only for targeted topk growth. It does not cap threshold growth or no-target growth.
max_iterations	12; positive integer	Maximum growth iterations. Target reached or stalled growth can stop earlier.
min_abs_coefficient	0.0; finite nonnegative number	Minimum absolute first-order coefficient. It remains a filter when the energy metric is selected; multistate mode compares the weighted score.
min_abs_energy	0.0; finite nonnegative number	Minimum absolute second-order energy contribution. It remains a filter when the coefficient metric is selected; multistate mode compares the weighted score.
denominator_tolerance	1.0e-12; finite nonnegative number	Rejects a root contribution when the absolute perturbative denominator is at or below this value.
max_candidates	null; positive integer	Retains only the highest-scoring candidates after denominator and threshold filtering. Null means no explicit cap.
selection_growth	topk; topk, threshold	topk adds a bounded targeted batch. threshold adds every retained candidate and can overshoot the target.
selection_metric	coefficient; coefficient, energy	Selects candidate ranking, the winning multistate root, and the threshold adjusted by adaptive mode. Both coefficient and energy filters still apply.
adaptive_threshold	false; Boolean	Valid only with selection_growth: threshold. Relaxes the selected metric threshold after sparse growth.
threshold_multiplier	0.75; finite number in (0, 1]	Multiplies the active threshold during adaptive reduction. Adaptive mode requires a value below one; fixed mode accepts the no-op value one.
threshold_floor	1.0e-7; finite nonnegative number	Lowest adaptive threshold. No reduction occurs if this floor is not below the current threshold.
min_new_determinants	100; positive integer	Adaptive reduction is considered after a noninitial iteration adds fewer determinants than this value.

With max_selected: null, the workflow still passes the default twelve iterations, and top-k growth adds every retained candidate because there is no target budget. Use explicit thresholds, max_candidates, and max_iterations to bound such a run.

Roots, Scoring, And Export

Key	Default and accepted values	Runtime effect and interactions
n_roots	1; positive integer	Number of lowest variational roots requested. The current determinant-space dimension can limit the roots actually returned.
selected_root	0; zero-based integer below n_roots	Root used for single-state selection, reported variational energy, and final stored CI coefficients. HF initialization supports only root zero.
multi_state	false; Boolean	Scores candidates from every returned root instead of only selected_root.
state_weighting	uniform; uniform, legacy-taum, inverse-participation, custom	Multiplies per-root candidate scores in multistate mode. Nonuniform modes require multi_state: true.
root_weights	null; finite nonnegative number list	Required only for custom; must have exactly n_roots entries and at least one positive value. Values are not normalized.
spin_adaptation_closure	spin-projection; spin-projection, spin-complement, none	Controls target counting and downstream export, not variational determinant generation. spin-complement skips complement generation for determinants with unequal alpha/beta counts.
final_diagonalization	always; always, never	always refreshes coefficients after final growth. never skips only that final pass and leaves mixed pre-growth/perturbative coefficients.

Runtime And Reports

Key	Default and accepted values	Runtime effect and interactions
omp_num_threads	-1; -1 or positive integer	-1 inherits the environment. A positive value sets OpenMP, MKL, and OpenBLAS thread counts; zero is rejected.
iteration_report	cipsixx_iterations.csv; path or null	Per-iteration counts, thresholds, energies, and timings. Relative paths resolve from the workflow workdir; null disables the report.
root_energy_report	cipsixx_root_energies.csv; path or null	Per-root energies for ordinary iterations. It does not include a separate final-rediagonalization row; null disables the report.

Report paths, when set, must be nonempty. Reports are not durable checkpoint outputs and are not regenerated when a valid selection checkpoint is reused.

The initial determinant-space dimension must exceed selected_root. Custom multistate weighting currently also requires the initial space to provide all n_roots roots. The schema rejects excited-root and multi-root custom weighting with HF initialization because HF contains one determinant. For CAS and HDF5 determinant initialization, provide a sufficiently large initial space.

The dump normalizes cipsixx orbital indices to zero-based values. With N_select > 0, /cipsixx/integrals uses the selected orbital space and carries orbital_space="selected". With N_select = 0, it uses the complete post-trim orbital space and carries orbital_space="full". The full route writes packed full-space ERIs in the required C1 destination ordering. The selected route uses the compact J/K and pair-packed ERI datasets defined by the selected-route contract.

Optional restartable DIAGPT and HEFFSO stages:

mppt:
  prefix: Pr
  diagpt:
    enabled: true
    title: Pr scalar states
    thrpri: 0.25
    wmupa: 1.0
    gap: 0.05
    zshift: false
    write_h0: true
    diagonal_diagnostics: false
    state_weights: null
    integral_space: auto     # auto | full | selected
    omp_num_threads: 8
  heffso:
    enabled: true
    title: Pr spin-orbit states
    properties: true
    nvectw: 8
    iorder: 2
    guess_space: null
    max_basis: null
    max_block: null
    max_matvecs: null
    residual_tolerance: 1.0e-6
    initial_vector_tolerance: 1.0e-7
    print_level: 1
    progress_interval_seconds: 60
    allow_constrained_basis: false
    preconditioner: true
    direct_sparse: true
    sparse_backend: auto     # auto | fortran | cuda
    omp_num_threads: 8
    report:
      configuration_weight_percent: 10.0
      configuration_top_n: 3

DIAGPT title, when set, must be nonempty and single-line. thrpri and gap are nonnegative, wmupa is in [0, 1], and state_weights must be nonnegative with at least one positive value. At execution, an explicit weight list must contain exactly one value per model-space state. When omitted, the generated DIAGPT input contains one 1.0 weight per state. DIAGPT always uses the mandatory repository-pinned PRIMME eigensolver.

DIAGPT and HEFFSO use one C1 scalar handoff at <prefix>heffso.h5.

Diagonal PT2 diagnostics

Set mppt.diagpt.diagonal_diagnostics: true to explain determinant-diagonal PT2 corrections. The native equivalent is zdiagnostics=.true. in &cidinp. The default is false; the option does not change the numerical kernels or request extra integral contractions.

The log reports each component’s mean, minimum, maximum and the corresponding one-based determinant IDs, plus the common pure-CVCV term and populated H0 energy ranges. All energies are in Hartree. These are determinant statistics, not automatically f/d labels or energy contributions to mixed eigenstates.

Diagram names and physical channels

Each name below identifies one recorded kernel contribution. For a diagonal element, bra and ket are the same model determinant. The arrows describe electron substitutions from that determinant to an intermediate determinant; the second interaction returns to the starting determinant. Model-space intermediates are removed by model_space_backplay.

The hole/particle labels refer to DIAGPT’s auxiliary reference vacuum. All indices in the table denote spin orbitals:

Indices	Occupation relative to the reference and the current determinant
h, k	Reference-occupied orbitals that are empty in the current determinant: holes.
p, q	Reference-empty orbitals that are occupied in the current determinant: particles.
i, j	Reference-occupied orbitals that remain occupied in the current determinant.
a, b	Reference-empty orbitals that remain empty in the current determinant.

These are occupation classes, not fixed core/active/external labels. Each substitution obeys the kernel’s spin, symmetry and occupancy restrictions.

Diagnostic component	Physical channel and recorded contribution
a0001_holes	Double i j → h k: fills two holes and creates two new holes within the reference-occupied space.
a0001_particles	Double p q → a b: moves two particles within the reference-empty space.
bubl01_holes	Single i → h: squared two-electron spectator (bubble) part of the single-substitution amplitude.
bubl01_particles	Single p → a: the corresponding squared spectator part for particle relocation.
a0002	Double i p → h a: relocates one hole and one particle.
a0003_holes	Double i p → h k: fills two holes while removing one particle and creating one hole.
a0003_particles	Double p q → h a: removes two particles while filling one hole and creating one particle.
bubl02	Single p → h: annihilates one particle–hole pair; includes Fock and spectator terms.
a0004_holes	Double i j → h a, plus the Fock-square and Fock–spectator cross terms for single i → h.
a0004_particles	Double i p → a b, plus the Fock-square and Fock–spectator cross terms for single p → a.
bubl03	Single i → a: creates one particle–hole pair; includes Fock and spectator terms.
a0005	Double p q → h k: annihilates two particle–hole pairs.
a0006_remainder	Double i j → a b: creates two particle–hole pairs, excluding the separately stored pure-CVCV scalar.
model_space_backplay	Exclusion correction for intermediate determinants already in the model space, using their single/double Hamiltonian couplings.

Here a spectator is an occupied orbital that contributes to a single-substitution matrix element through a two-electron interaction without itself being replaced. bubl01_holes and the single-substitution part of a0004_holes together contain the i → h channel; the particle counterparts similarly share p → a. The a0004 vectors therefore mix single- and double-substitution terms.

The separate pure_cvcv_hartree attribute contains the common part of a0006: double substitutions from two core orbitals into two external virtual orbitals on the selected route. Add this scalar once per determinant. The remainder may still contain other common contributions.

HDF5 output and interpretation

After MPPT2, the handoff gains an optional /diagpt_diagnostics group:

Field	Meaning
diagonal/<component>	Float64 vector of length ncf, signed as a contribution to H2−H1.
pure_cvcv_hartree attribute	Common scalar correction, excluded from a0006_remainder; add it once to each determinant.
h0/removal_weight, attachment_weight	Spin-summed state-average weights in full spatial-MO order.
h0/removal_energy_hartree, attachment_energy_hartree, average_energy_hartree	Actual H0 energies after native options, retaining raw sentinel values.
h0/removal_valid, attachment_valid	Integer masks for positive-weight channels; zero-weight sentinels are not physical energies.
h0/determinant_shift_hartree	Actual shifts in the same determinant order as the matrices.

The 14 named vectors above use the parent handoff’s determinant catalog, model-space/determinant hashes and selected orbital remap. H1/H2 and their scalar envide offsets are already stored in that same file. integral_source_path, when available, is a path, not an integral checksum; use the workflow’s input fingerprint for persisted integral identity.

The group carries schema mppt_diagpt_diagonal_v1 and complete=1 after its data are written. znocal does not build H2 and produces no diagnostic group. A new normal run recreates the handoff, so an old group is not retained when diagnostics are disabled. Buffer storage is O(14×ncf+norb); this is not a measured runtime-overhead guarantee.

Off-diagonal component matrices, weighted excitation-denominator histograms and projector/state-character analysis are not produced by this option. Orbital H0 ranges must not be read as extrema over all actually evaluated excitation denominators.

HEFFSO solver settings

Null PRIMME sizes are adaptive. guess_space becomes min(n, max(512, 2*nvectw)), max_basis becomes min(n, max(nvectw+64, 4*nvectw)), max_block uses at most eight OpenMP threads, and max_matvecs becomes max(10000, 400*nvectw). The workflow uses the generated namelist to make YAML solver controls authoritative. With inherited OpenMP threads, an explicit basis too small for the worst-case eight-vector adaptive block must also set max_block; this prevents a YAML configuration from becoming valid or invalid only because the caller’s thread environment changed. Explicit max_block cannot exceed nvectw, max_matvecs cannot be smaller than nvectw, and max_basis must hold nvectw + max_block. sparse_backend: cuda requires direct_sparse: true. When oneMKL sparse support is compiled, sparse_backend: auto with direct_sparse: true is the production default. Set sparse_backend: fortran with direct_sparse: false to validate the portable Fortran/OpenMP path. Both backends preserve numerical invariants, although eigenvector signs and bases within degenerate subspaces may differ. HEFFSO title, when set, must be nonempty and single-line. nvectw is in [1, 1000], iorder is 1 or 2, print_level is in [0, 5], guess_space is nonnegative, and progress_interval_seconds is positive. Residual and initial-vector tolerances must be finite and positive.

Every integral dump produced by the ordinary YAML workflow writes full-space intdip and intang tensors in the final MO basis, including dump-only runs and --stop-after dump. This is independent of heffso.enabled, heffso.properties, and the separate molecule.so switch. No extra property export setting is needed.

heffso.properties defaults to true. It controls the HEFFSO namelist setting properties and requires <prefix>heffso_properties.h5 after prefix normalization. The artifact uses mppt_heffso_properties_v4 and stores state energies, oscillator strengths and line strengths, angular values and residuals, and Cartesian L, S, J = L + S, and dipole matrices. Required groups also store complete PRIMME diagnostics and signed-int64 final determinant occupations in the minimal closed-shell-vacuum-relative orbital window. The main state table adds S^2, J^2, and oscillator strength after dE / cm-1; the angular values use two decimal places. It defines oscillator strength as the dimensionless electric-dipole strength from state 1. Set properties: false only to request the four-column energy table without the HDF5 properties artifact.

Setting properties: false changes HEFFSO reporting, not which property operators are saved by a new YAML dump. Previously exported HDF5 files are not updated automatically by this change.

Every primary report starts its bounded result with SOLVER DIAGNOSTICS. Enabled property reports add ANGULAR PROPERTIES, MAGNETIC PROPERTIES, PROPERTIES VALIDATION, and PROPERTIES SUMMARY after SPIN-ORBIT STATES. Occupations are written to <prefix>heffso_occupancy_analysis.log; dominant coefficients are written to <prefix>heffso_configuration_analysis.log. Both logs are required regardless of the properties setting. The primary state table is the sole per-state energy/oscillator-strength listing; complete line strengths remain in HDF5/Caspy. Oscillator strengths and magnetic residuals/response use scientific notation; energies and angular values use fixed decimal notation. Effective angular values are derived from the retained HEFFSO-state matrices and do not assign term symbols or multiplets. configuration_weight_percent is in [0, 100]; the strict threshold is supplemented by at least the positive configuration_top_n row count.

Magnetic properties

Use mppt.heffso.magnetic_properties to request g tensors, finite-field levels, magnetization and susceptibility.

Magnetic properties use the magnetic-moment operator at zeroth order in the MPPT perturbation, projected into retained states. heffso.iorder chooses the CASCI/selected-CI or MPPT2 Hamiltonian; it does not change the operator order.

mppt:
  heffso:
    enabled: true
    properties: true
    magnetic_properties:
      enabled: true
      spin_g: 2.00231930436092
      degeneracy_tolerance_hartree: 1.0e-8
      fields_tesla: [[0.0, 0.0, 0.0], [0.0, 0.0, 1.0]]
      temperatures_kelvin: [2.0, 10.0, 300.0]
      susceptibility: true
      store_field_matrices: false

The block is optional. With heffso.enabled: true and the default properties: true, omitting it still exports the zero-field magnetic model and eligible Kramers-pair g values. Fields and temperatures have no implicit grid. Include [0.0, 0.0, 0.0] explicitly for zero-field thermal response.

Key	Default	Meaning and constraints
enabled	null	Inherit heffso.properties; true requires properties: true. Set false to disable magnetic output while retaining other properties.
spin_g	2.00231930436092	Positive, finite electron-spin factor in the zeroth-order magnetic-moment operator. Use 2.0 explicitly for the nonrelativistic spin-only factor used in the Ce/Pr/OH examples.
degeneracy_tolerance_hartree	1.0e-8	Positive, finite minimum tolerance in hartree for grouping zero-field levels. The effective threshold also includes actual solver residuals; it never changes energies.
fields_tesla	[]	At most 256 explicit [Bx, By, Bz] vectors in input Cartesian coordinates, in tesla. Each vector has exactly three finite numbers; zero and negative components are allowed.
temperatures_kelvin	[]	At most 256 finite temperatures, each strictly positive, in kelvin. Requires a nonempty field list.
susceptibility	false	Compute differential dM/dB at each field–temperature point; requires temperatures.
store_field_matrices	false	Store dense field Hamiltonians as well as field levels; requires fields. Adds storage proportional to the field count times nvectw².

Boolean values must be YAML booleans. Numerical values must be numbers, not quoted strings; NaN and infinity are rejected. Unknown keys are rejected.

Choose the requested output

Request	Settings inside magnetic_properties	Result
Zero-field model and eligible g	{}	Moment/Zeeman matrices, time-reversal diagnostics and doublet classification
Field-dependent energies	fields_tesla: [[0.0, 0.0, 1.0]]	Levels at each requested field; no thermal response
Magnetization	Fields plus temperatures_kelvin: [2.0, 300.0]	M at every combination of field and temperature
Susceptibility	Fields, temperatures and susceptibility: true	M, the full χ tensor, its principal values and axes
Disable magnetic work	enabled: false, with empty grids	Other properties remain available; magnetic status is disabled

The YAML above requests two fields × three temperatures = six response points. All fields use the same temperature list. A temperature or snapshot request without fields is invalid, as is a field request with magnetic output disabled. properties: false cannot be combined with explicitly enabled magnetic output or a field request.

Changing any magnetic control invalidates the HEFFSO checkpoint; the next workflow run recomputes that stage. Choose nvectw to retain the relevant SOC states, including the states above a candidate doublet needed to establish its isolation. It also controls the state space for thermal response.

See Magnetic Properties for formulas, g eligibility, units and approximation limits, and Ce/Pr/OH examples for complete runnable inputs. The output contract lists stored arrays and status codes.

Stage execution and resource limits

All downstream stages are opt-in and default to disabled. The complete configuration, HDF5 group ownership, and checkpoint rules are documented in the unified cipsixx workflow.

Thread-count semantics differ by layer. For direct SCF/CASSCF, omp_num_threads: -1 selects all detected cores, 0 becomes one thread, and a positive value is capped at the detected core count. For cipsixx, DIAGPT, and HEFFSO, -1 inherits the caller’s environment, 0 is rejected, and a positive value sets OMP_NUM_THREADS, MKL_NUM_THREADS, and OPENBLAS_NUM_THREADS. Selection and DIAGPT fingerprints do not include inherited ambient thread variables; the HEFFSO fingerprint includes its solver-relevant inherited OpenMP, MKL, OpenBLAS, and CUDA variables.

Current model-space preflight rejects excitation rank above eight, DIAGPT ncf > 46340, metat > 1000, or metat > ncf. When HEFFSO is enabled it also rejects ncf > 35000 and a packed excitation-slot count above 280001. DIAGPT additionally requires 2*norb + 1 and its packed excitation-slot count to fit signed 32-bit integers.

---

Orbital Generation And Projection Analysis (mppt)

Use mppt.generate_projected_occupieds and mppt.generate_projected_virtuals to prepare the orbital coefficients used for export after SCF/CASSCF. Use casscf.avas_labels instead when the goal is the starting orbital guess for CASSCF. Both can be enabled in one input; see the complete example.

Goal	Setting	When it acts
Prepare a CASSCF orbital guess	casscf.avas_labels, optional casscf.avas_basis	Before the CASSCF kernel.
Prepare/order an occupied MO window	mppt.generate_projected_occupieds: true	After the chosen SCF/CASSCF result.
Put projected directions first in a virtual MO tail	mppt.generate_projected_virtuals: true	After occupied generation, when both are enabled.
Inspect character without rotating MOs	mppt.avas_labels_analysis, or occupied/virtual labels with generation disabled	In orbital-analysis output; see the preview commands below.

All generation options are opt-in. Labels alone request analysis, not orbital generation. A reference-basis setting alone does not activate either operation. Use avas_labels_analysis in new inputs. The historical spelling avas_labels_analyzis remains a supported alias. Both spellings produce the same stored settings and run identity; existing checkpoints retain their historical field name. If both keys are supplied, their values must match.

Orbital Source And Execution Order

mppt.orbitals selects the coefficient set to prepare and export:

Value	Orbital source
auto (default)	CASSCF orbitals when CASSCF ran, otherwise SCF orbitals.
scf	SCF orbitals, even if a CASSCF calculation also ran.
casscf	CASSCF orbitals; a CASSCF stage is required.

The fresh-run order is:

SCF -> optional AVAS guess -> CASSCF (if requested)
    -> choose mppt.orbitals -> pre-projection analysis
    -> occupied generation -> virtual generation -> integral export

Pre-projection analysis is printed when a generation flag is enabled. Generated orbitals are not fed back into the CASSCF calculation that has already completed. MO ranges and mapping targets below are one-based positions in this chosen coefficient set, before dump trimming, ordering and selected-window export.

AO Labels And Compound Projectors

Labels are PySCF AO search patterns, interpreted in the reference basis for their stage. For example, "Fe 3d" matches the 3d components on atoms labelled Fe; "Fe1 3d" targets that explicit atom label. Use actual AO labels or an appropriate regular expression; the literal "Fe 3d" does not automatically match the different label Fe1.

Supply a YAML list, not one comma-separated string. For orbital generation, each top-level entry defines one projector. A nested list defines the union of its AO matches as one joint projector:

mppt:
  avas_labels_analysis: ["Fe 3d", "O 2p"]
  avas_labels_virtual:
    - "Fe 4d"
    - ["O 2p", "Fe 4p"]

The two entries of avas_labels_virtual above are separate target subspaces. Within the second entry, repeated AO matches are counted once. Avoid repeating or overlapping entries unnecessarily: the generation count sums the matched AO counts of the top-level entries. Repeated placement requests belong in occupied_orbital_map, not in duplicated projector labels.

CASSCF AVAS differs in this detail: it uses the union of all requested labels for its initial-guess selection. See CASSCF AVAS initialization.

A numeric prefix inside an AO pattern, such as "0 O 2p", is a PySCF zero-based atom index. It is not one of the one-based MO indices used for generation ranges and mapping.

Occupied Generation And Placement

Enable occupied generation and choose a valid occupied window. This fragment illustrates one oxygen centre in a system with at least five occupied MOs; adapt the labels and positions to your actual orbital table:

mppt:
  orbitals: scf
  generate_projected_occupieds: true
  avas_labels_occupied: ["O 2p"]
  avas_basis_occupied:
    O: [library, sto-3g]
  generate_occupieds_from: 1
  generate_occupieds_to: 5
  occupied_orbital_map:
    "O 2p": [3, 4, 5]

Key	Default	Meaning
generate_projected_occupieds	false	Enables occupied-block preparation.
avas_labels_occupied	null	Required projector labels when generation is enabled.
avas_basis_occupied	null	Reference AO basis for generation, placement weights and occupied-label diagnostics.
generate_occupieds_from	1	First included MO, one-based.
generate_occupieds_to	Occupied SCF MO count	Last included MO, one-based and inclusive.
occupied_orbital_map	null	Optional placement of high-weight orbitals at specified absolute MO positions.

Explicit occupied bounds must be positive, with the upper bound no smaller than the lower bound; these input checks also apply when generation is disabled. The upper occupied bound is checked against the reference SCF occupations (mo_occ > 1e-8), including when CASSCF coefficients are selected. The runtime does not automatically exclude the CASSCF active block from occupied generation. Choose the range explicitly when those orbitals must be protected. Columns outside the selected window remain untouched.

The generator retains the projected occupied directions without Fock recanonicalization:

1. For each label, diagonalize its reference-AO projector inside the requested occupied window and take the leading contributing directions.

2. Orthogonalize the collected directions with QR and complete the basis inside the same occupied span. Projected directions come first, then the complement.

3. Apply the optional mapping to these projected orbitals. There is no final Fock diagonalization or sorting by orbital energy.

This rotates existing MOs; it neither runs a new SCF nor adds electrons or orbitals. For a window of equally occupied orbitals, the density and reference energy are preserved. Do not mix different occupations to obtain that guarantee; the range checks do not enforce equal occupations or protect a CASSCF active block automatically. The result is generally noncanonical. Projection quality still depends on the reference functions, their overlap with the chosen window, and orthogonalization between target subspaces; pure atomic orbitals are not guaranteed.

For each mapping entry, the code chooses the largest reference-projector weight among the still-unused orbitals in the window and places that orbital at the requested target. It then fills the remaining positions. Check the printed mapping weights: placement does not guarantee a large overlap, and there is no minimum-overlap acceptance test for the mapping itself.

Mappings accept a scalar target, a list of targets, or explicit repeated pairs:

mppt:
  occupied_orbital_map:
    - ["O 2p", 3]
    - ["O 2p", 4]
    - ["O 2p", 5]

Targets must be unique and inside the selected occupied range. Do not repeat dictionary keys in YAML to express multiple targets. The printed occupied Fock diagonal contains expectation values in final mapped order, not eigenvalues. Fock is used only for diagnostics and consistency checks: the runtime supplies the SCF Fock when available, with an orbital-energy-based fallback; see diagnostic energy semantics.

Ce Example: Place 5s/5p Immediately Before The Virtual Block

Consider a Ce-centred closed-shell reference with 750 MOs, 234 electrons and 117 doubly occupied MOs. Ce5s/5p character may lie deep among the occupied MOs while the highest occupied MOs are ligand-like. Project over all 1..117, not just the last few occupied columns, to collect that character.

This fragment belongs in an otherwise complete input for that reference. It assumes one Ce centre and AO labels matching one 5s and three 5p functions; inspect the actual labels, ranks and projection weights for your basis:

mppt:
  orbitals: scf
  generate_projected_occupieds: true
  avas_labels_occupied: ["Ce 5s", "Ce 5p"]
  # Omitted avas_basis_occupied uses the working AO basis.
  generate_occupieds_from: 1
  generate_occupieds_to: 117
  occupied_orbital_map:
    "Ce 5s": 114
    "Ce 5p": [115, 116, 117]

The intended placement, when all four target directions are available, is:

Final MO columns	Role
1..113	Remaining occupied orbitals
114	Projected Ce5s-like occupied orbital
115..117	Three projected Ce5p-like occupied orbitals
118..750	Virtual block, unchanged by occupied generation

“Immediately before the LUMO” means column placement, not raising the energies of deep occupied orbitals to the HOMO. These settings preserve the 234-electron reference; adding an electron for a Ce3+ target is a separate step. An AO shell label alone does not establish physical radial character; use avas_basis_occupied for suitable independent reference functions when needed.

If a separate virtual preparation puts the 16 desired 4f/5d/6s/6p directions in 118..133, a later N_start: 114, N_select: 20 selects the combined window. Occupied generation alone does not prepare or validate those virtual orbitals. Export integrals consistently for the final MO coefficients and selected window; changing indices in an existing integral file is not a substitute.

Virtual Generation And Its Starting Index

Enable virtual generation with target AO labels. The following fragment uses an oxygen reference basis for a chosen correlating p subspace:

mppt:
  generate_projected_virtuals: true
  avas_labels_virtual: ["O 3p"]
  avas_basis_virtual:
    O: [library, cc-pvdz]

Key	Default	Meaning
generate_projected_virtuals	false	Enables rotation of the selected MO tail.
avas_labels_virtual	null	Required target labels when generation is enabled.
avas_basis_virtual	null	Reference AO basis for virtual construction and virtual-label diagnostics.
generate_virtuals_from	Automatic, as defined below	First MO in the rotated tail, one-based; all earlier columns are preserved.

For each label entry, the largest projector-eigenvalue directions are placed first, followed by an orthonormal complement of the original tail. The total number of MOs does not change. Reference functions select directions available in the working MO span; they cannot add missing diffuse or correlating functions to the calculation basis.

The current automatic start uses the SCF occupied-MO count, not the CASSCF inactive-orbital count:

Selected orbital source	Automatic first rotated MO
SCF	nocc_scf + 1
CASSCF	nocc_scf + casscf.active_orbitals + 1

Here nocc_scf counts SCF occupations above 1e-8, and active_orbitals is the requested CAS size, not the AVAS-inferred size. The CASSCF formula can skip additional external virtuals; it is not ncore_casscf + ncas + 1. Set generate_virtuals_from explicitly when a different boundary is intended. The complete H2 example demonstrates this.

Important: an explicit start is used literally. It does not automatically advance past occupied or active MOs. Choose it after every block you want to protect, and leave at least one MO in the tail. Selecting a start inside an occupied/active block can rotate that block too.

The complete tail is rotated; this path has no functional end-index/count control. generate_virtuals_count is currently accepted by the schema but is not consumed by the generation implementation, so it is not an effective cap.

Projector Counts And Numerical Rank

Generation checks the sum of matched reference AO counts against the occupied-window or virtual-tail size before rank filtering. A label can match several atoms and several functions, so a small number of label strings does not necessarily request a small number of orbitals.

Within each target subspace, only directions with projector eigenvalues above 1e-10 are selected. The log reports expected, rank and picked; fewer directions may survive than the AO count suggests. With no contributing virtual directions, the original MO set is returned; an occupied block is left as-is before optional mapping, without recanonicalization. The diagnostic eigenvalue grouping tolerance is 1e-6; these are internal defaults, not YAML controls.

Overlapping target subspaces need not supply independent directions. Use a compound label for an intended joint subspace and inspect the final weights. N_select and delete_from act in the later dump stage; they do not limit the projector construction or replace the generation-range settings.

Independent AVAS Reference Bases

The three independent settings share one format:

Setting	Reference functions used for
casscf.avas_basis	CASSCF initial-guess AVAS
mppt.avas_basis_occupied	Occupied generation, mapping and occupied-label analysis
mppt.avas_basis_virtual	Virtual generation and virtual-label analysis

casscf:
  avas_basis:
    Fe: [library, def2-svp]

mppt:
  avas_basis_occupied:
    Fe: [library, sto-3g]
  avas_basis_virtual:
    Fe: [file, ./Fe_projectors.dat]
    Fe1: [file, ./Fe1_projectors.dat]

Each value is a map from an element or full atom label to [library, name] or [file, path]. Use the exact lowercase source tokens. A full atom-label override takes precedence over the element entry; unspecified atoms inherit the working basis. Every override key must match an atom label or element present in the molecule. Files use the chemical element in their basis headers: an Fe1 override loads iron functions from an Fe section.

Omission, null, or {} all select the working basis and preserve the old normalized input identity. These settings accept maps, not a bare basis-name string. They are independent of the top-level orbital basis and of density-fitting auxbasis, and do not activate AVAS/generation by themselves.

The reference may have a different AO count from the calculation. Projection uses reference/reference and reference/working overlaps, with a pseudoinverse for dependent reference functions. The working molecule and its Hamiltonian are not replaced by a new reference-basis SCF calculation.

Reference molecules retain geometry, ECP/effective-charge core offsets and Cartesian/spherical representation. For ECP/GRPP work, use appropriate reference functions and inspect their actual AO labels: there is no automatic conversion of an arbitrary all-electron basis into a valence-only reference, and a matching shell label alone does not establish the intended radial character.

Direct runs resolve files from the runtime work directory. Managed runs resolve them from the source YAML, capture immutable copies and include their contents in run identity. Declare custom resources with file; library entries are not copied or content-hashed as external files. See preview and restart rules.

Reading The Diagnostics

Output	How to interpret it
CASSCF AVAS projection basis and projector eigenvalues	Reference basis and selection information for the CASSCF guess, before orbital optimization.
PRE-PROJECTION ORBITAL ANALYSIS	Snapshot of the chosen SCF/CASSCF coefficients before occupied/virtual generation.
Occupied projection basis / Virtual projection basis	Actual reference basis used by that generator and its weights.
expected, rank, picked	Matched reference AO count, contributing projector rank, and selected directions. These are not correlated-state degeneracies.
Occupied mapping lines	Chosen source orbital, requested target position and its reference-projector weight.
Occupied Fock diagonal after projection/mapping	Expectations in final mapped order, in Hartree, printed ten columns per row. They need not be sorted; the final orbitals need not diagonalize Fock.
Occupied Fock-trace / HF-energy consistency checks	When available, check conservation under the occupied-space rotation; they do not certify orbital purity or CASSCF convergence.
Final/inspection projection tables	Per-MO weights for the current coefficients, using each label set’s reference basis.

avas_labels_analysis uses working AOs. Occupied and virtual label sets use their own configured projectors even when their generation flag is disabled. Labels are deduplicated by label and reference basis; the same AO label with two bases therefore produces separate, basis-labelled columns.

A projector weight describes overlap with a reference subspace, not an electron population. For normalized MOs it lies between zero and one up to numerical error, but weights for overlapping label subspaces need not sum to one. Mulliken character, projector eigenvalues and per-MO projection weights are different diagnostics.

Text tables round weights to two decimal places and normally leave values below 0.01 blank; a blank is not proof of zero overlap. A completed dump stores raw final weights in /mppt/orbital_analysis/projection_weight, with reference descriptions in label_display and optional per-label projection_basis_spec_json. See orbital-analysis output.

Source MO energies printed after rotations are metadata, not a claim that the final MOs are canonical eigenvectors with those energies. The HDF5 group also stores the final-basis Fock diagonal and the dump’s orbital-index mapping.

Complete Example: CASSCF AVAS And Both Generators

Save this as avas-h2.yaml. It uses only library bases and demonstrates the three stages on a small molecule; it is not a recommended active space for an unrelated chemical system.

# Complete example: AVAS and orbital generation
molecule:
  atoms:
    - [H, 0.0, 0.0, 0.0]
    - [H1, 0.0, 0.0, 1.4]
  units: bohr
  symmetry: false
  charge: 0
  so: false
basis:
  H: [library, 6-31g]
scf:
  spin: singlet
  type: rhf
  omp_num_threads: 1
  verbose: 0
casscf:
  active_orbitals: 2
  n_active_electrons: 2
  avas_labels: ["H 1s", "H1 1s"]
  avas_basis:
    H: [library, sto-3g]
  omp_num_threads: 1
  verbose: 0
mppt:
  orbitals: casscf
  no_dump: true
  avas_labels_analysis: ["H 1s", "H1 1s"]
  generate_projected_occupieds: true
  avas_labels_occupied: ["H1 1s"]
  avas_basis_occupied:
    H1: [library, sto-3g]
  generate_occupieds_from: 1
  generate_occupieds_to: 1
  generate_projected_virtuals: true
  avas_labels_virtual: ["H 2s"]
  avas_basis_virtual:
    H: [library, cc-pvdz]
  generate_virtuals_from: 3

The working H2/6-31g space has four MOs. This CAS has no inactive core and occupies the first two positions, so the explicit virtual start 3 rotates the two external virtuals. The current automatic CASSCF start would instead be 1 + 2 + 1 = 4. The one-column occupied window cannot mix the two active orbitals. no_dump: true avoids the final integral export.

Preview, Errors And Restart

Inspect the resulting orbitals without a two-electron integral dump:

pyscf2mppt avas-h2.yaml --output-dir runs/avas-h2 --stop-after orbitals
pyscf2mppt --inspect-checkpoint chk-avas-h2

The first command runs SCF, requested CASSCF and enabled generators. The second reconstructs the saved state and prints final orbital tables without rerunning those kernels or the full integral dump. It is also useful for analysis-only label sets: no_dump: true by itself does not print a final analysis table when no generation flag requests the pre-projection snapshot.

Symptom	Check / action
AO label not found	Inspect actual reference AO labels, atom tags, basis content and ECP core offsets.
Requested AO count exceeds the block size	Narrow the labels, combine overlapping labels where appropriate, or choose a larger valid block.
No virtuals remain	Check the chosen MO source and automatic start; specify generate_virtuals_from explicitly if needed.
Mapping does not show the desired character	Check its printed weights and the selected occupied window; mapping only orders available orbitals.
AVAS dimensions differ from the requested CAS	Review the labels/reference basis and explicitly requested counts; the warning does not resize CASSCF.
Edited settings appear ignored on resume	Start a fresh calculation/checkpoint to regenerate orbitals; direct resume restores saved input and completed stages.

Direct checkpoints retain the reference paths/settings but do not fingerprint resource contents. Keep their basis files unchanged. Managed runs capture/hash files and enforce input identity for reuse. --force-workflow reruns downstream stages, not SCF/CASSCF orbital preparation; --from-hdf5 does not reconstruct AVAS or regenerate MOs. See CLI restart semantics.

Python Entry Points

For a program that already owns mol, mf and the current mol_orb, the occupied helper accepts the same reference-basis concept:

from pyscf2mppt.orbitals import construct_occupied_via_projections

mol_orb = construct_occupied_via_projections(
    mol=mol,
    mo_coeff=mol_orb,
    labels=["Ce 4p"],
    start_orbital=10,
    end_orbital=18,
    mo_energy=mf.mo_energy,
    mo_occ=mf.mo_occ,
    orbital_map={"Ce 4p": [12, 13, 14]},
    basis={"Ce": ("file", "./Ce_projectors.dat")},
    scf_obj=mf,
)

This is a fragment for an existing matching molecule and valid occupied range. Python resource specifications use tuples; use absolute paths or paths relative to the process work directory. Mapping can also use {"Label": 12} or [("Label", 12), ("Label", 13)].

The corresponding entry points are construct_virtuals_via_pure_ao_projections(..., basis=...) and avas_from_labels(..., basis=...) (the latter is exported from pyscf2mppt). Their Python arguments expose algorithm controls that the YAML runner keeps fixed. For an external-reference export, ExportConfig.avas_basis_* controls diagnostics only; see external PySCF references.

---

CLI Runtime And Checkpoints

Run a YAML input directly:

pyscf2mppt input.yaml

Checkpoint and resume long calculations:

pyscf2mppt input.yaml --output-dir runs/calculation --stop-after scf
pyscf2mppt input.yaml --output-dir runs/calculation --resume

Inspect a checkpoint without running the full integral dump:

pyscf2mppt --inspect-checkpoint runs/calculation/checkpoints > inspect.out

Run only enabled downstream stages from any existing compatible HDF5 dump:

pyscf2mppt workflow.yaml --from-hdf5 checkpoints/calculation.h5

Matching completed stages are reused from /mppt/workflow/stages. Use --force-workflow to rerun enabled stages. Executable paths may be supplied with --selection-executable, --diagpt-executable, and --heffso-executable.

The explicit --from-hdf5 path is authoritative; mppt.output_hdf5 in a workflow-only file does not select the input. Top-level keys other than mppt and unknown keys directly under mppt are currently ignored in this mode. Nested downstream sections remain strict. The explicit HDF5 is a writable reference, validated even when all downstream stages are disabled. A fresh output directory is created for logs and results; the large input is copied only when an archive is explicitly requested.

--from-hdf5 cannot be combined with --stop-after. Use --resume to continue the same downstream run directory.

Supported --stop-after stages are:

• input_normalized

• scf

• casscf

• orbitals

• dump

An SCF stage recorded as completed is restored without constructing another initial guess, reading its starting-guess resource, or rerunning the SCF kernel. This also applies to a saved unconverged SCF result: stage completion does not mean convergence. Changing scf.initial_guess rejects incompatible managed resume. To try another guess, start a fresh output directory. Resume enforces input and resource identity.

The supplied YAML must still exist and pass parsing before resume validates the saved input/resource identity. Pre-dump checkpoints can continue; dump-complete reuse also requires the accepted HDF5 identity. The complete option, inspection, executable-resolution and restart semantics are in the CLI reference.

CLI runs default to runs/<input-stem>/ or use --output-dir. Relative resources resolve from the source YAML; generated outputs are grouped into data/, reports/, logs/ and checkpoints/. run.log captures the full pipeline.

The low-level Python run_from_yaml(workdir=...) API retains explicit checkpoint control. Its resources and stage outputs use the supplied workdir, while a relative dump path is resolved by the writer from the caller’s process directory. Prefer an explicit absolute dump path for that API.

---

Integral dump from an existing PySCF object

The library API remains independent of the YAML runner. Adapt a completed SCF or CASSCF object into validated reference data, then export it through the same HDF5 path used by full-YAML calculations:

from pathlib import Path

from pyscf2mppt import ExportConfig, dump_reference, reference_from_scf

# mf must already be converged; the adapter snapshots its final reference data.
reference = reference_from_scf(mf)

# Write integrals to HDF5 before starting any downstream MPPT stages.
dump_reference(
    reference,
    ExportConfig(output_path=Path("checkpoints/scf_integrals.h5")),
)

The adapter captures the public final get_hcore() result exactly once; an explicit hcore_ao override causes zero calls. See external PySCF references for CASSCF, explicit property operators, validation, overwrite behavior, and downstream HDF5 reuse.