Calculations

       ╭─────────────╮
Electron Correlation methods
       ╰─────────────╯

@ECinit(T=DEFAULT_ELTYPE[])

Initialize EC::ECInfo{T} and add molecular system and/or fcidump if variables geometry::String and basis::Dict{String,Any} and/or fcidump::String are defined.

T is the element type for the fcidump integrals (default: DEFAULT_ELTYPE[], which is Float64 unless changed via set_default_eltype! or @set_default_eltype).

If EC is already initialized, it will be overwritten.

Examples

geometry="He 0.0 0.0 0.0"
basis = Dict("ao"=>"cc-pVDZ", "jkfit"=>"cc-pvtz-jkfit", "mpfit"=>"cc-pvdz-mpfit")
@ECinit
# output
Occupied orbitals:[1]

@ECinit ComplexF64  # use complex integrals

@bohf(opts_block=nothing)

Run bi-orthogonal HF calculation using FCIDUMP integrals.

The orbital rotations are stored to WfOptions.dump. For open-shell systems (or UHF FCIDUMPs), the BO-UHF energy is calculated.

Optionally, a begin...end block can be provided to set local options for this call. The options are reset after the call completes.

Examples

fcidump = "FCIDUMP"
@bohf
# with local options:
@bohf begin
  @set scf maxit=100
end

@bouhf(opts_block=nothing)

Run bi-orthogonal UHF calculation using FCIDUMP integrals.

Optionally, a begin...end block can be provided to set local options for this call. The options are reset after the call completes.

Examples

fcidump = "FCIDUMP"
@bouhf
# with local options:
@bouhf begin
  @set scf maxit=100
end

@cc(method, args...)

Run coupled cluster calculation.

The type of the method is determined by the first argument (ccsd/ccsd(t)/dcsd etc). The method can be specified as a string or as a variable, e.g., @cc CCSD or @cc "CCSD" or ccmethod="CCSD"; @cc ccmethod.

Optionally, a begin...end block can be provided as the last argument to set local options for this call. The options are reset after the call completes.

Keyword arguments

• fcidump::String: fcidump file (default: "", i.e., use integrals from EC).
• occa::String: occupied α orbitals (default: "-").
• occb::String: occupied β orbitals (default: "-").

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".

Examples

geometry="bohr
O      0.000000000    0.000000000   -0.130186067
H1     0.000000000    1.489124508    1.033245507
H2     0.000000000   -1.489124508    1.033245507"
basis = Dict("ao"=>"cc-pVDZ", "jkfit"=>"cc-pvtz-jkfit", "mpfit"=>"cc-pvdz-mpfit")
@dfhf
@dfints
@cc ccsd
# with local options:
@cc ccsd begin
  @set wf charge=-1 ms2=1
  @set cc maxit=30
end

@check_molproinfo()

Check if MolproInterface.MolproInfo is initialized and return the files. If not initialized, throw an error.

@ciphi(args...)

Run CIPHI (CIΦ - CI via Perturbative and Heat-Bath Iterative selection) calculation.

Optionally, a begin...end block can be provided as the last argument to set local options for this call. The options are reset after the call completes.

Keyword arguments

• occa::String: occupied α orbitals (default: "-").
• occb::String: occupied β orbitals (default: "-").

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".

@sci and @ciϕ are aliases for this macro.

Examples

geometry="bohr
O      0.000000000    0.000000000   -0.130186067
H1     0.000000000    1.489124508    1.033245507
H2     0.000000000   -1.489124508    1.033245507"
basis = Dict("ao"=>"6-31g", "jkfit"=>"vdz-jkfit", "mpfit"=>"vdz-mpfit")
@dfhf
@ciphi
# with local options:
@ciphi begin
  @set ciphi epsilon=1.e-4
end

@ciϕ(args...)

Alias for @ciphi.

@copyfile(from_file, to_file, kwargs...)

Copy file from_file to to_file in EC.scr directory.

Keyword arguments

• overwrite::Bool: overwrite existing file (default: false).

@copywf(to_file::AbstractString=""; start=false, state=0)

Copy wavefunction data from the current trexio dump file to another dump file.

If to_file is not provided, the wavefunction is copied to EC.options.wf.store file. Note: This does not check the contents of the files.

Keyword Arguments

• start::Bool=false: If true, copy from wf.start file instead of wf.dump.
• state::Int=0: State number for determinant files. If 0, copies the main dump file. If >0, copies the state-specific determinant file (e.g., file_state2.h5).

Examples

julia> @copywf  # copy dump to store
julia> @copywf "backup.h5"  # copy dump to backup file
julia> @copywf start=true  # copy start file to store
julia> @copywf "backup.h5" start=true  # copy start file to backup
julia> @copywf state=2  # copy state 2 determinant file to store
julia> @copywf "state2_backup.h5" state=2  # copy state 2 to specific file

@deletefile(filename)

Delete file filename from EC.scr directory.

@dfcc(method="svd-dcsd", opts_block=nothing)

Run coupled cluster calculation using density fitted integrals.

The type of the method is determined by the first argument. The method can be specified as a string or as a variable, e.g., @dfcc SVD-DCSD or @dfcc "SVD-DCSD" or ccmethod="SVD-DCSD"; @dfcc ccmethod.

Optionally, a begin...end block can be provided to set local options for this call. The options are reset after the call completes.

Examples

geometry="bohr
O      0.000000000    0.000000000   -0.130186067
H1     0.000000000    1.489124508    1.033245507
H2     0.000000000   -1.489124508    1.033245507"
basis = Dict("ao"=>"cc-pVDZ", "jkfit"=>"cc-pvtz-jkfit", "mpfit"=>"cc-pvdz-mpfit")
@dfhf
@dfcc svd-dcsd
# with local options:
@dfcc svd-dcsd begin
  @set cc maxit=30
end

@dfhf(opts_block=nothing)

Run DF-HF calculation. The orbitals are stored to WfOptions.dump.

Optionally, a begin...end block can be provided to set local options for this call. The options are reset after the call completes.

Examples

@dfhf
# with local options:
@dfhf begin
  @set scf maxit=100 thr=1.e-12
  @set wf charge=-1
end

@dfints(opts_block=nothing)

Generate 2 and 4-idx MO integrals using density fitting. The MO coefficients are read from WfOptions.dump.

These integrals PERSIST for the rest of the session and are yours to manage: because they are built from a particular set of orbitals, they become stale if the orbitals change (a re-run @dfhf, @localize, an orbital-optimized method), and re-running @dfints is what refreshes them. A correlated driver (@cc, @fci, ...) that finds no integrals creates its own from the current orbitals and deletes them again when it finishes, so it can never use a stale set — use @dfints when you deliberately want ONE generation to serve several driver calls on the same orbitals.

Optionally, a begin...end block can be provided to set local options for this call. The options are reset after the call completes.

@dfmcscf(opts_block=nothing)

Run DF-MCSCF calculation. The orbitals are stored to WfOptions.dump.

Optionally, a begin...end block can be provided to set local options for this call. The options are reset after the call completes.

Examples

@dfmcscf
# with local options:
@dfmcscf begin
  @set scf maxit=100
  @set wf active="(4,4)"
end

@dfmp2(opts_block=nothing)

Run density-fitted MP2 calculation.

If save is set in CcOptions.save, the MP2 doubles amplitudes are saved to save*"_2" file.

Optionally, a begin...end block can be provided to set local options for this call. The options are reset after the call completes.

Examples

@dfmp2
# with local options:
@dfmp2 begin
  @set cc save="mp2_amplitudes"
end

@dfuhf(opts_block=nothing)

Run DF-UHF calculation. The orbitals are stored to WfOptions.dump.

Optionally, a begin...end block can be provided to set local options for this call. The options are reset after the call completes.

Examples

@dfuhf
# with local options:
@dfuhf begin
  @set scf maxit=100
end

@dummy(atoms)

Set atoms as dummy atoms in the system. atoms is a list of atom indices or atomic symbols.

After running the macro, only the atoms in the list are set as dummy atoms in the system.

Examples

@dummy [1,2,3]
@dummy ["H1","H2"]
@dummy [1,"H2",:H3]
@dummy [] # unset all dummy atoms

@export_molden(filename)

Export current orbitals to Molden file filename.

@fci(args...)

Run FCI calculation.

Optionally, a begin...end block can be provided as the last argument to set local options for this call. The options are reset after the call completes.

Keyword arguments

• occa::String: occupied α orbitals (default: "-").
• occb::String: occupied β orbitals (default: "-").

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".

Examples

geometry="bohr
O      0.000000000    0.000000000   -0.130186067
H1     0.000000000    1.489124508    1.033245507
H2     0.000000000   -1.489124508    1.033245507"
basis = Dict("ao"=>"6-31g", "jkfit"=>"vdz-jkfit", "mpfit"=>"vdz-mpfit")
@dfhf
@fci
# with local options:
@fci begin
  @set wf charge=-1
end

@freeze_orbs(freeze_orbs)

Freeze orbitals in the integrals according to an array or range freeze_orbs.

Alternatively, the orbitals can be specified as a String with the +/- or :/; syntax, e.g., "1-5+7-8", or "1:5;7-8".

Examples

fcidump = "FCIDUMP"
@freeze_orbs 1:5
...
@ECinit
@freeze_orbs [1,2,20,21]

@hf(opts_block=nothing)

Run closed-shell Hartree-Fock from exact (non-DF) AO integrals. If the AO integral files are not on file yet, they are generated first (equivalent to calling @ints). The orbitals are stored to WfOptions.dump.

Note: if EC.fd holds (MO/FCIDUMP) integrals they are discarded (with a warning) — @hf runs on exact AO integrals, and a leftover MO dump would shadow the AO flow in subsequent correlated calculations. To run HF on existing FCIDUMP integrals, use @bohf instead.

Optionally, a begin...end block can be provided to set local options for this call. The options are reset after the call completes.

@import_matrix(filename)

Import matrix from file file.

The type of the matrix is determined automatically.

@ints(opts_block=nothing)

Generate exact (non-density-fitted) AO integrals and store them as scratch files (overlap S_AA, core Hamiltonian h_AA, and the memory-mapped 4-index ⟨μν|ρσ⟩ ao_int2). EC.fd is not used — it holds MO integrals only; MO dumps are derived from the AO files on demand. This is the non-DF AO counterpart of @dfints.

Optionally, a begin...end block can be provided to set local options for this call. The options are reset after the call completes.

@loadfile(filename)

Read file filename from EC.scr directory.

Example

fock = @loadfile("f_mm")

@loadwf(what...; start=false, state=1)

Load wavefunction data from the trexio dump file.

The arguments what can be a vector of strings, a string variable or a list of arguments specifying what to load. Possible values are:

• all: load everything available (overrides other options)
• orbital_energies: molecular orbital energies
• orbital_occupations: molecular orbital occupations
• amplitudes: restricted CC amplitudes (T1, T2)
• unrestricted_amplitudes: unrestricted CC amplitudes (T1a, T1b, T2a, T2b, T2ab)
• determinants: selected CI determinants and coefficients

The loaded data are returned as a dictionary with keys corresponding to the requested data. basis, orbitals and orbital_type are always included in the output.

Keyword Arguments

• start::Bool=false: If true, read from wf.start file instead of wf.dump
• state::Int=1: State number for determinants (1 = ground state)
• OPattern::Type=UInt64: Orbital pattern type for determinants (use UInt128 for >64 orbitals)

Examples

julia> wf = @loadwf orbital_energies orbital_occupations
julia> wf["basis"]  # basis set information
julia> wf = @loadwf ["orbital_energies", "orbital_occupations"]
julia> wf = @loadwf amplitudes  # load CC amplitudes
julia> wf = @loadwf determinants state=2  # load determinants for excited state
julia> wf = @loadwf all start=true  # load everything from start file

@localize(opts_block=nothing)

Localize the current orbitals using IBO/Pipek-Mezey/Boys (occupied) and optionally OPAO (virtual).

The orbitals are read from WfOptions.start and stored to WfOptions.store. If start or store is not specified, the orbitals are read from and/or stored back to WfOptions.dump.

Optionally, a begin...end block can be provided to set local options for this call. The options are reset after the call completes.

Options (set via @set loc)

• virtual::Bool: if true (default), also localize virtual orbitals via OPAO.
• exponent::Int: IBO exponent, 2 for Pipek-Mezey, 4 for fourth-moment (default).

Examples

@dfhf
@localize
# with local options:
@localize begin
  @set loc virtual=false exponent=2
end

@mainname(file)

Return the main name of a file, i.e. the part before the last dot and the extension.

Examples

julia> @mainname("~/test.xyz")
("test", "xyz")

@moints(opts_block=nothing)

Generate 2 and 4-idx MO integrals from exact (non-density-fitted) AO integrals. If the AO integral files are not on file yet, they are generated first (equivalent to calling @ints). The MO coefficients are read from WfOptions.dump. This is the non-DF counterpart of @dfints.

As in @dfints, the dump covers the active space: the frozen core is folded into the one-electron integrals and the core energy, and deleted/frozen virtuals are left out (wf.freeze_nocc=0 keeps the core in the dump).

These integrals PERSIST for the rest of the session and are yours to manage: because they are built from a particular set of orbitals, they become stale if the orbitals change (a re-run @hf, @localize, an orbital-optimized method), and re-running @moints is what refreshes them. Use it when the MO integrals themselves are the point — to write them out with @write_ints, or to have ONE generation serve several driver calls on the same orbitals:

@hf
@moints
@write_ints "FCIDUMP"
@cc ccsd

Note that a correlated method that can run AO-direct (MP2/CCSD/DCSD and friends) is faster without @moints: it contracts the AO integrals directly and never forms the MO integrals.

Optionally, a begin...end block can be provided to set local options for this call. The options are reset after the call completes.

@molpro_input(filename="elemcoil")

Initialize the Molpro interface with the given filename.

It relies on the Molpro XML file to set up the molecule and basis set. If the basis variable exists, it will be updated with the AO basis set from the XML file.

See MolproInterface for more details on the Molpro interface.

@molpro_output(ecvariables, kwargs...)

Save key-value pairs from ecvariables to a ECVARIABLES file in the MolproInterface.MolproInfo object.

The ecvariables is a dictionary with the variables to be included in the output. The keyword arguments are passed to the MolproInterface.save_ecvariables_to_file function. Possible keyword arguments include:

• prefix::String: prefix for each variable in the output file (default: "")
• new::Bool: if true, create a new file, otherwise append to the existing file (default: true)

@opt(opt, kwargs...)

Alias for @set.

@print_input(print_init=false)

Print the input file content.

Can be used to print the input file content to the output.

@region(centers=nothing, opts_block=nothing)

Build a region-tagged orbital dump from localized occupied orbitals and fragment OPAOs.

centers is an optional list of atom indices or center labels. When omitted, the requested centers are taken from region.inclusive_centers and region.exclusive_centers. The macro reads orbitals from WfOptions.start when provided, otherwise from WfOptions.dump, and writes the tagged result to WfOptions.store if set, otherwise back to the main dump.

Optionally, a begin...end block can be provided to set local region or loc options for this call.

Examples

@region [1, 2]
@region [:O, :H1] begin
  @set region mode=:exclusive occ_charge_thr=0.25 atom_charge_thr=0.15
end
@region [:C1, :C2, :C3, :C4] begin
  @set region pi=:both pi_occupied=1 pi_virtual=1
end
@region begin
  @set region inclusive_centers=[2] exclusive_centers=[1]
end

@reset(opt)

Reset options for opt to default values.

@rotate_orbs(orb1, orb2, angle, kwargs...)

Rotate orbitals orb1 and orb2 from WfOptions.dump by angle (in degrees). For UHF, spin can be :α or :β (keyword argument).

The orbitals are stored to WfOptions.store.

Keyword arguments

• spin::Symbol: spin of the orbitals (default: :α).

Examples

@dfhf
# swap orbitals 1 and 2
@rotate_orbs 1, 2, 90

general runner

@savefile(filename, arr, kwargs...)

Save array or tuple of arrays arr to file filename in EC.scr directory.

Keyword arguments

• description::String: description of the file (default: "tmp").
• overwrite::Bool: overwrite existing file (default: false).

@savewf(wf::AbstractDict; state=1)

Save wavefunction data to the trexio dump file.

The argument wf is a dictionary with the data to be saved. Possible keys are:

Orbital data:

• "basis": basis set information
• "orbitals": molecular orbitals
• "rotations": orbital rotations (alternative to "orbitals")
• "orbital_type": type of the orbitals (e.g., "RHF", "UHF", "ROHF", "MCSCF")
• "orbital_energies": molecular orbital energies
• "orbital_occupations": molecular orbital occupations

Restricted CC amplitudes:

• "T1": singles amplitudes (nvirt × nocc)
• "T2": doubles amplitudes (nvirt × nvirt × nocc × nocc)

Unrestricted CC amplitudes:

• "T1a", "T1b": α and β singles amplitudes
• "T2a", "T2b", "T2ab": αα, ββ, and αβ doubles amplitudes

Selected CI (CIPHI) data:

• "determinants": vector of determinants
• "ci_coefficients": CI coefficients (vector for single state, matrix for multi-state)

Keyword Arguments

• state::Int=1: State number for determinants (used when ci_coefficients is a vector)

Examples

julia> wf = @loadwf orbital_energies orbital_occupations
julia> orbs = wf["orbitals"]
[...]
julia> wf1 = Dict("basis"=>wf["basis"], "orbitals"=>orbs, "orbital_type"=>"modified RHF") 
julia> @savewf wf1

julia> # Save amplitudes
julia> @savewf Dict("T1"=>T1, "T2"=>T2)

julia> # Save determinants for excited state
julia> @savewf Dict("determinants"=>dets, "ci_coefficients"=>coeffs) state=2

@sci(args...)

Alias for @ciphi.

@set(opt, kwargs...)

Set options for EC::ECInfo.

The first argument opt is the name of the option (e.g., scf, cc, cholesky), see ECInfos.Options. The keyword arguments are the options to be set (e.g., thr=1.e-14, maxit=10). The current state of the options can be stored in a variable, e.g., opt_cc = @set cc. The state can then be restored by @set cc opt_cc. If EC is not already initialized, it will be done.

Examples

optscf = @set scf thr=1.e-14 maxit=10
@set cc maxit=100
...
@set scf optscf

@set_default_eltype(T)

Set the default element type for new ECInfo objects.

Examples

@set_default_eltype ComplexF64
@ECinit  # will create ECInfo{ComplexF64}

@setupEC()

Setup EC::ECInfo with geometry, basis, and fcidump if defined.

@show_orbs(range=nothing)

Show orbitals in the integrals according to an array or range range.

Examples

@dfhf
@show_orbs 1:5

@transform_ints()

Rotate FCIDump integrals using rotations from WfOptions.dump as transformation matrices.

The orbital rotations are read from WfOptions.dump. If type of the rotations contains the word biorthogonal, the bi-orthogonal orbitals are used.

@tryECinit()

If EC::ECInfo is not yet initialized, run @ECinit macro.

@uhf(opts_block=nothing)

Run unrestricted Hartree-Fock from exact (non-DF) AO integrals. If the AO integral files are not on file yet, they are generated first (equivalent to calling @ints). The orbitals are stored to WfOptions.dump.

Note: if EC.fd holds (MO/FCIDUMP) integrals they are discarded (with a warning) — @uhf runs on exact AO integrals, and a leftover MO dump would shadow the AO flow in subsequent correlated calculations. To run UHF on existing FCIDUMP integrals, use @bouhf instead.

Optionally, a begin...end block can be provided to set local options for this call. The options are reset after the call completes.

@usewf(from_file::AbstractString=""; start=false, state=0)

Copy wavefunction data to the current trexio dump file from another dump file, i.e., it does the opposite of @copywf.

If from_file is not provided, the wavefunction is copied from EC.options.wf.store file. Note: This does not check the contents of the files.

Keyword Arguments

• start::Bool=false: If true, copy to wf.start file instead of wf.dump.
• state::Int=0: State number for determinant files. If 0, copies to the main dump file. If >0, copies to the state-specific determinant file (e.g., file_state2.h5).

Examples

julia> @usewf  # copy store to dump
julia> @usewf "backup.h5"  # copy from backup file to dump
julia> @usewf start=true  # copy store to start file
julia> @usewf "backup.h5" start=true  # copy backup file to start file
julia> @usewf state=2  # copy store file to state 2 determinant file
julia> @usewf "state2_backup.h5" state=2  # copy specific file to state 2

@write_ints(file="FCIDUMP", kwargs...)

Write FCIDump integrals to file file, which can be a string literal or a variable holding one.

The integrals must persist in EC.fd: create them explicitly with @dfints or @moints, or read an FCIDUMP — the integrals a correlated driver creates for itself are deleted again when it finishes.

The written file is self-contained: its NELEC (and MS2) describe the system as currently set up, i.e. with WfOptions.charge applied. Reading such a file back therefore needs no charge — and setting one would ionize it further, since wf.charge is always relative to the electron count of the integral source.

Keyword arguments

• tol::Float64: tolerance for writing integrals (default: -1.0 - all integrals are written).
• format::Symbol: format for writing integrals (default: :ascii). Can be :npy for NumPy format.

__init__()

Print the header with the version and the git hash of the current commit.