50 documentation update to fill in introduction and usage

anisoap/representations/ellipsoidal_density_projection.py

@@ -668,7 +668,9 @@ def transform(self, frames, show_progress=False, normalize=True, rust_moments=Tr
         else:
             return features
 
-    def power_spectrum(self, frames, sum_over_samples=True):
+    def power_spectrum(
+        self, frames, mean_over_samples=True, show_progress=False, rust_moments=True
+    ):
         """Function to compute the power spectrum of AniSOAP
 
         computes the power spectrum of AniSOAP with the inputs of AniSOAP hyperparameters
@@ -684,7 +686,7 @@ def power_spectrum(self, frames, sum_over_samples=True):
             'c_diameter[1]', 'c_diameter[2]', 'c_diameter[3]', 'c_q', 'positions', and 'numbers'.
             It only accepts c_q for the angular attribute of each frame.
 
-        sum_over_sample: bool
+        mean_over_samples: bool
             A function that returns the sum of coefficients of the frames in the sample.
 
         Returns
@@ -721,7 +723,9 @@ def power_spectrum(self, frames, sum_over_samples=True):
                 if "quaternion" in array:
                     raise ValueError(f"frame should contain c_q rather than quaternion")
 
-        mvg_coeffs = self.transform(frames, show_progress=True)
+        mvg_coeffs = self.transform(
+            frames, show_progress=show_progress, rust_moments=rust_moments
+        )
         mvg_nu1 = standardize_keys(mvg_coeffs)
 
         # Combines the mvg_nu1 with itself using the Clebsch-Gordan coefficients.
@@ -734,10 +738,10 @@ def power_spectrum(self, frames, sum_over_samples=True):
             other_keys_match=["types_center"],
         )
 
-        # If sum_over_samples = True, it returns simplified form of coefficients with fewer dimensions in the TensorMap for subsequent visualization.
+        # If mean_over_samples = True, it returns simplified form of coefficients with fewer dimensions in the TensorMap for subsequent visualization.
         # If not, it returns raw numerical data of coefficients in mvg_nu2 TensorMap
-        if sum_over_samples:
-            x_asoap_raw = metatensor.sum_over_samples(mvg_nu2, sample_names="center")
+        if mean_over_samples:
+            x_asoap_raw = metatensor.mean_over_samples(mvg_nu2, sample_names="center")
             x_asoap_raw = x_asoap_raw.block().values.squeeze()
             return x_asoap_raw
         else:

anisoap/representations/radial_basis.py

@@ -77,7 +77,7 @@ def gto_square_norm(n, sigma):
 def gto_prefactor(n, sigma):
     """Computes the normalization prefactor of an unnormalized GTO.
 
-    This prefactor is simply :math:`\\frac{1}{\\sqrt(\\text{square_norm_area)}}`.
+    This prefactor is simply :math:`\\frac{1}{\\sqrt{\\text{square_norm_area}}}`.
     Scaling a GTO by this prefactor will ensure that the GTO has square norm
     equal to 1.
 
@@ -155,7 +155,7 @@ def monomial_square_norm(n, r_cut):
 def monomial_prefactor(n, r_cut):
     """
     Computes the normalization prefactor of an unnormalized monomial basis.
-    This prefactor is simply :math:`1/sqrt{square_norm_area}`.
+    This prefactor is simply :math:`1/\sqrt{square\_norm\_area}`.
     Scaling a basis by this prefactor will ensure that the basis has square norm equal to 1.
 
     Parameters
@@ -183,8 +183,8 @@ def monomial_overlap(n, m, r_cut):
         .. math::
 
             \langle \phi_n, \phi_m \rangle &= \int_0^\infty dr r^2 r^n r^m \\
-                                           &= \int_0^r_{cut} dr r^2 |r^{(n+m)/2}|^2 \\
-                                           &= \int_0^r_{cut} dr r^2 |r^{n_{eff}}|^2
+                                           &= \int_0^{r_{cut}} dr r^2 |r^{(n+m)/2}|^2 \\
+                                           &= \int_0^{r_{cut}} dr r^2 |r^{n_{eff}}|^2
 
     Parameters
     ----------
@@ -315,7 +315,7 @@ class MonomialBasis(_RadialBasis):
 
     For monomial basis with coupled :math:`n_{\text{max}}` and :math:`l_{\text{max}}`,
     our radial basis set consists of monomials of order :math:`n=0` to
-    :math:`n=\text{max}{l_{\text{max}} + 2n_{\text{max}}}`
+    :math:`n=\max{l_{\text{max}} + 2n_{\text{max}}}`
 
     Monomials are not square-integrable from :math:`[0, \infty]`, so we orthonormalize
     by integrating up to the cutoff radius
@@ -362,7 +362,7 @@ def calc_overlap_matrix(self):
         The overlap matrix is a Gram matrix whose entries are the overlap:
 
             .. math::
-                S_{ij} = \int_{0}^{r_{cut} dr r^2 phi_i phi_j
+                S_{ij} = \int_{0}^{r_{cut}} dr r^2 \phi_i \phi_j
 
         The overlap has an analytic solution (see above functions).
 
@@ -442,7 +442,7 @@ def get_basis(self, rs):
 
         If lmax and nmax defined, then the number of functions outputted is lmax*(nmax+1)
 
-        If lmax and nmax coupled, then the number of functions outputted is \sum_{l=0}^{lmax} (number_of_radial_functions_per_l)
+        If lmax and nmax coupled, then the number of functions outputted is :math:`\sum_{l=0}^{lmax} (number\_of\_radial\_functions\_per\_l)`
 
         Parameters
         ----------
@@ -543,8 +543,7 @@ def calc_overlap_matrix(self):
         The overlap matrix is a Gram matrix whose entries are the overlap:
 
         .. math::
-
-            S_{ij} = \\int_0^\\infty dr \\, r^2 \\phi_i \\phi_j
+            S_{ij} = \int_0^\infty dr r^2 \phi_i \phi_j
 
         The overlap has an analytic solution (see above functions).
 

anisoap/utils/spherical_to_cartesian.py

@@ -86,8 +86,8 @@ def binom(n, k):
 def spherical_to_cartesian(lmax, num_ns):
     """
     Finds the coefficients for the cartesian polynomial form of solid harmonics
-    :math:`R_{lm} = sqrt((4pi)/(2l+1))*r^l*Y_{lm}`.  Note that our AniSOAP
-    expansion does not contain the sqrt((4pi)/(2l+1)), so in calculating
+    :math:`R_{lm} = \sqrt{(4\pi)/(2l+1)}*r^l*Y_{lm}`.  Note that our AniSOAP
+    expansion does not contain the :math:`\sqrt{(4\pi)/(2l+1)}` prefactor, so in calculating
     expansion coefficients, we need to divide by that coefficient.
 
     Parameters

docs/build/html/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 659e0c65a11d76910d18ee3f5a4960ac
+tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/build/html/_sources/api.rst.txt

@@ -0,0 +1,41 @@
+API Reference
+=============
+
+Representations
+---------------
+.. automodule:: anisoap.representations.ellipsoidal_density_projection
+   :members:
+   :show-inheritance:
+   :inherited-members:
+.. automodule:: anisoap.representations.radial_basis
+   :members:
+   :show-inheritance:
+   :inherited-members:
+
+Utilities
+---------
+.. automodule:: anisoap.utils.cyclic_list
+   :members:
+   :show-inheritance:
+   :inherited-members:
+.. automodule:: anisoap.utils.metatensor_utils
+   :members:
+   :show-inheritance:
+   :inherited-members:
+.. automodule:: anisoap.utils.moment_generator
+   :members:
+   :show-inheritance:
+   :inherited-members:
+.. automodule:: anisoap.utils.monomial_iterator
+   :members:
+   :show-inheritance:
+   :inherited-members:
+.. automodule:: anisoap.utils.shortcuts
+   :members:
+   :show-inheritance:
+   :inherited-members:
+.. automodule:: anisoap.utils.spherical_to_cartesian
+   :members:
+   :show-inheritance:
+   :inherited-members:
+

docs/build/html/_sources/getting_started.rst.txt

@@ -0,0 +1,31 @@
+===============
+Getting Started
+===============
+
+Introduction
+------------
+AniSOAP is a package for creating machine-learnable representations of systems 
+of particles in a way that preserves geometrical information.  AniSOAP works 
+similarly to SOAP (Smooth Overlap of Atomic Potentials) in many ways, with the 
+chief difference being AniSOAP's ability to represent ellipsoidal particles.
+
+First Steps
+-----------
+AniSOAP depends on and utilizes the packages `featomic (aka rascaline) 
+<https://metatensor.github.io/featomic/latest/index.html>`_, `metatensor <https://docs.metatensor.org/latest/index.html>`_,
+and `ase <https://wiki.fysik.dtu.dk/ase/index.html>`_.  
+It may be helpful to familiarize yourself with these packages before diving into
+AniSOAP.
+
+Key Concepts
+------------
+In the AniSOAP representation, particles are treated as multivariate Gaussians (MVGs).
+For each particle, we can consider its n-body interactions with nearby particles.
+Each local density field is then decomposed in terms of spherical harmonics and 
+some choice of radial basis functions in order to be compactly represented in
+vector form.
+
+A single AniSOAP vector represents the environment of a single central ellipsoid.
+A system of such particles can then be represented, for example, as a matrix of
+AniSOAP vectors.
+

docs/build/html/_sources/index.rst.txt

@@ -0,0 +1,29 @@
+===================================
+Welcome to AniSOAP's documentation!
+===================================
+
+**AniSOAP** is a Python library for creating descriptors of chemical systems 
+suitable for machine learning use.  This project aims to extend the popular Smooth Overlap of Atomic Positions (SOAP) 
+descriptors to coarse-grained systems consisting of aspherical particles 
+with anisotropic interactions.
+
+.. note::
+
+   This project is under active development.
+
+.. note::
+
+   AniSOAP documentation is a work in progress; please contact us with questions 
+   not yet addressed here.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   installation
+   getting_started
+   auto_examples/index
+   usage
+   api
+
+

docs/build/html/_sources/installation.rst.txt

@@ -0,0 +1,44 @@
+============ 
+Installation
+============
+
+Dependencies
+------------
+
+Before installing AniSOAP, please make sure you have the following installed (We recommend using an environment manager like `conda <https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html/>`_):
+
+* `Python: 3.9 or 3.10 <https://www.python.org/downloads/>`_
+* `numPy: 1.13 or higher <https://numpy.org/install/>`_
+* `sciPy: 1.4.0 or higher <https://scipy.org/install/>`_
+* `Atomic Simulation Environment (ASE): 3.18 or higher <https://wiki.fysik.dtu.dk/ase/install.html>`_
+* `Metatensor <https://docs.metatensor.org/latest/index.html>`_
+* `Featomic (aka Rascaline) <https://metatensor.github.io/featomic/latest/index.html>`_
+* `Rust -- We reccommend using 'rustup <https://rustup.rs/>`_
+
+
+Installing AniSOAP
+------------------
+
+Navigate to the directory where you would like the AniSOAP package to be located, then copy and paste the 
+following into your shell::
+
+  git clone https://github.com/cersonsky-lab/AniSOAP
+
+Then navigate to the AniSOAP directory with::
+
+  cd AniSOAP
+
+Now use pip to install the library::
+
+  pip install .
+
+
+Testing
+-------
+
+AniSOAP is still under active development, so you may want to run some tests to ensure that your installation is working properly.  From the main directory you can run the internal tests with::
+
+  pytest tests/.
+
+
+

docs/build/html/_sources/usage.rst.txt

@@ -0,0 +1,5 @@
+Usage
+=====
+
+AniSOAP interoperates heavily with `ASE <https://wiki.fysik.dtu.dk/ase/>`_ and 
+`Metatensor <https://docs.metatensor.org/latest/index.html>`_.