Spherical expansion

This calculator is registered with the spherical_expansion name.

SphericalExpansion hyper-parameters

Show full JSON schema
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "SphericalExpansionParameters",
  "description": "Parameters for spherical expansion calculator.\n\nThe spherical expansion is at the core of representations in the SOAP (Smooth Overlap of Atomic Positions) family. See [this review article](https://doi.org/10.1063/1.5090481) for more information on the SOAP representation, and [this paper](https://doi.org/10.1063/5.0044689) for information on how it is implemented in rascaline.",
  "type": "object",
  "required": [
    "atomic_gaussian_width",
    "center_atom_weight",
    "cutoff",
    "cutoff_function",
    "max_angular",
    "max_radial",
    "radial_basis"
  ],
  "properties": {
    "atomic_gaussian_width": {
      "description": "Width of the atom-centered gaussian used to create the atomic density",
      "type": "number",
      "format": "double"
    },
    "center_atom_weight": {
      "description": "Weight of the central atom contribution to the features. If `1` the center atom contribution is weighted the same as any other contribution. If `0` the central atom does not contribute to the features at all.",
      "type": "number",
      "format": "double"
    },
    "cutoff": {
      "description": "Spherical cutoff to use for atomic environments",
      "type": "number",
      "format": "double"
    },
    "cutoff_function": {
      "description": "Cutoff function used to smooth the behavior around the cutoff radius",
      "allOf": [
        {
          "$ref": "#/definitions/CutoffFunction"
        }
      ]
    },
    "max_angular": {
      "description": "Number of spherical harmonics to use in the expansion",
      "type": "integer",
      "format": "uint",
      "minimum": 0.0
    },
    "max_radial": {
      "description": "Number of radial basis function to use in the expansion",
      "type": "integer",
      "format": "uint",
      "minimum": 0.0
    },
    "radial_basis": {
      "description": "Radial basis to use for the radial integral",
      "allOf": [
        {
          "$ref": "#/definitions/RadialBasis"
        }
      ]
    },
    "radial_scaling": {
      "description": "radial scaling can be used to reduce the importance of neighbor atoms further away from the center, usually improving the performance of the model",
      "default": {
        "None": {}
      },
      "allOf": [
        {
          "$ref": "#/definitions/RadialScaling"
        }
      ]
    }
  },
  "definitions": {
    "CutoffFunction": {
      "description": "Possible values for the smoothing cutoff function",
      "oneOf": [
        {
          "description": "Step function, 1 if `r < cutoff` and 0 if `r >= cutoff`",
          "type": "object",
          "required": [
            "Step"
          ],
          "properties": {
            "Step": {
              "type": "object"
            }
          },
          "additionalProperties": false
        },
        {
          "description": "Shifted cosine switching function `f(r) = 1/2 * (1 + cos(π (r - cutoff + width) / width ))`",
          "type": "object",
          "required": [
            "ShiftedCosine"
          ],
          "properties": {
            "ShiftedCosine": {
              "type": "object",
              "required": [
                "width"
              ],
              "properties": {
                "width": {
                  "type": "number",
                  "format": "double"
                }
              }
            }
          },
          "additionalProperties": false
        }
      ]
    },
    "RadialBasis": {
      "description": "Radial basis that can be used in the SOAP or LODE spherical expansion",
      "oneOf": [
        {
          "description": "Use a radial basis similar to Gaussian-Type Orbitals.\n\nThe basis is defined as `R_n(r) ∝ r^n e^{- r^2 / (2 σ_n^2)}`, where `σ_n = cutoff * \\sqrt{n} / n_max`",
          "type": "object",
          "required": [
            "Gto"
          ],
          "properties": {
            "Gto": {
              "type": "object",
              "properties": {
                "spline_accuracy": {
                  "description": "Accuracy for the spline. The number of control points in the spline is automatically determined to ensure the average absolute error is close to the requested accuracy.",
                  "default": 1e-8,
                  "type": "number",
                  "format": "double"
                },
                "splined_radial_integral": {
                  "description": "compute the radial integral using splines. This is much faster than the base GTO implementation.",
                  "default": true,
                  "type": "boolean"
                }
              }
            }
          },
          "additionalProperties": false
        },
        {
          "description": "Compute the radial integral with user-defined splines.\n\nThe easiest way to create a set of spline points is the `rascaline.generate_splines` Python function.\n\nFor LODE calculations also the contribution of the central atom have to be provided. 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. Note that the integration range was deliberately left ambiguous since it depends on the radial basis, i.e. for the GTO basis, `r \\in R^+` is used, while `r \\in [0, cutoff]` for the monomial basis.",
          "type": "object",
          "required": [
            "TabulatedRadialIntegral"
          ],
          "properties": {
            "TabulatedRadialIntegral": {
              "type": "object",
              "required": [
                "points"
              ],
              "properties": {
                "center_contribution": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "items": {
                    "type": "number",
                    "format": "double"
                  }
                },
                "points": {
                  "type": "array",
                  "items": {
                    "$ref": "#/definitions/SplinePoint"
                  }
                }
              }
            }
          },
          "additionalProperties": false
        }
      ]
    },
    "RadialScaling": {
      "description": "Implemented options for radial scaling of the atomic density around an atom",
      "oneOf": [
        {
          "description": "No radial scaling",
          "type": "object",
          "required": [
            "None"
          ],
          "properties": {
            "None": {
              "type": "object"
            }
          },
          "additionalProperties": false
        },
        {
          "description": "Use a long-range algebraic decay and smooth behavior at $r \\rightarrow 0$ as introduced in <https://doi.org/10.1039/C8CP05921G>: `f(r) = rate / (rate + (r / scale) ^ exponent)`",
          "type": "object",
          "required": [
            "Willatt2018"
          ],
          "properties": {
            "Willatt2018": {
              "type": "object",
              "required": [
                "exponent",
                "rate",
                "scale"
              ],
              "properties": {
                "exponent": {
                  "type": "number",
                  "format": "double"
                },
                "rate": {
                  "type": "number",
                  "format": "double"
                },
                "scale": {
                  "type": "number",
                  "format": "double"
                }
              }
            }
          },
          "additionalProperties": false
        }
      ]
    },
    "SplinePoint": {
      "description": "A single point entering a spline used for the tabulated radial integrals.",
      "type": "object",
      "required": [
        "derivatives",
        "position",
        "values"
      ],
      "properties": {
        "derivatives": {
          "description": "Array of values for the tabulated radial integral (the shape should be `(max_angular + 1) x max_radial`)",
          "allOf": [
            {
              "$ref": "#/definitions/ndarray::Array"
            }
          ]
        },
        "position": {
          "description": "Position of the point",
          "type": "number",
          "format": "double"
        },
        "values": {
          "description": "Array of values for the tabulated radial integral (the shape should be `(max_angular + 1) x max_radial`)",
          "allOf": [
            {
              "$ref": "#/definitions/ndarray::Array"
            }
          ]
        }
      }
    },
    "ndarray::Array": {
      "title": "ndarray::Array",
      "description": "Serialization format used by ndarray",
      "type": "object",
      "required": [
        "data",
        "dim",
        "v"
      ],
      "properties": {
        "data": {
          "title": "Array_of_double",
          "description": "data of the array, in row-major order",
          "type": "array",
          "items": {
            "type": "number",
            "format": "double"
          }
        },
        "dim": {
          "title": "Array_of_uint",
          "description": "shape of the array",
          "type": "array",
          "items": {
            "type": "integer",
            "format": "uint",
            "minimum": 0.0
          }
        },
        "v": {
          "description": "version of the ndarray serialization scheme, should be 1",
          "examples": [
            1
          ],
          "type": "integer"
        }
      }
    }
  }
}

Parameters for spherical expansion calculator.

The spherical expansion is at the core of representations in the SOAP (Smooth Overlap of Atomic Positions) family. See this review article for more information on the SOAP representation, and this paper for information on how it is implemented in rascaline.

atomic_gaussian_width: number:

Width of the atom-centered gaussian used to create the atomic density

center_atom_weight: number:

Weight of the central atom contribution to the features. If 1 the center atom contribution is weighted the same as any other contribution. If 0 the central atom does not contribute to the features at all.

cutoff: number:

Spherical cutoff to use for atomic environments

cutoff_function: CutoffFunction:

Cutoff function used to smooth the behavior around the cutoff radius

max_angular: unsigned integer:

Number of spherical harmonics to use in the expansion

max_radial: unsigned integer:

Number of radial basis function to use in the expansion

radial_basis: RadialBasis:

Radial basis to use for the radial integral

radial_scaling: optional, RadialScaling:

radial scaling can be used to reduce the importance of neighbor atoms further away from the center, usually improving the performance of the model

CutoffFunction

Possible values for the smoothing cutoff function

  • Step: {}

    Step function, 1 if r < cutoff and 0 if r >= cutoff

  • ShiftedCosine: {width: number}

    Shifted cosine switching function f(r) = 1/2 * (1 + cos(π (r - cutoff + width) / width ))

RadialBasis

Radial basis that can be used in the SOAP or LODE spherical expansion

  • Gto: {spline_accuracy: number, splined_radial_integral: boolean}

    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

  • TabulatedRadialIntegral: {center_contribution: number[], points: SplinePoint[]}

    Compute the radial integral with user-defined splines.

    The easiest way to create a set of spline points is the rascaline.generate_splines Python function.

    For LODE calculations also the contribution of the central atom have to be provided. 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. Note that the integration range was deliberately left ambiguous since it depends on the radial basis, i.e. for the GTO basis, r \in R^+ is used, while r \in [0, cutoff] for the monomial basis.

RadialScaling

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

  • None: {}

    No radial scaling

  • Willatt2018: {exponent: number, rate: number, scale: number}

    Use a long-range algebraic decay and smooth behavior at $r \rightarrow 0$ as introduced in https://doi.org/10.1039/C8CP05921G: f(r) = rate / (rate + (r / scale) ^ exponent)

SplinePoint

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

derivatives: ndarray::Array:

Array of values for the tabulated radial integral (the shape should be (max_angular + 1) x max_radial)

position: number:

Position of the point

values: ndarray::Array:

Array of values for the tabulated radial integral (the shape should be (max_angular + 1) x max_radial)

ndarray::Array

Serialization format used by ndarray

data: number[]:

data of the array, in row-major order

dim: unsigned integer[]:

shape of the array

v: integer:

version of the ndarray serialization scheme, should be 1