ACEpotentials.jl API
Exported
ACEpotentials.acefit! — Methodacefit!(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_keyspecify
the label of the data to which the parameters will be fitted.
weightsspecifies the regression weights, default is 30 for energy, 1 for forces and virialssolverspecifies the lsq solver, default isBLR(BayesianLinearRegression)smoothnessspecifies the smoothness prior, i.e. how strongly damped parameters corresponding to high polynomial degrees are; is 2.priorspecifies a covariance of the prior, ifnothingthen a smoothness prior is used, using thesmoothnessparameterrepulsion_restraintspecifies whether to add artificial data to the training set that effectively introduces a restraints encouraging repulsion in the limit rij -> 0.restraint_weightspecifies 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
ACEpotentials.site_descriptors — Methodsite_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.
Not exported
ACEpotentials.at_dimer — Methodfunction at_dimer(r, z1, z0) : generates a dimer with separation r and atomic numbers z1 and z0. (can also use symbols or strings)
ACEpotentials.at_trimer — Methodfunction 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.
ACEpotentials.atom_energy — Methodfunction atom_energy(IP, z0) : energy of an isolated atom
ACEpotentials.copy_runfit — Function 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.
ACEpotentials.copy_tutorial — Function copy_tutorial(dest)Converts the ACEpotential-Tutorial.jl literate notebook to a jupyter notebook and copies it to the folder dest.
ACEpotentials.decohesion_curve — MethodGenerate a decohesion curve for testing the smoothness of a potential. Arguments:
at0: unit cellpot: potential implementingenergy
Keyword Arguments:
dim = 1: dimension into which to expandmult = 10: multiplicative factor for expanding the cell in dim directionaa = :auto: array of stretch values of the lattice parameter to usenpoints = 100: number of points to use in the stretch array (for auto aa)
ACEpotentials.dimer_energy — Methodfunction 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.
ACEpotentials.dimers — Methoddimers(potential, elements; kwargs...) : Generate a dictionary of dimer curves for a given potential.
potential: potential to use to evaluate energyelements: 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).
ACEpotentials.get_adf — Methodfunction 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 everyskipth atom in the dataset.maxsamples = 100_000: maximum number of samples to return.
ACEpotentials.get_rdf — Methodfunction 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 probabilitymin(1, (r0/r)^2).r0 = :min: parameter for resampling. If:minthen the minimum r occuring in the dataset is taken.maxsamples = 100_000: maximum number of samples to return.
ACEpotentials.make_model — Method make_model(model_dict::Dict)User-facing script to generate a model from a dictionary. See documentation for details.
ACEpotentials.save_model — Method save_model(model, filename; kwargs...)save model constructor, model parameters, and other information to a JSON file.
model: the model to be savedfilename: the name of the file to which the model will be savedmodel_spec: the arguments used to construct the model; without this the model cannot be reconstructed unless the original script is availableerrors: the fitting / test errors computed during the fittingverbose: print information about the saving processsave_project: save Project.toml and Manifest.toml for reproducibility
ACEpotentials.trimer_energy — Methodfunction trimer_energy(IP, r1, r2, θ, z0, z1, z2) : computes the energy of a trimer, subtracting the 2-body and 1-body contributions.
ACEpotentials.trimers — Methodtrimers(potential, elements, r1, r2; kwargs...) : Generate a dictionary of trimer curves for a given potential.
potential: potential to use to evaluate energyelements: list of chemical species, symbols for which the trimers are to be computedr1, 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).
ACEpotentials.Models.AADot — TypeImplementation of AA ⋅ θ; for easier use within the FastACE.
ACEpotentials.Models.ACE1_PolyEnvelope1sR — TypeThe pair basis radial envelope implemented in ACE1.jl
ACEpotentials.Models.NormalizedTransform — TypeMaps the transform trans to the standardized interval [-1, 1]
ACEpotentials.Models.OneBody — Typemutable 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.
ACEpotentials.Models._AA_dot — MethodThis 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.
ACEpotentials.Models._make_smatrix — MethodTakes an object and converts it to an SMatrix{NZ, NZ} via the following rules:
- if
objis already anSMatrix{NZ, NZ}then it just returnobj - if
objis anAbstractMatrixandsize(obj) == (NZ, NZ)then it converts it to anSMatrix{NZ, NZ}with the same entries. - otherwise it generates an
SMatrix{NZ, NZ}filled with the valueobj.
ACEpotentials.Models.agnesi_transform — Methodfunction 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.
ACEpotentials.Models.fast_evaluator — Method 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.
ACEpotentials.Models.get_nnll_spec — MethodGet the specification of the BBbasis as a list (Vector) of vectors of @NamedTuple{n::Int, l::Int}.
Parameters
model: an ACEModel
ACEpotentials.Models.get_nnll_spec — MethodGet the specification of the BBbasis as a list (Vector) of vectors of @NamedTuple{n::Int, l::Int}.
Parameters
tensor: a SparseEquivTensor, possibly from ACEModel
ACEpotentials.Models.set_onehot_weights! — MethodSet the radial weights as they would be in a linear ACE model.
ACEpotentials.Models.sparse_AA_spec — MethodThis 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 orderr_spec: radial basis specification in the formatVector{@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.TotalDegreeandEuclideanDegree
