From 7f80672f8ccb2ad83bb6f70876dfc03fa3b13cf0 Mon Sep 17 00:00:00 2001 From: frostedoyster Date: Wed, 28 Aug 2024 22:36:28 +0200 Subject: [PATCH] Update math page --- docs/src/maths.rst | 27 +++++++------ python/src/sphericart/spherical_harmonics.py | 40 ++++++++++---------- 2 files changed, 35 insertions(+), 32 deletions(-) diff --git a/docs/src/maths.rst b/docs/src/maths.rst index f26e5b271..eec92c352 100644 --- a/docs/src/maths.rst +++ b/docs/src/maths.rst @@ -12,11 +12,21 @@ There are multiple conventions for choosing normalization and phases, and it is possible to reformulate the spherical harmonics in a real-valued form, which leads to even further ambiguity in the definitions. -Within `sphericart` we take an opinionated stance: we compute only real-valued -harmonics, we express them as a function of the full Cartesian coordinates of a -point in three dimensions :math:`(x,y,z)` and compute by default "scaled" -versions :math:`\tilde{Y}^m_l(x, y, z)` which correspond to homogeneous polynomials -of the Cartesian coordinates: +Within `sphericart`, we compute only real-valued spherical harmonics and we express +them as a function of the full Cartesian coordinates of a point in three dimensions. +These correspond to the real spherical harmonics as defined in the corresponding +`Wikipedia article `_, which we +refer to as :math:`Y^m_l`. + +We also offer the possibility to compute "solid" harmonics, which are given by +:math:`\tilde{Y}^m_l = r^l\,{Y}_l^m`. Since these can be expressed as homogeneous +polynomials of the Cartesian coordinates :math:`(x,y,z)`, as opposed to +:math:`(x/r,y/r,z/r)`, they are less computationally expensive to evaluate. +Besides being slightly faster, they can also +provide a more natural scaling if used together with a radial expansion. + +The formulas used to compute the solid harmonics (and, with few modifications, +also for the spherical harmonics) are: .. math :: \tilde{Y}_l^m(x, y, z) = r^l\,{Y}_l^m(x, y, z) = F_l^{|m|} Q_l^{|m|}(z, r) \times @@ -41,13 +51,6 @@ If we neglect some constant normalization factors, these correspond to the See also the `reference paper `_ for further implementation details. -The radially normalized version of the spherical harmonics can also be computed by providing -the appropriate flag when creating the `sphericart` calculators. These correspond to -the real spherical harmonics as defined in the corresponding -`Wikipedia article `_. -However, we recommend using the scaled versions, which are slightly faster and -provide a more natural scaling if used together with a radial expansion. - The :math:`\tilde{Y}^m_l(x)` are stored contiguously in memory, e.g. as :math:`\{ (l,m)=(0,0), (1,-1), (1,0), (1,1), (2,-2), \ldots \}`. With zero-based indexing of the arrays, the ``(l,m)`` term is stored at diff --git a/python/src/sphericart/spherical_harmonics.py b/python/src/sphericart/spherical_harmonics.py index c8b4874d4..27e9dc5da 100644 --- a/python/src/sphericart/spherical_harmonics.py +++ b/python/src/sphericart/spherical_harmonics.py @@ -143,15 +143,15 @@ def compute_with_gradients(self, xyz: np.ndarray) -> Tuple[np.ndarray, np.ndarra A tuple containing: - an array of shape ``(n_samples, (l_max+1)**2)`` containing all the - spherical harmonics up to degree `l_max` in lexicographic order. - For example, if ``l_max = 2``, The last axis will correspond to - spherical harmonics with ``(l, m) = (0, 0), (1, -1), (1, 0), (1, - 1), (2, -2), (2, -1), (2, 0), (2, 1), (2, 2)``, in this order. + spherical harmonics up to degree `l_max` in lexicographic order. + For example, if ``l_max = 2``, The last axis will correspond to + spherical harmonics with ``(l, m) = (0, 0), (1, -1), (1, 0), (1, + 1), (2, -2), (2, -1), (2, 0), (2, 1), (2, 2)``, in this order. - an array of shape ``(n_samples, 3, (l_max+1)**2)`` containing all - the spherical harmonics' derivatives up to degree ``l_max``. The - last axis is organized in the same way as in the spherical - harmonics return array, while the second-to-last axis refers to - derivatives in the the x, y, and z directions, respectively. + the spherical harmonics' derivatives up to degree ``l_max``. The + last axis is organized in the same way as in the spherical + harmonics return array, while the second-to-last axis refers to + derivatives in the the x, y, and z directions, respectively. """ @@ -233,20 +233,20 @@ def compute_with_hessians( :return: A tuple containing: - an array of shape ``(n_samples, (l_max+1)**2)`` containing all the - spherical harmonics up to degree `l_max` in lexicographic order. - For example, if ``l_max = 2``, The last axis will correspond to - spherical harmonics with ``(l, m) = (0, 0), (1, -1), (1, 0), (1, - 1), (2, -2), (2, -1), (2, 0), (2, 1), (2, 2)``, in this order. + spherical harmonics up to degree `l_max` in lexicographic order. + For example, if ``l_max = 2``, The last axis will correspond to + spherical harmonics with ``(l, m) = (0, 0), (1, -1), (1, 0), (1, + 1), (2, -2), (2, -1), (2, 0), (2, 1), (2, 2)``, in this order. - an array of shape ``(n_samples, 3, (l_max+1)**2)`` containing all - the spherical harmonics' derivatives up to degree ``l_max``. The - last axis is organized in the same way as in the spherical - harmonics return array, while the second-to-last axis refers to - derivatives in the the x, y, and z directions, respectively. + the spherical harmonics' derivatives up to degree ``l_max``. The + last axis is organized in the same way as in the spherical + harmonics return array, while the second-to-last axis refers to + derivatives in the the x, y, and z directions, respectively. - an array of shape ``(n_samples, 3, 3, (l_max+1)**2)`` containing all - the spherical harmonics' second derivatives up to degree ``l_max``. - The last axis is organized in the same way as in the spherical - harmonics return array, while the two intermediate axes represent the - Hessian dimensions. + the spherical harmonics' second derivatives up to degree ``l_max``. + The last axis is organized in the same way as in the spherical + harmonics return array, while the two intermediate axes represent the + Hessian dimensions. """