LODE spherical expansion¶

This calculator is registered with the lode_spherical_expansion name.

LodeSphericalExpansion hyper-parameters¶

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "LodeSphericalExpansionParameters",
  "description": "Parameters for LODE spherical expansion calculator.\n\n The spherical expansion is at the core of representations in the LODE\n (long-distance equivariant) family. See [this\n article](https://aip.scitation.org/doi/10.1063/1.5128375) for more\n information on the LODE representation.",
  "type": "object",
  "properties": {
    "basis": {
      "description": "Definition of the basis functions used to expand the atomic density in\n local environments",
      "$ref": "#/$defs/SphericalExpansionBasis"
    },
    "density": {
      "description": "Definition of the density arising from atoms in the whole system",
      "$ref": "#/$defs/Density"
    },
    "k_cutoff": {
      "description": "Spherical reciprocal cutoff. If `k_cutoff` is `None`, a cutoff of\n `1.2 π / SmearedPowerLaw.width`, which is a reasonable value for most\n systems, is used.",
      "type": [
        "number",
        "null"
      ],
      "format": "double"
    }
  },
  "required": [
    "density",
    "basis"
  ],
  "$defs": {
    "Density": {
      "description": "Definition of the (atomic) density to expand on a basis",
      "type": "object",
      "properties": {
        "center_atom_weight": {
          "description": "Weight of the central atom contribution to the density. If `1` the\n center atom contribution is weighted the same as any other contribution.\n If `0` the central atom does not contribute to the density at all.",
          "type": "number",
          "format": "double",
          "default": 1.0
        },
        "scaling": {
          "description": "radial scaling can be used to reduce the importance of neighbor atoms\n further away from the center, usually improving the performance of the\n model",
          "anyOf": [
            {
              "$ref": "#/$defs/DensityScaling"
            },
            {
              "type": "null"
            }
          ],
          "default": null
        }
      },
      "oneOf": [
        {
          "description": "Dirac delta atomic density",
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "DiracDelta"
            }
          },
          "required": [
            "type"
          ]
        },
        {
          "description": "Gaussian atomic density `exp(-r^2/width^2)`",
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "Gaussian"
            },
            "width": {
              "description": "Width of the gaussian, the same width is used for all atoms",
              "type": "number",
              "format": "double"
            }
          },
          "required": [
            "type",
            "width"
          ]
        },
        {
          "description": "Smeared power law density, that behaves like `1 / r^p` as `r` goes to\n infinity, while removing any singularity at `r=0` and ensuring the\n density is differentiable everywhere.\n\n The density functional form is `f(r) = 1 / Γ(p/2) * γ(p/2, r^2/(2 σ^2))\n / r^p`, with σ the smearing width, Γ the Gamma function and γ the lower\n incomplete gamma function.\n\n For more information about the derivation of this density, see\n <https://doi.org/10.1021/acs.jpclett.3c02375> and section D of the\n supplementary information.",
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "SmearedPowerLaw"
            },
            "exponent": {
              "description": "Exponent of the density (`p`)",
              "type": "integer",
              "format": "uint",
              "minimum": 0
            },
            "smearing": {
              "description": "Smearing width of the density (`σ`)",
              "type": "number",
              "format": "double"
            }
          },
          "required": [
            "type",
            "smearing",
            "exponent"
          ]
        }
      ]
    },
    "DensityScaling": {
      "description": "Implemented options for radial scaling of the atomic density around an atom",
      "oneOf": [
        {
          "description": "Use a long-range algebraic decay and smooth behavior at `r → 0` as\n introduced in <https://doi.org/10.1039/C8CP05921G>:\n `f(r) = rate / (rate + (r / scale) ^ exponent)`",
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "Willatt2018"
            },
            "exponent": {
              "description": "see in the formula",
              "type": "number",
              "format": "double"
            },
            "rate": {
              "description": "see in the formula",
              "type": "number",
              "format": "double"
            },
            "scale": {
              "description": "see in the formula",
              "type": "number",
              "format": "double"
            }
          },
          "additionalProperties": false,
          "required": [
            "type",
            "scale",
            "rate",
            "exponent"
          ]
        }
      ]
    },
    "RadialBasis": {
      "description": "The different kinds of radial basis supported LODE calculators",
      "oneOf": [
        {
          "description": "Use a radial basis similar to Gaussian-Type Orbitals.\n\n The basis is defined as `R_n(r) ∝ r^n e^{- r^2 / (2 σ_n^2)}`, where `σ_n\n = radius * \\sqrt{n} / n_max`",
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "Gto"
            },
            "max_radial": {
              "description": "Maximal value of `n` to include in the radial basis function\n definition. The overall basis will have `max_radial + 1` basis\n functions, indexed from `0` to `max_radial` (inclusive).",
              "type": "integer",
              "format": "uint",
              "minimum": 0
            },
            "radius": {
              "description": "Radius of the Gto basis, i.e. how far should the local LODE field be\n integrated.",
              "type": "number",
              "format": "double"
            }
          },
          "additionalProperties": false,
          "required": [
            "type",
            "max_radial",
            "radius"
          ]
        },
        {
          "description": "Use pre-tabulated radial basis.\n\n This enables the calculation of the overall radial integral using\n user-defined splines.\n\n The easiest way to create such a tabulated basis is the corresponding\n functions in featomic's Python API.",
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "Tabulated"
            },
            "center_contribution": {
              "description": "The `center_contribution` is defined as `c_n = \\sqrt{4π} \\int dr r^2\n R_n(r) g(r)` where `g(r)` is a radially symmetric density function,\n `R_n(r)` the radial basis function and `n` the current radial channel.\n\n It is required for using tabulated basis with LODE, since we can not\n compute it using only the spline. This should be defined for the\n `lambda=0` angular channel.",
              "type": [
                "array",
                "null"
              ],
              "items": {
                "type": "number",
                "format": "double"
              }
            },
            "points": {
              "description": "Points defining the spline",
              "type": "array",
              "items": {
                "$ref": "#/$defs/SplinePoint"
              }
            }
          },
          "additionalProperties": false,
          "required": [
            "type",
            "points"
          ]
        }
      ]
    },
    "SphericalExpansionBasis": {
      "description": "Possible Basis functions to use for the SOAP or LODE spherical expansion.\n\n The basis is made of radial and angular parts, that can be combined in\n various ways.",
      "oneOf": [
        {
          "description": "This defines a tensor product basis, combining all possible radial basis\n functions with all possible angular basis functions.",
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "TensorProduct"
            },
            "max_angular": {
              "description": "Maximal value (inclusive) of the angular moment (quantum number `l`) to\n use for the spherical harmonics basis functions",
              "type": "integer",
              "format": "uint",
              "minimum": 0
            },
            "radial": {
              "description": "Definition of the radial basis functions",
              "$ref": "#/$defs/RadialBasis"
            },
            "spline_accuracy": {
              "description": "Accuracy for splining the radial integral. Using splines is typically\n faster than analytical implementations. If this is None, no splining is\n done.\n\n The number of control points in the spline is automatically determined\n to ensure the average absolute error is close to the requested accuracy.",
              "type": [
                "number",
                "null"
              ],
              "format": "double",
              "default": 1e-8
            }
          },
          "additionalProperties": false,
          "required": [
            "type",
            "max_angular",
            "radial"
          ]
        },
        {
          "description": "This defines an explicit basis, where only a specific subset of angular\n basis can be used, and every angular basis can use a different radial\n basis.",
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "Explicit"
            },
            "by_angular": {
              "description": "A map of radial basis to use for the specified angular channels.\n\n Only angular channels included in this map will be included in the\n output. Different angular channels are allowed to use completely\n different radial basis functions.",
              "type": "object",
              "additionalProperties": {
                "$ref": "#/$defs/RadialBasis"
              },
              "x-key-type": "integer"
            },
            "spline_accuracy": {
              "description": "Accuracy for splining the radial integral. Using splines is typically\n faster than analytical implementations. If this is None, no splining is\n done.\n\n The number of control points in the spline is automatically determined\n to ensure the average absolute error is close to the requested accuracy.",
              "type": [
                "number",
                "null"
              ],
              "format": "double",
              "default": 1e-8
            }
          },
          "additionalProperties": false,
          "required": [
            "type",
            "by_angular"
          ]
        }
      ]
    },
    "SplinePoint": {
      "description": "A single point entering a spline used for the tabulated radial integrals.",
      "type": "object",
      "properties": {
        "derivatives": {
          "description": "Array of derivatives for the tabulated radial integral",
          "type": "array",
          "items": {
            "type": "number",
            "format": "double"
          }
        },
        "position": {
          "description": "Position of the point",
          "type": "number",
          "format": "double"
        },
        "values": {
          "description": "Array of values for the tabulated radial integral",
          "type": "array",
          "items": {
            "type": "number",
            "format": "double"
          }
        }
      },
      "additionalProperties": false,
      "required": [
        "position",
        "values",
        "derivatives"
      ]
    }
  }
}

Parameters for LODE spherical expansion calculator.

The spherical expansion is at the core of representations in the LODE (long-distance equivariant) family. See this article for more information on the LODE representation.

basis: SphericalExpansionBasis:: Definition of the basis functions used to expand the atomic density in local environments
density: Density:: Definition of the density arising from atoms in the whole system
k_cutoff: number:: Spherical reciprocal cutoff. If k_cutoff is None, a cutoff of 1.2 π / SmearedPowerLaw.width, which is a reasonable value for most systems, is used.

SphericalExpansionBasis¶

Possible Basis functions to use for the SOAP or LODE spherical expansion.

The basis is made of radial and angular parts, that can be combined in various ways.

Pick one of the following according to its “type”:

{“type”: “TensorProduct”, “max_angular”: positive integer, “radial”: RadialBasis, “spline_accuracy”: number?}
This defines a tensor product basis, combining all possible radial basis functions with all possible angular basis functions.

max_angular: positive integer:

Maximal value (inclusive) of the angular moment (quantum number l) to use for the spherical harmonics basis functions

radial: RadialBasis:

Definition of the radial basis functions

spline_accuracy: optional, number:

Accuracy for splining the radial integral. Using splines is typically faster than analytical implementations. If this is None, no splining is done.

The number of control points in the spline is automatically determined to ensure the average absolute error is close to the requested accuracy.
{“type”: “Explicit”, “by_angular”: {[key: integer]: RadialBasis}, “spline_accuracy”: number?}
This defines an explicit basis, where only a specific subset of angular basis can be used, and every angular basis can use a different radial basis.

by_angular: {[key: integer]: RadialBasis}:

A map of radial basis to use for the specified angular channels.

Only angular channels included in this map will be included in the output. Different angular channels are allowed to use completely different radial basis functions.

spline_accuracy: optional, number:

Accuracy for splining the radial integral. Using splines is typically faster than analytical implementations. If this is None, no splining is done.

The number of control points in the spline is automatically determined to ensure the average absolute error is close to the requested accuracy.

Density¶

Definition of the (atomic) density to expand on a basis

Pick one of the following according to its “type”:

{“type”: “DiracDelta”, “center_atom_weight”: number?, “scaling”: DensityScaling?}
Dirac delta atomic density

center_atom_weight: optional, number:

See below.

scaling: optional, DensityScaling:

See below.
{“type”: “Gaussian”, “width”: number, “center_atom_weight”: number?, “scaling”: DensityScaling?}
Gaussian atomic density exp(-r^2/width^2)

width: number:

Width of the gaussian, the same width is used for all atoms

center_atom_weight: optional, number:

See below.

scaling: optional, DensityScaling:

See below.
{“type”: “SmearedPowerLaw”, “exponent”: positive integer, “smearing”: number, “center_atom_weight”: number?, “scaling”: DensityScaling?}
Smeared power law density, that behaves like 1 / r^p as r goes to infinity, while removing any singularity at r=0 and ensuring the density is differentiable everywhere.

The density functional form is f(r) = 1 / Γ(p/2) * γ(p/2, r^2/(2 σ^2)) / r^p, with σ the smearing width, Γ the Gamma function and γ the lower incomplete gamma function.

For more information about the derivation of this density, see https://doi.org/10.1021/acs.jpclett.3c02375 and section D of the supplementary information.

exponent: positive integer:

Exponent of the density (p)

smearing: number:

Smearing width of the density (σ)

center_atom_weight: optional, number:

See below.

scaling: optional, DensityScaling:

See below.

center_atom_weight: optional, number:: Weight of the central atom contribution to the density. If 1 the center atom contribution is weighted the same as any other contribution. If 0 the central atom does not contribute to the density at all.
scaling: optional, DensityScaling:: radial scaling can be used to reduce the importance of neighbor atoms further away from the center, usually improving the performance of the model

DensityScaling¶

Implemented options for radial scaling of the atomic density around an atom

Pick one of the following according to its “type”:

{“type”: “Willatt2018”, “exponent”: number, “rate”: number, “scale”: number}
Use a long-range algebraic decay and smooth behavior at r → 0 as introduced in https://doi.org/10.1039/C8CP05921G: f(r) = rate / (rate + (r / scale) ^ exponent)

exponent: number:

see in the formula

rate: number:

see in the formula

scale: number:

see in the formula

RadialBasis¶

The different kinds of radial basis supported LODE calculators

Pick one of the following according to its “type”:

{“type”: “Gto”, “max_radial”: positive integer, “radius”: number}
Use a radial basis similar to Gaussian-Type Orbitals.

The basis is defined as R_n(r) ∝ r^n e^{- r^2 / (2 σ_n^2)}, where σ_n = radius * \sqrt{n} / n_max

max_radial: positive integer:

Maximal value of n to include in the radial basis function definition. The overall basis will have max_radial + 1 basis functions, indexed from 0 to max_radial (inclusive).

radius: number:

Radius of the Gto basis, i.e. how far should the local LODE field be integrated.
{“type”: “Tabulated”, “center_contribution”: number[], “points”: SplinePoint[]}
Use pre-tabulated radial basis.

This enables the calculation of the overall radial integral using user-defined splines.

The easiest way to create such a tabulated basis is the corresponding functions in featomic’s Python API.

center_contribution: number[]:

The center_contribution is defined as c_n = \sqrt{4π} \int dr r^2 R_n(r) g(r) where g(r) is a radially symmetric density function, R_n(r) the radial basis function and n the current radial channel.

It is required for using tabulated basis with LODE, since we can not compute it using only the spline. This should be defined for the lambda=0 angular channel.

points: SplinePoint[]:

Points defining the spline

SplinePoint¶

A single point entering a spline used for the tabulated radial integrals.

derivatives: number[]:: Array of derivatives for the tabulated radial integral
position: number:: Position of the point
values: number[]:: Array of values for the tabulated radial integral