(docs) wrote docs for the new simplex_graph_limited function

Author: amkrajewski

nimplex.nim

@@ -263,13 +263,18 @@ proc simplex_graph_limited*(
         ndiv: int,
         limit: seq[seq[int]]
     ): (Tensor[int], seq[seq[int]]) =
-    ## .. image:: ../assets/small_GI.png
-    ## Generates a simplex graph in a `dim`-component space based on (1) grid of nodes following `ndiv` divisions per dimension (i.e., quantized to `1/ndiv`),
-    ## similar to `simplex_grid`_, and (2) a list of neighbor lists corresponding to edges. The result is a tuple of 
-    ## (1) a deterministically allocated Arraymancer `Tensor[int]` of shape `(N_S(dim, ndiv), dim)` containing all possible compositions in the simplex space
-    ## just like in `simplex_grid`_, and (2) a `seq[seq[int]]` containing a list of neighbors for each node. The current implementation utilizes GC-allocated `seq` for neighbors
-    ## to reduce memory footprint in cases where `ndiv` is close to `dim` and not all nodes have the complete set of `dim(dim-1)` neighbors. This is a tradeoff between memory and performance, which can be
-    ## adjusted by switching to a (N_S(dim, ndiv), dim(dim-1)) `Tensor[int]` with `-1` padding for missing neighbors, just like done in `outFunction_graph`_ for NumPy output generation.
+    ## .. image:: ../assets/small_GL.png
+    ## Generates a "limited" simplex graph in up to `dim`-component space represented by (1) grid of nodes quantized to `1/ndiv`, similar to `simplex_grid`_, and (2) a list of 
+    ## neighbor lists corresponding to edges, but only for nodes within the specified `limit` sequence of integer pairs denoting maximum and minimum values for each component 
+    ## in terms of fractions of `ndiv` (e.g. [[0, 24], [0, 12], [3, 6]] with `ndiv=24` would mean that the first component can take values from 0 to 100%, the second from 0 to 
+    ## 50%, and the third from 12.5 to 25%, inclusive). The figure above depicts an example of a 3-component simplex graph with `ndiv=12` and limits of [[1, 8], [1, 8], [1, 8]].
+    ## This implementation iterates over all nodes but only computes neighbors for those within the limits, which then gets prunned to avoid connecting to nodes outside the limits
+    ## (difficult to avoide for more than 3 components). The is rearranged and node indexes are remapped to be a dense uniformly spread grid in a subspace of the simplex, akin to
+    ## the full `simplex_graph`_ but with a smaller number of nodes and more elaborate shapes, such as in the figure below with `ndiv=24` and limits of 
+    ## [[0, 24], [0, 24], [0, 12], [0, 3]], resulting in a tetrahedron cut around its base and one corner.
+    ## .. image:: ../assets/small_GL2.png
+    ## The result is a tuple of (1) a runtime allocated Arraymancer `Tensor[int]` of shape `(N<=N_S(dim, ndiv), dim)` containing compositions and (2) a `seq[seq[int]]` containing 
+    ## a list of neighbors for each node.
 
     assert len(limit) == dim, "The size of limit sequence put on the simplex grid must match the dimensionality"
     for l in limit:
@@ -287,8 +292,10 @@ proc simplex_graph_limited*(
         projectedNodes: seq[seq[int]]
         projectedNeighbors: seq[seq[int]]
 
-    proc checkAgainstLimit(x:Tensor, dim:int, limit:seq[seq[int]]): bool {.inline.} =
-        ## Check if the current composition `x` is within the specified limits.
+    proc checkAgainstLimit(
+        x:Tensor, dim:int, limit:seq[seq[int]]
+        ): bool {.inline.} =
+        ## Check if the current composition `x` is within the specified `limit`.
         for i in 0..<dim:
             if x[i] > limit[i][1]:
                 return false