Spin-integrated STEOM-CCSD
STEOMCC is available from ccpy and ccpy.methods. It requires a
closed-shell restricted reference and computes singlet (multiplicity=1) or
triplet (multiplicity=3) excitation energies. The ground-state calculation
is CCSD; an upstream CCSD object is reused.
from ccpy import Molecule, RHF, CCSD, STEOMCC
mol = Molecule("Li 0 0 0; H 0 0 1.6", "sto-3g",
auxiliary_basis="def2-universal-jkfit", verbose=False)
mf = RHF(mol).run()
cc = CCSD(mf)
# State-averaged CIS natural orbitals select the active spaces automatically.
steom = STEOMCC(cc, nroots=2, multiplicity=1).solve()
print(steom.omega) # excitation energies in hartree
print(steom.energy()) # total excited-state energies in hartree
print(steom.energy(0)) # total energy of root 0
Manual active spaces
Specify both nacto and nactu to select the highest occupied and lowest
virtual canonical orbitals. Alternatively, give both active_occupied and
active_virtual as lists of distinct, zero-based indices within their
respective correlated spaces. Frozen occupied and deleted virtual orbitals
are excluded from these indices.
steom = STEOMCC(cc, nroots=2, nacto=1, nactu=2)
explicit = STEOMCC(cc, nroots=2, active_occupied=[1], active_virtual=[0, 1])
The active space selects the model orbitals and the targeted principal IP/EA roots. The auxiliary IP-EOMCCSD(2h-1p) and EA-EOMCCSD(2p-1h) correlation spaces retain all correlated orbitals. The final diagonalization also retains all occupied-to-virtual singles, including inactive ones. It is not an active-only CIS projection.
Automatic selection
The automatic algorithm forms the occupied and virtual state-averaged CIS
densities for the lowest nroots CIS states of the requested multiplicity.
It selects natural orbitals by cumulative population and diagonalizes the
active/active and inactive/inactive Fock blocks separately. Degenerate natural
orbital populations are kept together at the selection boundary.
The defaults follow Dutta et al., J. Chem. Phys. 146, 074103 (2017):
Parameter |
Singlets |
Triplets |
|---|---|---|
|
0.99 |
0.999 |
|
0.99 |
0.999 |
|
0.90 |
0.80 |
|
0.90 |
0.80 |
All thresholds are fractions, not percentages. IP/EA thresholds apply to the
one-hole/one-particle weight using the determinant metric (including a factor
of one half for same-spin doubles). Low-character roots are discarded, with
pivoted QR choosing a matching square subset of the original model orbitals.
An empty sector, an unconverged auxiliary solve, or an overlap condition number
above condition_limit (default 1e10) raises an error. Set the IP/EA
thresholds to zero to retain all converged auxiliary states.
CCSD and its HBar can be computed in the original orbitals: rotating their converged tensors is equivalent to recomputing them in the CIS-NO basis. The upstream reference, T amplitudes, and cached HBar are preserved. Automatic STEOM roots are matched one-to-one to the CIS states by maximum total squared overlap. Manual calculations return the lowest STEOM roots in energy order. Explicit neutral guesses can use per-irrep counts; the final Hamiltonian is not diagonalized in separate point-group blocks. See neutral targeting below.
Equations and diagnostics
ccpy/eomcc/steomccsd.py implements the spatial-orbital equations of
Nooijen and Bartlett, J. Chem. Phys. 107, 6812 (1997). The ab blocks of
the closed-shell CCpy HBar supply the spin-free two-electron coefficients in
1212 notation. Intermediate normalization uses a matrix solve on the active
one-hole/one-particle overlaps; IP amplitudes carry the extra hole-contraction
minus sign. The G construction includes the mixed IP/EA quadratic terms
that account for implicit triple excitations.
Only G.oo, G.vv, G.vovo and G.voov are formed. With row (a,i) and column
(b,j), the final matrix is
where c=2 for singlets and c=0 for triplets. The S1 transformation is
omitted because it preserves the spectrum of the full singles block.
The first H.ov * S(EA) contribution to the phph intermediate is positive
in this implementation, differing from the minus printed in Eq. (57).
An independent determinant-space normal-ordering oracle, with nonzero H.ov,
verifies this sign and all linear and quadratic contributions for singlets
and triplets. Eq. (44) also requires attention to the order of its EA indices:
s_ie^ab = s_ei^ba.
Useful result attributes include:
ipandea: auxiliaryR,omega,root_converged,singles_characterandretained_roots;active_occupiedandactive_virtual: retained model labels;S_ipandS_ea: compact tensors[m,i,j,b]and[e,a,b,j];Gandmatrix: the transformed blocks and singles matrix;orbital_rotations: occupied and virtual matrices, with old orbitals on rows and working orbitals on columns;active_weights: final right-vector squared weight in active singles;residual_normsandroot_converged: final eigenpair checks.
G, S and active labels refer to the working basis. R contains normalized
spin-resolved singles transformed back to the upstream orbital basis. These
are reduced-space eigenvectors, not full STEOM wavefunctions or transition
densities. The IP/EA and final matrices are non-Hermitian; selected complex
final eigenpairs raise an error when they are genuinely complex. Conjugate
pairs split only by numerical noise are converted to a real basis when the
resulting vectors satisfy the requested residual tolerance.
Current scope
This implementation materializes the legacy four-index HBar and uses dense CIS and final singles diagonalizations. It supports energies, with the common method API’s finite-difference gradients; no analytical STEOM gradients, transition properties, open-shell equations, or DF-specific STEOM contractions are provided. Auxiliary roots are followed individually from active orbital unit vectors using the existing Davidson solver. If separate guesses converge to linearly dependent roots, the model-overlap check rejects the calculation.
Validation
tests/eomcc/test_steomccsd.py compares the tensor contractions to independent
normal-ordered fermion algebra, including partial and full active spaces, and
checks normalization, filtering and CIS-NO selection.
tests/methods/test_steomcc.py exercises singlet/triplet molecular calculations,
automatic selection, full-space orbital covariance, upstream cache preservation,
cache invalidation and failure handling. These checks do not replace a broad
comparison against published excitation-energy benchmarks.
Higher-rank auxiliaries and an SD-sized neutral problem
STEOMCC(..., level="sdt") dispatches to STEOMCCSDT. The ground-state
operator remains CCSD. The new level solves IP-EOMCCSD(3h-2p) and
EA-EOMCCSD(3p-2h) auxiliaries and diagonalizes the final neutral Hamiltonian
over singles and doubles.
extended = STEOMCC(cc, level="sdt", nroots=5,
nacto=2, nactu=3,
auxiliary_solver="pspace").solve()
print(extended.omega)
print(extended.singles_weights)
print(extended.ip.model_weights)
print(extended.ea.model_weights)
# Equivalent explicit class; use dense auxiliary triples for comparison.
from ccpy import STEOMCCSDT
full_aux = STEOMCCSDT(cc, nroots=5, nacto=2, nactu=3,
auxiliary_solver="dense")
The auxiliary model is enlarged to include all correlated 1h/1p configurations
and all active 2h1p/2p1h doublets. Both the dense initial guesses and the
normalization use this enlarged model. The guesses come from ipcisd.py and
eacisd.py. One root is solved for each spin-adapted model configuration,
using block Davidson with a unique assignment of Ritz roots to guesses. This
allows predominantly 2h1p/2p1h roots to be retained rather than rejecting them
with the ordinary STEOM singles-character cutoff.
With auxiliary eigenvectors stored in the columns of R and an orthonormal model basis P, the wave operator satisfies
The number of auxiliary roots is therefore set by the model dimension, not by
the requested number of neutral roots. An unconverged root or an ill-conditioned
model overlap fails the calculation. In the new level ip_threshold and
ea_threshold apply to the total enlarged-model weight, including active
satellites. Both default to zero. No root is silently dropped because doing so
would leave the prescribed model incomplete.
P-space selection
Only the highest-rank auxiliary sector is restricted in P-space mode. Lower
1h+2h1p / 1p+2p1h amplitudes remain unrestricted. By default auxiliary triples
contain at least one active hole (IP) or one active particle (EA), matching
CCpy’s active 3h2p/3p2h convention. minimum_active=2 or 3 tightens that
condition. Empty spin cases use CCpy’s zero-amplitude sentinel convention.
ip_pspace and ea_pspace can provide custom aaa, aab and abb
arrays with one-based canonical rows. IP rows are [b,c,i,j,k]; EA rows are
[a,b,c,j,k]. These labels refer to the working basis after the reported
orbital rotation, not necessarily the upstream canonical basis. Custom spaces
should preserve spin symmetry. Fortran kernels may sort excitation lists;
the wrapper restores a fixed external ordering after every sigma evaluation
so that stored Davidson vectors retain their meaning. Caller-owned arrays
are copied.
auxiliary_order=2 selects the lower-rank IP/EA solvers with the same
enlarged model and neutral SD projection. It is useful for isolating the
higher-rank auxiliary contribution, but does not reproduce the 2000 paper’s
original one-hole/one-particle normalization model.
Transformation and neutral sigma vectors
The 2000 extended-STEOM paper extends the final diagonalization space while retaining an S2 transformation obtained from ordinary IP/EA auxiliaries. The implementation here goes beyond that paper: its enlarged satellite model requires additional normal-ordered operator components as well as the higher-rank auxiliary amplitudes.
Write S by the numbers of quasiparticle creation and annihilation operators:
S.one2: three creators and one annihilator;S.one3: five creators and one annihilator;S.same: three creators and three annihilators;S.higher: five creators and three annihilators.
The three-annihilator terms act on the satellite model. They are obtained recursively from the normalized auxiliary wave operator, subtracting the already determined one-annihilator action. Both IP and EA terms enter these subtractions. In particular, simply inserting improved R2 into the original STEOM S2 formula does not implement the enlarged-model transformation.
Let U be the normal exponential of S, and let C contain neutral singles and doubles. The code forms the induced components
Braces exclude contractions between the S operators. Implicit neutral quadruples are dropped before HBar acts, following the truncation strategy of Eq. (18) in the 2000 paper. The SD-projected sigma vector is computed with the existing EE-EOMCC(P) singles/doubles contractions and sparse induced triples. No dense R3 array is allocated and no neutral triples are optimized. The CCSD HBar’s factorized three-body contributions are retained by these existing contractions.
The SD block of U is lower triangular:
The final action is
The new rank-preserving satellite contribution makes the doubles block of M
nontrivial. The ordinary 1-S2 left factor is insufficient; a sparse LU
solve applies this inverse. This projected, omitted-quadruples extension is a
research implementation, not a claim of equivalence to the published
S2-only extended-STEOM method or to full EOMCCSDT.
Spin and solver behavior
The final basis contains unique Ms=0 SD configurations and is projected onto
singlets or triplets by diagonalizing small connected blocks of the spin
matrix. nroots may exceed the CIS dimension. Without an explicit neutral
guess, roots are returned in energy order, including doubly excited roots.
Configured neutral guesses instead determine both the targeted states and their
returned order. singles_weights are measured
in the transformed EOM picture, normalized over R1+R2, as in the paper.
G is a spin-adapted scipy.sparse.linalg.LinearOperator. Dimensions up to
dense_limit (default 80) use dense diagonalization; larger problems use
Arnoldi. Asking for almost all roots also uses dense diagonalization. matrix
is populated only for dense solves. The solver options maximum_iterations,
amp_convergence and davidson_max_subspace_size control the iterative
solves. Upstream CCSD amplitudes and HBar remain unchanged, and neutral R
vectors are returned in the upstream orbital basis.
Automatic orbital selection uses CIS by default. With a configured CISd guess, it instead includes the selected guesses’ singles and doubles contributions to the occupied-hole and virtual-particle densities. A manual auxiliary active space remains available. The sparse normal-product implementation is intended to establish correctness and avoids full Fock-space matrices, but its Python exterior-algebra loops are not a replacement for a fully factorized production tensor implementation. Large satellite models can require many auxiliary roots, substantial storage, and expensive induced-triples contractions. Published molecular benchmarks and systematic active-space convergence studies remain necessary.
Additional validation
tests/eomcc/test_steomccsdt_equations.py checks normal products against
independent fermion strings, verifies the enlarged-model normalization, and
compares the complete SD action and inverse metric against explicit small
Fock-space matrices. tests/methods/test_steomccsdt.py checks the exact
neutral two-electron limit, higher-rank full/P-space agreement, satellite roots,
Arnoldi diagonalization, and failure handling.
Targeting neutral CIS or CISd roots
Both STEOM levels support initial_guess("cis", ...) and
initial_guess("cisd", ...). CISd retains all singles and active doubles and
uses CCpy’s existing spin-adapted ccpy.eom_guess.cisd solver. The guess
multiplicity is the STEOM calculation’s multiplicity.
steom = STEOMCC(cc, level="sdt", nacto=2, nactu=3)
steom.initial_guess("cisd", nacto=2, nactu=4, roots=[1, 5])
steom.solve()
print(steom.omega) # targets in guess order: 1, then 5
print(steom.guess_singles_weights) # singles fractions of the CISd guesses
print(steom.guess_overlaps) # squared final overlaps with the guesses
roots are distinct zero-based indices in the energy-ordered, spin-adapted
guess spectrum. The call above computes enough CISd roots to select indices 1
and 5 and targets two final states, even if they are not the two lowest STEOM
states. Omitting roots targets the lowest nroots guess states. Optional
roots_per_irrep supplies guess counts using the actual molecular irrep
labels, with use_symmetry=True to enable symmetry restriction in the guess.
Explicit indices then refer to the concatenated guess output in dictionary
order. Without explicit indices all requested per-irrep guesses are targeted.
The guess nacto and nactu define the highest occupied / lowest virtual
canonical orbitals allowed in the neutral guess doubles. They are independent
of the auxiliary active space passed to the STEOM constructor. For manual
auxiliary spaces the guess counts default to the corresponding active counts;
for automatic selection provide explicit CISd guess counts. The guess is solved
on the bare Hamiltonian in the original reference orbital basis, then rotated
into the STEOM working basis.
For the extended SD problem, final C vectors are compared to CIS/CISd guesses
in the transformed EOM picture: R_SD = M C_SD. The normalized overlap uses
unique determinants, equivalently the metric with a 1/4 factor for same-spin
doubles and unit weight for mixed-spin doubles. A one-to-one assignment
maximizes the total squared overlap across targeted states. Dense solves search
the full spectrum. Configured iterative solves use block Davidson with the
same overlap criterion throughout; they do not search only the lowest-energy
Arnoldi roots. Intermediate complex Ritz pairs can occur in non-Hermitian
subspaces; real residual expansions are allowed, but converged targets must
satisfy the real full SD equation.
For automatic active-space selection, state averaging uses the selected CISd vectors’ full hole and particle densities. Thus a pure double with zero singles amplitude still selects its occupied and virtual orbitals. OO and VV one-body operators preserve excitation rank, so these densities contain the singles/singles and doubles/doubles contributions without cross terms.
Use level="sdt" to represent neutral states dominated by doubles. The
original level="sd" Hamiltonian has only a singles space: it can accept a
CISd guess’s singles projection, but a guess with no singles projection is
rejected. Neither guess selection nor root following enlarges that singles-only
Hamiltonian.
guess_energy and guess_vectors retain the selected bare CI energies
and normalized ClusterOperator guesses. Changing initial_guess invalidates
the cached neutral solution; geometry reconstruction preserves the guess setup.
Without initial_guess, the previous defaults remain: automatic ordinary
STEOM follows CIS roots, manual ordinary STEOM selects the lowest energies,
and extended STEOM selects the lowest energies.