Spherical expansion by pair¶

This calculator is registered with the spherical_expansion_by_pair name.

SphericalExpansionByPair hyper-parameters¶

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "SphericalExpansionParameters",
  "description": "Parameters for spherical expansion calculator.\n\n The spherical expansion is at the core of representations in the SOAP\n (Smooth Overlap of Atomic Positions) family. The core idea is to define\n atom-centered environments using a spherical cutoff; create an atomic\n density according to all neighbors in a given environment; and finally\n expand this density on a given set of basis functions. The parameters for\n each of these steps can be defined separately below.\n\n See [this review article](https://doi.org/10.1063/1.5090481) for more\n information on the SOAP representation, and [this\n paper](https://doi.org/10.1063/5.0044689) for information on how it is\n implemented in featomic.",
  "type": "object",
  "properties": {
    "basis": {
      "description": "Definition of the basis functions used to expand the atomic density",
      "$ref": "#/$defs/SphericalExpansionBasis"
    },
    "cutoff": {
      "description": "Definition of the atomic environment within a cutoff, and how\n neighboring atoms enter and leave the environment.",
      "$ref": "#/$defs/Cutoff"
    },
    "density": {
      "description": "Definition of the density arising from atoms in the local environment.",
      "$ref": "#/$defs/Density"
    }
  },
  "additionalProperties": false,
  "required": [
    "cutoff",
    "density",
    "basis"
  ],
  "$defs": {
    "Cutoff": {
      "description": "Definition of a local environment for SOAP calculations",
      "type": "object",
      "properties": {
        "radius": {
          "description": "Radius of the spherical cutoff to use for atomic environments",
          "type": "number",
          "format": "double"
        },
        "smoothing": {
          "description": "Cutoff function used to smooth the behavior around the cutoff radius",
          "$ref": "#/$defs/Smoothing"
        }
      },
      "additionalProperties": false,
      "required": [
        "radius",
        "smoothing"
      ]
    },
    "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 by SOAP 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 = cutoff * \\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": {
              "type": [
                "number",
                "null"
              ],
              "format": "double"
            }
          },
          "additionalProperties": false,
          "required": [
            "type",
            "max_radial"
          ]
        },
        {
          "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"
            },
            "points": {
              "description": "Points defining the spline",
              "type": "array",
              "items": {
                "$ref": "#/$defs/SplinePoint"
              }
            }
          },
          "additionalProperties": false,
          "required": [
            "type",
            "points"
          ]
        }
      ]
    },
    "Smoothing": {
      "description": "Possible values for the smoothing cutoff function",
      "oneOf": [
        {
          "description": "Shifted cosine smoothing function\n `f(r) = 1/2 * (1 + cos(π (r - cutoff + width) / width ))`",
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "ShiftedCosine"
            },
            "width": {
              "description": "Width of the switching function",
              "type": "number",
              "format": "double"
            }
          },
          "additionalProperties": false,
          "required": [
            "type",
            "width"
          ]
        },
        {
          "description": "Step smoothing function (i.e. no smoothing). This is 1 inside the cutoff\n and 0 outside, with a sharp step at the boundary.",
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "const": "Step"
            }
          },
          "additionalProperties": false,
          "required": [
            "type"
          ]
        }
      ]
    },
    "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 spherical expansion calculator.

The spherical expansion is at the core of representations in the SOAP (Smooth Overlap of Atomic Positions) family. The core idea is to define atom-centered environments using a spherical cutoff; create an atomic density according to all neighbors in a given environment; and finally expand this density on a given set of basis functions. The parameters for each of these steps can be defined separately below.

See this review article for more information on the SOAP representation, and this paper for information on how it is implemented in featomic.

basis: SphericalExpansionBasis:: Definition of the basis functions used to expand the atomic density
cutoff: Cutoff:: Definition of the atomic environment within a cutoff, and how neighboring atoms enter and leave the environment.
density: Density:: Definition of the density arising from atoms in the local environment.

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.

Cutoff¶

Definition of a local environment for SOAP calculations

radius: number:: Radius of the spherical cutoff to use for atomic environments
smoothing: Smoothing:: Cutoff function used to smooth the behavior around the cutoff radius

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 by SOAP 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 = cutoff * \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:
{“type”: “Tabulated”, “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.

points: SplinePoint[]:

Points defining the spline

Smoothing¶

Possible values for the smoothing cutoff function

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

{“type”: “ShiftedCosine”, “width”: number}
Shifted cosine smoothing function f(r) = 1/2 * (1 + cos(π (r - cutoff + width) / width ))

width: number:

Width of the switching function
{“type”: “Step”}
Step smoothing function (i.e. no smoothing). This is 1 inside the cutoff and 0 outside, with a sharp step at the boundary.

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