ACEpotentials.jl API

acefit!(rawdata, model; kwargs...)

provides a convenient interface to fitting the parameters of an ACE model. The data should be provided as a collection of AbstractSystem structures.

Keyword arguments:

• energy_key, force_key, virial_key specify

the label of the data to which the parameters will be fitted.

• weights specifies the regression weights, default is 30 for energy, 1 for forces and virials
• solver specifies the lsq solver, default is BLR (BayesianLinearRegression)
• smoothness specifies the smoothness prior, i.e. how strongly damped parameters corresponding to high polynomial degrees are; is 2.
• prior specifies a covariance of the prior, if nothing then a smoothness prior is used, using the smoothness parameter
• repulsion_restraint specifies whether to add artificial data to the training set that effectively introduces a restraints encouraging repulsion in the limit rij -> 0.
• restraint_weight specifies the weight of the repulsion restraint.
• export_lammps : path to a file to which the fitted potential will be exported in a LAMMPS compatible format (yace)
• export_json : path to a file to which the fitted potential will be exported in a JSON format, which can be read from Julia or Python

site_descriptors(system::AbstractSystem, model::ACEPotential;
                 domain, nlist)

Compute site descriptors for all atoms in system, returning them as a vector of vectors. If the optional kw argument domain is passed as a list of integers (atom indices), then only the site descriptors for those atoms are computed and returned. The neighbourlist nlist can be supplied optionally as a kw arg, otherwise it is recomputed.

function at_dimer(r, z1, z0) : generates a dimer with separation r and atomic numbers z1 and z0. (can also use symbols or strings)

function at_trimer(r1, r2, θ, z0, z1, z2) : generates a trimer with separations r1 and r2, angle θ and atomic numbers z0, z1 and z2 (can also use symbols or strings), where z0 is the species of the central atom, z1 at distance r1 and z2 at distance r2.

function atom_energy(IP, z0) : energy of an isolated atom

  copy_runfit(dest = pwd())

Copies the runfit.jl script and an example model parameter file to dest. If called from the destination directory, use

ACEpotentials.copy_runfit()

This is intended to setup a local project directory with the necessary scripts to run a fitting job.

  copy_tutorial(dest = pwd())

Converts the ACEpotential-Tutorial.jl and ACE+AtomsBase.jl literate notebooks to jupyter notebooks and copies them to the folder dest.

Generate a decohesion curve for testing the smoothness of a potential. Arguments:

• at0 : unit cell
• pot : potential implementing energy

Keyword Arguments:

• dim = 1 : dimension into which to expand
• mult = 10 : multiplicative factor for expanding the cell in dim direction
• aa = :auto : array of stretch values of the lattice parameter to use
• npoints = 100 : number of points to use in the stretch array (for auto aa)

function dimer_energy(pot, r, z1, z0) : energy of a dimer with separation r and atomic numbers z1 and z0 using the potential pot; subtracting the 1-body contributions.

dimers(potential, elements; kwargs...) : Generate a dictionary of dimer curves for a given potential.

• potential : potential to use to evaluate energy
• elements : list of chemical species, symbols for which the dimers are to be computed

The function returns a dictionary Ddim such that D[(s1, s2)] contains pairs or arrays (rr, E) which can be plotted plot(rr, E).

function get_adf(data::AbstractVector{<: Atoms}, r_cut; kwargs...) :

Angular distribution, i.e. list of angles in [0, π] between all pairs of bonds of length at most r_cut. Keyword arguments:

• skip = 3 : only consider every skipth atom in the dataset.
• maxsamples = 100_000 : maximum number of samples to return.

function get_rdf(data::AbstractVector{<: Atoms}, r_cut; kwargs...) :

Produce a list of r values that occur in the dataset, restricted to the cutoff radius r_cut. Keyword arguments:

• rescale = true : resample the data to account for volume scaling, i.e. a distance r will be kept with probability min(1, (r0/r)^2).
• r0 = :min : parameter for resampling. If :min then the minimum r occuring in the dataset is taken.
• maxsamples = 100_000 : maximum number of samples to return.

  make_model(model_dict::Dict)

User-facing script to generate a model from a dictionary. See documentation for details.

  save_model(model, filename; kwargs...)

save model constructor, model parameters, and other information to a JSON file.

• model : the model to be saved
• filename : the name of the file to which the model will be saved
• model_spec : the arguments used to construct the model; without this the model cannot be reconstructed unless the original script is available
• errors : the fitting / test errors computed during the fitting
• verbose : print information about the saving process
• save_project : save Project.toml and Manifest.toml for reproducibility

function trimer_energy(IP, r1, r2, θ, z0, z1, z2) : computes the energy of a trimer, subtracting the 2-body and 1-body contributions.

trimers(potential, elements, r1, r2; kwargs...) : Generate a dictionary of trimer curves for a given potential.

• potential : potential to use to evaluate energy
• elements : list of chemical species, symbols for which the trimers are to be computed
• r1, r2 : distance between the central atom and the first, second neighbour

The function returns a dictionary Dtri such that D[(s1, s2, s3)] contains pairs or arrays (θ, E) which can be plotted plot(θ, E).

Implementation of AA ⋅ θ; for easier use within the FastACE.

The pair basis radial envelope implemented in ACE1.jl

Maps the transform trans to the standardized interval [-1, 1]

mutable struct OneBody{T}

this should not normally be constructed by a user, but instead E0 should be passed to the relevant model constructor, which will construct it.

This naive code is not supposed to be fast, it is only used to generate a dynamic polynomial representating the operation AA ⋅ c -> εᵢ

The generated (giant) polynomial is then used to generate optimized evaluation and gradient code.

Takes an object and converts it to an SMatrix{NZ, NZ} via the following rules:

• if obj is already an SMatrix{NZ, NZ} then it just return obj
• if obj is an AbstractMatrix and size(obj) == (NZ, NZ) then it converts it to an SMatrix{NZ, NZ} with the same entries.
• otherwise it generates an SMatrix{NZ, NZ} filled with the value obj.

function agnesi_transform: constructs a generalized agnesi transform.

trans = agnesi_transform(r0, p, q)

with q >= p. This generates an AnalyticTransform object that implements

\[ x(r) = \frac{1}{1 + a (r/r_0)^q / (1 + (r/r0)^(q-p))}\]

with default a chosen such that $|x'(r)|$ is maximised at $r = r_0$. But a may also be specified directly as a keyword argument.

The transform satisfies

\[ x(r) \sim \frac{1}{1 + a (r/r_0)^p} \quad \text{as} \quad r \to 0 \quad \text{and} \quad x(r) \sim \frac{1}{1 + a (r/r_0)^p} \quad \text{as} r \to \infty.\]

As default parameters we recommend p = 2, q = 4 and the defaults for a.

  fast_evaluator(model; aa_static = :auto)

Constructs an experimental "fast evaluator" for a fitted model, which merges some operations resulting in a "slimmer" and usually faster evaluator. In some cases the performance gain can be significant, especially when the fitted parameters are sparse.

To construct the fast evaluator,

fpot = fast_evaluator(model)

An optional keyword argument aa_static = true can be used to enforce optimizing the n-correlation layer for very small models (at most a few hundred parameters). For larger models this results in a stack overflow.

Get the specification of the BBbasis as a list (Vector) of vectors of @NamedTuple{n::Int, l::Int}.

Parameters

• model : an ACEModel

Get the specification of the BBbasis as a list (Vector) of vectors of @NamedTuple{n::Int, l::Int}.

Parameters

• tensor : a SparseEquivTensor, possibly from ACEModel

Set the radial weights as they would be in a linear ACE model.

This is one of the most important functions to generate an ACE model with sparse AA basis. It generates the AA basis specification as a list (Vector) of vectors of @NamedTuple{n::Int, l::Int, m::Int}.

Parameters

• order : maximum correlation order
• r_spec : radial basis specification in the format Vector{@NamedTuple{a::Int64, b::Int64}}
• max_level : maximum level of the basis, either a single scalar, or an iterable (one for each order)
• level : a function that computes the level of a basis element; see e.g. TotalDegree and EuclideanDegree