Types and Functions

struct State the main type for states of input variables (particles). This type is intended only for storing of information but no arithmetic should be performed on it. For the latter, we have the DState.

struct DState: A State-like variable but acting like vector with arithmetic operations defined on it, while State acts more like a fixed object that cannot be manipulated. The main application of DState is as a derivative of a State; see also dstate_type, ``

struct ACEConfig: The canonical implementation of an AbstractConfiguration. Just wraps a Vector{<: AbstractState}

mutable struct PIBasis: implementation of a permutation-invariant basis based on the density projection trick.

The standard constructor is

PIBasis(basis1p, N, D, maxdeg)

• basis1p : a one-particle basis
• N : maximum interaction order
• D : an abstract degee specification, e.g., SparsePSHDegree
• maxdeg : the maximum polynomial degree as measured by D

struct SymmetricBasis

Constructors

Option 1: pass a OneParticleBasis

SymmetricBasis(φ, symgrp, basis1p, Bsel)
SymmetricBasis(φ, basis1p, Bsel)   # uses default symgrp = O3()

will first construct a PIBasis from these inputs and then call the second constructor.

Option 1: pass a PIBasis

SymmetricBasis(φ, symgrp, pibasis)
SymmetricBasis(φ, pibasis)

If the PIbasis is already available, this directly constructs a resulting SymmetricBasis; all possible permutation-invariant basis functions will be symmetrised and then reduced to a basis (rather than spanning set)

struct LinearACEModel: linear model for symmetric properties in terms of a SymmetricBasis.

The typical way to construct a linear model is to first construct a basis basis, some default coefficients c and then call

model = LinearACEModel(basis, c)

Multiple properties

If c::Vector{<: Number} then the output of the model will be the property encoded in the basis. But one can also use a single basis to produce multiple properties (with different coefficients). This can be achieved by simply supplying c::Vector{SVector{N, T}} where N will then be the number of properties.

Rn1pBasis

One-particle basis of the form $R_n(r_{ij})$, i.e., no dependence on species or on $l$.

This does two things: (1) translates the TransformedPolys into a valid one-particle basis; and (2) treat it as having vectorial input, i.e. value is scalar but gradient is vectorial.

The default symbols are :rr for the state and :n for the index of the basis function.

Ylm1pBasis

One-particle basis component of the form

\[\phi_{lm}({\bm r}) = Y_l^m(\hat{\br r})\]

Fundamental building block of ACE basis sets of the form

\[ R_{nl}^{\mu_i, \mu_j}(r_{ij}) Y_l^m(\hat{\bm r})\]

This type basically just translates the SHBasis into a valid one-particle basis.

Scal1pBasis

One-particle basis of the form $P_n(x_i)$ for a general scalar, invariant input x. This type basically just translates the TransformedPolys into a valid one-particle basis.

function init1pspec! : initialize the specification of the 1-particle basis, generates all possible 1-p basis functions, sorted by degree.

struct O3 <: SymmetryGroup : this is the default symmetry group; describing the action of a single O3 group on the basis.

Standard Usage:

O3()

will create an O3{:l, :m} instance, i.e. the group will expect the symbols :l, :m in the relevant 1p basis.

But if the Ylm component of the 1p basis uses different symbols then one can tell O3 this via O3(lsym, rsym). E.g. if the variable w.r.t. which we symmetrize is a spin s then we might call it O3(:ls, :ms). The main thing to remember is that the symbols in the Ylm basis and in the O3 basis must match.

struct O3O3 <: SymmetryGroup : This type implements the $O(3) \otimes O(3)$ symmetry group. This is useful when a particle has two euclidean vector attributes, say ${\bm r}$ and ${\bm s}$ and the action of the group on the pair is

\[ (Q_r, Q_s)[ (\boldsymbol{r}, \boldsymbol{s}) ] = (Q_r \boldsymbol{r}, Q_s \boldsymbol{s})\]

A canA canonical application is magnetism: it is known that spin-orbit coupling is a very weak effect. By ignoring it, i.e., letting positions and spins rotate independently of one another, one makes a small modelling error. This leads precisely to the $O(3) \otimes O(3)$ symmetry.

To construct this group, use

symgrp = O3(:lr, :mr) ⊗ O3(:ls, :ms)

or replace those symbols with the appropriate symbols used to specify the corresponding Ylm1pbasis objects.

No constraints on the basis - this selects that largest possible basis subject to additional constraints baked into the one-particle basis. In practise this should be equivalent to a naive max-norm basis selection, and likely never used in practise.

struct SimpleSparseBasis:

The most basic form of a sparse basis selection, using the total degree. Only the maximum correlation order and maximum degree may be specified. This should primarily be used for testing. Construct it via

SimpleSparseBasis(maxorder, maxdegree)

Note that maxdegree is a basic total degree.

SparseBasis: basic implementation of an AbstractSparseBasis.

• maxorder : maximum correlation order
• p : degree (level) is computed via a weighted p-norm of the 1p basis function degrees
• maxlevels : for each order ord, maxlevels[ord] is the maximum level for basis functions of that order. if maxlevels[ord] is not specified, then maxlevels["default"] is the fallback.
• weight : specify weights for the different channels of the 1p basis functions, e.g., for an Rn * Ylm basis, one might specify weight[:n] = 1 and weight[:l] = 2 to have more radial and fewer angular basis functions.