Cairn

Abstract type for defining criteria triggering the active learning step during simulation.

DoubleWell(; force_units, energy_units)

The double well potential energy surface with 2 minima.

The potential energy is defined as

\[V(x,y) = (1/6)*(4*(1-x^2-y^2)^2 + 2*(x^2-2)^2 + ((x+y)^2-1)^2 + ((x-y)^2-1)^2)\]

This potential is only compatible with 2D systems.

A general interaction that applies to single atoms (no multi-element interactions). Custom general interactions should sub-type this abstract type.

Himmelblau(; force_units, energy_units)

The Himmelblau potential energy surface with 4 minima.

The potential energy is defined as

\[V(x,y) = (x^2 + y - 11)^2 + (x + y^2 - 7)^2\]

This potential is only compatible with 2D systems.

A machine learning interatomic potential defining interactions between sets of atoms. Custom machine learning interactions should sub-type this abstract type.

MaxKernelEval(; thresh::Real=0.1)

An active learning trigger activated when the maximum kernel evaluation falls below a threshold thresh.

MaxVol(feature_func; thresh::Real=1.0)

An active learning trigger activated after the D-optimality based extrapolation grade exceeds a threshold thresh.

MeanKSD(; thresh::Real=0.1)

An active learning trigger activated when the mean magnitude of kernel Stein discrepancy (KSD) metric falls below a threshold thresh.

MullerBrownRotated(; A, a, b, c, x0, y0, force_units, energy_units)

The Müller-Brown potential energy surface, rotated counter-clockwise (default by 45 degrees).

The potential energy is defined as

\[V(x,y) = \sum_{n=1}^{4} A_k \exp[a_k(x-x_k^0)^2 + b_k(x-x_k^0)(y-y_k^0) + c_k(y-y_k^0)^2]\]

where A, a, b, c, x0, y0 are 4-element SVectors with standard defaults.

This potential is only compatible with 2D systems. It is often used for testing algorithms that find transition states or explore minimum energy pathways. There are 3 minima and 2 saddle points with the default parameters.

PolynomialChaos{P, F, E} <: MLInteraction

Total-degree polynomial chaos expansion (PCE) model defining the potential energy function for a single-atom system.

Arguments

• p :: Integer : total polynomial degree
• d :: Integer : dimension
• BasisFamily :: P : family of basis functions from SpecialPolynomials
• basis :: Vector{Vector} : set of basis functions
• gbasis :: Vector{Vector} : set of gradient basis functions
• force_units :: F : units of force
• energy_units :: E : units of energy

An abstract type for simulators. Custom simulators should sub-type this abstract type.

Sinusoid(; force_units, energy_units)

A sinusoidal potential energy surface with multiple basins.

The potential energy is defined as

\[V(x,y) = x^2/20 + y^2/20 + sin(x) + sin(y)\]

This potential is only compatible with 2D systems.

SteinRepulsiveLangevin(; <keyword arguments>)

Simulates a hybrid simulator combining OverdampedLangevin and a Stein repulsive term, after Ye et al. 2020 (https://arxiv.org/abs/2002.09070).

Arguments

• dt::S : the time step of the simulation.
• kernel::K : kernel used for computing kernelized forces.
• sys_fix::Vector{X} : Vector of systems of fixed atoms for computing kernelized forces.
• temperature::T : the equilibrium temperature of the simulation.
• friction::F : the friction coefficient of the simulation.
• remove_CM_motion=1 : remove the center of mass motion every this number of steps, set to false or 0 to not remove center of mass motion.

StepComponentLogger(observable::T, nsteps::Int, history::Vector{T})

A logger which holds a record of components of the update step to the coordinate positions.

Arguments

• observable::T : observable quantity of type T.
• n_steps::Int : time step interval at which the observable is recorded.
• history::Vector{T} : record of values of the observable.

StochasticSVGD(; <keyword arguments>)

Simulates a stochastic variant of Stein variational gradient descent (SVGD).

Arguments

• dt::S : the time step of the simulation.
• kernel::K : kernel used for computing kernelized forces.
• kernel_bandwidth::Function : function which computes the kernel bandwidth.
• sys_fix::Vector{X} : Vector of systems of fixed atoms for computing kernelized forces.
• temperature::T : the equilibrium temperature of the simulation.
• friction::F : the friction coefficient of the simulation.
• remove_CM_motion=1 : remove the center of mass motion every this number of steps, set to false or 0 to not remove center of mass motion.

TimeInterval(; interval::Real=1)

An active learning trigger activated after a fixed number of simulation steps specified by interval.

TriggerLogger(trigger::ActiveLearningTrigger, nsteps::Int, history::Vector{T})

A logger which holds a record of evaluations of the trigger function for active learning.

Arguments

• trigger::ActiveLearningTrigger : trigger function.
• observable::T : value of the trigger function of type T.
• n_steps::Int : time step interval at which the trigger function is evaluated.
• history::Vector{T} : record of the trigger function evaluation.

function Ensemble( inter, coords::Vector; distunits=u"nm", atommass=1.0u"g/mol", σ=0.3u"nm", ϵ=0.2u"kJ * mol^-1", boundary=RectangularBoundary(Inf*dist_units), loggers=false, data=nothing, )

Defines a Vector{<:System} for an ensemble of systems.

TotalDegreeMset(p::Int, d::Int)

Return a matrix of indices, where the columns are the multi-indices in dimension d with the total degree less than or equal to p.

Arguments

• p :: Int : The total degree of the polynomials
• d :: Int : The dimension of the problem

active_learn!(sys::Union{System, Vector{<:System}}, sim::Simulator, n_steps::Integer, sys_train::Vector{<:System}, ref::Union{GeneralInteraction, PairwiseInteraction}, trigger::Union{Bool, ActiveLearningTrigger}; n_threads::Integer=Threads.nthreads(), run_loggers=true)

Performs online active learning by molecular dynamics simulation defined in sim, using the retraining criterion defined in trigger.

Arguments

• sys::Union{System, Vector{<:System}} : a system or ensemble of systems to simulate
• sim::Simulator : simulator of the equations of motion
• n_steps::Integer : number of simulation time steps
• sys_train::Vector{<:System} : ensemble of systems representing the training data
• ref::Union{GeneralInteraction, PairwiseInteraction} : interaction for computing reference values
• trigger::Union{Bool, ActiveLearningTrigger} : trigger which instantiates retraining
• n_threads::Integer=Threads.nthreads() : number of threads
• run_loggers=true : Bool for running loggers

compute_error_metrics!(al::ActiveLearnRoutine)

Appends error metric calculations (RMSE in energies and forces, Fisher divergence in probability measures) to al.error_hist.

computekernelizedforces(sys::System, ens_fix::Vector{<:System}, knl::Kernel; feature::Union{Nothing,Feature} = nothing)

A function which computes the kernel and gradient kernel terms between a single atom in sys and fixed atoms in ens_fix, using kernel function knl.

computekernelizedforces(ens::Vector{<:System}, knl::Kernel)

A function which computes the kernel and gradient kernel terms all atoms in ens using kernel function knl.

get_atoms(ens::Vector{<:System})

Returns a vector of atoms contained in all systems of the ensemble ens.

get_coords(ens::Vector{<:System})

Returns a vector of atomic coordinates contained in all systems of the ensemble ens.

has_step_property(sys::System)
has_step_property(logger::Logger)

Returns a Bool evaluating whether the system sys contains any loggers which are of type StepComponentLogger.

trigger_activated(trigger::ActiveLearningTrigger, kwargs...)
trigger_activated(trigger::Bool, kwargs...)

A function which returns a Bool of whether or not the trigger for active learning is activated.

update_sys(sim::Simulator)

Performs online active learning by molecular dynamics simulation defined in sim, using the retraining criterion defined in trigger.

Arguments

• sim::Simulator : simulator of the equations of motion
• sys::Union{System,Vector{<:System}} : simulation system
• sys_train::Vector{<:System}: Vector of systems in the training data

Keyword Arguments

• n_add::Integer=10 : number of samples to add to sys_train
• steps::Integer=1000 : number of steps in the sample path over which to draw new training data

function computeforcedescriptors( ens::Vector{<:System}, inter; pbar = true )

Compute force descriptors of a basis system and dataset using threads.

function computelocaldescriptors( ens::Vector{<:System}, inter; pbar = true )

Computes the local energy descriptors each system in the ensemble using threads.

get_force_descriptors(sys::System)
get_force_descriptors(ens::Vector{<:System})

Returns the per-atom force descriptors of the system, sys, or ensemble of systems, ens.

get_local_descriptors(sys::System)
get_local_descriptors(ens::Vector{<:System})

Returns the local energy descriptors of the system, sys, or ensemble of systems, ens.

get_values(logger::Logger)
get_values(qt::Vector)
get_values(qt::Real)

Returns a Vector of unitless values of the logger history, vector, or scalar quantity.