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
1the center atom contribution is weighted the same as any other contribution. If0the 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 < cutoffand 0 ifr >= 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_splinesPython function.For LODE calculations also the contribution of the central atom have to be provided. The
center_contributionis defined asc_n = \sqrt{4π} \int dr r^2 R_n(r) g(r)whereg(r)is a radially symmetric density function,R_n(r)the radial basis function andnthe 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, whiler \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