Descriptors

This page lists every two-body (D2_*) and many-body (DM_*) descriptor compiled into Tadah!MLIP. The class name shown in each heading is exactly the keyword you write in your configuration file.

General workflow

  1. Decide which descriptor families you need (two-body, many-body, or both).

  2. Switch the family on with the corresponding INIT flag:

    INIT2B  true      # activate two-body block
INITMB  false     # skip many-body block

    At least one of INIT2B / INITMB must be true. If both are true Tadah! will build one descriptor of each type unless you say otherwise with TYPE2B / TYPEMB.

  3. Provide exactly one line per descriptor you want to build, using the formats below. If you need to concatenate several descriptors of the same family, use the meta classes D2_mJoin or DM_mJoin and list the components in a block right after the meta keyword.

The bias term

The first component of the overall descriptor vector can be a constant 1 (“bias”). Add it with

BIAS  true

Descriptor key syntax

Two-body:

TYPE2B  D2_<Name>   [param ...]   <EL1> <EL2> ...

Many-body:

TYPEMB  DM_<Name>  L  N_C  N_S  [N_CE  N_SE]  <EL1> <EL2> ...

where

  • <Name> is copied from the headings below (case-sensitive).

  • [param …] are the extra integers/doubles required by a given class (see its table for details).

  • <EL1> <EL2> are element symbols (use * for “any”). Multiple pairs are allowed, e.g. DM_EAD 1 4 4 Ti Ti Ti Nb.

  • L is the maximum angular momentum number needed by DM descriptors.

  • N_C, N_S are the sizes of the centre and width grids (CGRID* / SGRID*).

  • N_CE, N_SE appear only when a non-linear embedding function is used (CEMBFUNC / SEMBFUNC).

Remember to supply matching auxiliary keys:

RCTYPE2B

cutoff function(s) – one per descriptor in TYPE2B

RCUT2B

cutoff distance(s)

CGRID2B

centre grid(s) – if the descriptor uses them

SGRID2B

width grid(s) – same length as the corresponding centres

(and the analogous *MB variants for many-body descriptors).

Ordering matters: we recommend writing the block

TYPE2B   …
RCTYPE2B …
RCUT2B   …
CGRID2B  …
SGRID2B  …

together before starting the next descriptor family, so the eye can verify that list lengths match.

Composite Descriptors

Tadah!MLIP lets you stitch several primitive descriptors together into one feature vector – a composite descriptor – so you can embed physical insight (e.g. “add a short-range ZBL shield to a Blip term”) without editing source code. The idea is implemented via the meta-classes D2_mJoin (two-body) and DM_mJoin (many-body).

Key points

  • Activate the relevant family first: INIT2B / INITMB.

  • Declare the meta descriptor:

    TYPE2B  D2_mJoin or TYPEMB  DM_mJoin

  • Immediately follow with one TYPE line per constituent descriptor, in the order you want them concatenated.

  • Provide matching lists for every auxiliary key (RCTYPE*, RCUT*, CGRID*, SGRID*, and, if required, C/SEMBFUNC). List length must equal the number of constituents.

  • Each constituent can target its own element pair(s), cutoff type and distance.

Quick examples

Single Lennard-Jones descriptor

# -- simple monatomic model -----------------------------------------
INIT2B     true
TYPE2B     D2_LJ  Kr Kr    # no extra parameters
RCTYPE2B   Cut_Cos
RCUT2B     6.0

2-body BP + many-body EAD

# ----- two-body Behler-Parrinello ----------------------------------
INIT2B  true
TYPE2B     D2_BP 10 10 Kr Kr    # 10 radial functions
RCTYPE2B   Cut_Cos
RCUT2B     6.5
CGRID2B    LIN 10 0.0 6.5       # matching grid of centres
SGRID2B    GEOM 10 0.05 0.70    # matching grid of widths

# ----- many-body embedded density ----------------------------------
INITMB  true
TYPEMB     DM_EAD 1 7 7 Kr Kr  # L 1, 7 centres, 7 widths
RCTYPEMB   Cut_Poly
RCUTMB     6.5
CGRIDMB    LIN 7 0.0 6.5
SGRIDMB    GEOM 7 0.05 0.70

Composite 2-body terms with D2_mJoin

INIT2B  true

TYPE2B     D2_mJoin                # meta descriptor

TYPE2B     D2_MIE 12 6  Ti Ti      # --- component 1
RCUT2B     5.0
RCTYPE2B   Cut_Cos

TYPE2B     D2_Blip 4 4  Ti Nb      # --- component 2
RCUT2B     7.5
RCTYPE2B   Cut_Poly
CGRID2B    LIN 4 0.0 7.5
SGRID2B    GEOM 4 0.05 0.70

TYPE2B     D2_Blip 3 3  * *        # --- component 3
RCUT2B     4.0
RCTYPE2B   Cut_Cos
CGRID2B    LIN 3 0.0 7.5
SGRID2B    GEOM 3 0.05 0.70

Reading the tables below

Following this overview you will find the Two-Body and Many-Body sections. Each entry shows

  • a short description and equation,

  • Required config keys, i.e. the options you must specify in the configuration file.

Copy the class name into the TYPE2B / TYPEMB line, supply the required keys, and you are ready to train.

Two-Body

Label

Description

D2_LJ

Lennard-Jones 12-6 pair potential descriptor

D2_BP

Behler–Parrinello Gaussian radial symmetry functions

D2_Blip

Cubic B-spline (blip) radial basis

D2_EAM

Pair-density part of the Embedded Atom Method

D2_MIE

Mie potential with user-chosen exponents n, m

D2_ZBL

Ziegler–Biersack–Littmark screened nuclear repulsion

D2_Dummy

Identity descriptor (all ones); for testing

D2_mJoin

Concatenate multiple D2 descriptors into one vector

D2_LJ

class D2_LJ : public tadah::models::D2_Base

Standard Lennard - Jones descriptor.

\[ V_i = \sum_{j \neq i} 4 \epsilon \Bigg(\Big(\frac{\sigma}{r_{ij}}\Big)^{12} - \Big(\frac{\sigma}{r_{ij}}\Big)^6\Bigg) f_c(r_{ij}) \]

or equivalently:

\[ V_i = \sum_{j \neq i} \frac{C_{12}}{r_{ij}^{12}} - \frac{C_6}{r_{ij}^6} f_c(r_{ij}) \]

Note that machined learned coefficients \(C_6\) and \(C_{12}\) corresponds to \(\sigma\) and \(\epsilon\) through the following relation:

\[ \sigma = \Big(\frac{C_{12}}{C_6}\Big)^{1/6} \]
\[ \epsilon = \frac{1}{4} \frac{C_6^2}{C_{12}} w(Z) \]
where \(w(Z)\) is a species depended weight factor (default is an atomic number).

The machine learned \(\sigma\) and \(\epsilon\) only make sense (say to compare with the literature ones) when BIAS false and NORM false and system in monatomic. It is ok thought to set them to true it’s just that numerical values will be different.

Required tadah::core::Context Key: INIT2B

D2_BP

class D2_BP : public tadah::models::D2_Base

Behler-Parrinello two-body descriptor.

\[ V_i^{\eta,r_s} = \sum_{j \neq i} \exp{\Big(-\eta(r_{ij}-r_s)^2\Big)}f_c(r_{ij}) \]

CGRID2B parameters control position \( r_s \) of the gaussian basis function.

SGRID2B parameters control width \( \eta \) of the gaussian basis function.

This is essentially a \( G^1_i \) descriptor from the below paper with an exception that it can use any cutoff function defined in Ta-dah!:

Behler, J., Parrinello, M. (2007). Generalized neural-network representation of high-dimensional potential-energy surfaces. Physical Review Letters, 98(14), 146401. https://doi.org/10.1103/PhysRevLett.98.146401

Required tadah::core::Context keys: INIT2B CGRID2B SGRID2B

D2_Blip

class D2_Blip : public tadah::models::D2_Base

Blip two-body descriptor.

\[ V_i^{\eta,r_s} =\sum_{j \neq i} \mathcal{B}(\eta(r_{ij}-r_s))f_c(r_{ij}) \]

where \( f_c \) is a cutoff function and \( \mathcal{B} \) is a blip basis function centered at \(r_s\) of width \(4/\eta\).

CGRID2B parameters control position \( r_s \) of blip centres.

SGRID2B parameters control width \( \eta \) of blips.

Blip basis function is built out of 3rd degree polynomials in the four intervals [-2,-1], [-1,0], [0,1], [1,2] and is defined as:

\[\begin{split} \begin{equation} \mathcal{B}(r) = \begin{cases} 1-\frac{3}{2}r^2+\frac{3}{4}|r|^3 & \text{if} \qquad 0<|r|<1\\ \frac{1}{4}(2-|r|)^3 & \text{if} \qquad 1<|r|<2\\ 0 & \text{if} \qquad |r|>2 \end{cases} \end{equation} \end{split}\]

More details about the blip basis functions can be found in the following paper:

Hernández, E., Gillan, M., Goringe, C. (1997). Basis functions for linear-scaling first-principles calculations. Physical Review B - Condensed Matter and Materials Physics, 55(20), 13485–13493. https://doi.org/10.1103/PhysRevB.55.13485

Required keys: INIT2B CGRID2B SGRID2B

D2_EAM

class D2_EAM : public tadah::models::D2_Base

Pair-wise part for the Embedded Atom Method descriptor.

\[ V_i = \frac{1}{2} \sum_{j \neq i} \psi(r_{ij}) \]

This descriptor will load tabulated values for the two-body potential \( \phi \) from the provided SETFL file.

This descriptor is usually used together with the many-body descriptor DM_EAM although this is not required and user can mix it with any other descriptors or use it on its own.

This descriptor will enforce cutoff distance as specified in a SETFL file. Set RCUT2B to the same value to suppress the warning message.

Required tadah::core::Context keys: INIT2B SETFL

D2_MIE

class D2_MIE : public tadah::models::D2_Base

Mie descriptor.

\[ V_i = \sum_{j \neq i} C \epsilon \Bigg(\Big(\frac{\sigma}{r_{ij}}\Big)^{n} - \Big(\frac{\sigma}{r_{ij}}\Big)^m\Bigg) \]

where

\[ C=\frac{n}{n-m}\Big( \frac{n}{m} \Big)^{\frac{m}{n-m}} \]

Any cutoff can be used

Required tadah::core::Context Key: INIT2B TYPE2B

TYPE2B D2_MIE 12 6 ELEMENT1 ELEMENT2

will result in Lennard-Jones type descriptor

D2_ZBL

class D2_ZBL : public tadah::models::D2_Base

ZBL Descriptor.

The ZBL (Ziegler-Biersack-Littmark) potential is an empirical potential used to model short-range interactions between atoms.

The constant term \( \frac{e^2}{4 \pi \varepsilon_0 } \) is set to 1 and will be fitted as needed.

The simplified expression for the ZBL potential is given by:

\[ V(r) = \frac{Z_1 Z_2}{r} \phi\left(\frac{r}{a}\right) \]

where \( a \) is the screening length, expressed as:

\[ a = \frac{s_0 a_0}{Z_1^{p_0} + Z_2^{p_1}} \]

Here, \( a_0 \), \( s_0 \), \( p_0 \), and \( p_1 \) are adjustable hyperparameters. Setting any of these to -1 uses the default values:

  • \( a_0 = 0.52917721067 \, \text{Å} \)

  • \( s_0 = 0.88534 \)

  • \( p_0 = 0.23 \)

  • \( p_1 = 0.23 \)

The screening function \( \phi \) is defined as:

\[ \phi(x) = 0.1818 e^{-3.2x} + 0.5099 e^{-0.9423x} + 0.2802 e^{-0.4029x} + 0.02817 e^{-0.2016x} \]

Required tadah::core::Context Key: INIT2B TYPE2B

  • TYPE2B D2_ZBL \( a_0 \) \( s_0 \) \( p_0 \) \( p_1 \) ELEMENT1 ELEMENT2

Examples:

  • TYPE2B D2_ZBL 0.53 0.90 0.23 0.23 Kr Kr # Custom parameters

  • TYPE2B D2_ZBL -1 -1 -1 -1 Kr Kr # Default values

  • TYPE2B D2_ZBL 0.53 -1 -1 -1 Kr Kr # Mix of default and custom

D2_Dummy

class D2_Dummy : public tadah::models::D2_Base

Dummy two-body descriptor.

Use it to satisfy DescriptorsCalc requirements in case when two-body descriptor is not required.

D2_mJoin

class D2_mJoin : public tadah::models::D2_Base, public tadah::models::D_mJoin

Meta two-body descriptor for combining multiple D2 descriptors.

This descriptor provides a convenient interface for concatenating multiple two-body descriptors. The resulting descriptor can then be used by Tadah! like any standard two-body descriptor.

Each descriptor must have a specified type in a configuration file, along with a cutoff function, cutoff distance, and optionally SGRID2B and CGRID2B values if applicable.

When listing descriptors under the TYPE2B key, you must include parameters relevant to this descriptor.

Here is an example of how to configure these descriptors:

TYPE2B    D2_mJoin     # <-- Meta descriptor for concatenating two-body descriptors
TYPE2B    D2_MIE 11 6 Ti Ti   # <-- MIE exponents
RCTYPE2B  Cut_Cos
RCUT2B    3.0

TYPE2B    D2_Blip 6 6 Ti Nb Nb Nb   # <-- grid sizes
RCTYPE2B  Cut_Tanh
RCUT2B    7.5
SGRID2B   -2 6 0.1 10   # Grid for D2_Blip, blips widths, auto generated
CGRID2B   0 0 0 0 0 0   # Grid for D2_Blip, blip centers

Note: Grids can be specified on a single line, and the order of the grids is important.

There is no limit to the number of descriptors that can be concatenated.

  • Ensure the types and grids are correctly specified in the configuration file.

  • The cutoff functions (RCTYPE2B) and distances (RCUT2B) must be defined for each descriptor.

  • Both SGRID2B and CGRID2B should be included if relevant, with their sizes matching the given descriptors.

Many-Body

Label

Description

DM_Blip

Angular-momentum-projected blip basis; EAM-style density accumulation

DM_EAD

Embedded Atom Descriptor with Gaussian-type orbital basis

DM_EAM

Many-body part of the Embedded Atom Method

DM_mRLR

mEAD with s·ρ·log(c·ρ) embedding

DM_mSQRT

mEAD with s·√ρ embedding

DM_mBlip

mEAD with blip-function embedding

DM_mBlipEnv

mEAD with blip-function embedding gated by a Sin-inverse envelope

DM_PS_SQ

DM_Poly: blip radial, spherical, ρ² embedding

DM_PS_SQRT

DM_Poly: blip radial, spherical, √ρ embedding

DM_PS_RLR

DM_Poly: blip radial, spherical, ρ·log(ρ) embedding

DM_PS_Blip

DM_Poly: blip radial, spherical, blip embedding

DM_GPS_SQ

DM_Poly: Gaussian radial, spherical, ρ² embedding

DM_GPS_SQRT

DM_Poly: Gaussian radial, spherical, √ρ embedding

DM_GPS_RLR

DM_Poly: Gaussian radial, spherical, ρ·log(ρ) embedding

DM_GPS_Blip

DM_Poly: Gaussian radial, spherical, blip embedding

DM_OW_SQ

DM_Poly: blip radial, orbital-wise, ρ² embedding

DM_OW_SQRT

DM_Poly: blip radial, orbital-wise, √ρ embedding

DM_OW_RLR

DM_Poly: blip radial, orbital-wise, ρ·log(ρ) embedding

DM_OW_Blip

DM_Poly: blip radial, orbital-wise, blip embedding

DM_GOW_SQ

DM_Poly: Gaussian radial, orbital-wise, ρ² embedding

DM_GOW_SQRT

DM_Poly: Gaussian radial, orbital-wise, √ρ embedding

DM_GOW_RLR

DM_Poly: Gaussian radial, orbital-wise, ρ·log(ρ) embedding

DM_GOW_Blip

DM_Poly: Gaussian radial, orbital-wise, blip embedding

DM_Dummy

Identity descriptor (all ones); for testing

DM_mJoin

Concatenate multiple DM descriptors into one vector

DM_Blip

class DM_Blip : public tadah::models::DM_Base

Blip Many-Body Descriptor.

Angular-momentum-projected descriptor built from blip (cubic B-spline) basis functions. For each angular-momentum channel \( L \) and each grid point \((\eta,r_s)\) the descriptor component is:

\[\begin{split} V_i^{L,\eta,r_s} = \sum_{\substack{l_x,l_y,l_z \ge 0 \\ l_x+l_y+l_z=L}} \frac{L!}{l_x!\,l_y!\,l_z!} \Bigl(\rho_i^{\eta,r_s,l_x,l_y,l_z}\Bigr)^2 \end{split}\]

where the projected density is

\[ \rho_i^{\eta,r_s,l_x,l_y,l_z} = \sum_{j \neq i} x_{ij}^{l_x}\,y_{ij}^{l_y}\,z_{ij}^{l_z}\, \mathcal{B}\!\Bigl(\eta(r_{ij}-r_s)\Bigr)\,f_c(r_{ij}) \]

Here \( \mathcal{B} \) is the blip (cubic B-spline) basis function with compact support \( |\eta(r-r_s)| < 2 \) (see tadah::models::B), and \( f_c \) is the cutoff function.

The multinomial prefactor \( L!/({l_x!\,l_y!\,l_z!}) \) is normalised by \((4r_c)^L\) so that descriptor components at different \( L \) have comparable magnitudes.

CGRIDMB parameters control the centre \( r_s \) of each blip basis function.

SGRIDMB parameters control the inverse width \( \eta \); the full support of each blip in \( r \)-space is \( 4/\eta \).

Setting \( L_{\max}=2 \) generates descriptors for \( L=0,1,2 \) (s-, p-, d-orbital channels). Maximum supported \( L_{\max} = 6 \).

More information about this descriptor family:

Zhang, Y., Hu, C., Jiang, B. (2019). Embedded atom neural network potentials: efficient and accurate machine learning with a physically inspired representation. Journal of Physical Chemistry Letters, 10(17), 4962–4967. https://doi.org/10.1021/acs.jpclett.9b02037

Required tadah::core::Context keys: INITMB CGRIDMB SGRIDMB

DM_EAD

class DM_EAD : public tadah::models::DM_Base

Embedded Atom Descriptor

\[ V_i^{L,\eta,r_s} = \sum_{l_x,l_y,l_z}^{l_x+l_y+l_z=L} \frac{L!}{l_x!l_y!l_z!} \Big( \rho_i^{\eta,r_s,l_x,l_y,l_z} \Big)^2 \]

where density \( \rho \) is calculated using Gaussian Type Orbitals:

\[ \rho_i^{\eta,r_s,l_x,l_y,l_z} = \sum_{j \neq i} x_{ij}^{l_x}y_{ij}^{l_y}z_{ij}^{l_z} \exp{\Big(-\eta(r_{ij}-r_s)^2\Big)}f_c(r_{ij}) \]

CGRIDMB parameters control position \( r_s \) of the gaussian basis function.

SGRIDMB parameters control width \( \eta \) of the gaussian basis function.

e.g. \(L_{max}=2\) will calculate descriptors with \( L=0,1,2 \) (s,p,d orbitals).

More information about this descriptor:

Zhang, Y., Hu, C.,Jiang, B. (2019). Embedded atom neural network potentials: efficient and accurate machine learning with a physically inspired representation. Journal of Physical Chemistry Letters, 10(17), 4962–4967. https://doi.org/10.1021/acs.jpclett.9b02037

Required tadah::core::Context keys: INITMB CGRIDMB SGRIDMB

DM_EAM

class DM_EAM : public tadah::models::DM_Base

many-body part for the Embedded Atom Method descriptor.

\[ V_i = F\Bigg(\sum_{j \neq i} \rho(r_{ij}) \Bigg) \]

This descriptor will load tabulated values for the density \( \rho \) and embedded energy \( F \) from the provided SETFL file.

This descriptor is usually used together with the two-body descriptor D2_EAM although this is not required and user can mix it with any other descriptors or use it on its own.

This descriptor will enforce cutoff distance as specified in a SETFL file. Set RCUTMB to the same value to suppress the warning message.

Required tadah::core::Context keys: INITMB SETFL

DM_mEAD variants

These descriptors combine the mEAD density accumulation with a non-linear embedding function F applied before the quadratic sum. Choose the label that matches the embedding function you want:

Label

Embedding F

Form

DM_mRLR

F_RLR

s · ρ · log(c · ρ)

DM_mSQRT

F_SQRT

s · √ρ

DM_mBlip

F_Blip

blip-function B(ρ)

DM_mBlipEnv

F_mEnv

B(ρ) · Sin-inverse envelope (suppresses contribution near ρ = 0)
template<typename F>
class DM_mEAD : public tadah::models::DM_Base

Modified Embedded Atom Descriptor

REQUIRED KEYS: SGRIDMB, CGRIDMB, and KEYS OF THE EMBEDDING FUNCTION

This descriptor has a mathematical form very similar to DM_EAD but allows the usage of a custom-defined embedding function, \( \mathcal{F} \), in place of the default quadratic one.

Available implementations:

  1. DM_mRLR uses F_RLR

  2. DM_mSQRT uses F_SQRT

\[ V_i^{L,\eta,r_s} = \sum_{l_x,l_y,l_z}^{l_x+l_y+l_z=L} \frac{L!}{l_x!l_y!l_z!} \mathcal{F}\Big( \rho_i^{\eta,r_s,l_x,l_y,l_z} \Big) \]

where the density \( \rho \) is calculated using Gaussian Type Orbitals:

\[ \rho_i^{\eta,r_s,l_x,l_y,l_z} = \sum_{j \neq i} x_{ij}^{l_x} y_{ij}^{l_y} z_{ij}^{l_z} \exp{\Big(\eta(r_{ij}-r_s)\Big)} f_c(r_{ij}) \]

CGRIDMB parameters control the position \( r_s \) of the Gaussian basis function.

SGRIDMB parameters control the width \( \eta \) of the Gaussian basis function.

e.g., \(L_{max}=2\) will calculate descriptors with \( L=0,1,2 \) (s, p, d orbitals).

# TYPEMB params: L, size(cgrid), size(sgrid),
# size(cembfunc), size(sembfunc), list of element pairs
TYPEMB    DM_mRLR 0 7 7 1 1 Ta Ta    
RCTYPEMB  Cut_Tanh
RCUTMB    7.5
SGRIDMB   -2 7 0.1 10
CGRIDMB   0 0 0 0 0 0 0
SEMBFUNC  1.2
CEMBFUNC  0.5

# TYPEMB params: L, size(cgrid), size(sgrid),
# size(cembfunc), size(sembfunc), list of element pairs
TYPEMB    DM_mSQRT 1 5 5 0 1 * * 
RCTYPEMB  Cut_Cos
RCUTMB    3.0
CGRIDMB   -1 5 0 3.0
SGRIDMB   -2 5 1.0 10.0
SEMBFUNC   1.5

For dimension-expanding embedding functions (e.g. F_Blip), CGRIDMB and SGRIDMB must have size 1, while CEMBFUNC/SEMBFUNC determine the descriptor output dimension:

TYPEMB    DM_mBlip 1 1 1 5 5 Ta Ta
RCTYPEMB  Cut_Cos
RCUTMB    5.0
CGRIDMB   0.0
SGRIDMB   -1.5
CEMBFUNC  0.0 0.5 1.0 1.5 2.0
SEMBFUNC  1.0 1.0 1.0 1.0 1.0

Required Config keys: INITMB CGRIDMB SGRIDMB

Warning

Rotational invariance holds only when \(\mathcal{F}=\rho^2\) (i.e. F_SQ). For any other channel function and \(L>0\) the descriptor is not rotationally invariant because \(\mathcal{F}\) is applied to individual orbital densities before the invariance-restoring quadratic sum. A runtime warning is emitted in that case. Use DM_mBlipL for a descriptor that is invariant for arbitrary \(\mathcal{F}_L\).

Embedding functions

class F_RLR : public tadah::models::F_Base

Implements an embedding function of the form: \( s \rho \log(c \rho) \).

This class supports embedding functions characterized by two main parameters:

  • SEMBFUNC: Controls the depth, \( s \), of the embedding function.

  • CEMBFUNC: Determines the x-intercept, with the x-intercept at \( 1/c \).

    Require: size(SEMBFUNC)=size(CEMBFUNC)=size([C/S]GRIDMB)

The number of keys for these parameters must match the entries in the mEAD descriptor.

class F_SQ : public tadah::models::F_Base
class F_SQRT : public tadah::models::F_Base

Implements \( s \sqrt{\rho} \).

Optional parameter:

  • SEMBFUNC: Controls the strength, \( s \), of the embedding function. If no; value is provided, the default is 1 for every s/cgrid point.

    Require: size(SEMBFUNC)=(0 or size([C/S]GRIDMB)) and size(CEMBFUNC)=0

class F_Blip : public tadah::models::F_Base

Implements a “blip” embedding function.

F_Blip is a dimension-expanding embedding function: it requires CGRID/SGRID of size 1 (a single radial basis function producing one ρ per orbital) and CEMBFUNC/SEMBFUNC of size ≥ 1. Each (orbital, embedding-grid-point) pair produces one descriptor component, so the descriptor dimension per L is CEMBFUNC.size().

Param context:

Reference to a Context instance.

template<typename F>
class F_mEnv : public tadah::models::F_Base

F_Blip multiplied by an envelope cutoff that suppresses ρ near 0.

Identical interface to F_Blip (dimension-expanding, requires CGRID/SGRID of size 1 and equal-length CEMBFUNC/SEMBFUNC) but the embedded value is: \( F(\rho) = f_{\text{env}}(\rho)\, B(\rho, \eta_p, \mu_p) \), where \( f_{\text{env}} \) is a cutoff-style function (template parameter) with width set by the new RCUTENV key.

Required Config keys: RCUTENV CEMBFUNC SEMBFUNC.

DM_Poly variants

DM_Poly is a generalised many-body descriptor with three independent choices:

  • Radial basis – how the atomic density is expanded radially: blip (cubic B-spline) or Gaussian.

  • Aggregation – spherical (rotationally invariant sum) or orbital-wise (one channel per angular-momentum orbital).

  • Embedding function F – applied per-channel before the invariant sum: ρ² (SQ), √ρ (SQRT), ρ·log(ρ) (RLR), or blip (Blip).

The 16 registered labels follow the pattern DM_{radial}{aggregation}_{embedding}:

Label

Radial basis

Aggregation

Embedding F

DM_PS_SQ

Blip

Spherical

ρ²

DM_PS_SQRT

Blip

Spherical

√ρ

DM_PS_RLR

Blip

Spherical

ρ·log(ρ)

DM_PS_Blip

Blip

Spherical

blip B(ρ)

DM_GPS_SQ

Gaussian

Spherical

ρ²

DM_GPS_SQRT

Gaussian

Spherical

√ρ

DM_GPS_RLR

Gaussian

Spherical

ρ·log(ρ)

DM_GPS_Blip

Gaussian

Spherical

blip B(ρ)

DM_OW_SQ

Blip

Orbital-wise

ρ²

DM_OW_SQRT

Blip

Orbital-wise

√ρ

DM_OW_RLR

Blip

Orbital-wise

ρ·log(ρ)

DM_OW_Blip

Blip

Orbital-wise

blip B(ρ)

DM_GOW_SQ

Gaussian

Orbital-wise

ρ²

DM_GOW_SQRT

Gaussian

Orbital-wise

√ρ

DM_GOW_RLR

Gaussian

Orbital-wise

ρ·log(ρ)

DM_GOW_Blip

Gaussian

Orbital-wise

blip B(ρ)
template<typename ChannelFn, typename RadialBasis = BlipRadial, typename AggMode = PowerSpectrum>
class DM_Poly : public tadah::models::DM_Base

Generalised many-body descriptor with swappable radial basis, channel function, and aggregation mode.

\[ \rho_{i}^{L,c,l_x,l_y,l_z} = \sum_{j \neq i} x_{ij}^{l_x}\,y_{ij}^{l_y}\,z_{ij}^{l_z}\, \phi_c(r_{ij})\,f_c(r_{ij}) \]

PowerSpectrum mode (default, always invariant):

\[ V_{i}^{L,c} = \mathcal{F}\!\left( \sum_{\substack{l_x+l_y+l_z=L}} \frac{L!}{l_x!\,l_y!\,l_z!}\, (\rho_{i}^{L,c,l_x,l_y,l_z})^2 \right) \]

OrbitalWise mode (DM_mEAD-equivalent, invariant only for F_SQ and L=0):

\[ V_{i}^{L,c} = \sum_{\substack{l_x+l_y+l_z=L}} \frac{L!}{l_x!\,l_y!\,l_z!}\, \mathcal{F}(\rho_{i}^{L,c,l_x,l_y,l_z}) \]

The multinomial prefactor is normalised by \((4r_c)^L\).

Available instantiations registered in dm_all.cpp:

Config name

ChannelFn

RadialBasis

AggMode

DM_PS_SQ

F_SQ

BlipRadial

PowerSpectrum

DM_PS_SQRT

F_SQRT

BlipRadial

PowerSpectrum

DM_PS_RLR

F_RLR

BlipRadial

PowerSpectrum

DM_PS_Blip

F_Blip

BlipRadial

PowerSpectrum

DM_GPS_SQ

F_SQ

GaussianRadial

PowerSpectrum

DM_GPS_SQRT

F_SQRT

GaussianRadial

PowerSpectrum

DM_GPS_RLR

F_RLR

GaussianRadial

PowerSpectrum

DM_GPS_Blip

F_Blip

GaussianRadial

PowerSpectrum

DM_OW_SQ

F_SQ

BlipRadial

OrbitalWise

DM_OW_SQRT

F_SQRT

BlipRadial

OrbitalWise

DM_OW_RLR

F_RLR

BlipRadial

OrbitalWise

DM_OW_Blip

F_Blip

BlipRadial

OrbitalWise

DM_GOW_SQ

F_SQ

GaussianRadial

OrbitalWise

DM_GOW_SQRT

F_SQRT

GaussianRadial

OrbitalWise

DM_GOW_RLR

F_RLR

GaussianRadial

OrbitalWise

DM_GOW_Blip

F_Blip

GaussianRadial

OrbitalWise

Required Config keys: INITMB CGRIDMB SGRIDMB (plus channel-function keys)

Template Parameters:

  • ChannelFn – Channel function (F_SQ, F_SQRT, F_RLR, F_Blip, …).

  • RadialBasis – Radial basis policy (BlipRadial, GaussianRadial, …). Default: BlipRadial.

  • AggMode – Aggregation mode (PowerSpectrum, OrbitalWise). Default: PowerSpectrum.

DM_Dummy

class DM_Dummy : public tadah::models::DM_Base

Dummy many-body descriptor.

Use it to satisfy DescriptorsCalc requirements in case when many-body descriptor is not required.

DM_mJoin

class DM_mJoin : public tadah::models::DM_Base, public tadah::models::D_mJoin

Meta many-body descriptor for combining multiple DM descriptors.

This descriptor provides an interface for concatenating various many-body descriptors. The resulting descriptor can then be used by Tadah! like any standard many-body descriptor.

Each descriptor must have a specified type in a configuration file, along with a cutoff function, cutoff distance, and other optional keys that are typically expected for this descriptor, such as SGRIDMB and CGRIDMB.

When listing descriptors under the TYPEMB key, include parameters relevant to this descriptor.

Here is an example of configuring these descriptors:

TYPEMB    DM_mJoin         # Meta descriptor for concatenating many-body descriptors
TYPEMB    DM_EAD 1 5 5 * *    # L number, cgrid, sgrid, list of element pairs
RCTYPEMB  Cut_Cos
RCUTMB    3.0
CGRIDMB   -1 5 0 3.0       # Grid for DM_EAD, blips centers, auto-generated
SGRIDMB   -2 5 1.0 10.0    # Grid for DM_EAD, blips widths, auto-generated

TYPEMB    DM_Blip 0 7 7 Ta Ta   # L number, cgrid, sgrid, list of element pairs
RCTYPEMB  Cut_Tanh
RCUTMB    7.5
SGRIDMB   -2 7 0.1 10      # Grid for DM_Blip, blips widths, auto-generated
CGRIDMB   0 0 0 0 0 0 0    # Grid for DM_Blip, blips centers

Note: Grids can be specified on a single line, and the order of the grids should match the order of descriptors.

There is no limit to the number of descriptors that can be concatenated.

  • Ensure the types and grids are correctly specified in the configuration file.

  • The cutoff functions (RCTYPEMB) and distances (RCUTMB) must be defined for each descriptor.

  • Both SGRIDMB and CGRIDMB should be included if relevant, with their sizes matching the given descriptors.