Quick Start#

Calculate relativistic, spin–orbit-split energy levels of Ce³⁺, starting from an SCF reference. Prepare orbitals through MPPT’s custom PySCF interface, then run the Fortran/C++ correlation and spin–orbit stages separately.

Complete the installation and activate the mppt environment. The commands below expect pyscf2mppt, cipsixx_select, diagpt and heffso on PATH. The CLI reference also supports explicit executable paths.

Prepare The Example#

Download both files into a new ce-example/ directory:

ce.yaml — the complete calculation input.
Ce_expt_so_with_gh.dat — the Ce basis and relativistic pseudopotential, including its spin–orbit part.

cd ce-example

Keep the filenames as shown. File-based resources resolve relative to the YAML and are copied into the run directory. The example uses the full integral route; allow at least 1 GB of free disk space for each run and its intermediates.

Reference Orbitals And Target Ion#

The SCF calculation deliberately uses closed-shell Ce⁴⁺ (charge: 4). The downstream model space describes Ce³⁺: 13 doubly occupied orbitals plus one electron distributed over 12 active orbitals. With the 28-electron core replaced by the pseudopotential, these stages contain 26 and 27 explicit electrons, respectively.

This is the repository’s compact Ce regression example. It illustrates the workflow and spin–orbit splitting; the small model space is not a converged spectroscopic benchmark. Here the complete one-electron CAS has only 12 determinants in the selected spin projection; larger problems can use iterative determinant selection.

Prepare Orbitals With The PySCF Interface#

pyscf2mppt wraps PySCF SCF, optional CASSCF and orbital preparation in a YAML interface. This example runs SCF and writes the integrals needed by MPPT:

pyscf2mppt ce.yaml --output-dir runs/ce-reference --stop-after dump

--stop-after dump stops before the downstream programs, even though they are enabled in ce.yaml. The shared data file is runs/ce-reference/data/ce.h5.

Read runs/ce-reference/summary.md and logs/pyscf.log. The reference SCF energy is approximately −468.77274881 Eh. The run also retains the executed input, resource copies and checkpoints.

Stop At An Earlier Stage#

To pause after SCF instead, start a separate run and continue its checkpoints into the integral dump:

pyscf2mppt ce.yaml --output-dir runs/ce-paused --stop-after scf
pyscf2mppt ce.yaml --output-dir runs/ce-paused --resume --stop-after dump

The PySCF-side stage names are input_normalized, scf, casscf, orbitals and dump. Choose a stage that is present in your calculation: this Ce input has no CASSCF or optional orbital-preparation stage. See the stage-control rules for absent-stage behavior.

Use the CLI to inspect saved checkpoints without a Python script:

pyscf2mppt --inspect-checkpoint runs/ce-reference/checkpoints

Inspection reports the saved orbital state. --inspect-full is currently metadata-only; it does not inspect the complete HDF5 calculation.

Run The MPPT Core Separately#

Reuse ce.yaml with the saved HDF5 file. In this mode only its mppt section is read; PySCF is not rerun:

pyscf2mppt ce.yaml \
  --from-hdf5 runs/ce-reference/data/ce.h5 \
  --output-dir runs/ce-levels

The native programs construct the determinant model space, assemble and diagonalize the second-order effective Hamiltonian, then include spin–orbit coupling to produce 24 states. The terminal shows progress; complete output is saved in runs/ce-levels/run.log.

The shared HDF5 is updated in place with selection and workflow checkpoints. Keep it together with both run directories. In particular, downstream execution changes the original reference run’s recorded HDF5 identity; use the downstream run for subsequent workflow resume or archiving.

Choose A Downstream Stopping Point#

The downstream stages are controlled by YAML enabled fields:

Finish after	`mppt.cipsixx.enabled`	`mppt.diagpt.enabled`	`mppt.heffso.enabled`
Model-space construction	`true`	`false`	`false`
Scalar MPPT energies	`true`	`true`	`false`
Spin–orbit levels	`true`	`true`	`true`

For either shorter route, save a copy of ce.yaml with those settings and use a new --output-dir. A workflow-only YAML may also contain just the mppt section. --from-hdf5 cannot be combined with --stop-after.

To continue the unchanged full downstream run after an interruption:

pyscf2mppt ce.yaml \
  --from-hdf5 runs/ce-reference/data/ce.h5 \
  --output-dir runs/ce-levels --resume

Matching completed stages are reused when their fingerprints and required outputs remain valid. Changed scientific settings require a new run directory; prerequisites can be recomputed if their outputs are unavailable there.

Read The Energy Levels#

Start with runs/ce-levels/summary.md, then the energy table in runs/ce-levels/logs/heffso.log. Energies are reported in Hartree, with relative levels in eV and cm⁻¹. The table should contain 24 states with nonzero spin–orbit splitting and Kramers pairs.

Path below `runs/ce-levels/`	Contents
`summary.md`, `run.log`	Run status and complete pipeline output.
`logs/cipsixx.log`, `logs/diagpt.log`, `logs/heffso.log`	Model-space, scalar and spin–orbit diagnostics.
`data/Ce_heffso.h5`	Scalar effective-Hamiltonian handoff.
`data/Ce_sovec`	Spin–orbit eigenvectors.
`data/Ce_heffso_properties.h5`	State energies and property matrices.

The output guide describes all artifacts and restart rules. Caspy turns the property output into tables and spectra.

One Input For The Full Calculation#

The same complete ce.yaml also runs every stage from scratch. Use a new output directory and omit --stop-after and --from-hdf5:

pyscf2mppt ce.yaml --output-dir runs/ce-full

# Ce3+ levels in orbitals optimized for the closed-shell Ce4+ reference.
molecule:
  symmetry: false
  charge: 4
  so: true
  atoms:
    - [Ce, 0.0, 0.0, 0.0]

basis:
  Ce: [file, Ce_expt_so_with_gh.dat]
ecp:
  Ce: [file, Ce_expt_so_with_gh.dat]

scf:
  omp_num_threads: 1
  spin: singlet
  type: rhf
  conv_tol: 1.0e-12

mppt:
  prefix: Ce
  output_hdf5: ce.h5
  downstream_nocc: 14
  cipsixx:
    enabled: true
    initial_space: cas
    max_selected: 12
    batch_size: 12
    max_iterations: 1
    n_roots: 12
    multi_state: true
    selection_growth: topk
    selection_metric: coefficient
    state_weighting: legacy-taum
    cas_orbitals: [14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25]
    core_orbitals: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13]
    frozen_orbitals: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13]
    cas_alpha_electrons: 1
    cas_beta_electrons: 0
    omp_num_threads: 1
  diagpt:
    enabled: true
    integral_space: full
    omp_num_threads: 1
  heffso:
    enabled: true
    nvectw: 24
    residual_tolerance: 1.0e-5
    initial_vector_tolerance: 1.0e-5
    omp_num_threads: 1

For larger calculations, continue with the workflow guide, YAML reference and scaling guidance.