FNOs, active spaces and selected determinants

Experimental CIM domains are a separate local-correlation model; see Cluster-in-molecule local correlation. Current CIM wrappers cannot be composed with FNOs.

Three different reductions

A frozen core removes occupied orbitals from correlation. FNOs rotate and truncate virtual orbitals for the whole correlated calculation. A P space selects individual high-rank excitations within those working orbitals. An initial guess active space restricts only its preliminary CI problem. These choices are independent; specify which one you intend to change.

Enable DF-MP2 FNOs at the start of a chain

from ccpy import CCSD, EOMCCSD, FNOOptions

options = FNOOptions(source="mp2", occupation_cutoff=1.e-6)
cc = CCSD(mf, nfrozen=1, fno=options)
completed_ground = cc.energy()
eom = EOMCCSD(cc)
eom.initial_guess(method="cisd", multiplicity=1, nacto=2, nactu=2,
                  roots_per_irrep={"A": 2})
completed_states = eom.energy()
print(cc.raw_energy(), cc.fno_result.delta_ground)
print(eom.completed_omega)

Preparation computes full-space DF-MP2 energy and virtual density, diagonalizes the density, selects virtual natural orbitals, semicanonicalizes the retained virtual Fock block, transforms DF factors and recomputes DF-MP2 in the reduced space. Occupied orbitals and the SCF determinant are unchanged. CC/EOM kernels then treat the reduced virtual dimension as the ordinary working dimension. The ground MP2 provider uses three-index occupied-pair contractions rather than storing a full MP2 doubles tensor. ROHF uses the specified spin-Fock partition, including first-order singles when Fov is nonzero.

Use exactly one selection criterion:

by_occupation = FNOOptions(occupation_cutoff=1.e-6)
by_population = FNOOptions(retained_population=0.999)
by_count = FNOOptions(nvirtuals=20)
full_retention = FNOOptions(occupation_cutoff=0.)

The default is occupation cutoff 1e-6. Restricted occupations use spatial 0–2 normalization; UHF uses spin 0–1. nvirtuals counts external spatial virtuals for restricted references. For UHF it specifies a minimum per-spin count with equal removals enforced. Symmetry, degeneracy and protected-space closure can increase the final count. Removing all external virtuals is rejected. FNO thresholds are occupation criteria, not guaranteed energy-error bounds; check energy/gap convergence as the retained space grows.

Automatic composite energy completion

The default energy_completion="ground" returns

\[E_{\mathrm{reported}}=E_{\mathrm{high,trunc}} +E_{\mathrm{low,full}}-E_{\mathrm{low,trunc}}.\]

energy() includes this shift automatically. raw_energy(), correlation_energy and raw omega do not. Ground corrections and final STEOM/EOM totals apply the completion once; auxiliary eigenvalues are not independently shifted. For MP2 selection the same ground correction shifts all target totals and the parent, so target-minus-parent gaps are unchanged. A corrected total is still an approximation to the full-space high-level energy; the composite formula does not recover missing high-level amplitudes.

energy_completion="none" reports uncompleted truncated totals. "state_specific" requires ADC target energies and applies a distinct low-level full-minus-reduced shift to each target. completed_omega is the completed target-minus-completed-parent difference on EOM/ADC/STEOM objects. There is no correction for manually deleted virtuals with ndelete.

State-specific ADC-FNOs

from ccpy import CCSD, EAEOM2, FNOOptions, FNOTarget

targets = (FNOTarget("EA", root=0, irrep="A", formulation="folded"),)
policy = FNOOptions(
    source="adc2", targets=targets, space_policy="root_specific",
    occupation_cutoff=1.e-6, energy_completion="state_specific",
)
cc = CCSD(mf, nfrozen=1, fno=policy)
ea = EAEOM2(cc, fno_targets=targets)
ea.initial_guess(method="eacis", roots_per_irrep={"A": 1})
completed_target_total = ea.energy(root=0)

The native provider supports EE/IP/EA on RHF/ROHF/UHF, including noncanonical references. FNOTarget fields are sector, zero-based root within the provider’s irrep, optional irrep, optional positive multiplicity, and formulation="folded"|"full". Omit charged multiplicity to use the provider’s unadapted default; -1 is a guess setting, not an allowed FNOTarget.multiplicity. On a symmetry reference, provide the irrep.

Folded selection uses bare CIS/IP-CIS/EA-CIS guesses and is intended for primary-dominated states. Full selection uses bare CISd/IP-CISd/EA-CISd, including active doubles, and supports satellite/doubles targeting:

satellite = FNOTarget("IP", root=3, irrep="A", formulation="full")
double_excitation = FNOTarget("EE", root=4, irrep="A", multiplicity=1,
                             formulation="full")

The built-in full-space CISd provider uses up to two active occupied/virtual orbitals; requesting a higher root does not enlarge that active model. For other active-space choices or more elaborate root identification, register a custom provider. Its density must be a state virtual block with the documented ISR order, not a transition density or an arbitrary particle population. Native DEA/DIP/SF ADC-FNO selection is not implemented; DF-MP2 FNOs still apply to those high-level methods.

Multiple targets and root identities

space_policy="average" diagonalizes a weighted average target density; weights supplies positive weights, normalized by preparation. "union" selects each target subspace separately and retains their span. "root_specific" requires exactly one target and a separate chain per target. The default shared policy is average. Union/average can combine supported sectors or ADC formulations; all high-level calculations must use the resulting same reference to share amplitudes.

targets = (
    FNOTarget("EE", root=0, irrep="A", multiplicity=1),
    FNOTarget("EE", root=2, irrep="A", multiplicity=1),
)
policy = FNOOptions(source="adc2", targets=targets, weights=(1., 2.),
                    space_policy="average", nvirtuals=10,
                    energy_completion="state_specific")
cc = CCSD(mf, nfrozen=1, fno=policy)
eom = EOMCCSD(cc, fno_targets=targets)
eom.initial_guess(method="cisd", multiplicity=1, nacto=2, nactu=2,
                  roots_per_irrep={"A": 3}, roots=[0, 2])
totals = eom.energy()

fno_targets maps low-level state identities into returned high-level root order. Its length, sectors, irreps and specified spins must match that output. The API cannot prove that a high-level root has the intended low-level physical character: check the states yourself. Mixed-sector references with state-specific completion need each EOM object’s corresponding subset of targets.

The provider projects full-space physical vectors through the actual orbital transformation to seed reduced calculations. It follows overlaps and rejects a normalized projected overlap below 0.5. Degeneracies can require a larger space or a provider with subspace tracking. A root label is not a guarantee of an unchanged energy ordering.

Protected orbitals and reference inspection

protected_virtuals=(0, 2) adds specified input virtual directions to the retained span. These are zero-based external virtual labels (excluding ROHF singly occupied spatial orbitals); for UHF they are local spin-virtual labels. This protects directions, not final individual natural orbitals. Dense protected subspaces can also be supplied by custom providers.

All singly occupied ROHF spatial orbitals are preserved. Only the common external virtual space is rotated/truncated, preserving the restricted open-shell determinant. Symmetry and occupation degeneracies are preserved; degeneracy_tolerance and density_tolerance control associated checks.

result = cc.fno_result
print(result.discarded, result.retained_population)
print(result.occupations)
print(result.full.ground_energy, result.truncated.ground_energy)
full_reference = cc.reference.fno_parent

fno_result is shared through the reduced reference. Occupations are reported before virtual semicanonicalization. A new threshold requires a new chain from SCF or the full reference. You cannot add FNOs after allocating an upstream CC calculation, disable inherited FNOs downstream, combine them with ndelete, or reuse full-space amplitudes after a dense virtual rotation.

Active and selected spaces after FNO preparation

from ccpy import (Reference, prepare_fno, CCSDT_P, EOMCCSDT_P,
                  get_active_triples_pspace)

ref = prepare_fno(Reference(mf, nfrozen=1), FNOOptions(nvirtuals=6))
ref.system.set_active_space(nact_occupied=2, nact_unoccupied=2)
t3 = get_active_triples_pspace(ref.system, num_active=1)
r3 = get_active_triples_pspace(ref.system, num_active=1)
ccp = CCSDT_P(ref, t3)
eom_p = EOMCCSDT_P(ccp, r3_excitations=r3)
eom_p.initial_guess(method="cis", multiplicity=1,
                    roots_per_irrep={"A": 1})
selected_total = eom_p.energy(root=0)

Active occupied labels are frontier occupied orbitals and active virtual labels are the lowest working virtuals; set_active_space derives spin-specific counts for open-shell references. Setting active counts alone does not constrain an ordinary CCSDT/EOMCCSDT solve. Generate P lists and choose a selected-space method to restrict high-rank excitations.

P lists are integer, one-based orbital labels in the working correlated MO basis, with particles first and holes second. Use Fortran-contiguous arrays and the spin cases/order expected by the kernel:

Selected high-rank spaces

Model / helper

Dictionary keys

Rows

Ground/EE triples, get_active_triples_pspace

aaa, aab, abb, bbb

[a,b,c,i,j,k]

IP 3h2p, get_active_3h2p_pspace

aaa, aab, abb

[b,c,i,j,k] with particle/holes spin strings derived from the sector.

EA 3p2h, get_active_3p2h_pspace

aaa, aab, abb

[a,b,c,j,k]

DEA 4p2h, get_active_4p2h_pspace

abaa, abab, abbb

[a,b,c,d,k,l]

For IP the particle/hole spin strings are aa/aaa, ab/aab, bb/abb; for EA they are aaa/aa, aab/ab, abb/bb. For DEA they are abaa/aa, abab/ab, abbb/bb. Each side gives the spin of each particle/hole column in order. The triples helper requires at least num_active active holes and active particles; IP counts active holes, EA/DEA active particles. target_irrep can filter generated lists.

Empty spin blocks conventionally use a single all-ones row with zero amplitude, not a zero-row array. Same-spin indices have canonical ordering/antisymmetry; helpers enforce the kernel’s convention. For restricted closed-shell CC(P), wrappers derive beta-related lists from their alpha partners. Fortran kernels may sort lists in place together with amplitudes; do not rely on caller order remaining unchanged.

CCSDT_P.set_pspace retains amplitudes by extending its selected operator. New excitations must be appended consistently to the current list/order; it is not a general arbitrary-list remapper. EOM..._P.set_pspace resets right states and recomputes from guesses. Ground t3_excitations and excited r3_excitations are separate data even if generated by the same helper.

Build charged selected models similarly:

from ccpy import (IPEOM3_P, EAEOM3_P, DEAEOM4_P,
                  get_active_3h2p_pspace, get_active_3p2h_pspace,
                  get_active_4p2h_pspace)

ip_space = get_active_3h2p_pspace(ref.system, num_active=1)
ea_space = get_active_3p2h_pspace(ref.system, num_active=1)
dea_space = get_active_4p2h_pspace(ref.system, num_active=2)
ip = IPEOM3_P(ref, r3_excitations=ip_space)
ea = EAEOM3_P(ref, r3_excitations=ea_space)
dea = DEAEOM4_P(ref, r3_excitations=dea_space)

These constructors create their standard CCSD parents unless a compatible parent is supplied. Configure guesses before calling energy(). The name r3_excitations is also used by the DEA wrapper for its selected 4p2h sector; it is an API parameter name, not a claim of three-particle rank.

Custom FNO providers

register_fno_provider(name, callable) installs a provider accepting (reference, targets=(), need_density=True, full_result=None) and returning FNOEvaluation. Ground/target energies are absolute totals, including the parent determinant energy, with signed charged conventions. Density dictionaries are keyed by targets (or None for ground selection), then a/b spin blocks in the supplied reference’s virtual basis. The reduced call receives the full result for physical-root matching. Honor need_density=False without changing the energy convention. Providers may return metadata and protected subspaces. See Frozen natural orbitals for the complete extension contract and an example.

External determinant-space readers

get_triples_pspace_from_cipsi(path, system) and get_quadruples_pspace_from_cipsi(path, system) extract the respective ranks from headerless determinant records with identifier/coefficient followed by occupied spin-orbital labels. They use correlated-space numbering (alpha odd, beta even), not AO labels or all-electron frozen-core numbering. Check the function’s returned tuple before passing its excitation dictionary to a method; the triples reader also reports excitation counts by symmetry. get_pspace_from_qmc reads integer signed walker populations and filters by threshold_walkers; the present implementation selects triples. These readers do not transform determinants between orbital bases. Inspect the source and a small known determinant before using a new external generator’s output.