From 1140212b1246c750a2d29f8a55e29dc945709870 Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Mon, 4 Nov 2024 22:33:25 +0000 Subject: [PATCH] build based on 5218d5b --- dev/.documenter-siteinfo.json | 2 +- dev/fitting-eft/index.html | 2 +- dev/fitting-mbdpd/index.html | 2 +- dev/function-manual/index.html | 2 +- dev/index.html | 2 +- dev/installation/index.html | 2 +- dev/overview/index.html | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 4536429..9191cd0 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.11.1","generation_timestamp":"2024-11-01T20:58:12","documenter_version":"1.7.0"}} \ No newline at end of file +{"documenter":{"julia_version":"1.11.1","generation_timestamp":"2024-11-04T22:33:20","documenter_version":"1.7.0"}} \ No newline at end of file diff --git a/dev/fitting-eft/index.html b/dev/fitting-eft/index.html index fe870d3..cfb186f 100644 --- a/dev/fitting-eft/index.html +++ b/dev/fitting-eft/index.html @@ -45,4 +45,4 @@ set_params!(fm, c)

Evaluating the Friction Model

The trained friction model can be used to evaluate the friction tensor ${\bm \Gamma}$ and diffusion coeccifient matrix ${\bm \Sigma}$ at configurations as follows 

at = fdata["test"][1].atoms # extract atomic configuration from the test set
 Gamma(fm, at) # evaluate the friction tensor
 Σ = Sigma(fm, at) # evaluate the diffusion coeffcient matrix

To simulate a Langevin equation, typically, both the friction coefficient and the diffusion coefficient matrix must be evaluated. Instead of evaluating them seperately it is more efficient to first evaluate the diffusion coefficient matrix and then evaluate the friction tensor from the the pre-computed diffusion coefficient matrix:

Σ = Sigma(fm, at) # evaluate the diffusion coeffcient matrix
-Gamma(fm, Σ) # compute the friction tensor from the pre-computeed diffusion coefficient matrix.

The diffusion coefficient matrix $\Sigma$ can also be used to efficiently generate Gaussian pseudo random numbers ${\rm Normal}(0,{\bf \Gamma})$ as 

R = randf(fm,Σ)
+Gamma(fm, Σ) # compute the friction tensor from the pre-computeed diffusion coefficient matrix.

The diffusion coefficient matrix $\Sigma$ can also be used to efficiently generate Gaussian pseudo random numbers ${\rm Normal}(0,{\bf \Gamma})$ as 

R = randf(fm,Σ)
diff --git a/dev/fitting-mbdpd/index.html b/dev/fitting-mbdpd/index.html index b68f26f..e56d2ef 100644 --- a/dev/fitting-mbdpd/index.html +++ b/dev/fitting-mbdpd/index.html @@ -37,4 +37,4 @@ push!(loss_traj[tt], weighted_l2_loss(ffm,flux_data[tt])) end println("Epoch: $epoch, Abs avg Training Loss: $(loss_traj["train"][end]/n_train)), Test Loss: $(loss_traj["test"][end]/n_test))") -end

After training for 2000 epochs, the resulting model is almost a perfect fit:

True vs fitted entries of the friction tensor True vs fitted entries of the friction tensor.

Multi-Body Dissipative Particle Dynamics

By specifying maxorder=1 in the above construction of the friction model, we restrict the underlying ACE-basis to only incorporate pair-wise interactions. This is fine for the here considered sythentic data as the underlying toy model is in fact based on only pair-wise interactions. However, in more complex systems the random force and the dissipative force may not decompose to pairwise interactions. To incorporate higher body-order interactions in the friction model, say interactions up to body order 4, we can change the underlying ACE-basis expansion to incorporate correlation terms up to order 3 by setting maxorder=3.

+end

After training for 2000 epochs, the resulting model is almost a perfect fit:

True vs fitted entries of the friction tensor True vs fitted entries of the friction tensor.

Multi-Body Dissipative Particle Dynamics

By specifying maxorder=1 in the above construction of the friction model, we restrict the underlying ACE-basis to only incorporate pair-wise interactions. This is fine for the here considered sythentic data as the underlying toy model is in fact based on only pair-wise interactions. However, in more complex systems the random force and the dissipative force may not decompose to pairwise interactions. To incorporate higher body-order interactions in the friction model, say interactions up to body order 4, we can change the underlying ACE-basis expansion to incorporate correlation terms up to order 3 by setting maxorder=3.

diff --git a/dev/function-manual/index.html b/dev/function-manual/index.html index 90d318d..872921c 100644 --- a/dev/function-manual/index.html +++ b/dev/function-manual/index.html @@ -1,4 +1,4 @@ Function Manual (@id Function-Manual) · ACEds.jl

Function Manual (@id Function-Manual)

ACEds.FrictionModels.jl

A friction model is a wrapper around a named tuple of matrix models, i.e. 

struct FrictionModel{MODEL_IDS} <: AbstractFrictionModel
     matrixmodels::NamedTuple{MODEL_IDS} 
-end

The symbols contained in the tuple MODEL_IDS are referred to as "IDs" of the corresponding matrix models. When evaluated at an atomic configuration, the resulting friction tensor is the sum of the friction tensors of all matrix models in the friction model, whereas diffusion coefficient matrices are evaluated seperately for each matrix model and returned in the form of a named tuple of the same signature. The following functions act on structures of type FrictionModel:

ACEds.FrictionModels.Gamma — Function
Gamma(fm::FrictionModel, at::Atoms; filter=(_,_)->true, T=Float64)

Evaluates the friction tensor according to the friction model fm at the atomic configuration at::Atoms. The friction tensor is the sum of the friction tensors of all matrix models in fm.matrixmodels.

Arguments:

  • fm – the friction model of which the friction tensor is evaluated.
  • at – the atomic configuration at which the basis is evaluated
  • filter – (optional, default: (_,_)->true) a filter function of the generic form (i::Int,at::Atoms) -> Bool. Only atoms at[i] for which filter(i,at) returns true are included in the evaluation of the friction tensor.

Output:

A friction tensor in the form of a sparse 3N x 3N matrix, where N is the number of atoms in the atomic configuration at.

source
Gamma(fm::FrictionModel{MODEL_IDS}, Σ_vec::NamedTuple{MODEL_IDS}) where {MODEL_IDS}

Computes the friction tensor from a pre-computed collection of diffusion coefficient matrices. The friction tensor is the sum of the squares of all diffusion coefficient matrices in the collection.

Arguments:

  • fm – the friction model of which the friction tensor is evaluated. The friction tensor is the sum of the friction tensors of all matrix models in fm.matrixmodels.
  • Σ – a collection of diffusion coefficient matrices. The friction tensor is the sum of the squares of all matrices in Σ.

Output:

A friction tensor in the form of a sparse 3N x 3N matrix, where N is the number of atoms in the atomic configuration at. The friction tensor is the sum of the symmetric squares $\Sigma\Sigma^T$ of all diffusion coefficient matrices $\Sigma$ in Σ_vec.

source
ACEds.FrictionModels.Sigma — Function
Sigma(fm::FrictionModel{MODEL_IDS}, at::Atoms; filter=(_,_)->true, T=Float64) where {MODEL_IDS}

Computes the diffusion coefficient matrices for all matrix models in the friction model at a given configuration.

Arguments:

  • fm – the friction model of which the diffusion coefficient matrices are evaluated
  • at – the atomic configuration at which the diffusion coefficient matrices are evaluated
  • filter – (optional, default: (_,_)->true) a filter function of the generic form (i::Int,at::Atoms) -> Bool. Only atoms at[i] for which filter(i,at) returns true are included in the evaluation of the diffusion coefficient matrices.

Output:

A NamedTuple of diffusion coefficient matrices, where the keys are the IDs of the matrix models in the friction model.

source
ACEds.MatrixModels.randf — Function
randf(fm::FrictionModel{MODEL_IDS}, Σ::NamedTuple{MODEL_IDS}) where {MODEL_IDS}

Generates a ${\rm Normal}({\bm 0}, {\bm \Gamma})$-distributed Gaussian pseudo random number from a precomputed diffusion coeffiient matrices.

Arguments:

  • fm – the friction model of which the friction tensor is evaluated. The friction tensor is the sum of the friction tensors of all matrix models in fm.matrixmodels.
  • Σ – a collection of diffusion coefficient matrices. The friction tensor is the sum of the squares of all matrices in Σ.

Output:

A ${\rm Normal}({\bm 0}, {\bm \Gamma})$-distributed Gaussian vector R::Vector{3,Float64} of length N, where N is the number of atoms in the configuration for which Σ was evaluated.

source
ACEds.MatrixModels.basis — Function
basis(fm::FrictionModel{MODEL_IDS}, at::Atoms; join_sites=false, filter=(_,_)->true, T=Float64) where {MODEL_IDS}

Evaluates the ACE-basis functions of the friction model fm at the atomic configuration at::Atoms.

Arguments:

  • fm – the friction model of which the basis is evaluated
  • at – the atomic configuration at which the basis is evaluated
  • join_sites – (optional, default: false) if true, the basis evaulations of all matrix models are concatenated into a single array. If false, the basis evaluations are returned as a named tuple of the type NamedTuple{MODEL_IDS}.
  • filter – (optional, default: (_,_)->true) a filter function of the generic form (i::Int,at::Atoms) -> Bool. The atom at[i] will be included in the basis iff filter(i,at) returns true.
source

Setter and getter functions for model parameters

ACE.params — Function
params(fm::FrictionModel{MODEL_IDS}) where {MODEL_IDS}

Returns the parameters of all matrix models in the FrictionModel object as a NamedTuple.

source
ACE.nparams — Function
nparams(fm::FrictionModel{MODEL_IDS}) where {MODEL_IDS}

Returns the total number of scalar parameters of all matrix models in the FrictionModel object.

source
ACE.set_params! — Function
set_params!(fm::FrictionModel, θ::NamedTuple)

Sets the parameters of all matrix models in the FrictionModel object whose ID is contained in θ::NamedTuple to the values specified therein.

source

ACEds.MatrixModels.jl

ACEds.FrictionFit.jl

+end

The symbols contained in the tuple MODEL_IDS are referred to as "IDs" of the corresponding matrix models. When evaluated at an atomic configuration, the resulting friction tensor is the sum of the friction tensors of all matrix models in the friction model, whereas diffusion coefficient matrices are evaluated seperately for each matrix model and returned in the form of a named tuple of the same signature. The following functions act on structures of type FrictionModel:

ACEds.FrictionModels.Gamma — Function
Gamma(fm::FrictionModel, at::Atoms; filter=(_,_)->true, T=Float64)

Evaluates the friction tensor according to the friction model fm at the atomic configuration at::Atoms. The friction tensor is the sum of the friction tensors of all matrix models in fm.matrixmodels.

Arguments:

  • fm – the friction model of which the friction tensor is evaluated.
  • at – the atomic configuration at which the basis is evaluated
  • filter – (optional, default: (_,_)->true) a filter function of the generic form (i::Int,at::Atoms) -> Bool. Only atoms at[i] for which filter(i,at) returns true are included in the evaluation of the friction tensor.

Output:

A friction tensor in the form of a sparse 3N x 3N matrix, where N is the number of atoms in the atomic configuration at.

source
Gamma(fm::FrictionModel{MODEL_IDS}, Σ_vec::NamedTuple{MODEL_IDS}) where {MODEL_IDS}

Computes the friction tensor from a pre-computed collection of diffusion coefficient matrices. The friction tensor is the sum of the squares of all diffusion coefficient matrices in the collection.

Arguments:

  • fm – the friction model of which the friction tensor is evaluated. The friction tensor is the sum of the friction tensors of all matrix models in fm.matrixmodels.
  • Σ – a collection of diffusion coefficient matrices. The friction tensor is the sum of the squares of all matrices in Σ.

Output:

A friction tensor in the form of a sparse 3N x 3N matrix, where N is the number of atoms in the atomic configuration at. The friction tensor is the sum of the symmetric squares $\Sigma\Sigma^T$ of all diffusion coefficient matrices $\Sigma$ in Σ_vec.

source
ACEds.FrictionModels.Sigma — Function
Sigma(fm::FrictionModel{MODEL_IDS}, at::Atoms; filter=(_,_)->true, T=Float64) where {MODEL_IDS}

Computes the diffusion coefficient matrices for all matrix models in the friction model at a given configuration.

Arguments:

  • fm – the friction model of which the diffusion coefficient matrices are evaluated
  • at – the atomic configuration at which the diffusion coefficient matrices are evaluated
  • filter – (optional, default: (_,_)->true) a filter function of the generic form (i::Int,at::Atoms) -> Bool. Only atoms at[i] for which filter(i,at) returns true are included in the evaluation of the diffusion coefficient matrices.

Output:

A NamedTuple of diffusion coefficient matrices, where the keys are the IDs of the matrix models in the friction model.

source
ACEds.MatrixModels.randf — Function
randf(fm::FrictionModel{MODEL_IDS}, Σ::NamedTuple{MODEL_IDS}) where {MODEL_IDS}

Generates a ${\rm Normal}({\bm 0}, {\bm \Gamma})$-distributed Gaussian pseudo random number from a precomputed diffusion coeffiient matrices.

Arguments:

  • fm – the friction model of which the friction tensor is evaluated. The friction tensor is the sum of the friction tensors of all matrix models in fm.matrixmodels.
  • Σ – a collection of diffusion coefficient matrices. The friction tensor is the sum of the squares of all matrices in Σ.

Output:

A ${\rm Normal}({\bm 0}, {\bm \Gamma})$-distributed Gaussian vector R::Vector{3,Float64} of length N, where N is the number of atoms in the configuration for which Σ was evaluated.

source
ACEds.MatrixModels.basis — Function
basis(fm::FrictionModel{MODEL_IDS}, at::Atoms; join_sites=false, filter=(_,_)->true, T=Float64) where {MODEL_IDS}

Evaluates the ACE-basis functions of the friction model fm at the atomic configuration at::Atoms.

Arguments:

  • fm – the friction model of which the basis is evaluated
  • at – the atomic configuration at which the basis is evaluated
  • join_sites – (optional, default: false) if true, the basis evaulations of all matrix models are concatenated into a single array. If false, the basis evaluations are returned as a named tuple of the type NamedTuple{MODEL_IDS}.
  • filter – (optional, default: (_,_)->true) a filter function of the generic form (i::Int,at::Atoms) -> Bool. The atom at[i] will be included in the basis iff filter(i,at) returns true.
source

Setter and getter functions for model parameters

ACE.params — Function
params(fm::FrictionModel{MODEL_IDS}) where {MODEL_IDS}

Returns the parameters of all matrix models in the FrictionModel object as a NamedTuple.

source
ACE.nparams — Function
nparams(fm::FrictionModel{MODEL_IDS}) where {MODEL_IDS}

Returns the total number of scalar parameters of all matrix models in the FrictionModel object.

source
ACE.set_params! — Function
set_params!(fm::FrictionModel, θ::NamedTuple)

Sets the parameters of all matrix models in the FrictionModel object whose ID is contained in θ::NamedTuple to the values specified therein.

source
ACEds.MatrixModels.set_zero! — Function
set_zero!(fm::FrictionModel, model_ids)

Sets the parameters of all matrix models in the FrictionModel object to zero.

source

ACEds.MatrixModels.jl

ACEds.FrictionFit.jl

diff --git a/dev/index.html b/dev/index.html index 3ad2e1b..2245e33 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,2 +1,2 @@ -Home · ACEds.jl

Introduction

The julia package ACEds.jl facilitates simulation and machine learning of configuration-dependent friction tensor models from data. The models are based on an equivariant Atomic Cluster Expansion (ACE) and, as such, are computationally highly efficient and size transferable. The underlying framework of model construction is described in detail in Sachs et al., (2024).

For a quick start, we recommend reading the Installation Instructions and the Overview section, followed by the Workflow Examples. Detailed documentation of front-end-facing functions can be found in the Function Manual.

References

If you are using ACEds.jl in your work, please cite the following article:

  • Sachs, M., Stark, W. G., Maurer, R. J., & Ortner, C. (2024). Equivariant Representation of Configuration-Dependent Friction Tensors in Langevin Heatbaths. [arxiv]
+Home · ACEds.jl

Introduction

The julia package ACEds.jl facilitates simulation and machine learning of configuration-dependent friction tensor models from data. The models are based on an equivariant Atomic Cluster Expansion (ACE) and, as such, are computationally highly efficient and size transferable. The underlying framework of model construction is described in detail in Sachs et al., (2024).

For a quick start, we recommend reading the Installation Instructions and the Overview section, followed by the Workflow Examples. Detailed documentation of front-end-facing functions can be found in the Function Manual.

References

If you are using ACEds.jl in your work, please cite the following article:

  • Sachs, M., Stark, W. G., Maurer, R. J., & Ortner, C. (2024). Equivariant Representation of Configuration-Dependent Friction Tensors in Langevin Heatbaths. [arxiv]
diff --git a/dev/installation/index.html b/dev/installation/index.html index 77e01bf..2258719 100644 --- a/dev/installation/index.html +++ b/dev/installation/index.html @@ -1,4 +1,4 @@ Installation Guide · ACEds.jl

Prerequisites

You will need to have Julia (v1.7 or newer) installed. The latest release and installation instruction for Julia are available here here.

Warning

If you are running Julia for the first time, there is a chance that the General Registrity is not added to you installation. To install the General Registry run the following code from within a Julia REPL.

using Pkg
 Pkg.Registry.add("General")

Installation

The package ACEds and some required dependencies can be downloaded from ACEregistry. To add this registry and install ACEds execute the following steps from within a Julia REPL.

  1. Add the ACEregistry registry:

    using Pkg
-Pkg.Registry.add(RegistrySpec(url="https://github.com/ACEsuit/ACEregistry"))

  2. Install ACEds:

    Pkg.add("ACEds")

Done! Now you can use the functionality of ACEds in your project by running using ACEds.

Note

It is recommended to install ACEds within a dedicated julia environment, where approriate version bounds can be set within the Project.toml file, and versions of dependencies are tracked in a Manifest.toml file.

To create a new project, simply create a new directory, navigate to that directory and run

Pkg.activate(".")

Then, execute sthe teps 1. and 2. from within the project directory.

+Pkg.Registry.add(RegistrySpec(url="https://github.com/ACEsuit/ACEregistry"))

  • Install ACEds:

    Pkg.add("ACEds")

    • Done! Now you can use the functionality of ACEds in your project by running using ACEds.

    Note

    It is recommended to install ACEds within a dedicated julia environment, where approriate version bounds can be set within the Project.toml file, and versions of dependencies are tracked in a Manifest.toml file.

    To create a new project, simply create a new directory, navigate to that directory and run

    Pkg.activate(".")

    Then, execute sthe teps 1. and 2. from within the project directory.

    diff --git a/dev/overview/index.html b/dev/overview/index.html index bacaaed..40de3ed 100644 --- a/dev/overview/index.html +++ b/dev/overview/index.html @@ -2,4 +2,4 @@ Overview · ACEds.jl

    Model Overview

    The package ACEds provides an ACE-based implementation of the size-transferrable, E(3)-equivariant models introduced in Sachs et al., (2024) for configuration-dependent friction or diffusion tensors.

    In a nutshell, the package provides utilities to efficiently learn and evaluate E(3)-equivariant symmetric positive semi-definite matrix functions of the form

    \[{\bm \Gamma} \left ( ({\bm r}_{i},z_i)_{i=1}^{N_{\rm at}} \right ) \in \mathbb{R}^{3 N_{\rm at} \times 3N_{\rm at}},\]

    where the ${\bm r}_{i}$s are the positions and the $z_{i}$s are the atomic element types of atoms in an atomic configuration comprised of $N_{\rm at}$ atoms.

    The underlying model is based on an equivariance-preserving matrix square root decomposition,

    \[{\bm \Gamma} = {\bm \Sigma}{\bm \Sigma}^T,\]

    where block entries of the matrix square root ${\bm \Sigma}\left ( ({\bm r}_{i},z_i)_{i=1}^{N_{\rm at}} \right ) \in \mathbb{R}^{3 N_{\rm at} \times m}$ with some $m \in \mathbb{N}$, are linearly expanded using an equivariant linear atomic cluster expansion.

    Code Overview

    The package ACEds is comprised of three main sub-modules:

    1. The sub-module FrictionModels implements the structure FrictionModel, which facilitates the specification of and evaluation of friction models. The module implements the functions Gamma(fm::FrictionModel, at::Atoms), Sigma(fm::FrictionModel, at::Atoms) which evaluate the friction model fm at the atomic configuration at to the correspong friction tensor ${\bm \Gamma}$ and diffusion coefficient matrix ${\bm \Sigma}$, respectively. Moreover, it provides the functions Gamma(fm::FrictionModel, Σ), randf(fm::FrictionModel, Σ) for efficient computation of the friction tensor and generation of ${\rm Normal}({\bm 0}, {\bm \Gamma})$-distributed Gaussian random numbers from a precomputed diffusion coeffiient matrix Σ.

    2. The sub-module MatrixModels implements various matrix models, which make up a friction model and, in essence, specify (i) properties of the ACE-basis used to evaluate blocks ${\bm \Sigma}_{ij}$ of the difffusion matrix, and (ii) how blocks ${\bm \Sigma}_{ij}$ are combined in the assembly of the friction tensor ${\bm \Gamma}$. The assembly of the friction tensor is governed by what is referred to in Sachs et al., (2024) as the coupling scheme and implements versions of the the pair-wise coupling and row-wise coupling described therein.

    3. The sub-module FrictionFit provides utility functions for training of friction models using the julia machine learning library Flux.jl.

    Prototypical Applications

    Learned models of ${\bm \Gamma}$ (and the corresponding matrix root ${\bm \Sigma}$) can be used to parametrize tensor-valued coefficients in an Itô diffusion process such as a configuration-dependent friction tensor in a kinetic Langevin equation,

    \[\begin{aligned} \dot{{\bm r}} &= - M^{-1}{\bm p},\\ \dot{{\bm p}} &= - \nabla U({\bm r}) - {\bm \Gamma}({\bm r})M^{-1}{\bm p} + \sqrt{2 \beta^{-1}} {\bm \Sigma} \dot{{\bm W}}, -\end{aligned}\]

    or a configuration-dependent diffusion tensor in an overdamped Langevin equation,

    \[\dot{{\bm r}} = - {\bm\Gamma}({\bm r}) \nabla U({\bm r}) + \sqrt{2 \beta^{-1}} {\bm\Sigma}\circ \dot{{\bm W}}. %+ \beta^{-1}{\rm div}({\bm \Gamma}(r)).\]

    The model and code allows imposing additional symmetry constraints on the matrix ${\bm \Gamma}$. In particular, the learned friction-tensor ${\bm \Gamma}$ can be specified to satisfy relevant symmetries for the dynamics (1) to be momentum-conserving, thus enabling learning and simulation of Multi-Body Dissipative Particle Dynamics (MD-DPD).

    +\end{aligned}\]

    or a configuration-dependent diffusion tensor in an overdamped Langevin equation,

    \[\dot{{\bm r}} = - {\bm\Gamma}({\bm r}) \nabla U({\bm r}) + \sqrt{2 \beta^{-1}} {\bm\Sigma}\circ \dot{{\bm W}}. %+ \beta^{-1}{\rm div}({\bm \Gamma}(r)).\]

    The model and code allows imposing additional symmetry constraints on the matrix ${\bm \Gamma}$. In particular, the learned friction-tensor ${\bm \Gamma}$ can be specified to satisfy relevant symmetries for the dynamics (1) to be momentum-conserving, thus enabling learning and simulation of Multi-Body Dissipative Particle Dynamics (MD-DPD).