vibeqc.SolverResult¶

class vibeqc.SolverResult(energy, method, converged=True, n_iter=0, energy_trace=<factory>, ci_coeffs=None, ci_labels=None, rdm1=None, rdm2=None, truncation_error=None, bond_dim=None, constraint_residual=None, pt2_correction=None, stop_reason=None, tc_diagnostics=None, root_energies=None, root_s2=None, selected_pt2=None, multistate=None, gradient=None, nonadiabatic_pair=None, nonadiabatic_coupling=None, natural_orbitals=None, natural_occupations=None)[source]¶

Bases: object

Common result container for all non-mean-field solvers.

Fields marked method-specific are populated by individual backends and may be None.

Parameters:

energy (float)
method (str)
converged (bool)
n_iter (int)
energy_trace (list[float])
ci_coeffs (ndarray | None)
ci_labels (list[tuple[int, ...]] | None)
rdm1 (ndarray | None)
rdm2 (ndarray | None)
truncation_error (float | None)
bond_dim (int | None)
constraint_residual (float | None)
pt2_correction (float | None)
stop_reason (str | None)
tc_diagnostics (dict | None)
root_energies (list[float] | None)
root_s2 (list[float] | None)
selected_pt2 (list[dict] | None)
multistate (dict | None)
gradient (ndarray | None)
nonadiabatic_pair (tuple[int, int] | None)
nonadiabatic_coupling (ndarray | None)
natural_orbitals (ndarray | None)
natural_occupations (ndarray | None)

__init__(energy, method, converged=True, n_iter=0, energy_trace=<factory>, ci_coeffs=None, ci_labels=None, rdm1=None, rdm2=None, truncation_error=None, bond_dim=None, constraint_residual=None, pt2_correction=None, stop_reason=None, tc_diagnostics=None, root_energies=None, root_s2=None, selected_pt2=None, multistate=None, gradient=None, nonadiabatic_pair=None, nonadiabatic_coupling=None, natural_orbitals=None, natural_occupations=None)¶

Parameters:

energy (float)
method (str)
converged (bool)
n_iter (int)
energy_trace (list[float])
ci_coeffs (ndarray | None)
ci_labels (list[tuple[int, ...]] | None)
rdm1 (ndarray | None)
rdm2 (ndarray | None)
truncation_error (float | None)
bond_dim (int | None)
constraint_residual (float | None)
pt2_correction (float | None)
stop_reason (str | None)
tc_diagnostics (dict | None)
root_energies (list[float] | None)
root_s2 (list[float] | None)
selected_pt2 (list[dict] | None)
multistate (dict | None)
gradient (ndarray | None)
nonadiabatic_pair (tuple[int, int] | None)
nonadiabatic_coupling (ndarray | None)
natural_orbitals (ndarray | None)
natural_occupations (ndarray | None)

Return type:

None

Methods

__init__(energy, method[, converged, ...])

Attributes

`bond_dim`	Bond dimension, DMRG.
`ci_coeffs`	Wavefunction coefficients (determinant x configuration), CI only.
`ci_labels`	Determinant / configuration labels, CI only.
`constraint_residual`	N-representability residual norm, v2RDM.
`converged`	Whether the solver considers itself converged.
`energy_total`	Alias for `energy`.
`gradient`	Analytic nuclear gradient (n_atoms, 3) in Hartree/bohr.
`multistate`	`mode`, `heff` (symmetrized effective Hamiltonian), `heff_asym`, `mixing`, `ss_energies`, `ref_energies`, `e2_corr`, `xms_rotation`.
`n_iter`	Number of macro-iterations / sweeps taken.
`natural_occupations`	Occupation numbers matching `natural_orbitals` column for column, in the same order.
`natural_orbitals`	Natural orbitals in the AO basis, shape `(n_ao, n_mo)`; columns are orbitals, matching the mean-field `mo_coeffs` convention.
`nonadiabatic_coupling`	State-pair nonadiabatic derivative coupling (n_atoms, 3) in bohr^-1.
`nonadiabatic_pair`	Ordered physical-root pair for `nonadiabatic_coupling`.
`pt2_correction`	Perturbative correction, Selected-CI.
`rdm1`	1-RDM (norb, norb), if computed by the solver.
`rdm2`	2-RDM (norb, norb, norb, norb), if computed by the solver.
`root_energies`	Per-root total energies (Hartree), multi-root CASCI / SA-CASSCF / multi-state CASPT2 only.
`root_s2`	Per-root <S^2> alongside `root_energies` (same ordering), so the .out root table shows which spin sector each averaged root lives in.
`selected_pt2`	Per-root Epstein-Nesbet PT2 on a selected-CI wavefunction (`vibeqc.solvers.selected_ci_pt2()` dicts: `e_pt2`, `e_total`, `stderr`, `n_perturbers`), requested via `CASSCFOptions.pt2`.
`stop_reason`	Why the solver stopped, Selected-CI.
`tc_diagnostics`	Transcorrelated diagnostics dict.
`truncation_error`	Truncation error / discarded weight, DMRG.
`energy`	Total energy (Hartree).
`method`	Method name, e.g. `"selected_ci"`, `"dmrg"`, `"v2rdm"`.
`energy_trace`	Energy trace per macro-iteration (if tracked).

energy: float¶: Total energy (Hartree). Always includes nuclear repulsion.

method: str¶: Method name, e.g. "selected_ci", "dmrg", "v2rdm".

converged: bool = True¶: Whether the solver considers itself converged.

n_iter: int = 0¶: Number of macro-iterations / sweeps taken.

energy_trace: list[float]¶: Energy trace per macro-iteration (if tracked).

ci_coeffs: ndarray | None = None¶: Wavefunction coefficients (determinant x configuration), CI only.

ci_labels: list[tuple[int, ...]] | None = None¶: Determinant / configuration labels, CI only.

rdm1: ndarray | None = None¶: 1-RDM (norb, norb), if computed by the solver.

rdm2: ndarray | None = None¶: 2-RDM (norb, norb, norb, norb), if computed by the solver.

truncation_error: float | None = None¶: Truncation error / discarded weight, DMRG.

bond_dim: int | None = None¶: Bond dimension, DMRG.

constraint_residual: float | None = None¶: N-representability residual norm, v2RDM.

pt2_correction: float | None = None¶: Perturbative correction, Selected-CI.

stop_reason: str | None = None¶: Why the solver stopped, Selected-CI. One of "energy" (the delta-E criterion fired), "target_size" (the requested determinant-space size was reached), "space_exhausted" (the candidate pool emptied below target_size – distinguishable from an energy-converged run), or "max_iter" (iteration cap). None for solvers that do not report a reason.

tc_diagnostics: dict | None = None¶: Transcorrelated diagnostics dict.

root_energies: list[float] | None = None¶: Per-root total energies (Hartree), multi-root CASCI / SA-CASSCF / multi-state CASPT2 only. energy remains the headline value (ground root, or the weighted state average for SA-CASSCF).

root_s2: list[float] | None = None¶: Per-root <S^2> alongside root_energies (same ordering), so the .out root table shows which spin sector each averaged root lives in. None when not computed (diagnostic; degrades to omission).

selected_pt2: list[dict] | None = None¶: Per-root Epstein-Nesbet PT2 on a selected-CI wavefunction (vibeqc.solvers.selected_ci_pt2() dicts: e_pt2, e_total, stderr, n_perturbers), requested via CASSCFOptions.pt2. energy stays variational; this is the SHCI perturbative estimate on top.

multistate: dict | None = None¶

mode, heff (symmetrized effective Hamiltonian), heff_asym, mixing, ss_energies, ref_energies, e2_corr, xms_rotation.

Type:: Multi-state PT2 diagnostics (MS/XMS-CASPT2)

gradient: ndarray | None = None¶: Analytic nuclear gradient (n_atoms, 3) in Hartree/bohr. Computed for CASSCF; None for other methods.

nonadiabatic_pair: tuple[int, int] | None = None¶: Ordered physical-root pair for nonadiabatic_coupling.

nonadiabatic_coupling: ndarray | None = None¶: State-pair nonadiabatic derivative coupling (n_atoms, 3) in bohr^-1. Currently available for the under-review MS/XMS-CASPT2 route.

natural_orbitals: ndarray | None = None¶: Natural orbitals in the AO basis, shape (n_ao, n_mo); columns are orbitals, matching the mean-field mo_coeffs convention. Populated for CASCI/CASSCF, where they are the eigenvectors of the converged one-particle density matrix: inactive orbitals pass through unchanged (they are already natural, with occupancy 2), active orbitals are the converged CAS orbitals rotated by the eigenvectors of the active-block 1-RDM, and virtuals pass through unchanged. None for solvers that do not optimize orbitals.

natural_occupations: ndarray | None = None¶: Occupation numbers matching natural_orbitals column for column, in the same order. Electron counts per orbital, so they sum to the number of electrons. Integer for the inactive (2.0) and virtual (0.0) blocks; genuinely fractional across the active space, where the departure from {0, 2} is the multireference character.

property energy_total: float¶: Alias for energy.