API Reference

AbstractPotential

The abstract supertype of all interatomic potentials.

BasisPotential <: AbstractPotential

Abstract type for potentials that are functions of descriptors of atomic environments, instead of the raw positions themselves.

BasisSystem

Abstract type to define methods for producing a set of local and force descriptors for a given configuration. Examples include the Atomic Cluster Expansion, SOAP descriptors, and SNAP descriptors.

BornMayer{T<:AbstractFloat} <: EmpiricalPotential{NamedTuple{(:A, :ρ)},NamedTuple{(:rcutoff,)}}

The Born-Mayer-Huggins potential is a two-body intermolecular potential with five typical parameters, primarily describing the interaction of neutral atoms. Formally, the interaction between two atoms at a distance, $r$, is given by

\[\begin{aligned} V_{LJ}(r; \epsilon, \sigma, rcutoff, species) = \begin{cases} 0 & r > rcutoff \\ A e^{\frac{\sigma-r}{\rho}} + \left( \frac{C}{r} \right)^8 - \left( \frac{D}{r} \right) & r < rcutoff. \end{cases} \end{aligned}\]

Users must supply five parameters, $A$ (units of energy), $\sigma$ (units of distance), $\rho$ (units of distance), $C$ $\&$ $D$ (units of energy $\times$ units of distance), and radial cutoff (units of distance).

Coulomb{T<:AbstractFloat} <: EmpiricalPotential{NamedTuple{()},NamedTuple{(:rcutoff,)}}

The Coulomb, or electrical potential is a simple two-body intermolecular potential that describes the electrical potential energy between two atoms with charge $q_{1}$ and $q_{2}$, at a distance $r$, is given by

\[\begin{equation} V_{LJ}(r; \epsilon, \sigma, rcutoff, species) = \begin{cases} 0 & r > rcutoff \\ \frac{k_{e} q_{1} q_{2}}{r} & r < rcutoff. \end{cases} \end{equation}\]

where $k_{e}$ is known as Coulomb's constant.

Users must supply the electric charges of the atoms, $q_{1}$ and $q_{2}$, and the radial cutoff.

EmpiricalPotential{P<:NamedTuple,HP<:NamedTuple} <: TrainablePotential{P,HP}

Defines an empirical potential, a heuristic function used to describe the intermolecular potential energy of a configuration of atoms. Various potentials have been found to agree empirically with the experimentally obtained potential energy of a configuration of atoms for particular atoms in particular situations. This package implements a number of such popular potentials.

P is a NamedTuple of parameter names and HP is a NamedTuple of hyperparameter names.

LBasisPotential <: LinearBasisPotential

Type covering interatomic potentials that produce energies and forces as a linear function of the basis descriptors. Typical examples include vanilla ACE/SNAP. Each struct contains the parameters of the potential, β', and the basis system being used,basis'.

LennardJones{T<:AbstractFloat} <: EmpiricalPotential{NamedTuple{(:ϵ, :σ)},NamedTuple{(:rcutoff,)}}

The Lennard-Jones potential is a simple two-body intermolecular potential with two typical parameters, primarily describing the interaction of neutral atoms. Formally, the interaction between two atoms at a distance, $r$, is given by

\[\begin{equation} V_{LJ}(r; \epsilon, \sigma, rcutoff, species) = \begin{cases} 0 & r > rcutoff \\ 4\epsilon \lbrack \frac{\sigma}{r})^{12} - (\frac{\sigma}{r})^6 \rbrack & r < rcutoff. \end{cases} \end{equation}\]

Users must supply two parameters, $\epsilon$ (units of energy), $\sigma$ (units of distance), and radial cutoff (units of distance).

LinearBasisPotential <: AbstractPotential

Abstract type for potentials that are linear functions of descriptors of atomic environments, instead of the raw positions themselves.

LinearCombinationPotential <: MixedPotential

A potential which represents the linear combination of multiple sub-potentials. Performing algebraic operations on any AbstractPotential will create a potential of this type.

MixedPotential <: AbstractPotential

Abstract type for potentials that are the combination of multiple sub-potentials.

Morse{T<:AbstractFloat} <: EmpiricalPotential{NamedTuple{(:D, :α, :σ)},NamedTuple{(:rcutoff,)}}

The Morse potential is a simple two-body intermolecular potential with three typical parameters, primarily describing the interaction of neutral atoms with more complex bond interactions. Formally, the interaction between two atoms at a distance, $r$, is given by

\[\begin{equation} V_{M}(r; D, \alpha, \sigma, rcutoff, species) = \begin{cases} 0 & r > rcutoff \\ D \left( 1 - e^{\alpha(r - \sigma)}\right)^2 & r < rcutoff. \end{cases} \end{equation}\]

Users must supply three parameters, $D$ (units of energy), $\alpha$ (units of inverse distance), $\sigma$ (units of distance), and radial cutoff (units of distance).

NNBasisPotential <: NeuralNetworkBasisPotential

Definition of the neural network basis potential composed type.

NeuralNetworkBasisPotential <: AbstractPotential

Abstract type for potentials that produce results as neural network functions of descriptors of atomic environments, instead of the raw positions themselves.

NonTrainablePotential <: AbstractPotential

Abstract type for potentials that aren't trainable.

TrainablePotential{P<:NamedTuple,HP<:NamedTuple} <: AbstractPotential

Abstract type for potentials that are trainable. P is a NamedTuple of parameter names and HP is a NamedTuple of hyperparameter names.

ZBL{T<:AbstractFloat} <: EmpiricalPotential{NamedTuple{()},NamedTuple{(:rcutoff,)}}

The Ziegler-Biersack-Littmark (ZBL) screened nuclear repulsion for describing high-energy collisions between atoms.

length(params::BasisParameters) :: Int

Retrieve the length of the descriptor vector, the number of descriptors used in the basis potential.

compute_all_descriptors(s::AbstractSystem, b::BasisSystem; T = Float64)::Vector{Vector{Vector}}

Compute the local, force, and virial descriptors for an abstract system s using the basis system defined in b. These types are defined in this package.

compute_force_descriptors(s::AbstractSystem, b::BasisSystem; T = Float64)::Vector{Vector{Vector}}

Compute the force descriptors for an abstract system s using the basis system defined in b. These types are defined in this package.

For a system s with n_atom number of atoms this method compute_force_descriptors returns a Vector{Matrix{T<:Real}}}, containing n_atom vectors each containing a matrix with rows corresponding to x-, y-, and z-components of dimension d as defined by the basis system.

compute_local_descriptors(s::AbstractSystem, b::BasisSystem; T = Float64)::Vector{Vector}

Compute the local descriptors for an abstract system s using the basis system defined in b.

For a system s with n_atom number of atoms this method compute_local_descriptors returns a Vector{Vector{T<:Real}}, containing n_atom vectors each of dimension d as defined by the basis system.

compute_virial_descriptors(s::AbstractSystem, b::BasisSystem; T = Float64)::Vector{Vector{Vector}}

Compute the virial descriptors for an abstract system s using the basis system defined in b. These types are defined in this package.

For a system s with n_atom number of atoms this method compute_virial_descriptors returns a Matrix{T<:Real}, containing 6 rows corresponding to entries of the stress tensor and columns of dimension d as defined by the basis system.

deserialize_hyperparameters(p::P<:AbstractPotential, hyperparameters::AbstractVector{<:AbstractFloat})::P

Generate a new potential of the same type as an exising potential but with modified trainable hyperparameters. This function takes in the trainable hyperparameters as a Vector in the same form as produced by serialize_hyperparameters(p).

For a TrainablePotential{P,HP}, the function converts the Vector of hyperparameters into the type parameter HP then calls the set_hyperparameters implementation. Note that this behavior should be overloaded for a potential type that has any non-scalar trainable hyperparameters. For a NonTrainablePotential, the function returns the original potential, unchanged.

deserialize_parameters(p::P<:AbstractPotential, parameters::AbstractVector{<:AbstractFloat})::P

Generate a new potential of the same type as an exising potential but with modified trainable parameters. This function takes in the trainable parameters as a Vector in the same form as produced by serialize_parameters(p).

For a TrainablePotential{P,HP}, the function converts the Vector of parameters into the type parameter P then calls the set_parameters implementation. Note that this behavior should be overloaded for a potential type that has any non-scalar trainable parameters. For a NonTrainablePotential, the function returns the original potential, unchanged.

energy_and_force(s::AbstractSystem, p::AbstractPotential)::NamedTuple{(:e, :f), Tuple{Unitful.Energy,Vector{SVector{3, Unitful.Force}}}}

Calculate the unit-annotated potential energy of a system and the force acting on each particle in a system using the provided interatomic potential. This combined function is offered because it is usually more efficient to calculate both properties simultaneously.

force(s::AbstractSystem, p::AbstractPotential)::Vector{SVector{3, Unitful.Force}}

Calculate the unit-annotated force acting on each particle in a system using the provided interatomic potential. The default implementation uses the :f property of energy_and_force(s,p).

get_hyperparameters(p::AbstractPotential)::NamedTuple

Retrieve a NamedTuple with the trainable hyperparameters of a potential.

For a TrainablePotential{P,HP}, the function automatically extracts the fields with names in the type parameter HP. For a NonTrainablePotential, the function returns an empty NamedTuple.

get_parameters(p::AbstractPotential)::NamedTuple

Retrieve a NamedTuple with the trainable parameters of a potential.

For a TrainablePotential{P,HP}, the function automatically extracts the fields with names in the type parameter P. For a NonTrainablePotential, the function returns an empty NamedTuple.

get_rcutoff(p::AbstractPotential)::AbstractFloat

Retrieve the radius cutoff for the provided potential. This is the cutoff used for neighbor list calculations. (i.e. Any pairs beyond this cutoff will be ignored.) Defaults to Inf if a potential type does not implement a custom method.

get_rpi(ace_params::ACE)::ACE1.RPI

Retrive the underlying RPI parameter type from ACE1. This is a convience function for exporting ACE parameters to file.

get_species(p::AbstractPotential)::Union{Tuple,Missing}

Retrieve the species to be included in an interaction (pairs including a species not in the list are ignored). A value of missing indicates that all species should be included, which is the default behavior if a potential type does not implement a custom method.

potential_energy(s::AbstractSystem, p::AbstractPotential)::Unitful.Energy

Calculate the unit-annotated potential energy of a system using the provided interatomic potential. The default implementation uses the :e property of energy_and_force(s,p).

serialize_hyperparameters(p::AbstractPotential)::Vector{<:AbstractFloat}

Generate a Vector form of the trainable hyperparameters of a potential.

For a TrainablePotential{P,HP}, the function automatically extracts the fields with names in the type parameter HP and collects them into a Vector. Note that this behavior should be overloaded for a potential type that has any non-scalar trainable hyperparameters. For a NonTrainablePotential, the function returns an empty Vector.

serialize_parameters(p::AbstractPotential)::Vector{<:AbstractFloat}

Generate a Vector form of the trainable parameters of a potential.

For a TrainablePotential{P,HP}, the function automatically extracts the fields with names in the type parameter P and collects them into a Vector. Note that this behavior should be overloaded for a potential type that has any non-scalar trainable parameters. For a NonTrainablePotential, the function returns an empty Vector.

set_hyperparameters(p::P<:AbstractPotential, hyperparameters::NamedTuple)::P

Generate a new potential of the same type as an exising potential but with modified trainable hyperparameters.

For a TrainablePotential{P,HP}, the function copies over all fields and replaces the fields from the type parameter HP. For a NonTrainablePotential, the function returns the original potential, unchanged.

set_parameters(p::P<:AbstractPotential, parameters::NamedTuple)::P

Generate a new potential of the same type as an exising potential but with modified trainable parameters.

For a TrainablePotential{P,HP}, the function copies over all fields and replaces the fields from the type parameter P. For a NonTrainablePotential, the function returns the original potential, unchanged.

virial(s::AbstractSystem, p::AbstractPotential)::Unitful.Energy

Calculate the unit-annotated virial of a system, officially calculated as the trace contraction of the sum of radial-force outerproducts: $tr\left( \sum r_{ij} \bigotimes F_{ij} \right)$

virial_stress(s::AbstractSystem, p::AbstractPotential)::SVector{6,Unitful.Energy}

Calculate the unit-annotated virial stress tensor of a system, officially calculated as the sum of radial-force outerproducts: $\sum r_{ij} \bigotimes F_{ij}$, only returns the unique lower-diagonal components.

Coulomb constant in atomic units. https://en.wikipedia.org/wiki/Coulomb_constant

Vacuum permittivity in atomic units. https://en.wikipedia.org/wiki/Vacuum_permittivity