Docstrings (#22)

README.md

@@ -189,16 +189,8 @@ I = in_element_aabb(queries,V,F) # This is a C++ binding
 ``` -->
 
 # TO-DO
-## Must do before first PyPi release
-- \[Oded\] Add docstrings for `array_correspondence`, `boundary_edges`,
-  `boundary_loops`, `boundary_vertices`, `cotangent_laplacian_intrinsic`,
-  `cotangent_laplacian`, `cotangent_weights_intrinsic`, `cotangent_weights`,
-  `doublearea_intrinsic`, `edges`, `halfedge_edge_map`,
-  `halfedge_lengths_squared`, `halfedge_lengths`, `halfedges`,
-  `min_quad_with_fixed`, `read_mesh`, `subdivide`, `tip_angles_intrinsic`,
-  `tip_angles`, `triangle_triangle_adjacency`, `write_mesh`.
-- \[Oded\] Add FD-type linear solve with Dirichlet conditions function.
-- \[Silvia\] When Oded does this^, fix `test_quadtree_laplacian.py`.
+
+
 
 ## Future to-dos
 - Add examples to docstrings.

src/gpytoolbox/array_correspondence.py

@@ -1,21 +1,30 @@
 import numpy as np
 
 def array_correspondence(A,B,axis=None):
-    # Computes a map from the a to the equal elements in b
-    #
-    # Inputs:
-    #       A:  #a numpy array (must be 1-dim or 2-dim)
-    #       B:  #b numpy array (must be 1-dim or 2-dim)
-    #       Optional:
-    #                axis: If None, will treat A and B as flat arrays.
-    #                      If a number, will check for equality of the
-    #                      entire axis, in which case the dimension of
-    #                      A and B across that axis must be equal.
-    # Outputs:
-    #       f  #A numpy index list mapping from the a to b, with -1 if there is
-    #          no matching entry.
-    #          If b contains multiple eligible entries, return an arbitrary one.
-    #          If there are no -1s, b[f] == a
+    """Computes a map from A to the equal elements in B
+
+    Parameters
+    ----------
+    A : (a,) or (a,k) numpy array (must be 1-dim or 2-dim)
+    B : (b,) or (b,k) numpy array (must be 1-dim or 2-dim)
+    axis : int or None, optional (default None)
+        If None, will treat A and B as flat arrays.
+        If a number, will check for equality of the entire axis, in which case
+        the dimension of A and B across that axis must be equal.
+
+    Returns
+    -------
+    f : (a,) numpy int array
+        index list mapping from A to B, with -1 if there is no
+        matching entry.
+        If b contains multiple eligible entries, return an arbitrary one.
+        If there are no -1s, `b[f] == a`
+
+    Examples
+    --------
+    TODO
+    
+    """
 
     if axis is None:
         A = A.ravel()

src/gpytoolbox/boundary_edges.py

@@ -1,14 +1,25 @@
 from gpytoolbox.edges import edges
 
 def boundary_edges(F):
-    # Given a triangle mesh with face indices F, returns all unique oriented
-    # boundary edges as indices into the vertex array.
-    # Works only on manifold meshes.
-    #
-    # Inputs:
-    #       F  #F by 3 face index list of a triangle mesh
-    # Outputs:
-    #       bE  #bE by 2 indices of boundary edges into the vertex array
+    """Given a triangle mesh with face indices F, returns all unique oriented
+    boundary edges as indices into the vertex array.
+    Works only on manifold meshes.
+
+    Parameters
+    ----------
+    F : (m,3) numpy int array.
+        face index list of a triangle mesh
+
+    Returns
+    -------
+    bE : (be,2) numpy int array.
+        indices of boundary edges into the vertex array
+
+    Examples
+    --------
+    TODO
+    
+    """
 
     E,b = edges(F, return_boundary_indices=True)
     return E[b,:]

src/gpytoolbox/boundary_loops.py

@@ -3,21 +3,29 @@
 
 
 def boundary_loops(f, allow_wrong_orientations=True):
-    # Computes oriented boundary loop for each boundary component of a triangle
-    # mesh.
-    #
-    # This function only works on manifold triangle meshes.
-    # TODO: assert manifoldness when running this function
-    #
-    # Input:
-    #       F  #F by 3 face index list of a triangle mesh
-    #       Optional:
-    #                allow_wrong_orientations  whether to allow F to contain
-    #                                          wrongly oriented triangles
-    #
-    # Output:
-    #       loops  list of numpy array list of boundary vertices
-    #              in oriented loops
+    """Computes oriented boundary loop for each boundary component of a triangle
+    mesh.
+    This function only works on manifold triangle meshes.
+
+    TODO: assert manifoldness when running this function
+
+    Parameters
+    ----------
+    F : (m,3) numpy int array
+        face index list of a triangle mesh
+    allow_wrong_orientations: bool, optional (default True).
+        whether to allow F to contain wrongly oriented triangles
+
+    Returns
+    -------
+    loops : list of numpy arrays that are themselves lists of boundary vertices
+        in oriented loops
+
+    Examples
+    --------
+    TODO
+    
+    """
 
     assert f.shape[0] > 0
     assert f.shape[1] == 3

src/gpytoolbox/boundary_vertices.py

@@ -2,13 +2,25 @@
 from gpytoolbox.boundary_edges import boundary_edges
 
 def boundary_vertices(F):
-    # Given a triangle mesh with face indices F, returns the indices of all
-    # boundary vertices. Works only on manifold meshes.
-    #
-    # Inputs:
-    #       F  #F by 3 face index list of a triangle mesh
-    # Outputs:
-    #       bV  #bV list of indices into F of boundary vertices
+    """Given a triangle mesh with face indices F, returns the indices of all
+    boundary vertices.
+    Works only on manifold meshes.
+
+    Parameters
+    ----------
+    F : (m,3) numpy int array
+        face index list of a triangle mesh
+
+    Returns
+    -------
+    bV : (bv,) numpy int array
+        list of indices into F of boundary vertices
+
+    Examples
+    --------
+    TODO
+    
+    """
 
     return np.unique(boundary_edges(F))
 

src/gpytoolbox/cotangent_laplacian.py

@@ -3,14 +3,25 @@
 from gpytoolbox.cotangent_laplacian_intrinsic import cotangent_laplacian_intrinsic
 
 def cotangent_laplacian(V,F):
-    # Builds the (pos. def.) cotangent Laplacian for a triangle mesh.
-    #
-    # Input:
-    #       V  #V by 3 numpy array of mesh vertex positions
-    #       F  #F by 3 int numpy array of face/edge vertex indeces into V
-    #
-    # Output:
-    #       L  #V by #V scipy csr_matrix cotangent Laplacian
+    """Builds the (pos. def.) cotangent Laplacian for a triangle mesh.
+
+    Parameters
+    ----------
+    V : (n,d) numpy array
+        vertex list of a triangle mesh
+    F : (m,3) numpy int array
+        face index list of a triangle mesh
+
+    Returns
+    -------
+    L : (n,n) scipy csr_matrix
+        cotangent Laplacian
+
+    Examples
+    --------
+    TODO
+    
+    """
 
     l_sq = halfedge_lengths_squared(V,F)
     return cotangent_laplacian_intrinsic(l_sq,F,n=V.shape[0])

src/gpytoolbox/cotangent_laplacian_intrinsic.py

@@ -3,18 +3,25 @@
 from gpytoolbox.cotangent_weights_intrinsic import cotangent_weights_intrinsic
 
 def cotangent_laplacian_intrinsic(l_sq,F,n=None):
-    # Builds the (pos. def.) cotangent Laplacian for a triangle mesh using only
-    # intrinsic information (squared halfedge edge lengths).
-    #
-    # Input:
-    #       l_sq  #F by 3 numpy array of squared halfedge lengths as computed
-    #             by halfedge_lengths_squared
-    #       F  #F by 3 int numpy array of face/edge vertex indeces into V
-    #       Optional:
-    #                n  an integer denoting the number of vertices in the mesh
-    #
-    # Output:
-    #       L  #V by #V scipy csr_matrix cotangent Laplacian
+    """Builds the (pos. def.) cotangent Laplacian for a triangle mesh.
+
+    Parameters
+    ----------
+    l_sq : (m,3) numpy array
+        squared halfedge lengths as computed by halfedge_lengths_squared
+    F : (m,3) numpy int array
+        face index list of a triangle mesh
+
+    Returns
+    -------
+    L : (n,n) scipy csr_matrix
+        cotangent Laplacian
+
+    Examples
+    --------
+    TODO
+    
+    """
 
     assert F.shape[1] == 3
     assert l_sq.shape == F.shape

src/gpytoolbox/cotangent_weights.py

@@ -3,19 +3,30 @@
 from gpytoolbox.cotangent_weights_intrinsic import cotangent_weights_intrinsic
 
 def cotangent_weights(V,F):
-    # Builds the cotangent weights (cotangent/2) for each halfedge.
-    #
-    # The ordering convention for halfedges is the following:
-    # [halfedge opposite vertex 0,
-    #  halfedge opposite vertex 1,
-    #  halfedge opposite vertex 2]
-    #
-    # Input:
-    #       V  #V by 3 numpy array of mesh vertex positions
-    #       F  #F by 3 int numpy array of face/edge vertex indeces into V
-    #
-    # Output:
-    #       C  #F by 3 numpy array of cotangent weights for each halfedge
+    """Builds the cotangent weights (cotangent/2) for each halfedge.
+
+    The ordering convention for halfedges is the following:
+    [halfedge opposite vertex 0,
+     halfedge opposite vertex 1,
+     halfedge opposite vertex 2]
+
+    Parameters
+    ----------
+    V : (n,d) numpy array
+        vertex list of a triangle mesh
+    F : (m,3) numpy int array
+        face index list of a triangle mesh
+
+    Returns
+    -------
+    C : (m,3) numpy array
+        cotangent weights for each halfedge
+
+    Examples
+    --------
+    TODO
+    
+    """
 
     l_sq = halfedge_lengths_squared(V,F)
     return cotangent_weights_intrinsic(l_sq,F)

src/gpytoolbox/cotangent_weights_intrinsic.py

@@ -2,21 +2,31 @@
 from gpytoolbox.doublearea_intrinsic import doublearea_intrinsic
 
 def cotangent_weights_intrinsic(l_sq,F):
-    # Builds the cotangent weights (cotangent/2) for each halfedge using only
-    # intrinsic information (squared halfedge edge lengths).
-    #
-    # The ordering convention for halfedges is the following:
-    # [halfedge opposite vertex 0,
-    #  halfedge opposite vertex 1,
-    #  halfedge opposite vertex 2]
-    #
-    # Input:
-    #       l_sq  #F by 3 numpy array of squared halfedge lengths as computed
-    #             by halfedge_lengths_squared
-    #       F  #F by 3 int numpy array of face/edge vertex indeces into V
-    #
-    # Output:
-    #       C  #F by 3 numpy array of cotangent weights for each halfedge
+    """Builds the cotangent weights (cotangent/2) for each halfedge using only
+    intrinsic information (squared halfedge edge lengths).
+
+    The ordering convention for halfedges is the following:
+    [halfedge opposite vertex 0,
+     halfedge opposite vertex 1,
+     halfedge opposite vertex 2]
+
+    Parameters
+    ----------
+    l_sq : (m,3) numpy array
+        squared halfedge lengths as computed by halfedge_lengths_squared
+    F : (m,3) numpy int array
+        face index list of a triangle mesh
+
+    Returns
+    -------
+    C : (m,3) numpy array
+        cotangent weights for each halfedge
+
+    Examples
+    --------
+    TODO
+    
+    """
 
     assert F.shape[1] == 3
     assert l_sq.shape == F.shape

src/gpytoolbox/decimate.py

@@ -7,10 +7,10 @@ def decimate(V,F,face_ratio=0.1,num_faces=None):
 
     Parameters
     ----------
-    V : numpy double array
-        Matrix of vertex coordinates
-    F : numpy int array
-        Matrix of triangle indices
+    V : (n,d) numpy array
+        vertex list of a triangle mesh
+    F : (m,3) numpy int array
+        face index list of a triangle mesh
     face_ratio: double, optional (default 0.1)
         Desired ratio of output faces to input faces 
     num_faces : int, optional (default None)

src/gpytoolbox/doublearea.py

@@ -8,14 +8,16 @@ def doublearea(V,F=None):
 
     Parameters
     ----------
-    V : numpy double array
-        Matrix of vertex coordinates
-    F : numpy int array, optional
-        Matrix of triangle indices, None if ordered polyline (by default, None)
+    V : (n,d) numpy array
+        vertex list of a polyline or triangle mesh
+    F : numpy int array, optional (default: None)
+        if None or (m,2), interpret input as ordered polyline;
+        if (m,3) numpy int array, interpred as face index list of a triangle
+        mesh
 
     Returns
     -------
-    dblA : numpy double array
+    dblA : (m,) numpy double array
         vector of twice the (unsigned) area/length 
 
     See Also