Drivers for various electron-correlation methods

Drivers

Module for methods drivers (ccdriver, dfccdriver, etc).

ccdriver(EC::ECInfo, method; fcidump="", occa="-", occb="-")

Run electronic structure calculation for EC::ECInfo using method::String.

The integrals are read from fcidump::String. If fcidump::String is empty, the integrals from EC.fd are used. The occupied α orbitals are given by occa::String (default: "-"). The occupied β orbitals are given by occb::String (default: "-"). If occb::String is empty, the occupied β orbitals are the same as the occupied α orbitals (closed-shell case). The occupation strings can be given as a + separated list, e.g. occa = 1+2+3 or equivalently 1-3. Additionally, the spatial symmetry of the orbitals can be specified with the syntax orb.sym, e.g. occa = "-5.1+-2.2+-4.3".

dfccdriver(EC::ECInfo, method)

Run electronic structure calculation for EC::ECInfo using method::String.

The integrals are calculated using density fitting. If EC.fd.df3idx is set, uses pre-existing 3-index integrals (mmL/MML) from fcidump.

extrapolate(energies1::OutDict, energies2::OutDict)

Extrapolate energies using two sets of energies with corresponding corrections.

The keys with suffix "-correction" are used for extrapolation. Return a new OutDict with the extrapolated energies. Extrapolation is done to the limit where the correction goes to zero.

mo_integrals(EC::ECInfo)

Generate MO integrals from the exact (non-density-fitted) AO integrals and store them in EC.fd. This is the entry point behind the @moints macro, and the non-DF counterpart of dfdump (@dfints): the AO integrals are generated first if they are not on file yet (as @ints would), and are then transformed to the MO basis of the current orbitals (derive_mo_basis!, so the dump covers the active space — the frozen core is folded into int0/int1).

Unlike the dump a correlated driver derives for itself, these integrals PERSIST for the rest of the session and are yours to manage: they are built from a particular set of orbitals and become stale if the orbitals change, and re-running @moints is what refreshes them.

ao_direct_method(ecm::ECMethod) -> Bool

Whether ecm runs directly on the AO integral files without a preceding MO transform: MP2/UMP2/RMP2, or CCSD/DCSD/CCD/DCD optionally with perturbative triples and/or a Λ, EOM, QV, orbital-optimizing (O) or Brueckner (B) prefix. FCI and iterative triples always derive a transient MO dump (see derive_mo_basis!).

check_fcidump(EC::ECInfo, fcidump)

Read the integrals from fcidump if it is not empty.

check_occs(EC::ECInfo, occa, occb)

Check the occupation strings occa and occb and set the corresponding options in WfOptions. Return the previous values of occa and occb.

checkset_unrestricted_closedshell!(ecmethod::ECMethod, closed_shell, unrestricted)

Check if the method is unrestricted/closed-shell and if necessary set the corresponding options in ECMethod. Return closed_shell_method::Bool.

correlated_dipole(EC::ECInfo, rdm::SpinMatrix)

Evaluate the dipole moment from a correlated MO-space 1-RDM when the current wavefunction dump still contains orbitals and AO-basis metadata.

defer_lambda_perturbative_triples(method::ECMethod)

Return true when perturbative triples must be evaluated after the lambda equations rather than in the initial energy-only pass.

derive_mo_basis!(EC::ECInfo; persistent=false)

Derive an MO-basis EC.fd from the exact AO integrals (the ± supermatrix store, "h_AA", see ao_integrals) and the current orbitals, reducing the dump to the active space so that the MO integrals (and all downstream methods) scale with the active space rather than nao — the non-DF analogue of dfdump:

• The frozen orbitals are selected exactly like for a dfdump (freeze_orbitals!): chemical/explicit frozen core, and class-honored deleted (incl. linearly-dependent) or explicitly frozen virtuals.
• Deleted and frozen virtual orbitals are excluded from the transform — they carry no electrons, so no folding is needed and there is no reason to pay the O(N⁵) transform.
• Frozen occupied orbitals are excluded from the transform too: their mean field is built directly in the AO basis (the same 2J−K / J(Dα+Dβ)−K(Dσ) core Fock the AO-direct setup uses) and folded into int0/int1 by generate_mo_dump.
• orig_orbs records the active↔full orbital map, so user orbital lists (occa etc.) and property post-processing interpret the reduced dump correctly; the freeze options are not modified.

The derived dump is transient by default: the driver discards it at the end of the run, and it is re-derived from the AO files on demand. With persistent=true (mo_integrals, the @moints macro) the dump and its scratch file survive the run and are the user's to refresh.

dfmp2_property_rdm(EC::ECInfo, method::ECMethod)

Build the restricted DF-MP2 correlated 1-RDM directly from the saved doubles amplitudes. DF-MP2 properties use U2 = T2 and do not require a separate Lagrange-multiplier solve.

eval_cc_groundstate(EC::ECInfo, ecmethod::ECMethod, energies_in::OutDict; save_pert_t3=false)

Evaluate the coupled-cluster ground-state energy for the integrals in EC.fd. Fock matrix and HF energy must be calculated before. Return the updated energies::OutDict with the correlation energy (method*"c") and the total energy (key method).

eval_df3idx_mo_integrals(EC::ECInfo, energies::OutDict, closed_shell)

Build the Fock matrix and reference energy from pre-existing 3-index MO integrals (mmL/MML) and fcidump one-electron integrals.

Return the reference energy as HF key in OutDict and true if the integrals use unrestricted orbitals.

eval_df_mo_integrals(EC::ECInfo, energies::OutDict; save3idx=true)

Evaluate the density-fitted integrals in MO basis and store in the correct file. If save3idx is true, save the 3-index integrals, otherwise only the 2-index integrals.

Return the reference energy as HF key in OutDict and true if the integrals are calculated using unrestricted orbitals.

eval_dmrg_groundstate(EC::ECInfo, energies::OutDict)

Evaluate the DMRG ground-state energy for the integrals in EC.fd. HF energy must be calculated before. Return the updated energies::OutDict with the correlation energy ("DMRGc") and the total energy (key "DMRG").

eval_hf_energy(EC::ECInfo, energies::OutDict, closed_shell)

Evaluate the Hartree-Fock energy for the integrals in EC.fd. Return the updated energies::OutDict with the Hartree-Fock energy (field HF).

eval_mp2_energy(EC::ECInfo, energies::OutDict, closed_shell, restricted)

Evaluate the MP2 energy for the integrals in EC.fd. Fock matrix and HF energy must be calculated before. Return the updated energies::OutDict with same-spin(MP2-SS), opposite-spin(MP2-OS), open-shell(MP2-O) components, SCS-MP2 energy (SCS-MP2), correlation energy (MP2c) and the MP2 energy (field MP2).

eval_svd_dc_ccsdt(EC::ECInfo, ecmethod::ECMethod, energies::OutDict)

Evaluate the coupled-cluster ground-state energy for the integrals in EC.fd using SVD-Triples. Fock matrix and HF energy must be calculated before. Return the updated energies::OutDict with the correlation energy (method*"c") and the total energy (key method).

fci_property_rdms(EC::ECInfo, rdm_a::AbstractMatrix, rdm_b::AbstractMatrix, closed_shell::Bool)

Construct the dipole and storage 1-RDM payloads used by FCI and CIPHI property post-processing in the full orbital space.

full_space_fci_rdm(EC::ECInfo, rdm_active::AbstractMatrix, occ_key::Char, occval)

Embed an active-space FCI/CIPHI 1-RDM into the full orbital space and restore the frozen occupied reference contribution.

has_perturbative_triples(method::ECMethod)

Return true when method carries a perturbative triples correction.

need_correlated_properties(EC::ECInfo)

Return true when the conventional or DF correlated drivers must construct a correlated 1-RDM for property output or natural-orbital storage.

need_fci_properties(EC::ECInfo, ciphi::Bool)

Return true when FCI or CIPHI must construct correlated property data for dipole output or natural-orbital storage.

need_lagrange_multipliers(EC::ECInfo, method::ECMethod)

Return true when the calculation requires lambda amplitudes either because the requested method is a Λ-variant or because post-processing needs the correlated density.

output_2d_energy(EC::ECInfo, En::OutDict, energies::OutDict, method; print=true)

Print the energy components for 2D methods and return the updated energies::OutDict with singlet("SING"*method), triplet("TRIP"*method), singlet correlation("SING"*method*"c") and triplet correlation("TRIP"*method*"c") components.

output_energy(EC::ECInfo, En::OutDict, energies::OutDict, mname; print=true)

Print the energy components and return the updated energies::OutDict with correction to the correlation energy (mname*"-correction", e.g., ΔMP2, if available), same-spin(mname*"-SS"), opposite-spin(mname*"-OS"), open-shell(mname*"-O") components, SCS energy ("SCS-"*mname), correlation energy (mname*"c") and the total energy (field mname).

write_fci_dipole(EC::ECInfo, ciphi::Bool)

Return true when the FCI or CIPHI driver should print and store dipole components in the returned output dictionary.