doc updates for tree coupling and common

Author: jmgoff

mala/descriptors/acelib/common_utils.py

@@ -8,22 +8,21 @@
 
 def filled_perm(tuples, rank):
     """
-    Create a filled permutation.
-
-    ACE_DOCS_MISSING - What is this used for?
+    Returns the sympy permutation from permutations of N tabulated from GAP
 
     Parameters
     ----------
     tuples : List
-        List of tuples.
+        list of touples indicating the partitions of N (e.g., for the (2,2) partition of 4,
+        tuples should be [(0,1),(2,3)]
 
     rank : int
-        Rank of the permutation.
+        Rank of the descriptor (N)
 
     Returns
     -------
     Permutation : sympy.combinatorics.Permutation
-        Permutation object.
+        Permutation object for the permutations.
     """
     allinds = list(range(rank))
     try:
@@ -152,7 +151,7 @@ def group_vector_by_nodes_pairwise(vector, nodes, remainder=None):
         List of nodes by which to pair vector.
 
     remainder
-        ACE_DOCS_MISSING
+        Remainder node for binary trees with odd numbers of leaves.
 
     Returns
     -------
@@ -162,8 +161,7 @@ def group_vector_by_nodes_pairwise(vector, nodes, remainder=None):
         tuple([vector[node[0]], vector[node[1]]]) for node in nodes
     ]
 
-    # ACE_DOCS_MISSING - Am I missing something here that needs to be
-    # documented or does remainder really do nothing?
+    # for combinations of 2-cycles, nothing else needs to be done
     if remainder is not None:
         vector_by_tuples = vector_by_tuples
     return vector_by_tuples
@@ -173,12 +171,12 @@ def get_ms(l_vector, M_R=0):
     r"""
     Retrieve the set of m_i combination with \sum_i m_i = M_R.
 
-    These combinations are retrieved for an arbitrary l vector.
+    These combinations are retrieved for an arbitrary l multiset.
 
     Parameters
     ----------
     l_vector : List
-        Arbitrary vector.
+        collection of angular momentum quantum numbers corresponding to spherical harmonics l1,l2...lN 
 
     M_R : int
         Sum to which combinations sum.
@@ -203,18 +201,19 @@ def get_ms(l_vector, M_R=0):
 
 def check_triangle(l1, l2, l3):
     """
-    Check if a triangle can be formed with the given sides.
+    check if three quantum angular momenta obey triangle conditions. Note that
+    the order matters.
 
     Parameters
     ----------
     l1 : int
-        Length of the first side.
+        angular momentum quantum number 1
 
     l2 : int
-        Length of the second side.
+        angular momentum quantum number 2
 
     l3 : int
-        Length of the third side.
+        angular momentum quantum number 3
 
 
     Returns

mala/descriptors/acelib/coupling_utils.py

@@ -53,8 +53,8 @@ def build_tree_for_l_intermediates(l, L_R=0):
     Parameters
     ----------
     l : List
-        List of angular momentum quantum numbers. These correspond to the N
-        spherical harmonics in the ACE descriptor(s).
+        list (multiset) of angular momentum indices l1,l2,...lN. These correspond
+        to the N spherical harmonics in the ACE descriptor(s).
 
     L_R : int
         Resultant angular momentum quantum number. This determines the equivariant

mala/descriptors/acelib/tree_sorting.py

@@ -270,13 +270,16 @@ def build_full_tree(l, L, L_R):
     Parameters
     ----------
     l : List
-        ACE_DOCS_MISSING
+        list (multiset) of angular momentum indices l1,l2,...lN
 
     L : List
-        ACE_DOCS_MISSING
+        list (multiset) of intermediate angular momentum indices l1,l2,...lN
 
     L_R : int
-        ACE_DOCS_MISSING
+        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.
 
     Returns
     -------
@@ -359,7 +362,7 @@ def rank_2_binary(l_parent, l_left, l_right):
 
 def build_quick_tree(l):
     """
-    Build a quick tree from the given list.
+    Build a binary tree from the given list.
 
     Rank is assumed to be the length of the list. If the rank is odd, a
     remainder is returned.