From c3d3f62cec77cfa8a8433966333154bcf7ed8c03 Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Wed, 11 Sep 2024 19:03:04 +0000 Subject: [PATCH] build based on 2c039b4 --- dev/.documenter-siteinfo.json | 2 +- dev/all_exported/index.html | 4 +- dev/gettingstarted/aceintro/index.html | 2 +- dev/gettingstarted/installation/index.html | 2 +- .../parallel-fitting/index.html | 2 +- dev/gettingstarted/pkg/index.html | 2 +- .../saving-and-loading/index.html | 2 +- dev/index.html | 2 +- .../basic_julia_workflow/index.html | 120 ++- .../dataset_analysis/2f993c5b.svg | 854 ++++++++++++++++++ .../dataset_analysis/eadf077c.svg | 854 ------------------ .../dataset_analysis/ed339471.svg | 361 -------- .../{6ae02bf1.svg => edefcc2f.svg} | 606 ++++++------- .../dataset_analysis/f00e5a42.svg | 361 ++++++++ .../dataset_analysis/index.html | 6 +- .../{be0508a2.svg => b1992461.svg} | 100 +- .../{8ee817d8.svg => bcc4472e.svg} | 76 +- .../{caf73828.svg => e27fbf57.svg} | 84 +- .../smoothness_priors/index.html | 8 +- dev/tutorials/index.html | 2 +- dev/tutorials/lammps/index.html | 2 +- dev/tutorials/molly/index.html | 2 +- dev/tutorials/python_ase/index.html | 2 +- dev/tutorials/scripting/index.html | 2 +- 24 files changed, 1722 insertions(+), 1736 deletions(-) create mode 100644 dev/literate_tutorials/dataset_analysis/2f993c5b.svg delete mode 100644 dev/literate_tutorials/dataset_analysis/eadf077c.svg delete mode 100644 dev/literate_tutorials/dataset_analysis/ed339471.svg rename dev/literate_tutorials/dataset_analysis/{6ae02bf1.svg => edefcc2f.svg} (57%) create mode 100644 dev/literate_tutorials/dataset_analysis/f00e5a42.svg rename dev/literate_tutorials/smoothness_priors/{be0508a2.svg => b1992461.svg} (88%) rename dev/literate_tutorials/smoothness_priors/{8ee817d8.svg => bcc4472e.svg} (86%) rename dev/literate_tutorials/smoothness_priors/{caf73828.svg => e27fbf57.svg} (87%) diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index a947bd56..780be33f 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.10.5","generation_timestamp":"2024-09-10T21:58:55","documenter_version":"1.7.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.10.5","generation_timestamp":"2024-09-11T19:02:46","documenter_version":"1.7.0"}} \ No newline at end of file diff --git a/dev/all_exported/index.html b/dev/all_exported/index.html index 3a94761e..f1dcf3bb 100644 --- a/dev/all_exported/index.html +++ b/dev/all_exported/index.html @@ -1,5 +1,5 @@ -Reference · ACEpotentials.jl

ACEpotentials.jl API

Exported

ACEpotentials.acefit! — Method

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
source

Not exported

ACEpotentials.at_dimer — Method

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

source
ACEpotentials.at_trimer — Method

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.

source
ACEpotentials.copy_runfit — Method
  copy_runfit(dest)

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

ACEpotentials.copy_runfit(@__DIR__())

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

source
ACEpotentials.decohesion_curve — Method

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)
source
ACEpotentials.dimer_energy — Method

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.

source
ACEpotentials.dimers — Method

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).

source
ACEpotentials.get_adf — Method

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.
source
ACEpotentials.get_rdf — Method

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.
source
ACEpotentials.make_model — Method
  make_model(model_dict::Dict)

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

source
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 saved
  • filename : the name of the file to which the model will be saved
  • make_model_args : 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
source
ACEpotentials.trimer_energy — Method

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

source
ACEpotentials.trimers — Method

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).

source
ACEpotentials.Models.OneBody — Type

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.

source
ACEpotentials.Models._make_smatrix — Method

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.
source
ACEpotentials.Models.agnesi_transform — Method

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 +Reference · ACEpotentials.jl

ACEpotentials.jl API

Exported

ACEpotentials.acefit! — Method

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
source

Not exported

ACEpotentials.at_dimer — Method

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

source
ACEpotentials.at_trimer — Method

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.

source
ACEpotentials.copy_runfit — Method
  copy_runfit(dest)

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

ACEpotentials.copy_runfit(@__DIR__())

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

source
ACEpotentials.decohesion_curve — Method

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)
source
ACEpotentials.dimer_energy — Method

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.

source
ACEpotentials.dimers — Method

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).

source
ACEpotentials.get_adf — Method

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.
source
ACEpotentials.get_rdf — Method

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.
source
ACEpotentials.make_model — Method
  make_model(model_dict::Dict)

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

source
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 saved
  • filename : the name of the file to which the model will be saved
  • make_model_args : 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
source
ACEpotentials.trimer_energy — Method

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

source
ACEpotentials.trimers — Method

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).

source
ACEpotentials.Models.OneBody — Type

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.

source
ACEpotentials.Models._make_smatrix — Method

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.
source
ACEpotentials.Models.agnesi_transform — Method

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.

source
ACEpotentials.Models.get_nnll_spec — Method

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
source
ACEpotentials.Models.sparse_AA_spec — Method

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
source
+ 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.

source
ACEpotentials.Models.get_nnll_spec — Method

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
source
ACEpotentials.Models.sparse_AA_spec — Method

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
source
diff --git a/dev/gettingstarted/aceintro/index.html b/dev/gettingstarted/aceintro/index.html index b5713dbd..5df2011a 100644 --- a/dev/gettingstarted/aceintro/index.html +++ b/dev/gettingstarted/aceintro/index.html @@ -6,4 +6,4 @@ \sum_j \phi_{nlm}({\bm r}_j).\]

Density correlations

Next, we form the $N$-correlations of the density, $\rho^{\otimes N}$ and project them onto the tensor project basis,

\[ {\bm A}_{\mathbf{nlm}} = \Big\langle \otimes_{t = 1}^N \phi_{n_t l_t m_t}, \rho^{\otimes N} \Big\rangle = \prod_{t = 1}^N A_{n_t l_t m_t}.\]

The reason to introduce these is that in the next step, the symmetrisation step, the density project would lose all angular information while the $N$-correlations retain most (though not all) of it.

Symmetrisation

Finally, we symmetrise the $N$-correlations, by integrating over the $O(3)$-Haar measure,

\[ B_{\mathbf{nlm}} \propto - \int_{O(3)} {\bm A}_{\mathbf{nlm}} \circ Q \, dQ \]

Because of properties of the spherical harmonics one can write this as

\[ {\bm B} = \mathcal{U} {\bm A},\]

where ${\bm A}$ is the vector of 1, 2, ..., N correlations (the maximal $N$ is an approximation parameter!) and $\mathcal{U}$ is a sparse matrix (the coupling coefficients).

If one symmetrised all possible $N$-correlations then this would create a spanning set, but one can easily reduce this to an actual basis. This construction then yields a basis of the space of symmetric polynomials.

Notes:

Linear Dependence

The construction described above introduces a lot of linear dependence which is removed in the ACE basis construction in a mixed symbolic / numerical procedure. In the end we no longer index the symmetrized basis functions as $B_{\bm nlm}$ but as $B_{\mathbf{nl}i}$ with $i$ indexing the linearly independent basis functions from the $\mathbf{nl}$ block.

+ \int_{O(3)} {\bm A}_{\mathbf{nlm}} \circ Q \, dQ \]

Because of properties of the spherical harmonics one can write this as

\[ {\bm B} = \mathcal{U} {\bm A},\]

where ${\bm A}$ is the vector of 1, 2, ..., N correlations (the maximal $N$ is an approximation parameter!) and $\mathcal{U}$ is a sparse matrix (the coupling coefficients).

If one symmetrised all possible $N$-correlations then this would create a spanning set, but one can easily reduce this to an actual basis. This construction then yields a basis of the space of symmetric polynomials.

Notes:

Linear Dependence

The construction described above introduces a lot of linear dependence which is removed in the ACE basis construction in a mixed symbolic / numerical procedure. In the end we no longer index the symmetrized basis functions as $B_{\bm nlm}$ but as $B_{\mathbf{nl}i}$ with $i$ indexing the linearly independent basis functions from the $\mathbf{nl}$ block.

diff --git a/dev/gettingstarted/installation/index.html b/dev/gettingstarted/installation/index.html index 73f65856..239be031 100644 --- a/dev/gettingstarted/installation/index.html +++ b/dev/gettingstarted/installation/index.html @@ -8,4 +8,4 @@ registry add https://github.com/ACEsuit/ACEregistry

Press Backspace or Ctrl-c to exit the package manager. Use Ctrl-d, or exit() followed by Enter, to close the Julia REPL.

Setting up a new ACEpotentials.jl project

Create a folder for your new project and change to it. Start the Julia REPL and activate a new project by switching to the package manager with ], and then running

activate .

Now you can install ACEpotentials. Remaining in the package manager, use

add ACEpotentials

Depending on your usage you may also need to add other packages, e.g. AtomsBase, Molly, DFTK etc.

Returning to a project

When returning to a project, there are several methods for reactivating it. One is to simply activate . in the package manager, as above. Alternatively set the JULIA_PROJECT environment variable to the directory with Project.toml before starting julia, or call julia as julia --project=<dir>. Special syntax like JULIA_PROJECT=@. or julia --project=@. searches the current directory and its parents for a Project.toml file.

Setting up the Python ASE calculator

Warning

The current version of ACEpotentials does not have a tested ASE interface. If you need an ASE interface, consider using a version < 0.8 of ACEpotentials.

We use a wrapper called pyjulip to call julia and evaluate ACE potentials. In a terminal, with the correct julia project and python environment selected, run the following code:

python -m pip install julia
 python -c "import julia; julia.install()"

Make sure to use the correct python and pip, e.g. the ones that are in the correct Conda environment. Then, to set up pyjulip:

git clone https://github.com/casv2/pyjulip.git
 cd pyjulip
-pip install .

Troubleshooting

There are currently no known recurring problems with ACEpotentials installation.

+pip install .

Troubleshooting

There are currently no known recurring problems with ACEpotentials installation.

diff --git a/dev/gettingstarted/parallel-fitting/index.html b/dev/gettingstarted/parallel-fitting/index.html index af13c60a..b71f25bb 100644 --- a/dev/gettingstarted/parallel-fitting/index.html +++ b/dev/gettingstarted/parallel-fitting/index.html @@ -5,4 +5,4 @@ @everywhere using ACEpotentials

Parallel BLAS or LAPACK

Many ACEfit solvers, and possibly other routines, utilize BLAS or LAPACK. To see benefits from threading, one should set one or more of the following environment variables, depending on the particular library used.

export OMP_NUM_THREADS=8
 export MKL_NUM_THREADS=8
 export OPENBLAS_NUM_THREADS=8
-export VECLIB_MAXIMUM_THREADS=8

Distributed solution of the linear least squares systems is currently not supported. We would welcome collaboration on this with interested developers.

+export VECLIB_MAXIMUM_THREADS=8

Distributed solution of the linear least squares systems is currently not supported. We would welcome collaboration on this with interested developers.

diff --git a/dev/gettingstarted/pkg/index.html b/dev/gettingstarted/pkg/index.html index 03790564..d2744cc7 100644 --- a/dev/gettingstarted/pkg/index.html +++ b/dev/gettingstarted/pkg/index.html @@ -1,4 +1,4 @@ Using the Julia Package Manager · ACEpotentials.jl

Using the Julia Package Manager

This is a very brief introduction to the Julia package manager, intended for newcomers to Julia who are here primarily to use the ACEsuit. But it is not really ACE specific at all.

The package manager provides functionality to organize reproducable Julia projects. A project is specified by a Project.toml where the user specifies which packages are required, and version bounds on those packages. The Package manager can then resolve these dependencies which results in a Manifest.toml where the full Julia environment is precisely specified. This can be used in a workflow as follows:

  1. To start a new project that uses ACEpotentials.jl, e.g. to develop a new interatomic potential for TiAl we first create a new folder where the project will live, e.g., ace_TiAl_project. Change to that folder and start the Julia REPL. Type ] to switch to the package manager, then activate a new project in the current directory via activate .

  2. You now have an empty project. Start adding the packages you need, often just add ACEpotentials will suffice. Type status to see your required packages listed. (Note this is only a subset of the installed packages!). Exit the REPL and type ls; you will then see a new file Project.toml which lists the project requirements, and a Manifest.toml which lists the actually packages and the version that have been installed.

  3. Specify version bounds: We strongly encourage doing this rigorously! Open Project.toml in an editor and under the [compat] section you can now add version bounds, e.g. ACEpotentials = "0.6.1" following semver. Please see the Pkg.jl docs for details on how to specify those bounds. Start a Julia REPL again, type ] to switch to the package manager and then up to up- or down-grade all installed packages to the latest version compatible with your bounds.

Using a Development Branch (rarely required)

If you are a user rather than developer it should almost never be required for you to check out a package (or, dev it in the package manager). When developers make changes to - say - ACEpotentials.jl they will always immediately tag another version and then you can adjust your version bounds in your project to update as well as enforce which version to use. However a developer would frequently do this, and occasionally it might be required when iterating between a user and developer for testing. There are multiple ways to achieve this; the following is our recommended procedure:

Suppose for example that a development branch co/dev of ACE1.jl is needed in a project project. Then one should perform the following steps:

  • Make sure ACE1 has been added to project/Project.toml
  • In a separate folder, /path/to/ , clone ACE1.jl
cd /path/to
 git clone git@github.com:ACEsuit/ACE1.jl.git
-git checkout co/dev

so that the repo will now live in /path/to/ACE1.jl

  • Go to and activate project, then in a Julia REPL switch to the package manager ] and execute
dev /path/to/ACE1.jl

This will replace the ACE1 package in the Manifest with the version that lives in /path/to/ACE1.jl

Later on, when you want to go back to the standad Pkg versin control you can simply free ACE1.

Further Notes

  • The Project.toml should always be committed to your project git repo. Whether Manifest.toml is also committed is a matter of taste or context. Tracking the Manifest will (normally) ensure future compatibility since it allows you to reconstruct the precise Julia environment that was used when the Manifest was created.
  • https://pkgdocs.julialang.org/v1/
  • https://pkgdocs.julialang.org/v1/compatibility/
+git checkout co/dev

so that the repo will now live in /path/to/ACE1.jl

dev /path/to/ACE1.jl

This will replace the ACE1 package in the Manifest with the version that lives in /path/to/ACE1.jl

Later on, when you want to go back to the standad Pkg versin control you can simply free ACE1.

Further Notes

diff --git a/dev/gettingstarted/saving-and-loading/index.html b/dev/gettingstarted/saving-and-loading/index.html index a96d61e9..db8df085 100644 --- a/dev/gettingstarted/saving-and-loading/index.html +++ b/dev/gettingstarted/saving-and-loading/index.html @@ -9,4 +9,4 @@ ACEpotentials v0.6.3 ACEfit v0.1.4 -If you have problems using this potential, pin your installation to above versions.

If you have problems with the potential, you can use the given version numbers to build an installation that should have the potential working.

By default the loaded potential is in JuLIP style format. To load a new ACEmd style ACEpotential you can give keyword new_format=true

potential = load_potential("my-potential-file.json"; new_format=true)

Exporting Potentials for Other Programs

LAMMPS export is described in section ACEpotentials potentials in LAMMPS.

+If you have problems using this potential, pin your installation to above versions.

If you have problems with the potential, you can use the given version numbers to build an installation that should have the potential working.

By default the loaded potential is in JuLIP style format. To load a new ACEmd style ACEpotential you can give keyword new_format=true

potential = load_potential("my-potential-file.json"; new_format=true)

Exporting Potentials for Other Programs

LAMMPS export is described in section ACEpotentials potentials in LAMMPS.

diff --git a/dev/index.html b/dev/index.html index db69329b..975e0b54 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -Home · ACEpotentials.jl

ACEpotentials.jl Documentation

ACEpotentials.jl facilitates the creation and use of atomic cluster expansion (ACE) interatomic potentials. For a quick start, we recommend reading the installation instructions, followed by the tutorials.

ACE models are defined in terms of body-ordered invariant features of atomic environments. For mathematical details, see this brief introduction and the references listed below.

Overview

ACEpotentials.jl ties together several Julia packages implementing different aspects of ACE modelling and fitting and provides some additional fitting and analysis tools for convenience. For example, it provides routines for parsing and manipulating the data to which interatomic potentials are fit (total energies, forces, virials, etc). Moreover, it integrates ACE potentials with the JuliaMolSim eco-system. These pages document ACEpotentialstogether with the relevant parts of the wider ecosystem.

References

  • Drautz, R.: Atomic cluster expansion for accurate and transferable interatomic potentials. Phys. Rev. B Condens. Matter. 99, 014104 (2019). [DOI] [arxiv]

  • G. Dusson, M. Bachmayr, G. Csanyi, S. Etter, C. van der Oord, and C. Ortner. Atomic cluster expansion: Completeness, efficiency and stability. J. Comp. Phys. 454, 110946, 2022. [DOI] [arxiv]

  • W. C. Witt, C. van der Oord, E. Gelžinyté, T. Järvinen, A. Ross, J. P. Darby, C. H. Ho, W. J. Baldwin, M. Sachs, J. Kermode, N. Bernstein, G. Csányi, and C. Ortner. ACEpotentials.jl: A Julia Implementation of the Atomic Cluster Expansion. J. Chem. Phys., 159:164101, 2023. [DOI] [arxiv]

Key Dependencies

+Home · ACEpotentials.jl

ACEpotentials.jl Documentation

ACEpotentials.jl facilitates the creation and use of atomic cluster expansion (ACE) interatomic potentials. For a quick start, we recommend reading the installation instructions, followed by the tutorials.

ACE models are defined in terms of body-ordered invariant features of atomic environments. For mathematical details, see this brief introduction and the references listed below.

Overview

ACEpotentials.jl ties together several Julia packages implementing different aspects of ACE modelling and fitting and provides some additional fitting and analysis tools for convenience. For example, it provides routines for parsing and manipulating the data to which interatomic potentials are fit (total energies, forces, virials, etc). Moreover, it integrates ACE potentials with the JuliaMolSim eco-system. These pages document ACEpotentialstogether with the relevant parts of the wider ecosystem.

References

  • Drautz, R.: Atomic cluster expansion for accurate and transferable interatomic potentials. Phys. Rev. B Condens. Matter. 99, 014104 (2019). [DOI] [arxiv]

  • G. Dusson, M. Bachmayr, G. Csanyi, S. Etter, C. van der Oord, and C. Ortner. Atomic cluster expansion: Completeness, efficiency and stability. J. Comp. Phys. 454, 110946, 2022. [DOI] [arxiv]

  • W. C. Witt, C. van der Oord, E. Gelžinyté, T. Järvinen, A. Ross, J. P. Darby, C. H. Ho, W. J. Baldwin, M. Sachs, J. Kermode, N. Bernstein, G. Csányi, and C. Ortner. ACEpotentials.jl: A Julia Implementation of the Atomic Cluster Expansion. J. Chem. Phys., 159:164101, 2023. [DOI] [arxiv]

Key Dependencies

diff --git a/dev/literate_tutorials/basic_julia_workflow/index.html b/dev/literate_tutorials/basic_julia_workflow/index.html index cc9774c3..2fbbd5ea 100644 --- a/dev/literate_tutorials/basic_julia_workflow/index.html +++ b/dev/literate_tutorials/basic_julia_workflow/index.html @@ -47,77 +47,63 @@ [ Info: Assembling linear problem. [ Info: - Creating feature matrix with size (1770, 270). [ Info: - Beginning assembly with processor count: 1. - Progress: 3%|█▎ | ETA: 0:08:02 Progress: 18%|███████▌ | ETA: 0:01:24 Progress: 23%|█████████▍ | ETA: 0:01:06 Progress: 27%|███████████▏ | ETA: 0:00:54 Progress: 32%|█████████████ | ETA: 0:00:45 Progress: 36%|██████████████▉ | ETA: 0:00:38 Progress: 41%|████████████████▊ | ETA: 0:00:33 Progress: 45%|██████████████████▋ | ETA: 0:00:28 Progress: 50%|████████████████████▌ | ETA: 0:00:24 Progress: 55%|██████████████████████▍ | ETA: 0:00:21 Progress: 59%|████████████████████████▎ | ETA: 0:00:18 Progress: 64%|██████████████████████████▏ | ETA: 0:00:15 Progress: 68%|████████████████████████████ | ETA: 0:00:13 Progress: 73%|█████████████████████████████▉ | ETA: 0:00:11 Progress: 77%|███████████████████████████████▋ | ETA: 0:00:09 Progress: 82%|█████████████████████████████████▌ | ETA: 0:00:07 Progress: 86%|███████████████████████████████████▍ | ETA: 0:00:05 Progress: 91%|█████████████████████████████████████▎ | ETA: 0:00:03 Progress: 95%|███████████████████████████████████████▏ | ETA: 0:00:02 Progress: 100%|█████████████████████████████████████████| Time: 0:00:32 + Progress: 3%|█▎ | ETA: 0:07:33 Progress: 9%|███▊ | ETA: 0:02:39 Progress: 14%|█████▋ | ETA: 0:01:45 Progress: 18%|███████▌ | ETA: 0:01:18 Progress: 23%|█████████▍ | ETA: 0:01:01 Progress: 27%|███████████▏ | ETA: 0:00:50 Progress: 32%|█████████████ | ETA: 0:00:42 Progress: 36%|██████████████▉ | ETA: 0:00:35 Progress: 41%|████████████████▊ | ETA: 0:00:30 Progress: 45%|██████████████████▋ | ETA: 0:00:26 Progress: 50%|████████████████████▌ | ETA: 0:00:22 Progress: 55%|██████████████████████▍ | ETA: 0:00:19 Progress: 59%|████████████████████████▎ | ETA: 0:00:17 Progress: 64%|██████████████████████████▏ | ETA: 0:00:14 Progress: 68%|████████████████████████████ | ETA: 0:00:12 Progress: 73%|█████████████████████████████▉ | ETA: 0:00:10 Progress: 77%|███████████████████████████████▋ | ETA: 0:00:08 Progress: 82%|█████████████████████████████████▌ | ETA: 0:00:06 Progress: 92%|█████████████████████████████████████▉ | ETA: 0:00:02 Progress: 97%|███████████████████████████████████████▊ | ETA: 0:00:01 Progress: 100%|█████████████████████████████████████████| Time: 0:00:30 [ Info: - Assembly completed. [ Info: Assembling full weight vector. Progress: 3%|█▎ | ETA: 0:00:04 Progress: 100%|█████████████████████████████████████████| Time: 0:00:00 Iter Function value Gradient norm 0 4.531070e+03 2.176975e+03 - * time: 0.01811695098876953 + * time: 0.015491008758544922 1 4.511962e+03 3.381033e+02 - * time: 0.9834449291229248 + * time: 0.992671012878418 2 3.126360e+03 4.498989e+02 - * time: 0.9959418773651123 + * time: 1.005924940109253 3 3.075386e+03 3.787742e+02 - * time: 1.004356861114502 + * time: 1.0146820545196533 4 3.042578e+03 3.110060e+02 - * time: 1.0086679458618164 + * time: 1.0191349983215332 5 2.996447e+03 1.577183e+02 - * time: 1.013443946838379 + * time: 1.0235769748687744 6 2.956635e+03 1.426538e+02 - * time: 1.0175349712371826 + * time: 1.027940034866333 7 2.904828e+03 5.021431e+02 - * time: 1.023725986480713 + * time: 1.0343999862670898 8 2.633319e+03 3.264234e+03 - * time: 1.031831979751587 - 9 2.132198e+03 9.266793e+02 - * time: 1.0380120277404785 - 10 1.305131e+03 2.650595e+01 - * time: 1.0520269870758057 - 11 1.300301e+03 1.728293e+02 - * time: 1.0601599216461182 - 12 1.136214e+03 1.788392e+03 - * time: 1.0663809776306152 - 13 9.266012e+02 1.724255e+03 - * time: 1.0724689960479736 - 14 8.683949e+02 8.369342e+02 - * time: 1.0785119533538818 - 15 8.542060e+02 1.201551e+01 - * time: 1.0825278759002686 - 16 8.460812e+02 6.359867e+02 - * time: 1.0886340141296387 - 17 8.383413e+02 2.347904e+02 - * time: 1.0947620868682861 - 18 8.375127e+02 1.452580e+01 - * time: 1.1007380485534668 - 19 8.374630e+02 3.586540e+00 - * time: 1.1066958904266357 - 20 8.374628e+02 8.463511e-02 - * time: 1.1107800006866455 - 21 8.374628e+02 1.338073e-04 - * time: 1.1168689727783203 - 22 8.374628e+02 6.335823e-06 - * time: 1.1208829879760742 - 23 8.374628e+02 2.930268e-05 - * time: 1.1250300407409668 - 24 8.374628e+02 5.257466e-05 - * time: 1.1290209293365479 - 25 8.374628e+02 1.233950e-05 - * time: 1.1349389553070068 - 26 8.374628e+02 4.329790e-06 - * time: 1.1409549713134766 - 27 8.374628e+02 2.312466e-05 - * time: 1.1489129066467285 - 28 8.374628e+02 3.107526e-05 - * time: 1.1589128971099854 - 29 8.374628e+02 7.533624e-06 - * time: 1.1650478839874268 - 30 8.374628e+02 2.602438e-06 - * time: 1.1969640254974365 - 31 8.374628e+02 2.179592e-05 - * time: 1.2761509418487549 - 32 8.374628e+02 3.491240e-06 - * time: 1.2802250385284424 + * time: 1.042922019958496 + 9 2.132198e+03 9.266791e+02 + * time: 1.0493199825286865 + 10 1.305131e+03 2.650596e+01 + * time: 1.0638530254364014 + 11 1.300301e+03 1.728341e+02 + * time: 1.072309970855713 + 12 1.136213e+03 1.788406e+03 + * time: 1.0787079334259033 + 13 9.266028e+02 1.724264e+03 + * time: 1.0849158763885498 + 14 8.683957e+02 8.369458e+02 + * time: 1.0911190509796143 + 15 8.542065e+02 1.202458e+01 + * time: 1.0952808856964111 + 16 8.460816e+02 6.359850e+02 + * time: 1.1014549732208252 + 17 8.383414e+02 2.348007e+02 + * time: 1.1076538562774658 + 18 8.375127e+02 1.452398e+01 + * time: 1.1139190196990967 + 19 8.374630e+02 3.587759e+00 + * time: 1.1201109886169434 + 20 8.374628e+02 8.462346e-02 + * time: 1.1243228912353516 + 21 8.374628e+02 1.975340e-04 + * time: 1.1306428909301758 + 22 8.374628e+02 4.682667e-05 + * time: 1.1368529796600342 + 23 8.374628e+02 9.691217e-06 + * time: 1.143190860748291 + 24 8.374628e+02 2.150332e-05 + * time: 1.1474409103393555 + 25 8.374628e+02 5.243516e-06 + * time: 1.1515898704528809 * Status: success (objective increased between iterations) * Candidate solution @@ -127,17 +113,17 @@ Algorithm: L-BFGS * Convergence measures - |x - x'| = 4.39e-10 ≤ 1.0e-08 - |x - x'|/|x'| = 3.35e-12 ≰ 0.0e+00 - |f(x) - f(x')| = 1.43e-06 ≰ 0.0e+00 - |f(x) - f(x')|/|f(x')| = 1.71e-09 ≰ 0.0e+00 - |g(x)| = 3.49e-06 ≰ 0.0e+00 + |x - x'| = 9.30e-09 ≤ 1.0e-08 + |x - x'|/|x'| = 7.09e-11 ≰ 0.0e+00 + |f(x) - f(x')| = 3.15e-06 ≰ 0.0e+00 + |f(x) - f(x')|/|f(x')| = 3.76e-09 ≰ 0.0e+00 + |g(x)| = 5.24e-06 ≰ 0.0e+00 * Work counters Seconds run: 1 (vs limit Inf) - Iterations: 32 - f(x) calls: 168 - ∇f(x) calls: 168

We can display an error table as follows:

@info("Training Error Table")
+    Iterations:    25
+    f(x) calls:    96
+    ∇f(x) calls:   96

We can display an error table as follows:

@info("Training Error Table")
 err_train = ACEpotentials.linear_errors(train_data, model; weights=weights);
[ Info: Training Error Table
 [ Info: RMSE Table
 ┌────────────┬─────────┬──────────┬─────────┐
@@ -178,4 +164,4 @@
 └────────────┴─────────┴──────────┴─────────┘

If we want to save the fitted potentials to disk to later use we can simply save the hyperparameters and the parameters. At the moment this must be done manually but a more complete and convenient interface for this will be provided, also adding various sanity checks.

using JSON
 open("TiAl_model.json", "w") do f
 	 JSON.print(f, Dict("hyperparams" => hyperparams, "params" => model.ps))
-end

To load the model back from disk it is safest to work within the same Julia project, i.e. the same version of all packages; ideally the the Manifest should not be changed. One then generates the model again, loads the parameters from disk and then sets them in the model. Again, this will be automated in the future.

Finally, we delete the model to clean up.

rm("TiAl_model.json")

This page was generated using Literate.jl.

+end

To load the model back from disk it is safest to work within the same Julia project, i.e. the same version of all packages; ideally the the Manifest should not be changed. One then generates the model again, loads the parameters from disk and then sets them in the model. Again, this will be automated in the future.

Finally, we delete the model to clean up.

rm("TiAl_model.json")

This page was generated using Literate.jl.

diff --git a/dev/literate_tutorials/dataset_analysis/2f993c5b.svg b/dev/literate_tutorials/dataset_analysis/2f993c5b.svg new file mode 100644 index 00000000..514b68be --- /dev/null +++ b/dev/literate_tutorials/dataset_analysis/2f993c5b.svg @@ -0,0 +1,854 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/dev/literate_tutorials/dataset_analysis/eadf077c.svg b/dev/literate_tutorials/dataset_analysis/eadf077c.svg deleted file mode 100644 index 50c13b1f..00000000 --- a/dev/literate_tutorials/dataset_analysis/eadf077c.svg +++ /dev/null @@ -1,854 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/dev/literate_tutorials/dataset_analysis/ed339471.svg b/dev/literate_tutorials/dataset_analysis/ed339471.svg deleted file mode 100644 index 9d48e3d5..00000000 --- a/dev/literate_tutorials/dataset_analysis/ed339471.svg +++ /dev/null @@ -1,361 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/dev/literate_tutorials/dataset_analysis/6ae02bf1.svg b/dev/literate_tutorials/dataset_analysis/edefcc2f.svg similarity index 57% rename from dev/literate_tutorials/dataset_analysis/6ae02bf1.svg rename to dev/literate_tutorials/dataset_analysis/edefcc2f.svg index d844faba..48919e19 100644 --- a/dev/literate_tutorials/dataset_analysis/6ae02bf1.svg +++ b/dev/literate_tutorials/dataset_analysis/edefcc2f.svg @@ -1,321 +1,321 @@ - + - + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/dev/literate_tutorials/dataset_analysis/f00e5a42.svg b/dev/literate_tutorials/dataset_analysis/f00e5a42.svg new file mode 100644 index 00000000..8dce2bbd --- /dev/null +++ b/dev/literate_tutorials/dataset_analysis/f00e5a42.svg @@ -0,0 +1,361 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/dev/literate_tutorials/dataset_analysis/index.html b/dev/literate_tutorials/dataset_analysis/index.html index d00d0084..9f58d148 100644 --- a/dev/literate_tutorials/dataset_analysis/index.html +++ b/dev/literate_tutorials/dataset_analysis/index.html @@ -15,7 +15,7 @@ xlabel = L"\theta", ylabel = "ADF", xlims = (0, π)) vline!([ eq_angle,], label = "109.5˚", lw=3) -plot(plt_rdf, plt_adf, layout = (2,1), size = (800, 400))Example block output

One way we can use these distribution functions is to look at fitted potentials relative to where data is given. But even before a potential is fitted we can illustrate some properties of the basis functions used in ACEpotentials. E.g. we can illustrate why we have chosen the distance transforms. First, we generate a default Si model and a second one with modified transform. Note that we are stripping the units from r_cut because ACEpotentials currently expects unitless values; implicitly understood as Å and eV.

r_cut_ul = ustrip(u"Å", r_cut)
+plot(plt_rdf, plt_adf, layout = (2,1), size = (800, 400))
Example block output

One way we can use these distribution functions is to look at fitted potentials relative to where data is given. But even before a potential is fitted we can illustrate some properties of the basis functions used in ACEpotentials. E.g. we can illustrate why we have chosen the distance transforms. First, we generate a default Si model and a second one with modified transform. Note that we are stripping the units from r_cut because ACEpotentials currently expects unitless values; implicitly understood as Å and eV.

r_cut_ul = ustrip(u"Å", r_cut)
 
 model1 = ace1_model(elements = [:Si,], order = 3,
                     totaldegree = 10, rcut = r_cut_ul)
@@ -40,7 +40,7 @@
                      yticks = [], xlims = (0, r_cut_ul))
 vline!([ustrip(rnn(:Si)),], label = L"r_{\rm nn}", lw=3)
 
-plot(plt_t, plt_rdf, layout=grid(2, 1, heights=[0.7, 0.3]), size = (800, 400))
Example block output

To finish this tutorial, we quickly demonstrate what happens when there is more than one chemical species present in a dataset.

tial_data, _, _ = ACEpotentials.example_dataset("TiAl_tutorial")
+plot(plt_t, plt_rdf, layout=grid(2, 1, heights=[0.7, 0.3]), size = (800, 400))
Example block output

To finish this tutorial, we quickly demonstrate what happens when there is more than one chemical species present in a dataset.

tial_data, _, _ = ACEpotentials.example_dataset("TiAl_tutorial")
 
 rdf = ACEpotentials.get_rdf(tial_data, r_cut)
 plt_TiTi = histogram(rdf[(:Ti, :Ti)], bins=100, xlabel = "", c = 1,
@@ -49,4 +49,4 @@
          ylabel = "RDF - TiAl", label = "", yticks = [], xlims = (0, r_cut_ul) )
 plt_AlAl = histogram(rdf[(:Al, :Al)], bins=100, xlabel = L"r [\AA]", c = 3,
          ylabel = "RDF - AlAl", label = "", yticks = [], xlims = (0, r_cut_ul), )
-plot(plt_TiTi, plt_TiAl, plt_AlAl, layout = (3,1), size = (700, 700))
Example block output

This page was generated using Literate.jl.

+plot(plt_TiTi, plt_TiAl, plt_AlAl, layout = (3,1), size = (700, 700))Example block output

This page was generated using Literate.jl.

diff --git a/dev/literate_tutorials/smoothness_priors/be0508a2.svg b/dev/literate_tutorials/smoothness_priors/b1992461.svg similarity index 88% rename from dev/literate_tutorials/smoothness_priors/be0508a2.svg rename to dev/literate_tutorials/smoothness_priors/b1992461.svg index 9c14b4c4..515ae9f6 100644 --- a/dev/literate_tutorials/smoothness_priors/be0508a2.svg +++ b/dev/literate_tutorials/smoothness_priors/b1992461.svg @@ -1,64 +1,64 @@ - + - + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/dev/literate_tutorials/smoothness_priors/8ee817d8.svg b/dev/literate_tutorials/smoothness_priors/bcc4472e.svg similarity index 86% rename from dev/literate_tutorials/smoothness_priors/8ee817d8.svg rename to dev/literate_tutorials/smoothness_priors/bcc4472e.svg index ceca7ab1..6d63e999 100644 --- a/dev/literate_tutorials/smoothness_priors/8ee817d8.svg +++ b/dev/literate_tutorials/smoothness_priors/bcc4472e.svg @@ -1,52 +1,52 @@ - + - + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/dev/literate_tutorials/smoothness_priors/caf73828.svg b/dev/literate_tutorials/smoothness_priors/e27fbf57.svg similarity index 87% rename from dev/literate_tutorials/smoothness_priors/caf73828.svg rename to dev/literate_tutorials/smoothness_priors/e27fbf57.svg index f72b2995..9616bbf0 100644 --- a/dev/literate_tutorials/smoothness_priors/caf73828.svg +++ b/dev/literate_tutorials/smoothness_priors/e27fbf57.svg @@ -1,56 +1,56 @@ - + - + - + - + - + - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/dev/literate_tutorials/smoothness_priors/index.html b/dev/literate_tutorials/smoothness_priors/index.html index 449e822f..6f1230ed 100644 --- a/dev/literate_tutorials/smoothness_priors/index.html +++ b/dev/literate_tutorials/smoothness_priors/index.html @@ -17,7 +17,7 @@ [ Info: Assembling linear problem. [ Info: - Creating feature matrix with size (1052, 223). [ Info: - Beginning assembly with processor count: 1. - Progress: 4%|█▌ | ETA: 0:03:13 Progress: 11%|████▋ | ETA: 0:01:11 Progress: 17%|███████ | ETA: 0:00:50 Progress: 23%|█████████▎ | ETA: 0:00:38 Progress: 28%|███████████▋ | ETA: 0:00:31 Progress: 34%|█████████████▉ | ETA: 0:00:26 Progress: 40%|████████████████▎ | ETA: 0:00:22 Progress: 45%|██████████████████▋ | ETA: 0:00:18 Progress: 51%|████████████████████▉ | ETA: 0:00:16 Progress: 57%|███████████████████████▎ | ETA: 0:00:13 Progress: 62%|█████████████████████████▌ | ETA: 0:00:11 Progress: 68%|███████████████████████████▉ | ETA: 0:00:09 Progress: 74%|██████████████████████████████▏ | ETA: 0:00:07 Progress: 79%|████████████████████████████████▌ | ETA: 0:00:06 Progress: 85%|██████████████████████████████████▊ | ETA: 0:00:04 Progress: 91%|█████████████████████████████████████▏ | ETA: 0:00:03 Progress: 96%|███████████████████████████████████████▌ | ETA: 0:00:01 Progress: 100%|█████████████████████████████████████████| Time: 0:00:28 + Progress: 4%|█▌ | ETA: 0:01:37 Progress: 9%|███▉ | ETA: 0:00:48 Progress: 15%|██████▎ | ETA: 0:00:33 Progress: 21%|████████▌ | ETA: 0:00:26 Progress: 26%|██████████▉ | ETA: 0:00:22 Progress: 32%|█████████████▏ | ETA: 0:00:18 Progress: 38%|███████████████▌ | ETA: 0:00:16 Progress: 43%|█████████████████▊ | ETA: 0:00:14 Progress: 49%|████████████████████▏ | ETA: 0:00:12 Progress: 53%|█████████████████████▋ | ETA: 0:00:11 Progress: 58%|████████████████████████ | ETA: 0:00:09 Progress: 64%|██████████████████████████▎ | ETA: 0:00:08 Progress: 70%|████████████████████████████▋ | ETA: 0:00:07 Progress: 75%|███████████████████████████████ | ETA: 0:00:05 Progress: 81%|█████████████████████████████████▎ | ETA: 0:00:04 Progress: 87%|███████████████████████████████████▋ | ETA: 0:00:03 Progress: 92%|█████████████████████████████████████▉ | ETA: 0:00:02 Progress: 98%|████████████████████████████████████████▎| ETA: 0:00:00 Progress: 100%|█████████████████████████████████████████| Time: 0:00:20 [ Info: - Assembly completed. [ Info: Assembling full weight vector.

A positive definite matrix P specifies a normal prior distribution in the Bayesian framework, but for the purpose of this tutorial it is maybe more intuitive to simply think of it as a regularisation operator. The regularised linear least squares problem is

\[ \| A c - y \|^2 + \lambda \| P c \|^2\]

where A is the design matrix, $y$ is the vector of observations, $c$ is the vector of parameters, and $\lambda$ is a regularisation parameter. The prior matrix $P$ is specified by the user. At present we support diagonal operators $P$. The diagonal elements of $P$ are the prior variances. The larger the prior variance, the smoother the fitted potential. Although not strictly true, we can think of each basis function as specified by a the parameters $(n_t, l_t)_{t = 1}^N$, where $N$ is the correlation-order. The corresponding prior matrix element must be a function of those $n_t, l_t$ values. We currently support three classes: algebraic, exponential and gaussian.

TODO: write down the precise definitions.

In the following we demonstrate the usage of algebraic and gaussian priors. The choices for σl, σn made here may seem "magical", but there is a good justification and we plan to automate this in future releases.

Pa2 = algebraic_smoothness_prior(model; p=2)
 Pa4 = algebraic_smoothness_prior(model; p=4)
@@ -51,14 +51,14 @@
     plot!(plt_dim, D[(:Si, :Si)]..., label = l, lw=2)
 end
 vline!([r_nn,], lw=2, ls=:dash, label = L"r_{\rm nn}")
-plt_dim
Example block output

Next, we look at a trimer curve. This is generated using ACEpotentials.trimers. Both the Id and Algebraic(2) regularised models contain fairly significant oscillations while the Algebraic(4) and Gaussian models are much smoother. In addition, it appears that the Gaussian regularised model is somewhat more physically realistic on this slice with high energy at small bond-angles (thought the low energy at angle π seems somewhat strange).

plt_trim = plot(legend = :topright, xlabel = L"\theta", ylabel = "E [eV]",
+plt_dim
Example block output

Next, we look at a trimer curve. This is generated using ACEpotentials.trimers. Both the Id and Algebraic(2) regularised models contain fairly significant oscillations while the Algebraic(4) and Gaussian models are much smoother. In addition, it appears that the Gaussian regularised model is somewhat more physically realistic on this slice with high energy at small bond-angles (thought the low energy at angle π seems somewhat strange).

plt_trim = plot(legend = :topright, xlabel = L"\theta", ylabel = "E [eV]",
                xlims = (0, pi), ylims = (-0.6, 0.2))
 for l in labels
     D = ACEpotentials.trimers(pots[l], [:Si,], r_nn*u"Å",  r_nn*u"Å")
     plot!(plt_trim, D[(:Si, :Si, :Si)]..., label = l, lw=2)
 end
 vline!(plt_trim, [1.90241,], lw=2, label = "equilibrium angle")
-plt_trim
Example block output

Finally, we plot a decohesion curve, which contains more significant many-body effects. Arguably, none of our potentials perform very well on this test. Usually larger datasets, and longer cutoffs help in this case.

using AtomsBuilder  # gives us `bulk`
+plt_trim
Example block output

Finally, we plot a decohesion curve, which contains more significant many-body effects. Arguably, none of our potentials perform very well on this test. Usually larger datasets, and longer cutoffs help in this case.

using AtomsBuilder  # gives us `bulk`
 
 at0 = bulk(:Si, cubic=true)
 plt_dec = plot(legend = :topright, xlabel = L"r [\AA]", ylabel = "strain [eV/Å]",
@@ -67,4 +67,4 @@
     rr, E, dE = ACEpotentials.decohesion_curve(at0, pots[l])
     plot!(plt_dec, ustrip.(rr), ustrip.(dE), label = l, lw=2)
 end
-plt_dec
Example block output

This page was generated using Literate.jl.

+plt_decExample block output

This page was generated using Literate.jl.

diff --git a/dev/tutorials/index.html b/dev/tutorials/index.html index ca5c1f1c..939dc623 100644 --- a/dev/tutorials/index.html +++ b/dev/tutorials/index.html @@ -24,4 +24,4 @@ * [TiAl Potential (ACEpotentials)](../literate_tutorials/ACEpotentials_TiAl.md) * [TiAl Potential (command line JSON)](../outdated/first_example_json.md) ---> +--> diff --git a/dev/tutorials/lammps/index.html b/dev/tutorials/lammps/index.html index 2f2b2399..32d1c1d7 100644 --- a/dev/tutorials/lammps/index.html +++ b/dev/tutorials/lammps/index.html @@ -19,4 +19,4 @@ pair_coeff 1 3 table potential_pairpot.table I_Pb pair_coeff 2 2 table potential_pairpot.table Cs_Cs pair_coeff 2 3 table potential_pairpot.table Cs_Pb -pair_coeff 3 3 table potential_pairpot.table Pb_Pb

where we are using the ordering I, Cs, Pb.

+pair_coeff 3 3 table potential_pairpot.table Pb_Pb

where we are using the ordering I, Cs, Pb.

diff --git a/dev/tutorials/molly/index.html b/dev/tutorials/molly/index.html index e80f5b52..b38740d2 100644 --- a/dev/tutorials/molly/index.html +++ b/dev/tutorials/molly/index.html @@ -36,4 +36,4 @@ dt=1.0u"fs", coupling=AndersenThermostat(temp, 1.0u"ps"), )

After this you can run the simulation by

# Perform MD for 1000 steps
-simulate!(sys, simulator, 1000)
+simulate!(sys, simulator, 1000) diff --git a/dev/tutorials/python_ase/index.html b/dev/tutorials/python_ase/index.html index 6d13fd68..2f0b8bcb 100644 --- a/dev/tutorials/python_ase/index.html +++ b/dev/tutorials/python_ase/index.html @@ -2,4 +2,4 @@ python-ase · ACEpotentials.jl

python-ase

An ACEpotentials.jl model can be used in python as an ase calculator. To do this, you will need to install two python packages, julia and pyjulip as documented on the installation page.

Python reads the potential.json file directly. To load an ACE potential as an ase calculator, use the following syntax:

import pyjulip
 calc = pyjulip.ACE1("first_potential.json")

Using that calculator, we can then evaluatuate energies, forces, etc, e.g., 

ats = ase.io.read('atoms_object.xyz')
 ats.calc = calc
-print(ats.get_potential_energy())

See the ase documentation for more details.

Another option: ASE's LAMMPSlib calculator

Alternatively, to avoid direct Julia-Python interaction, one can export to LAMMPS (see LAMMPS) and utilize ASE's LAMMPSlib calculator.

+print(ats.get_potential_energy())

See the ase documentation for more details.

Another option: ASE's LAMMPSlib calculator

Alternatively, to avoid direct Julia-Python interaction, one can export to LAMMPS (see LAMMPS) and utilize ASE's LAMMPSlib calculator.

diff --git a/dev/tutorials/scripting/index.html b/dev/tutorials/scripting/index.html index 6c880971..28942450 100644 --- a/dev/tutorials/scripting/index.html +++ b/dev/tutorials/scripting/index.html @@ -1,4 +1,4 @@ Basic Shell Workflow · ACEpotentials.jl

Basic Shell Workflow

This short introduces a basic workflow where models are specified via JSON files and model fitting is achieved via a shell script.

At the start of a new project we

  • create a project folder
  • activate a Julia project in that folder
  • add ACEpotentials to the Julia project 
mkdir myace
 cd myace
-julia --project=. -e 'using Pkg; Pkg.add("ACEpotentials")'

Next we can use an ACEpotentials utility to copy a script for running the model fitting, and an example model specification file. 

julia --project=. -e 'using ACEpotentials; ACEpotentials.copy_runfit(@__DIR__())'

This should create two new files in the myace folder:

  • runfit.jl
  • example_params.json

Copy (or move) the example_params.json file to a new filename, e.g. 

cp example_params.json myace_params_1.json

then edit that file to specify the model hyperparameters, the fitting method, and the path to the dataset (or, datasets if validation and or test sets are also provided). To produce a fit, use 

julia --project=. runfit.jl -p myace_params_1.json

This will produce an output file e.g. results.jl (the output filename can be changed in the input json), which contains the model specification, the fitted model parameters, and a dictionary of computed errors (rmse, mae).

+julia --project=. -e 'using Pkg; Pkg.add("ACEpotentials")'

Next we can use an ACEpotentials utility to copy a script for running the model fitting, and an example model specification file. 

julia --project=. -e 'using ACEpotentials; ACEpotentials.copy_runfit(@__DIR__())'

This should create two new files in the myace folder:

  • runfit.jl
  • example_params.json

Copy (or move) the example_params.json file to a new filename, e.g. 

cp example_params.json myace_params_1.json

then edit that file to specify the model hyperparameters, the fitting method, and the path to the dataset (or, datasets if validation and or test sets are also provided). To produce a fit, use 

julia --project=. runfit.jl -p myace_params_1.json

This will produce an output file e.g. results.jl (the output filename can be changed in the input json), which contains the model specification, the fitted model parameters, and a dictionary of computed errors (rmse, mae).