Core Types

ParamFreeFunc{F<:Function} <: CompositeFunction

A direct wrapper struct for f::F that does not have reachable Quiqbox.ParamBox through reflection functions.

≡≡≡ Property/Properties ≡≡≡

f::F: Stored function. noStoredParam(f) must return true when it is used to construct a instance of ParamFreeFunc{F}.

≡≡≡ Initialization Method(s) ≡≡≡

ParamFreeFunc(f::F) where {F<:Function} -> ParamFreeFunc{T}

HFconfig{R<:Real, T<:Union{Complex{T}, T} where T<:Real{R}, HFT<:Union{RCHartreeFock, UOHartreeFock}, 
         CM<:Quiqbox.OrbCoeffInitialConfig{T, HFT}, SCFM<:SCFconfig, S} <: Quiqbox.ConfigBox

The container of a Hartree–Fock method's configuration.

≡≡≡ Property/Properties ≡≡≡

type::HFT: Hartree–Fock method type. Available types are (RCHartreeFock, UOHartreeFock) ("Restricted closed-shell (RHF)", "Unrestricted open-shell (UHF)").

initial::CM: Initial guess of the orbital coefficient matrix/matrices of the canonical orbitals. When initial is as an argument of HFconfig's constructor, it can be set to sym::Symbol where available values of sym are (:Direct, :CoreH, :GWH, :SAD).

strategy::SCFM: SCF iteration strategy. For more information please refer to SCFconfig.

maxStep::Int: Maximum iteration steps allowed regardless if the iteration converges.

earlyStop::Bool: Whether automatically terminate (or skip) a convergence method early when its performance becomes unstable or poor.

saveTrace::NTuple{4, Bool}: Determine whether saving (by pushing) the intermediate information from all the iterations steps to the field .temp of the output HFfinalInfo of runHartreeFock. The types of relevant information are:

≡≡≡ Initialization Method(s) ≡≡≡

HFconfig(::Type{T}, type::HFT=RCHartreeFock(); 
         initial::Union{Quiqbox.OrbCoeffInitialConfig{T}, Symbol}=:SAD, 
         strategy::SCFconfig=SCFconfig(), 
         maxStep::Int=200, earlyStop::Bool=true, 
         saveTrace::NTuple{4, Bool}=(false, false, false, true)) where 
        {R, T<:RealOrComplex{R}, HFT<:Union{RCHartreeFock, UOHartreeFock}} -> 
HFconfig{R, T, HFT}

≡≡≡ Initialization Example(s) ≡≡≡

julia> HFconfig(Float64, UOHartreeFock());

HFfinalInfo{R<:Real, D, T<:Union{Complex{T}, T} where T<:Real{R}, HFT<:Union{RCHartreeFock, UOHartreeFock}, HFTS, 
            B<:Quiqbox.MultiOrbitalData{R, D, T}} <: StateBox{T}

The container of the final values after a Hartree–Fock SCF procedure. HFTS specifies the number of distinct data sectors corresponding to the specified spin configurations. For restricted closed-shell Hartree–Fock (RHF), HFTS is 1.

≡≡≡ Property/Properties ≡≡≡ @NamedTuple{spin::Quiqbox.OccupationState{2}, geometry::NuclearCluster{R, T}}: The spin and nuclear-geometry configurations of the target system. .spin specifies numbers of electrons in two orthonormal spin configurations (e.g., spin-up vs. spin-down). For any property data (::P) enclosed in NTuple{HFTS, P} and HFTS==2, each element correspond to one spin configuration.

energy::NTuple{2, R}: The electronic and nuclear (repulsion potential) parts of the target system's ground-state energy under the Hartree–Fock and the Born–Oppenheimer approximation.

coeff::NTuple{HFTS, MatrixMemory{T}}: Distinct orbital coefficient matrix/matrices.

density::NTuple{HFTS, MatrixMemory{T}}: Distinct one-electron density matrix/matrices.

fock::NTuple{HFTS, MatrixMemory{T}}: Distinct Fock matrix/matrices.

occu::NTuple{HFTS, Quiqbox.MemoryPair{ R, NTuple{2, Bool} }}: The spin occupations of distinct canonical (spatial) orbitals and their corresponding orbital energies.

memory::NTuple{HFTS, Quiqbox.HFtempInfo{R, T, HFT}}: the intermediate data stored during the Hartree–Fock SCF (self-consistent field) interactions. (NOTE: The interface of Quiqbox.HFtempInfo is internal and subject to BREAKING CHANGES.)

converged::Union{Bool, Missing}: Whether the SCF iteration is converged in the end. When convergence detection is off (see SCFconfig), it is set to missing.

basis::B: The orbital basis-set data used for the Hartree–Fock SCF computation.

SCFconfig{T<:Real, L, MS<:NTuple{L, Val}} <: Quiqbox.ConfigBox

The conatiner to configure the self-consistent field (SCF) iteration strategy for Hartree–Fock computation.

≡≡≡ Property/Properties ≡≡≡

method::MS: The applied convergence methods. The parameters S::Symbol in each Val{S} specifies a SCF ietration method. The available methods their corresponding supported keyword arguments are:

¹ The reset threshold (resetThreshold::Real) determines when to clear the memory of the DIIS-based method's subspace and reset the second-to-latest residual vector as the first reference. The reset is executed when the latest computed energy increases an amount above the threshold compared to the second-to-latest computed energy. In default, the threshold is slightly larger than the machine epsilon of the numerical data type applied to the SCF computation.

Convergence Methods

• :DD: Direct diagonalization of the Fock matrix.
• :DIIS: Direct inversion in the iterative subspace.
• :EDIIS: Energy-DIIS.
• :ADIIS: DIIS based on the augmented Roothaan–Hall (ARH) energy function.

DIIS-Method Solvers

• :LBFGS: Limited-memory BFGS with box constraints.
• :LCM: Lagrange multiplier solver.
• :SPGB: Spectral Projected Gradient Method with box constraints.

interval::NTuple{L, T}: The stopping (or skipping) thresholds for required methods. The last threshold will be the convergence threshold for the SCF procedure. When the last threshold is set to NaN, there will be no convergence detection.

methodConfig::NTuple{L, Memory{ <:Pair{Symbol} }}: The additional keywords arguments for each method stored as Tuples of Pairs.

secondaryConvRatio::NTuple{2, T}: The ratios of the secondary convergence criteria to the primary convergence indicator, i.e., the change of the energy (ΔE):

oscillateThreshold::T: The threshold for oscillatory convergence.

≡≡≡ Initialization Method(s) ≡≡≡

SCFconfig(methods::NTuple{L, Symbol}, intervals::NTuple{L, T}, 
          config::AbstractDict{Int64, <:AbstractVector{<:Pair{Symbol}}}=Quiqbox.EmptyDict{Int, Vector{ Pair{Symbol} }}(); 
          secondaryConvRatio::Union{Real, NTuple{2, Real}}=
          T.((1000, 1000)), oscillateThreshold::Real=
          T(5.0e-6)) where {L, T<:AbstractFloat} -> 
SCFconfig{T, L}

methods and intervals are the convergence methods to be applied and their stopping (or skipping) thresholds respectively. config specifies additional keyword argument(s) for each methods by a Pair{Symbol} of which the key i::Int is for ith method and the pointed AbstractVector{<:Pair} is the pairs of keyword arguments and their values respectively. If secondaryConvRatio is AbstractFloat, it will be assigned as the value for all the secondary convergence ratios.

SCFconfig(;threshold::AbstractFloat=1.0e-9, 
          secondaryConvRatio::Union{Real, NTuple{2, Real}}=(1000, 1000), 
          oscillateThreshold::Real=5.0e-6) -> 
SCFconfig{Float64, 3}

threshold will replace the stopping threshold of the default SCF configuration with a new value.

≡≡≡ Example(s) ≡≡≡

julia> SCFconfig((:DD, :ADIIS, :DIIS), (1e-4, 1e-12, 1e-13), Dict(2=>[:solver=>:LCM]));

julia> SCFconfig(threshold=1e-8, oscillateThreshold=1e-5)
SCFconfig{Float64, 3, Tuple{Val{:DD}, Val{:ADIIS}, Val{:DIIS}}}((Val{:DD}(), Val{:ADIIS}(), Val{:DIIS}()), (0.005, 0.0001, 1.0e-8), (Pair{Symbol}[], Pair{Symbol}[], Pair{Symbol}[]), (1000.0, 1000.0), 1.0e-5)