formatting docs and additional updates

Author: jmgoff

mala/common/parameters.py

@@ -471,50 +471,47 @@ class ParametersDescriptors(ParametersBase):
         descriptor calculation.
 
     ace_ranks : list
-        ACE_DOCS_MISSING: I think I know what this does, but I am not sure
-        how to best communicate to users how to set this.
+        Orders of the expansion, referred to as `N` in Drautz 2019, of the
+        descriptors to be enumerated
 
     ace_nmax  : list
-        ACE_DOCS_MISSING: I think I know what this does, but I am not sure
-        how to best communicate to users how to set this.
+        Maximum radial basis function index per descriptor rank
 
     ace_lmax : list
-        ACE_DOCS_MISSING: I think I know what this does, but I am not sure
-        how to best communicate to users how to set this.
+        Maximum angular momentum number per descriptor rank (maximum angular function index)
 
     ace_lmin : list
-        ACE_DOCS_MISSING: I think I know what this does, but I am not sure
-        how to best communicate to users how to set this.
+        Lower bound on angular momentum quantum number per rank.
 
     ace_nshell : list
-        ACE_DOCS_MISSING: I think I know what this does, but I am not sure
-        how to best communicate to users how to set this.
+        Number(s) to multiply atomic radii by to get radial cutoffs
 
     ace_apply_shift : list
-        ACE_DOCS_MISSING: I think I know what this does, but I am not sure
-        how to best communicate to users how to set this.
+        Constants to shift radial cutoffs by (useful for small elements like H).
 
     ace_metal_max : list
-        ACE_DOCS_MISSING: I think I know what this does, but I am not sure
-        how to best communicate to users how to set this.
+        Maximize radial cutoffs for "metals", effectively increases radial cutoffs for certain elements.
 
     ace_use_vdw : list
-        ACE_DOCS_MISSING: I think I know what this does, but I am not sure
-        how to best communicate to users how to set this.
+        Flag to use vdW radii (larger automated radial cutoffs generated). 
 
     ace_L_R : list
-        ACE_DOCS_MISSING: I am not sure how to set this.
+        Resultant angular momentum quantum number. This determines the equivariant
+        character of the rank N descriptor after reduction. L_R=0 corresponds to
+        a rotationally invariant feature, L_R=1 corresponds to a feature that
+        transforms like a vector, L_R=2 a tensor, etc.
 
     ace_M_R : list
-        ACE_DOCS_MISSING: I am not sure how to set this.
+        Resultant projection quantum number. This also determines the equivariant
+            character of the rank N descriptor after reduction. M_R must obey
+            -L_R <= M_R <= L_R
 
     ace_coupling_type : str
         Coupling type used for reduction of spherical harmonic products.
         Can be "clebsch_gordan" or "wigner_3j".
 
     ace_reduction_coefficients_lmax : int
-        ACE_DOCS_MISSING: I think I know what this does, but I am not sure
-        how to best communicate to users how to set this.
+        Global maximum angular momentum for precalculating generalized coupling coefficients.
     """
 
     def __init__(self):

mala/descriptors/ace.py

@@ -16,17 +16,11 @@
 
 class ACEPotential:
     """
-    Class to manage interface between ACE descriptor enumeration library and
-    LAMMPS. By default, it will enumerate ACE descriptors according to the 
-    Permutation-adapted approach described in https://doi.org/10.1016/j.jcp.2024.113073.
-    However, there are options for assigning descriptor labels if desired, manually
-    for example.
-
-    After enumerating descriptors, it assigns all relevant hyperparamters needed
-    to evaluate the ACE descriptors in LAMMPS. It saves a .yace file needed to
-    evaluate ACE descriptors in LAMMPS (containing coupling coefficients). It does this
-    by writing an ACE potential file, readable by LAMNMPS, that contains only
-    information to evaluate descriptors, not energy models.
+    Class to manage interface between ACE descriptor enumeration library and LAMMPS. By default, it will enumerate ACE descriptors according to the Permutation-adapted approach described in https://doi.org/10.1016/j.jcp.2024.113073.
+
+    However, there are options for assigning descriptor labels if desired, manually for example.
+
+    After enumerating descriptors, it assigns all relevant hyperparamters needed to evaluate the ACE descriptors in LAMMPS. It saves a .yace file needed to evaluate ACE descriptors in LAMMPS (containing coupling coefficients). It does this by writing an ACE potential file, readable by LAMNMPS, that contains only information to evaluate descriptors, not energy models.
     
     Parameters
     ----------
@@ -79,7 +73,7 @@ class ACEPotential:
          0.0 (OFF) for each bond type in MALA. 
 
     lmin : int/list
-        lower bound on angular momentum quantum number per rank.
+        Lower bound on angular momentum quantum number per rank.
 
     manual_labels : str
         File for loading labels. If not None, then labels will be loaded from
@@ -88,6 +82,11 @@ class ACEPotential:
 
     **kwarg : dict
         Additional keyword arguments.
+
+    Returns
+    -------
+    ACEPotential : class
+        Class containing ACE descriptor and hyperparamter info.
     """
 
     def __init__(
@@ -231,9 +230,9 @@ def __init__(
 
     def __set_embeddings(self, npoti="FinnisSinclair", FSparams=[1.0, 1.0]):
         """
-        Set 'embeddings' in the .yace file for lammps. Some terms here control
-        if a square-root embedding term is added. This should always be OFF
-        for descriptor calculations in MALA
+        Set 'embeddings' in the .yace file for lammps. Some terms here control if a square-root embedding term is added.
+
+        This should always be OFF for descriptor calculations in MALA.
 
         Parameters
         ----------
@@ -263,12 +262,11 @@ def __set_bonds(self):
 
     def __set_bond_base(self):
         """
-        Set the per-bond radial basis parameters. The 'bonds' are determined based
-        on the elements. If the elements are ['Al','G'], the bonds may be
-        determined with :code:`itertools.product()` in python. They are
-        (Al,Al)(Al,G)(G,Al)(G,G). Some hyperparameters must be specified per bond
-        label shown here.
+        Set the per-bond radial basis parameters. The 'bonds' are determined based on the elements.
+
+        If the elements are ['Al','G'], the bonds may be determined with :code:`itertools.product()` in python. They are (Al,Al)(Al,G)(G,Al)(G,G).
 
+        Some hyperparameters must be specified per bond label shown here.
         
         """
         bondstrs = ["[%d, %d]" % (b[0], b[1]) for b in self.__bondlsts]
@@ -352,8 +350,7 @@ def __set_bond_base(self):
 
     def set_funcs(self, nulst=None, print_0s=True):
         """
-        Set ctilde 'functions' in the .yace file, used to calculate
-        descriptors in lammps
+        Set ctilde 'functions' in the .yace file, used to calculate descriptors in lammps.
 
         Parameters
         ----------

mala/descriptors/acelib/ace_potential.py

@@ -9,11 +9,10 @@ def clebsch_gordan_coupling(
 ):
     """
     Compute generalized Clebsch-Gordan coefficients for a given L_R.
-    These are all defined according to the pairwise coupling scheme
-    in Goff et al. 2024. 
 
-    The approach to construct generalized Clebsch-Gordan coefficients is
-    manually defined for each rank for pedagogical and clarity purposes. 
+    These are all defined according to the pairwise coupling scheme in Goff et al. 2024. 
+
+    The approach to construct generalized Clebsch-Gordan coefficients is manually defined for each rank for pedagogical and clarity purposes. 
 
     Parameters
     ----------
@@ -53,15 +52,10 @@ def _rank_1_tree(_clebsch_gordan_coefficients, _l, _L_R=0, _M_R=0):
             list of angular momentum quantum numbers [l1]
 
         _L_R : int
-            Resultant angular momentum quantum number. This determines the equivariant
-            character of the rank N descriptor after reduction. L_R=0 corresponds to
-            a rotationally invariant feature, L_R=1 corresponds to a feature that
-            transforms like a vector, L_R=2 a tensor, etc.
+            Resultant angular momentum quantum number. This determines the equivariant character of the rank N descriptor after reduction. L_R=0 corresponds to a rotationally invariant feature, L_R=1 corresponds to a feature that transforms like a vector, L_R=2 a tensor, etc.
 
         _M_R : int
-            Resultant projection quantum number. This also determines the equivariant
-            character of the rank N descriptor after reduction. M_R must obey
-            -L_R <= M_R <= L_R
+            Resultant projection quantum number. This also determines the equivariant character of the rank N descriptor after reduction. M_R must obey -L_R <= M_R <= L_R.
 
         Returns
         -------

mala/descriptors/acelib/clebsch_gordan_coupling.py

@@ -8,9 +8,9 @@
 
 def filled_perm(tuples, rank):
     """
-    Returns a sympy Permutation object for permutations tabulated from GAP. This function
-    uses `rank` to fill in missing permutation indices from GAP. For example tuples = [(0,1)],
-    rank=4 would yeild Permutation(3)(0,1) corresponding to the cycles (0,1)(2)(3)
+    Return sympy Permutation object for permutations tabulated from GAP. This function uses `rank` to fill in missing permutation indices from GAP.
+
+    For example tuples = [(0,1)], rank=4 would yeild Permutation(3)(0,1) corresponding to the cycles (0,1)(2)(3).
 
     Parameters
     ----------
@@ -203,8 +203,9 @@ def get_ms(l_vector, M_R=0):
 
 def check_triangle(l1, l2, l3):
     """
-    check if three quantum angular momenta obey triangle conditions. Note that
-    the order matters.
+    Check if three quantum angular momenta obey triangle conditions.
+
+    Note that the order matters.
 
     Parameters
     ----------