# Orbital equations

## Hamiltonian

`AtomicStructure.OrbitalHamiltonianTerm`

— Type`OrbitalHamiltonianTerm(i, j, coeff, A, integrals)`

Represents a term in the orbital Hamiltonian arising from a variation of the energy expressions between configurations `i`

and `j`

in the multi-configurational expansion. `coeff`

is the numeric coefficient, `A`

is the operator acting on the orbital, and `integrals`

is a vector of `OrbitalIntegral`

s arising from the presence of non-orthogonal orbitals and whose values should be multiplied to form the overall coefficient.

`AtomicStructure.coefficient`

— Function`coefficient(term::OrbitalHamiltonianTerm)`

Return the multiplicative coefficient pertaining to `term`

, *excluding* the `conj(c_i)*c_j`

mixing coefficients, due to the configuration-interaction.

`coefficient(term::OrbitalHamiltonianTerm, c::Vector)`

Return the multiplicative coefficient pertaining to `term`

, *including* the `conj(c_i)*c_j`

mixing coefficients, due to the configuration-interaction.

`AtomicStructure.OrbitalHamiltonian`

— Type`OrbitalHamiltonian(R, terms, mix_coeffs, projector, orbital)`

The Hamiltonian for `orbital`

is constructed from a radial basis `R`

, a set of `OrbitalHamiltonianTerm`

`terms`

that describe the various interactions between orbitals, `mix_coeffs`

which are the mixing coefficents for the multi-configurational expansion. The `projector`

ensures orthogonality between orbital pairs which have Lagrange multipliers associated with them, by projecting out components of other orbitals every time the `OrbitalHamiltonian`

action on `orbital`

is computed.

`AtomicStructure.Projector`

— Type`Projector(ϕs, orbitals, S)`

Represents the projector on the subspace spanned by the radial orbitals `ϕs`

(corresponding to `orbitals`

).

`AtomicStructure.projectout!`

— Function`projectout!(y, projector)`

Project out all components of `y`

parallel to the radial orbitals `projector.ϕs`

.

`AtomicStructure.SCF.energy_matrix!`

— Method`energy_matrix!(H, hamiltonian, ϕ)`

Compute the contribution of `hamiltonian`

to the Hamiltonian matrix `H`

by repeatedly acting on the associated radial orbital `ϕ`

with the different multi-configurational `OrbitalHamiltonianTerm`

s of `hamiltonian`

.

`Base.filter`

— Method`filter(fun::Function, H::OrbitalHamiltonian)`

Filter the `OrbitalHamiltonianTerm`

s of `H`

according to the predicate `fun`

.

`Base.copyto!`

— Method`copyto!(dest::AbstractMatix, hamiltonian::OrbitalHamiltonian)`

Materialize the orbital `hamiltonian`

into matrix form and store it in `dest`

, using the current values of all other orbitals. This is only possible if the orbital `hamiltonian`

does *not* contain any `ExchangePotential`

s or `SourceTerm`

s (which are not diagonal in orbital space), since the former is non-local (and thus not representable as a matrix) and the latter is not a linear operator (but an affine one).

Typical usage is to compute an easily factorizable matrix that can be used for preconditioning the solution of the full equation.

`Base.:+`

— Method`h::OrbitalHamiltonian + λ::UniformScaling`

Shift the `OrbitalHamiltonian`

`h`

by `λ`

.

`Base.:-`

— Method`h::OrbitalHamiltonian - λ::UniformScaling`

Shift the `OrbitalHamiltonian`

`h`

by `-λ`

.

`AtomicStructure.SCF.KrylovWrapper`

— Type`KrylovWrapper(hamiltonian)`

Proxy object used in the Krylov iterations, during orbital improvement. This is useful, since `hamiltonian`

may be defined to act on objects such as vectors living in function spaces (as e.g. implemented using ContinuumArrays.jl), whereas the SCF iterations act on the coefficients directly.

Missing docstring for `LinearAlgebra.mul!(y::V₁, A::KrylovWrapper{T,Hamiltonian}, x::V₂) where {V₁,V₂,T,B,Hamiltonian<:OrbitalHamiltonian}`

. Check Documenter's build log for details.

## Orbital integrals and terms

`AtomicStructure.OrbitalIntegral`

— Type`OrbitalIntegral{N}`

Abstract type for integrals of rank `N`

of orbitals, whose values need to be recomputed every time the orbitals are updated. Rank 0 corresponds to a scalar value, rank 1 to a diagonal matrix, etc.

`AtomicStructure.OrbitalOverlapIntegral`

— Type`OrbitalOverlapIntegral(a, b, av, bv, value)`

Represents the orbital overlap integral `⟨a|b⟩`

, for orbitals `a`

and `b`

, along with `view`

s of their radial orbitals `av`

and `bv`

and the current `value`

of the integral.

`AtomicStructure.SCF.update!`

— Method`SCF.update!(oo::OrbitalOverlapIntegral)`

Update the value of the integral `oo`

.

`AtomicStructure.HFPotential`

— Type`HFPotential(k, a, b, av, bv, V̂, poisson)`

Represents the `k`

:th multipole exansion of the Hartree–Fock potential formed by orbitals `a`

and `b`

(`av`

and `bv`

being `view`

s of their corresponding radial orbitals). `V̂`

is the resultant one-body potential formed, which can act on a third orbital and `poisson`

computes the potential by solving Poisson's problem.

`AtomicStructure.DirectPotential`

— Type`DirectPotential`

Special case of `HFPotential`

for the direct interaction, in which case the potential formed from two orbitals can be precomputed before acting on a third orbital.

`AtomicStructure.SCF.update!`

— Method`update!(eqs; kwargs...)`

Update the equation system `eqs`

, for the current iteration. *To be overloaded by the user.*

`SCF.update!(p::DirectPotential)`

Update the direct potential `p`

by solving the Poisson problem with the current values of the orbitals forming the mutual density.

`Base.Broadcast.materialize!`

— Method`materialize!(::MulAdd{<:Any, <:Any, <:Any, T, <:AtomicOneBodyHamiltonian, Source, Dest})`

Materialize the lazy multiplication–addition of the type `y ← α*H*x + β*y`

where `H`

is a `AtomicOneBodyHamiltonian`

and `x`

and `y`

are `RadialOrbital`

s.

`AtomicStructure.ExchangePotential`

— Type`ExchangePotential`

Special case of `HFPotential`

for the exchange interaction, in which case the potential is formed from the orbital acted upon, along with another orbital, and then applied to a third orbital. Thus this potential *cannot* be precomputed, but must be recomputed every time the operator is applied. This makes this potential expensive to handle and the number of times it is applied should be minimized, if possible.

`Base.Broadcast.materialize!`

— Method`materialize!(::MulAdd{<:Any, <:Any, <:Any, T, <:AtomicOneBodyHamiltonian, Source, Dest})`

Materialize the lazy multiplication–addition of the type `y ← α*H*x + β*y`

where `H`

is a `AtomicOneBodyHamiltonian`

and `x`

and `y`

are `RadialOrbital`

s.

`AtomicStructure.SourceTerm`

— Type`SourceTerm(operator, source_orbital, ov)`

The point of `SourceTerm`

is to implement inhomogeneous terms that contribute to the equation for an orbital, and whose input is some other `source_orbital`

. This kind of term appears in multi-configurational problems.

`AtomicStructure.ShiftTerm`

— Type`ShiftTerm(λ)`

The point of `ShiftTerm`

is to implement an overall energy shift of the Hamiltonian.

## Orbital equations

`AtomicStructure.AtomicOrbitalEquation`

— Type`AtomicOrbitalEquation(atom, equation, orbital, ϕ, hamiltonian)`

Governs the evolution of an atomic `orbital`

belonging to an `atom`

. `equation`

is the symbolic expression, from which `hamiltonian`

is constructed. `ϕ`

is the `QuasiVector`

representing the radial orbital.

`AtomicStructure.SCF.energy`

— Function`SCF.energy(hfeq::AtomicOrbitalEquation[, which=:total])`

Compute the orbital energy for the orbital governed by `hfeq`

. Optionally select which contribution is computed (`:total`

, `:onebody`

, `:direct`

, or `:exchange`

).