Initial guesses, symmetry and choosing roots
Guess configuration is separate from the final equation model
initial_guess is shared by EOMCC, ADC and STEOM. It configures a CI-like
problem used to initialize and identify targets. It does not reduce the
subsequent full EOM excitation space. In particular, guess nacto/nactu
restrict guess doubles, not all EOM doubles/triples.
eom.initial_guess(
method="cisd", multiplicity=1,
nacto=3, nactu=4,
roots_per_irrep={"A1": 3, "B2": 2},
roots=[0, 2, 4], use_symmetry=True,
)
This example requires a reference with matching point-group labels, such as
C2v; it cannot be copied onto a C1 reference without changing the labels.
Use debug=True for supported guess diagnostics.
Guess |
Space |
Typical use |
|---|---|---|
|
All neutral singles. |
Primary-dominated EE; default folded EE-ADC(2). |
|
All neutral singles plus active doubles. |
Ordinary EE-EOM default; full EE-ADC default; doubles-character targeting. |
|
1h / 1h plus active 2h1p. |
Folded IP-ADC / IP-EOM or full IP-ADC. |
|
1p / 1p plus active 2p1h. |
Folded EA-ADC / EA-EOM or full EA-ADC. |
|
Leading 2h configurations. |
DIP-EOM families. |
|
Leading 2p configurations. |
DEA-EOM families. |
|
Leading single spin flips. |
SF-EOM families. |
For native DF methods method="cisd" is mapped to "cisd_chol".
It is an implementation selection, not a different user-facing root model.
nacto=None and nactu=None become zero in the generic mixin, so explicitly
supply positive counts when seeking active-double character. Open-shell guess
builders derive spin-specific active counts from the reference multiplicity,
subject to available dimensions. Consult printed active counts.
EOMCC guesses normally use the selected HBar (and T for DF CISd), not the bare SCF Hamiltonian. ADC and STEOM override this behavior and use the bare Hamiltonian. A bare CISd guess therefore need not have the same energies or ordering as an EOMCC CISd guess, even on the same reference.
Request a guess pool, then choose entries from it
roots_per_irrep={"A1": 3, "B2": 2} requests up to three A1 and two B2 guess
states. For symmetry-blocked guesses the concatenation follows dictionary
insertion order. Within each block the guess states are energy ordered.
roots=[0, 2, 4] selects entries of that concatenated guess pool, not
root 0/2/4 within every irrep, and not absolute final eigenvalue indices.
guess index 0 1 2 3 4
guess irrep A1 A1 A1 B2 B2
selected yes yes yes
returned index 0 1 2
After solving, energy(root=1) refers to the second returned state, which
was seeded by guess index 2 in this example. Likewise R[1] and
omega[1] are output indices. All these indices are zero based.
FNOTarget.root is different again: it labels the low-level provider’s root
within an irrep; see FNOs, active spaces and selected determinants.
A constructor roots=[...] provides the same guess-index selection for EOM
and ADC, but initial_guess(roots=...) takes precedence. Prefer configuring
selection in one place. If the guess pool provides fewer states than requested
because of spin, symmetry or active-space dimension, requesting a missing index
raises an error. Asking for a larger pool does not guarantee those states exist.
eom.initial_guess(method="cisd", multiplicity=1, nacto=2, nactu=3,
roots_per_irrep={"A": 6}, roots=[1, 4])
eom.run_guess() # optional inspection before the expensive EOM solve
print(eom.guess_energy, eom.guess_irreps)
totals = eom.energy()
print(eom.root_irreps)
For EOM, run_guess() can build the ground CC and HBar on demand. The
subsequent solve may regenerate guesses when no right vectors have yet been
initialized; it is an inspection step, not a persistent checkpoint.
Irrep dictionaries, integer counts and disabled symmetry
An integer roots_per_irrep=4 asks for the lowest four guess states without
irrep quotas. With symmetry disabled, a dictionary is treated as a total root
count rather than as enforced per-irrep quotas. Use a dictionary with
use_symmetry=True when distinct irrep counts matter.
CIS/CISd, IP-/EA-CISd and DIP-/DEA-CIS are symmetry blocked. IP-CIS, EA-CIS and
SF-CIS are diagonalized in their full leading space and classified afterward
by a leading amplitude. Printed guess_irreps records the resulting labels.
Final EOM root symmetry is checked against the guess and mismatches produce
warnings; this general check is not itself a projector. ADC additionally
restricts its Davidson action to the requested spatial irrep.
Spin multiplicity
For neutral EOM, the default guess multiplicity is the reference multiplicity.
Set 1 for singlets or 3 for triplets on a closed-shell parent. IP, EA, DIP, DEA
and SF default to -1, meaning no guess spin adaptation. multiplicity
selects the CI guess spin subspace when supported; it does not change the
molecule’s electron number or reference SCF spin.
EOM disables the closed-shell amplitude shortcut when the target multiplicity
is not 1. RHF_symmetry is an equation-level spin-block shortcut, not the
point-group symmetry switch and not an instruction to run RHF SCF.
A spin-adapted guess does not make a spin-contaminated UHF Hamiltonian spin pure.
STEOM separately restricts its reference to closed-shell restricted CCSD and its
target multiplicity to 1 or 3.
Following state character
davidson_selection_method="overlap" (default) follows the trial-state
character in the projected problem; "energy" selects the Ritz eigenvalue
nearest the current energy estimate. Neither guarantees an ordinal final root
of the exact spectrum. Inspect amplitudes, irreps, rel and overlaps when
states are close, reorder, or have strong double-excitation character.
For ordinary EOM, davidson_solver="standard" solves roots sequentially;
"multiroot" selects the existing block-Davidson implementation. Sequential
EOM passes previous vectors to the solver, but that is not the same as a
universal strict root-deflation projector. Confirm distinct roots rather than
assuming that an arbitrary set of guesses must converge to distinct states.
EOM-CC3 uses its omega-dependent nonlinear DIIS solver for either setting.
ADC exposes sequential Davidson only, with explicit full-space locking in
full mode and duplicate detection in folded mode. STEOM has its own auxiliary
and final diagonalization procedures.
For satellite or doubles-dominated targets:
Choose a model that includes the relevant R sectors.
Enlarge the CISd active space and request enough guess states.
Select the desired guess indices explicitly.
For ADC use
formulation="full"; for a neutral SD STEOM projection useSTEOMCCSDTrather than ordinary singles-only STEOM.Verify final character and convergence. FNO density selection must follow the same physical target in full and reduced spaces.
Changing initial_guess clears the existing right-state setup. Geometry
reconstruction copies guess settings, but generic EOM finite differences do
not implement a universal cross-geometry overlap tracker. Near crossings,
check the state identity explicitly; a fixed guess index is not proof that
the same physical state was followed.