PySCF Scientific Reports

Open <output-dir>/logs/pyscf.log for the system specification, effective calculation controls, energies and orbital populations. Every CLI calculation writes these reports alongside native PySCF output. Use --full-output to mirror them to the terminal; the default console shows concise progress.

Report Sections

Section	Contents
Calculation setup	Versions, input, fresh/resumed mode, planned stages
System specification	Charge, multiplicity, electrons, atoms, shells, AO functions, ECP/GRPP and SO policy
Geometry and resources	Coordinates and units, effective atomic charges, per-atom/per-element AO counts, basis/potential resources, point charges
SCF setup and results	Effective solver settings, DF/auxiliary basis, initial guess, threads, convergence, energy components and MO populations
CASSCF setup and results	Active space, state groups/weights, convergence settings, energies, excitation energies, S² and correlated populations

Scientific tables use space-separated columns without borders. This includes the interface’s existing orbital, projection and Fock tables. Native PySCF diagnostics retain their native formatting. The ! SCF energy and ! CASSCF energy markers remain available to existing parsers. The CASCI energy: marker is also retained; it denotes the active-space CI contribution returned by the CASSCF kernel, not the total molecular energy.

Missing values are printed as NA. Energy units appear in the headings. Source orbital energies accompanying projected orbitals are metadata, not newly canonicalized eigenvalues.

CASSCF Populations

CASSCF populations come from the spin-summed one-particle density matrix in the final MO basis. Inactive orbitals have occupation two, active populations are the density diagonal, and external virtual orbitals have occupation zero. State averaging uses the solver’s actual weights and each state’s correct spin sector. Root identifiers remain in solver order even when the energy table is sorted by energy.

For projected/rotated orbitals, the density is transformed into the reported orbital basis before extracting populations. The stored active matrix retains off-diagonal information; simply rotating a vector of populations is incorrect.

Enable per-state analysis with:

casscf:
  verbose: 5

At casscf.verbose >= 5, each root has an active-MO population table and a separately labelled natural-occupation spectrum. Values below five keep the main averaged population and energy tables. The existing CASSCF verbosity default is six, so its default output includes per-state analysis.

Natural occupations are density eigenvalues. Their rank is not an index into the current MO list. All roots use the same optimized CASSCF orbitals for the current-basis population tables.

Downstream Pseudo-Restricted Occupations

Physical populations are distinct from the doubly occupied reference used by MPPT. Without an explicit mppt.downstream_nocc, the occupied prefix is:

nocc = ceil(N_electrons / 2)
     = n_inactive + ceil(N_active_electrons / 2)

One or two active electrons add one downstream occupied orbital; three add two. The number of fractionally occupied MOs does not enter this formula. Explicit downstream_nocc remains an override. The electron count comes from the actual reference molecule, including CASSCF charge overrides.

New HDF5 exports record physical source_mo_occupation separately from downstream_reference_occupation under /mppt/orbital_analysis. The additive occupation_source attribute identifies casscf-1rdm, scf, provided, or unavailable populations. Historical artifacts without this attribute retain their historical semantics.

Energy Conventions

SCF decomposition reuses PySCF’s final one-/two-electron energy summary rather than building J/K again. The potential contribution includes ECP/GRPP and any installed embedding potential. The closure residual compares the components with the reported SCF total.

The SCF nuclear/classical constant follows the actual solver’s energy_nuc. For point-charge inputs, the existing MPPT export constant can additionally include nucleus–point-charge and point-charge–point-charge terms. These constants must not be interchanged when comparing energies.

Progress And Restart

SCF, CASSCF, orbital preparation and export emit timed substage messages. SCF iterations and completed CASSCF macroiterations expose energy changes and available gradient norms. Iteration notifications are throttled to ten seconds; the final available snapshot is flushed at exit. Iterative convergence is not reported as a percentage.

Structured progress uses kind: progress in logs/events.jsonl, separate from parent-stage lifecycle transitions. Consumers calculating stage status should ignore these diagnostic records. Reports and progress are captured once in logs/pyscf.log and in the timestamped run.log.

New CASSCF checkpoints retain active densities, weights and S² in the saved MO basis. Partial continuation can report them without rerunning the CI solver. Fully reused Python stages retain their original raw log and producing attempt.

Old checkpoints without density evidence remain readable. Their correlated populations are labelled NA in reports; compatibility reference vectors in new exports carry occupation_source=unavailable. Start a fresh run to obtain the missing densities. Reusing an old complete HDF5 artifact does not regenerate its reports or apply the new downstream occupied-prefix rule.