EnergyEvaluation

module EnergyEvaluation

Structs and functions relating to the calculation of energy. Includes both low and high level functions from individual PES calculations to state-specific functions. The structure is as follows:

• Define abstract potential and potential_variables
• Define PES functions
  • DimerPotential
  • ELJB
  • Embedded Atom Model
  • Machine Learning Potentials
• EnergyUpdate function
  • Calculates a new energy based on a trialpos for each PES type
• InitialiseEnergy function
  • Calculates potentialvariables and total energy from a new config to be used when initialising MCStates
• SetVariables function
  • Initialises the potential variables, aka creates a blank version of the struct for each type of PES

AbstractDimerPotential <: AbstractPotential

Implemented dimer potentials:

• ELJPotential
• ELJPotentialEven

Needs methods for

• dimer_energy_atom
• dimer_energy_config

AbstractDimerPotentialB <: AbstractPotential

Implemented dimer potentials:

• ELJPotentialB

AbstractMachineLearningPotential <: AbstractPotential

Abstract type for all Machine Learning Potentials.

AbstractPotential

Abstract type for possible potentials. implemented subtype:

• AbstractDimerPotential
• AbstractDimerPotentialB
• EmbeddedAtomPotential
• AbstractMachineLearningPotential

When defining a new type, the functions relating a potential to the rest of the Monte Carlo code are explicated at the end of this file. Each potential also requires a PotentialVariable AbstractPotentialVariables struct to hold all non-static information relating a potential to the current configuration.

Needs method for:

• energy_update!
• initialise_energy
• set_variables

AbstractPotentialVariables

An abstract type defining a class of mutable struct containing all the relevant vectors and arrays each potential will need throughout the course of a simulation to prevent over-definitions inside the MCState struct. Implemented subtypes:

• DimerPotentialVariables
• ELJPotentialBVariables
• EmbeddedAtomVariables
• NNPVariables

DimerPotentialVariables

The struct contains only the en_atom_vec::Vector{T}, particular special features for this potential type. This vector is the energy per atom in the system.

ELJPotential{N,T}

Implements type for extended Lennard Jones potential; subtype of AbstractDimerPotential<:AbstractPotential; as sum over c_i r^(-i), starting with i=6 up to i=N+6 field name: coeff::SVector{N,T} : contains ELJ coefficients c_i from i=6 to i=N+6, coefficient for every power needed. Constructors: ELJPotential{N}(c::VorS) where N ELJPotential(c::VorS)

ELJPotentialB{N,T}

Extended Lennard-Jones Potential in a magnetic field where there is anisotropy in the coefficient vectors coeff_a::SVector{N,T}, coeff_b::SVector{N,T}, coeff_c::SVector{N,T}. Constructors: ELJPotentialB{N}(a::VorS, b::VorS, c::VorS) where N ELJPotentialB(a::VorS, b::VorS, c::VorS)

ELJPotentialBVariables{T}

Contains the en_atom_vec::Array{T}, tan_mat::Matrix{T} and new_tan_vec::Vector{T} for the ELJPotentialB potential.

ELJPotentialEven{N,T}

Implements type for extended Lennard Jones potential with only even powers; subtype of AbstractDimerPotential<:AbstractPotential; as sum over c_i r^(-i), starting with i=6 up to i=N+6 with only even integers i field name: coeff::SVector{N,T} : contains ELJ coefficients c_i from i=6 to i=N+6 in steps of 2, coefficient for every even power needed. Constructors: ELJPotentialEven{N}(c::VorS) where N ELJPotentialEven(c::VorS)

EmbeddedAtomPotential

Struct containing the important quantities for calculating EAM (specifically Sutton-Chen type) potentials.

• Fields:
  • n::Float64 the exponent for the two-body repulsive ϕ component
  • m::Float64 the exponent for the embedded electron density ρ
  • ean::Float64 multiplicative factor ϵa^n /2 for ϕ
  • eCam::Float64 multiplicative factor ϵCa^(m/2) for ρ

EmbeddedAtomPotential(n::Number,m::Number,ϵ::Number,C::Number,a::Number)

Function to initalise the EAM struct given the actual constants cited in papers. The exponents n,m, the energy constant ϵ the distance constant a standard in all EAM models, and a dimensionless parameter C scaling ρ with respect to ϕ.

EmbeddedAtomVariables{T}

Contains the component_vector::Matrix{T} and new_component_vector::Matrix{T} for the EAM potential.

NNPVariables{T}

Bundle of variables used for the NNP potential:

• en_atom_vec::Vector{T} – the per-atom energy vector
• new_en_atom::Vector{T} – the new per-atom energy vector
• g_matrix::Matrix{T} – the G matrix
• f_matrix::Matrix{T} – the F matrix
• new_g_matrix::Matrix{T} – the new G matrix
• new_f_vec::Vector{T} – the new F vector

Todo: someone who knows what these are should write a better description

NNPVariables2a{T,Na,Ng} <: AbstractPotentialVariables
T  variable type, usually Float64 
Na number of atoms
Ng number of symmetry functions

Mutable parameters relevant to a 2 atom NNP using the RuNNer Package. fields include: -enatomvec: atomic energy corresponding to config -newenatom: after an atom move, the new atomic energy -gmatrix: matrix of symmetry values, length NgxNa -fmatrix: matrix of cutoff function values aor atom pairs i,j -newgmatrix: after atom move, new symmetry values -newfvec: after atom move, new cutoff values

RuNNerPotential <: AbstractMachineLearningPotential

Contains the important structs required for a neural network potential defined in the MachineLearningPotential package:

• Fields are:
  • nnp::NeuralNetworkPotential – a struct containing the weights, biases and neural network parameters.
  • radsymfunctions::StructVector{RadialType2{Float64}} – a vector containing the hyperparameters used to calculate symmetry function values
  • angsymfunctions::StructVector{AngularType3{Float64}} – a vector containing the hyperparameters used to calculate symmetry function values
  • r_cut::Float64 – every symmetry function has an r_cut, but saving it here saves annoying memory unpacking

RuNNerPotential(nnp::NeuralNetworkPotential,radsymvec::VorS,angsymvec::VorS)

RuNNerPotential constructor/initializer function, given a neural network potential nnp and the symmetry functions radsymvec,angsymvec and the cutoff radius r_cut.

RuNNerPotential2Atom <: AbstractMachineLearningPotential

Contains the important structs required for a neural network potential defined in the MachineLearningPotential package for a 2 atom system: Fields are: nnp# – structs containing the weights, biases and neural network parameters. symmetryfunctions – a vector containing the hyperparameters used to calculate symmetry function values rcut – every symmetry function has an rcut, but saving it here saves annoying memory unpacking

calc_components(componentvec::VorS,distancevec::VorS,n::Number,m::Number)
calc_components(new_component_vec::Matrix{Float64},atomindex::Int,old_r2_vec::VorS,new_r2_vec::VorS,n::Number,m::Number)
calc_components(component_vec::Matrix{Float64},new_component_vec::Matrix{Float64},atomindex::Int,old_r2_vec::VorS,new_r2_vec::VorS,n::Number,m::Number)

Primary calculation of ϕ,ρ for atom i, given each other atom's distance to i in distancevec. eatomvec stores the ϕ and ρ components.

Second method also includes an existing new_component_vec atomindex and old and new interatomic distances from an atom at atomindex stored in vectors new_r2_vec,old_r2_vec. This calculates the new_component_vec based on the updated distances and returns this.

calc_new_runner_energy!(potential_variables::NNPVariables,pot::RuNNerPotential)

Function designed to calculate the new per-atom energy according to the RuNNer forward pass with parameters defined in pot. utilises the new_g_matrix to redefine the new_en and new_en_atom variables within the potential_variables struct.

calc_new_runner_energy!(potential_variables::NNPVariables2a{T,Na,Ng},pot::RuNNerPotential2Atom{Nrad,Nang,N1,N2}) where {T,Na,Ng} where {Nrad,Nang,N1,N2}

Function to calculate the energy of a new configuration after an atom move. Accepts the potentialvariables struct and runs a forward pass on the newg_matrix. Returns the new energy.

dimer_energy(pot::ELJPotential{N}, r2::Number) where N
dimer_energy(pot::ELJPotentialEven{N}, r2::Number) where N
dimer_energy(pot::ELJPotentialB{N}, r2::Number, z_angle::Number) where N

Calculates energy of dimer for given potential pot and squared distance r2 between atoms Methods implemented for:

• ELJPotential

• ELJPotentialEven

Dimer energy when the distance square between two atom is r2 and the angle between the line connecting them and z-direction is z_angle. When r2 < 5.30, returns 1.

dimer_energy_atom(i::Int, d2vec::VorS, pot::AbstractDimerPotential)
dimer_energy_atom(i::Int, d2vec::VorS, r_cut::Number, pot::AbstractDimerPotential)
dimer_energy_atom(i::Int, d2vec::VorS, tanvec::VorS,pot::AbstractDimerPotentialB)
dimer_energy_atom(i::Int, d2vec::VorS, tanvec::VorS, r_cut::Number, pot::AbstractDimerPotentialB)

Sums the dimer energies for atom i with all other atoms Needs vector of squared distances d2vec between atom i and all other atoms in configuration See get_distance2_mat and potential information pot AbstractPotential

Second method includes additional variable r_cut to exclude distances outside the cutoff radius of the potential.

Final two methods relate to the use of magnetic field potentials such as the ELJB potential.

dimer_energy_config(distmat::Matrix{Float64}, NAtoms::Int, potential_variables::DimerPotentialVariables, pot::AbstractDimerPotential)
dimer_energy_config(distmat::Matrix{Float64}, NAtoms::Int, potential_variables::DimerPotentialVariables, r_cut::Number, bc::CubicBC, pot::AbstractDimerPotential)
dimer_energy_config(distmat::Matrix{Float64}, NAtoms::Int, potential_variables::DimerPotentialVariables, r_cut::Number, bc::RhombicBC, pot::AbstractDimerPotential)
dimer_energy_config(distmat::Matrix{Float64}, NAtoms::Int, potential_variables::ELJPotentialBVariables, pot::AbstractDimerPotentialB)
dimer_energy_config(distmat::Matrix{Float64}, NAtoms::Int, potential_variables::ELJPotentialBVariables, r_cut::Number, bc::CubicBC, pot::AbstractDimerPotentialB)

Stores the total of dimer energies of one atom with all other atoms in vector and calculates total energy of configuration.

First two methods are for standard dimer potentials, one with a cutoff radius, one without a cutoff radius. The final two methods are for the same calculation using a magnetic potential such as the ELJB potential.

Needs squared distances matrix, see get_distance2_mat and potential information pot AbstractPotential

dimer_energy_update!(index::Int,dist2_mat::Matrix{Float64},new_dist2_vec::VorS,en_tot::Float64,pot::AbstractDimerPotential)
dimer_energy_update!(index::Int,dist2_mat::Matrix{Float64},new_dist2_vec::VorS,en_tot::Float64,r_cut::Number,pot::AbstractDimerPotential)
dimer_energy_update!(index::Int,dist2_mat::Matrix{Float64},tanmat::Matrix{Float64},new_dist2_vec::VorS,new_tan_vec::VorS,en_tot::Float64,pot::AbstractDimerPotentialB)
dimer_energy_update!(index::Int,dist2_mat::Matrix{Float64},tanmat::Matrix{Float64},new_dist2_vec::VorS,new_tan_vec::VorS,en_tot::Float64,r_cut::Number,pot::AbstractDimerPotentialB)

dimer_energy_update is the potential-level-call where for a single mc_state we take the new position pos, for atom at index , inside the current config , where the interatomic distances dist2_mat and the new vector based on the new position new_dist2_vec; these use the potential to calculate a deltaenergy and modify the current `entot`. These quantities are modified in place and returned.

Final two methods are for use with a dimer potential in a magnetic field, where there is anisotropy in the coefficients.

energy_update!(ensemblevariables::Etype, config::Config, potential_variables, dist2_mat, new_dist2_vec, en_tot, pot::AbstractDimerPotential) where Etype <: NVTVariables
energy_update!(ensemblevariables::Etype, config::Config, potential_variables, dist2_mat, new_dist2_vec, en_tot, pot::AbstractDimerPotential) where Etype <: NPTVariables
energy_update!(ensemblevariables::Etype, config::Config, potential_variables::ELJPotentialBVariables, dist2_mat, new_dist2_vec, en_tot, pot::AbstractDimerPotentialB) where Etype <: NVTVariables
energy_update!(ensemblevariables::Etype, config::Config, potential_variables::ELJPotentialBVariables, dist2_mat, new_dist2_vec, en_tot, pot::AbstractDimerPotentialB) where Etype <: NPTVariables
energy_update!(ensemblevariables::Etype, config::Config, potential_variables::EmbeddedAtomVariables, dist2_mat, new_dist2_vec, en_tot, pot::EmbeddedAtomPotential) where Etype <: AbstractEnsembleVariables
energy_update!(ensemblevariables::Etype, config::Config, potential_variables::NNPVariables, dist2_mat, new_dist2_vec, en_tot, pot::RuNNerPotential) where Etype <: AbstractEnsembleVariables
energy_update!(ensemblevariables::Etype, config::Config, potential_variables::NNPVariables2a, dist2_mat, new_dist2_vec, en_tot, pot::RuNNerPotential2Atom) where Etype <: AbstractEnsembleVariables

Energy update function for use within a cycle. at the top level this is called with the new position trial_pos which is the index-th atom in the config it operates on the potential_variables along with the dist2_mat. Using pot the potential to find the new_en.

Has additional methods including r_cut where appropriate for use with periodic boundary conditions.

This function is designed as a curry function. The generic get_energy! function operates on a vector of states, this function takes each state and the set potential and calls the potential specific energy_update! function.

• Methods defined for :
  • AbstractDimerPotential
  • AbstractDimerPotentialB
  • EmbeddedAtomPotential
  • RuNNerPotential
  • RuNNerPotential2Atom

get_new_state_vars!(trial_pos, atomindex, config::Config, potential_variables::NNPVariables2a, dist2_mat, new_dist2_vec, pot::RuNNerPotential2Atom{Nrad, Nang, N1, N2}) where {Nrad, Nang, N1, N2}
get_new_state_vars!(indices, config, potential_variables, dist2_mat, potential::RuNNerPotential2Atom{Nrad, Nang, N1, N2}) where {Nrad, Nang, N1, N2}

Function to calculate the altered state variables after an atom move: Takes the new trialposition, its index, the total config, the current state variables, the distance matrix and updated vector and potential values. Calculates the new cutoff function values, the updated symmetry function matrix and passes these back to potentialvariables.

Method 2 calculates the new state variables based on an atomswap. Accepts many of the same variables, but the main difference is the indices vector, indicating which two atoms we are swapping. Also returns, most imporantly `potentialvariables.newgmatrix`.

get_new_state_vars!(trial_pos::PositionVector,atomindex::Int,config::Config,potential_variables::NNPVariables,dist2_mat::Matrix{Float64},new_dist2_vec::Vector{Float64},pot::RuNNerPotential{Nrad,Nang}) where {Nrad,Nang}

Function for finding the new state variables for calculating an NNP. Redefines new_f and new_g matrices based on the trial_pos of atom at atomindex and adjusts the parameters in the potential_variables according to the variables in pot.

initialise_energy(config::Config,dist2_mat::Matrix{Float64},potential_variables::AbstractPotentialVariables,ensemble_variables::NVTVariables,pot::AbstractDimerPotential)
initialise_energy(config::Config,dist2_mat::Matrix{Float64},potential_variables::AbstractPotentialVariables,ensemble_variables::NPTVariables,pot::AbstractDimerPotential)
initialise_energy(config::Config,dist2_mat::Matrix{Float64},potential_variables::AbstractPotentialVariables,ensemble_variables::NVTVariables,pot::AbstractDimerPotentialB)
initialise_energy(config::Config,dist2_mat::Matrix{Float64},potential_variables::AbstractPotentialVariables,ensemble_variables::NPTVariables,pot::AbstractDimerPotentialB)
initialise_energy(config::Config,dist2_mat::Matrix{Float64},potential_variables::AbstractPotentialVariables,ensemble_variables::AbstractEnsembleVariables,pot::EmbeddedAtomPotential)
initialise_energy(config::Config,dist2_mat::Matrix{Float64},potential_variables::AbstractPotentialVariables,ensemble_variables::AbstractEnsembleVariables,pot::RuNNerPotential)

Initialise energy is used during the MCState call to set the starting energy of a config according to the potential as pot and the configurational variables potential_variables. Written with general input means the top-level is type-invariant. Methods included for: - Dimer Potential with and without magnetic field and with and without PBC - EmbeddedAtomModel - Machine Learning Potentials

invrexp(r2::Number,n::Number,m::Number)

Function to calculate the ϕ,ρ components given a square distance r2 and the exponents n,m

lrc(NAtoms::Int,r_cut::Number,pot::ELJPotentialEven{N}) where N
lrc(NAtoms::Int,r_cut::Number,pot::ELJPotentialB{N}) where N

The long range correction for the extended Lennard-Jones potential (even). r_cut is the cutoff distance. lrc is an integral of all interactions outside the cutoff distance, using the uniform density approximation. Second method applies to the ELJ potential in extreme magnetic fields ELJB.

set_variables(config::Config{N, BC, T}, dist_2_mat::Matrix{Float64}, pot::AbstractDimerPotential) where {N, BC, T}
set_variables(config::Config{N, BC, T}, dist2_matrix::Matrix{Float64}, pot::AbstractDimerPotentialB) where {N, BC, T}
set_variables(config::Config{N, BC, T}, dist2_matrix::Matrix{Float64}, pot::EmbeddedAtomPotential) where {N, BC, T}
(set_variables(config::Config{N, BC, T}, dist2_mat::Matrix{Float64}, pot::RuNNerPotential{nrad, nang}) where {N, BC, T}) where {nrad, nang}
(set_variables(config::Config{N, BC, T}, dist2_mat, pot::RuNNerPotential2Atom{nrad, nang, n1, n2}) where {N, BC, T}) where {nrad, nang, n1, n2}

Initialises the PotentialVariable struct for the various potentials. Defined in this way to generalise the MCState function as this must be type-invariant with respect to the potential.

swap_energy_update(ensemble_variables,config,potential_variables,dist2_matrix,en_tot,pot)

This is used as a replacement for the energyupdate! function when swapping atoms. It does not function in quite the same way, but stands as a replacement. First calculates `getnewstatevars!and thencalcnewrunnerenergy!` returning the newenergy.