Extending ACEfriction

New matrix-model types can be defined in other packages, on top of the models provided here. A matrix model is a subtype of ACEfriction.MatrixModels.MatrixModel that produces the diffusion matrix ${\bm \Sigma}$ (one sparse N×N block matrix per replica) of a configuration, and its un-contracted basis for fitting. The names below are the public extension API of ACEfriction.MatrixModels (declared public, not exported).

What a model type provides

  • the fields n_rep, inds::SiteInds, id, and its site-model dictionaries onsite and/or offsite: the generic parameter plumbing (params, set_params!, nparams, scaling, …) reads these;
  • methods for matrix(M, at; filter, T) and basis(M, at; join_sites, filter, T); basis returns one sparse block matrix per basis function such that Σ[r] = Σ_k c[k][r] * B[k];
  • a method for randf(M, Σ) (random force with covariance ${\bm \Gamma}$);
  • write_dict(M) and read_dict(::Val{:<id>}, D) (ACEbase FIO) for serialization;
  • a sigma_structure method if its friction tensor is not ${\bm \Gamma} = {\bm \Sigma}{\bm \Sigma}^T$ of a general block matrix (the default). It selects both the friction-tensor assembly and the layout of the fitting data, so a model that declares it is fitted with flux_assemble / FluxFrictionModel without further code.

Building blocks

Atom-centred pair models are built from a bond basis (offsite_linbasis) and one OffSiteModel per species pair, and assembled with the same fast per-centre evaluation as the built-in coupling schemes:

ACEfriction.MatrixModels.offsite_models — Function
offsite_models(bb::BondBasis, cutoff, species_friction, n_rep;
               speciescoupling = SpeciesUnCoupled()) -> OffSiteModels

One OffSiteModel (bond basis bb, cutoff, n_rep replicas, random coefficients) per species pair of species_friction: all ordered pairs for SpeciesUnCoupled(), unordered (sorted) pairs for SpeciesCoupled().

source
ACEfriction.MatrixModels.offsite_matrix — Function
offsite_matrix(offsite, at; speciescoupling = SpeciesUnCoupled(),
               self_images = ExcludeSelfImages(), filter = (_, _) -> true, T = Float64)

Atom-centred pair blocks of the offsite models offsite (SphericalCutoff) on the system at: one sparse N×N block matrix per replica whose block (i, j), for every neighbour j of i (subject to filter and self_images), is the block of the pair's model evaluated on the environment of i with bond partner j. The diagonal is empty unless periodic self-images are included. Uses the fast per-centre evaluation (all bonds of a centre share its neighbour data; see SphericalCutoff's partner_in_env).

source
ACEfriction.MatrixModels.offsite_basis — Function
offsite_basis(offsite, at; inds = site_inds(offsite), speciescoupling = SpeciesUnCoupled(),
              self_images = ExcludeSelfImages(), filter = (_, _) -> true, T = Float64)

Un-contracted counterpart of offsite_matrix: one sparse N×N block matrix per basis function (index ranges inds), such that Σ_k c[k][r] B[k] is the r-th matrix of offsite_matrix.

source
ACEfriction.MatrixModels.site_inds — Function
site_inds(offsite) -> SiteInds
site_inds(onsite, offsite) -> SiteInds

Basis-function index ranges of the site models (per species / species pair), in the order used by params / basis.

source
ACEfriction.MatrixModels.SigmaStructure — Type
SigmaStructure

How a matrix model's friction tensor is formed from its diffusion matrix Σ (per replica); selects the friction-tensor assembly and the layout of the fitting data:

  • FullSigma(): Γ = Σ Σᵀ with Σ a general sparse N×N block matrix (the default; e.g. CWCMatrixModel);
  • PairSigma(): pairwise coupling, Γij = Σij Σjiᵀ (i ≠ j) and Γii = Σj Σij Σ_ijᵀ (PWCMatrixModel);
  • DiagonalSigma(): block-diagonal Σ, Γii = Σii Σ_iiᵀ (OnsiteOnlyMatrixModel).
source
ACEfriction.MatrixModels.n_rep — Function
n_rep(M::MatrixModel)
n_rep(models::Union{OnSiteModels, OffSiteModels})

Number of replicas (independent linear maps per basis function).

source

test/test_extension_api.jl defines a complete example model type (atom-centred pair blocks only) using nothing but this API, and checks it against the built-in models, serialization and fitting.