SOAP radial spectrum¶

This calculator is registered with the soap_radial_spectrum name.

SoapRadialSpectrum hyper-parameters¶

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "RadialSpectrumParameters",
  "description": "Parameters for the SOAP radial spectrum calculator.\n\n The SOAP radial spectrum represent each atom by the radial average of the density\n of its neighbors. It is very similar to a radial distribution function\n `g(r)`. It is a 2-body representation, only containing information about the\n distances between atoms.\n\n See [this review article](https://doi.org/10.1063/1.5090481) for more\n information on the SOAP representations.",
  "type": "object",
  "properties": {
    "basis": {
      "description": "Definition of the basis functions used to expand the atomic density",
      "$ref": "#/$defs/RadialSpectrumBasis"
    },
    "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"
    }
  },
  "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"
          ]
        }
      ]
    },
    "RadialSpectrumBasis": {
      "description": "Information about radial spectrum basis functions",
      "type": "object",
      "properties": {
        "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": [
        "radial"
      ]
    },
    "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"
          ]
        }
      ]
    },
    "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 the SOAP radial spectrum calculator.

The SOAP radial spectrum represent each atom by the radial average of the density of its neighbors. It is very similar to a radial distribution function g(r). It is a 2-body representation, only containing information about the distances between atoms.

See this review article for more information on the SOAP representations.

basis: RadialSpectrumBasis:: 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.

RadialSpectrumBasis¶

Information about radial spectrum 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.

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