Update math page

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 <https://en.wikipedia.org/wiki/Spherical_harmonics>`_, 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 <https://arxiv.org/abs/2302.08381>`_ 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 <https://en.wikipedia.org/wiki/Spherical_harmonics>`_.
-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 

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.
 
         """