Consistently adapt docstrings

Author: amgebauer

src/biomesh/__init__.py

@@ -3,13 +3,9 @@
 # See the LICENSE file in the top-level for license information.
 #
 # SPDX-License-Identifier: MIT
-"""
-biomesh
-=======
-
-biomesh is a Python package for working with 3D meshes, providing tools for mesh generation, manipulation, and analysis
-tailored for finite element simulations of biomechanical applications.
-"""
+"""Biomesh is a Python package for working with 3D meshes, providing tools for
+mesh generation, manipulation, and analysis tailored for finite element
+simulations of biomechanical applications."""
 from . import run_gmsh
 import pathlib
 from . import mesh
@@ -38,17 +34,14 @@ def combine_colored_stl_files(*stl_files: pathlib.Path) -> meshio.Mesh:
 def mesh_colored_stl_files(*stl_files: pathlib.Path, mesh_size: float) -> meshio.Mesh:
     """Generate a mesh from multiple colored STL files.
 
-    Parameters
-    ----------
-    *stl_files : pathlib.Path
-        Paths to the STL files to be merged.
+    Args
+        *stl_files:
+            Paths to the STL files to be merged.
 
-    mesh_size : float
-        The target size for the mesh elements.
+        mesh_size:
+            The target size for the mesh elements.
 
     Returns
-    -------
-    meshio.Mesh
         The generated mesh.
     """
     assert len(stl_files) > 0, "At least one STL file must be provided."

src/biomesh/adapt.py

@@ -80,13 +80,12 @@ def lin_to_quad(mesh: meshio.Mesh) -> meshio.Mesh:
     This function returns a new mesh in which all linear elements (triangles, quadrilaterals, tetrahedra, and hexahedra)
     are converted into their corresponding quadratic elements.
 
-    Args:
-    -------
-    mesh: meshio.Mesh
-        The input mesh containing linear elements.
+    Args
+        mesh:
+            The input mesh containing linear elements.
 
     Returns:
-        meshio.Mesh: The modified mesh with quadratic elements.
+        The modified mesh with quadratic elements.
     """
 
     new_points = [coord for coord in mesh.points]

src/biomesh/fe.py

@@ -37,24 +37,19 @@ def _create_symfem_element(cell_type: str) -> symfem.finite_element.FiniteElemen
 def ref_coords(cell_type: str) -> np.ndarray:
     """Return the reference coordinates for the nodes of a given cell type.
 
-    Parameters
-    ----------
-    cell_type : str
-        The type of the cell. Supported values are:
-        - "hexahedron": 8-node hexahedral element (cube).
-        - "tetra": 4-node tetrahedral element.
-        - "tetra10": 10-node quadratic tetrahedral element.
+    Args
+        cell_type:
+            The type of the cell. Supported values are:
+            - "hexahedron": 8-node hexahedral element (cube).
+            - "tetra": 4-node tetrahedral element.
+            - "tetra10": 10-node quadratic tetrahedral element.
 
     Returns
-    -------
-    np.ndarray
         An array of shape (n_nodes, 3) containing the reference coordinates
         of the nodes for the specified cell type.
 
     Raises
-    ------
-    ValueError
-        If the provided cell_type is not supported.
+        ValueError: If the provided cell_type is not supported.
     """
     element = _create_symfem_element(cell_type)
     return np.array(element.dof_plot_positions(), dtype=float)[
@@ -68,33 +63,27 @@ def int_points_weights(
     """Compute integration (quadrature) points and weights for given cell type
     and number of points.
 
-    Parameters
-    ----------
-    cell_type : str
-        The type of cell for which to compute integration points and weights.
-        Supported values are strings starting with "hexahedron" or "tetra".
-    num_points : int
-        The number of integration points to use.
-        Supported values:
+    Args
+        cell_type:
+            The type of cell for which to compute integration points and weights.
+            Supported values are strings starting with "hexahedron" or "tetra".
+        num_points
+            The number of integration points to use.
+            Supported values:
             - For "hexahedron": 1 or 8
             - For "tetra": 1 or 4
 
     Returns
-    -------
-    tuple[np.ndarray, np.ndarray]
         A tuple containing:
             - points: np.ndarray of shape (num_points, dim)
                 The coordinates of the integration points in the reference cell.
             - weights: np.ndarray of shape (num_points,)
                 The corresponding integration weights.
 
     Raises
-    ------
-    ValueError
-        If the cell type or number of points is not supported.
+    ValueError: If the cell type or number of points is not supported.
 
-    Examples
-    --------
+    Examples:
     >>> points, weights = int_points_weights("hexahedron", 8)
     >>> points.shape
     (8, 3)
@@ -190,28 +179,23 @@ def shape_function_first_derivatives(cell_type: str, xi: np.ndarray) -> np.ndarr
     """Compute the derivatives of shape functions with respect to the reference
     coordinates for various cell types.
 
-    Parameters
-    ----------
-    cell_type : str
-        The type of finite element cell. Supported values are:
-            - "hexahedron": 8-node trilinear hexahedral element
-            - "tetra": 4-node linear tetrahedral element
-            - "tetra10": 10-node quadratic tetrahedral element
-    xi : np.ndarray
-        The local (reference) coordinates at which to evaluate the shape function derivatives.
-        For 3D elements, this should be a 1D array of length 3: [xi, eta, zeta].
+    Args
+        cell_type
+            The type of finite element cell. Supported values are:
+                - "hexahedron": 8-node trilinear hexahedral element
+                - "tetra": 4-node linear tetrahedral element
+                - "tetra10": 10-node quadratic tetrahedral element
+        xi
+            The local (reference) coordinates at which to evaluate the shape function derivatives.
+            For 3D elements, this should be a 1D array of length 3: [xi, eta, zeta].
 
     Returns
-    -------
-    np.ndarray
         The derivatives of the shape functions with respect to the reference coordinates.
         The shape of the returned array is (n_nodes, 3), where n_nodes is the number of nodes
         for the specified cell type.
 
     Raises
-    ------
-    ValueError
-        If an unsupported cell type is provided.
+        ValueError: If an unsupported cell type is provided.
     """
 
     if cell_type not in _first_derivative_storage:
@@ -235,17 +219,11 @@ def grad(mesh: meshio.Mesh, phi: np.ndarray) -> np.ndarray:
 
     The gradient is computed at the nodes where it is averaged from the surrounding elements.
 
-    Parameters
-    ----------
-    mesh : meshio.Mesh
-        The input mesh.
-
-    phi : np.ndarray
-        The scalar field defined at the nodes of the mesh.
+    Args
+        mesh: The input mesh.
+        phi: The scalar field defined at the nodes of the mesh.
 
     Returns
-    -------
-    np.ndarray
         The gradient of the scalar field at the nodes of the mesh.
     """
 

src/biomesh/filter.py

@@ -21,16 +21,14 @@ def filter_by_cellblock_point_mapping(
     original number of points in the mesh. For points included in the filtered cell blocks, the array contains their new
     consecutive indices; for points not included, the value is -1.
 
-    Args:
-        mesh: meshio.Mesh
-            The input mesh object containing points and cell blocks.
+    Args
+        mesh:The input mesh object containing points and cell blocks.
 
-        filter: Callable[[meshio.CellBlock], bool])
-            A function that takes a cell block and returns True if it should be included.
+        filter: A function that takes a cell block and returns True if it should be included.
 
     Returns:
-        np.ndarray: An array of length `len(mesh.points)` where each entry is the new index of the point if it is included
-                    in the filtered cell blocks, or -1 otherwise.
+        An array of length `len(mesh.points)` where each entry is the new index of the point if it is included
+        in the filtered cell blocks, or -1 otherwise.
     """
 
     cell_filter = np.array(
@@ -66,21 +64,15 @@ def filter_by_cellblock(
 ) -> meshio.Mesh:
     """Filter a mesh to include only cells of specified types.
 
-    Parameters
-    ----------
-    mesh : meshio.Mesh
-        The input mesh to filter.
-    filter : Callable[[meshio.CellBlock], bool]
-        A function that takes a cell block and returns True if it should be included.
+    Args
+        mesh: The input mesh to filter.
+        filter: A function that takes a cell block and returns True if it should be included.
 
     Returns
-    -------
-    meshio.Mesh
         A new meshio.Mesh object containing only the cells of the specified types,
         with unused points removed and point/cell data filtered accordingly.
 
     Notes
-    -----
     - If no cells of the specified types are found, returns an empty mesh with zero points and cells.
     """
 
@@ -101,15 +93,12 @@ def filter_by_block_ids(mesh: meshio.Mesh, cellblock_ids: np.ndarray) -> meshio.
 
     Given a meshio.Mesh object and an array of cell block indices, this function creates a new mesh containing only the cells from the specified cell blocks and the points referenced by those cells. The point indices are remapped so that the resulting mesh is consistent and compact. Associated point and cell data are also filtered accordingly.
 
-    Parameters:
-        mesh: meshio.Mesh
-            The input mesh from which to extract cell blocks.
-
-        cellblock_ids: np.ndarray
-            An array of indices specifying which cell blocks to include in the output mesh.
+    Args:
+        mesh: The input mesh from which to extract cell blocks.
+        cellblock_ids: An array of indices specifying which cell blocks to include in the output mesh.
 
     Returns:
-        meshio.Mesh: A new meshio.Mesh object containing only the specified cell blocks and their associated points and data.
+        A new meshio.Mesh object containing only the specified cell blocks and their associated points and data.
 
     Notes:
         - If cellblock_ids is empty, returns an empty mesh with no points or cells.

src/biomesh/laplace.py

@@ -21,16 +21,11 @@ def get_cell_stiffness(cell_type: str, nodal_coords: np.ndarray) -> np.ndarray:
     """Computes the element stiffness matrix for a finite element cell for a
     simple Laplace problem.
 
-    Parameters
-    ----------
-    cell_type : str
-        The type of the finite element cell (e.g., 'triangle', 'tetrahedron').
-    nodal_coords : np.ndarray
-        An array of shape (num_nodes, dim) containing the coordinates of the cell's nodes.
-
-    Returns
-    -------
-    np.ndarray
+    Args:
+        cell_type: The type of the finite element cell (e.g., 'triangle', 'tetrahedron').
+        nodal_coords: An array of shape (num_nodes, dim) containing the coordinates of the cell's nodes.
+
+    Returns:
         The element stiffness matrix of shape (num_nodes, num_nodes) for the given cell.
     """
 
@@ -91,19 +86,15 @@ def solve_onezero(
     """Solves a Laplace problem on the given mesh with Dirichlet boundary
     conditions set to 1 on `one_nodes` and 0 on `zero_nodes`.
 
-    Parameters:
-        mesh: meshio.Mesh
-            The mesh on which to solve the Laplace problem.
+    Args:
+        mesh: The mesh on which to solve the Laplace problem.
 
-        one_nodes: np.ndarray
-            Array of node indices where the Dirichlet boundary condition is set to 1.
+        one_nodes: Array of node indices where the Dirichlet boundary condition is set to 1.
 
-        zero_nodes: np.ndarray
-            Array of node indices where the Dirichlet boundary condition is set to 0.
+        zero_nodes: Array of node indices where the Dirichlet boundary condition is set to 0.
 
     Returns:
-        np.ndarray
-            Solution array corresponding to the mesh nodes.
+        Solution array corresponding to the mesh nodes.
     """
     dbc_nodes = np.concatenate((np.array(one_nodes), np.array(zero_nodes)))
     dbc_values = np.concatenate((np.ones(len(one_nodes)), np.zeros(len(zero_nodes))))

src/biomesh/merge.py

@@ -15,11 +15,11 @@ def merge(*meshes: meshio.Mesh) -> meshio.Mesh:
     into a new meshio.Mesh object. It handles the necessary index adjustments for points and
     cells, and ensures that point and cell data are correctly merged and aligned.
 
-    Parameters:
-        *meshes (meshio.Mesh): Variable number of meshio.Mesh objects to merge.
+    Args:
+        *meshes: Variable number of meshio.Mesh objects to merge.
 
     Returns:
-        meshio.Mesh: A new meshio.Mesh object containing the merged data from all input meshes.
+        A new meshio.Mesh object containing the merged data from all input meshes.
 
     Notes:
         - Point and cell data arrays are padded with zeros if not present at other meshes.

src/biomesh/mesh.py

@@ -40,14 +40,10 @@ def merge_colored_stl(
 ) -> tuple[meshio.Mesh, list[set[int]]]:
     """Merge multiple colored STL files into a single mesh.
 
-    Parameters
-    ----------
-    *stl_files : str
-        Paths to the STL files to be merged.
-
-    Returns
-    -------
-    tuple[meshio.Mesh, list[list[int]]]
+    Args:
+        *stl_files: Paths to the STL files to be merged.
+
+    Returns:
         The merged mesh and the surface ID mapping enclosing the different volumes define by the surface ids.
     """
     base_mesh = lnmmeshio.read_mesh(str(base_stl), file_format="mimicsstl")

src/biomesh/reorder.py

@@ -24,8 +24,9 @@ def build_csr_from_multiple_elements(
 ) -> sp.csr_array:
     """Build a CSR adjacency matrix from multiple lists of cell connectivity.
 
-    n_nodes: total number of nodes
-    elements_lists: variable number of arrays/lists of elements
+    Args:
+        n_nodes: total number of nodes
+        elements_lists: variable number of arrays/lists of elements
     """
     adj = defaultdict(set)
 
@@ -57,10 +58,11 @@ def reorder(mesh: meshio.Mesh) -> meshio.Mesh:
     This function uses the reverse Cuthill-McKee algorithm to find an optimal ordering
     of the nodes in the mesh, which is particularly useful for sparse matrices.
 
-    Parameters
-    ----------
-    mesh : meshio.Mesh
-        The mesh to be reordered.
+    Args:
+        mesh: The mesh to be reordered.
+
+    Returns:
+        The mesh with reordered points.
     """
     csr_array = build_csr_from_multiple_elements(
         len(mesh.points), *mesh.cells_dict.values()

src/biomesh/run_gmsh.py

@@ -46,13 +46,13 @@ def remesh_file(
     provided surface loops and applying a specified mesh size.
 
     Args:
-        file_path: pathlib.Path
+        file_path:
             Path to the input mesh file to be remeshed.
 
-        surface_loops: list[set[int]]
+        surface_loops:
             List of sets, where each set contains surface IDs to be grouped into a surface loop for volume creation.
 
-        mesh_size: float
+        mesh_size:
             Target mesh size to be used for remeshing.
 
     Returns: