Merge pull request #29 from JXRepo/Jun_2025_10_26

Finished updating docstring in Kanapy/src /kanapy/

Author: AHartmaier

src/kanapy/core/api.py

@@ -18,7 +18,23 @@ def main(ctx):
 @main.command(name='gui')
 @click.pass_context
 def gui(ctx):
-    """ Start Kanapy's GUI (experimental alpha-version). """
+    """
+    Start Kanapy's graphical user interface (experimental alpha version)
+
+    This function initializes and launches the Kanapy GUI using Tkinter.
+    It creates a main application window with multiple tabs for different
+    RVE generation modes, such as particle-based and cuboid-based RVEs.
+
+    Parameters
+    ----------
+    ctx : object
+        Execution context (reserved for CLI or application integration)
+
+    Notes
+    -----
+    - This GUI version is experimental and intended for testing only
+    - Requires `matplotlib` and `tkinter` libraries
+    """
     import matplotlib.pyplot as plt
     import tkinter as tk
     import tkinter.font as tkFont
@@ -54,7 +70,26 @@ def gui(ctx):
 @click.option('--no_texture', default=False)
 @click.pass_context
 def tests(ctx, no_texture: bool):
-    """ Runs unittests built within kanapy."""
+    """
+    Run Kanapy's internal unittests
+
+    Executes the built-in test suite for Kanapy using pytest.
+    Depending on the `no_texture` flag, it either runs a subset of tests
+    or all available tests in the `tests` directory.
+
+    Parameters
+    ----------
+    ctx : object
+        Execution context (reserved for CLI or internal use)
+    no_texture : bool
+        If True, run tests excluding texture-related modules;
+        if False, run the full test suite
+
+    Notes
+    -----
+    - Must be executed from the root directory of the Kanapy installation
+    - Temporary dump files generated during testing are automatically removed
+    """
     click.echo('Will only work in root directory of kanapy installation.')
     cwd = os.getcwd()
     if no_texture:
@@ -73,16 +108,40 @@ def tests(ctx, no_texture: bool):
 @main.command(name='readDocs')
 @click.pass_context
 def docs(ctx):
-    """Open webpage with  Kanapy documentation."""
+    """
+    Open the Kanapy documentation webpage
+
+    Launches the default web browser and navigates to the official
+    Kanapy documentation page hosted on GitHub Pages.
+
+    Parameters
+    ----------
+    ctx : object
+        Execution context (reserved for CLI or internal use)
+    """
     webbrowser.open("https://icams.github.io/Kanapy/")
 
 
 @main.command(name='copyExamples')
 @click.pass_context
 def download_subdir(ctx):
     """
-    Download examples from Kanapy's GitHub repository.
+    Download example files from Kanapy's GitHub repository
+
+    Fetches the latest Kanapy repository archive from GitHub,
+    extracts the `examples` subdirectory, and saves it to the local
+    working directory as `kanapy_examples`.
 
+    Parameters
+    ----------
+    ctx : object
+        Execution context (reserved for CLI or internal use)
+
+    Notes
+    -----
+    - Requires an active internet connection
+    - Downloads from the `master` branch of the Kanapy repository
+    - Automatically creates the output directory if it does not exist
     """
     zip_url = f"https://github.com/ICAMS/kanapy/archive/refs/heads/master.zip"
     output_dir = os.path.join(os.getcwd(), 'kanapy_examples')
@@ -113,12 +172,42 @@ def download_subdir(ctx):
 @main.command(name='setupMTEX')
 @click.pass_context
 def setup_mtex(ctx):
-    """ Starts Matlab engine and initializes MTEX."""
+    """
+    Start the MATLAB engine and initialize MTEX
+
+    Launches the MATLAB engine from Python and sets up the
+    MTEX toolbox environment for crystallographic computations.
+
+    Parameters
+    ----------
+    ctx : object
+        Execution context (reserved for CLI or internal use)
+
+    Notes
+    -----
+    - Requires MATLAB and the MTEX toolbox to be installed
+    - Calls `setPaths()` to configure MATLAB path settings
+    """
     setPaths()
 
 
 def chkVersion(matlab):
-    """ Read the version of Matlab"""
+    """
+    Read the installed MATLAB version from a version string
+
+    Parses the given MATLAB version string to extract the release year
+    (e.g., 'R2023a' → 2023). If the version cannot be determined, returns None.
+
+    Parameters
+    ----------
+    matlab : str
+        String containing MATLAB version information
+
+    Returns
+    -------
+    int or None
+        MATLAB release year if successfully parsed, otherwise None
+    """
     ind = matlab.find('R20')
     if ind < 0:
         version = None 
@@ -132,7 +221,23 @@ def chkVersion(matlab):
 
 
 def setPaths():
-    """ Starts matlab engine, after installation if required, and initializes MTEX.
+    """
+    Start the MATLAB engine and initialize the MTEX environment
+
+    Checks if the MATLAB engine for Python is installed and installs it if missing.
+    Then initializes the MATLAB engine and MTEX toolbox for use with Kanapy.
+
+    Raises
+    ------
+    ModuleNotFoundError
+        If `kanapy-mtex` or MATLAB are not installed,
+        or if the MATLAB engine installation fails
+
+    Notes
+    -----
+    - Requires MATLAB 2025a or later
+    - Automatically installs the `matlabengine` package if not found
+    - Configures Kanapy for texture analysis by running `init_engine.py`
     """
     try:
         from kanapy_mtex import ROOT_DIR

src/kanapy/core/cli.py

@@ -4,21 +4,30 @@
 
 def collision_routine(E1, E2):
     """
-    Calls the method :meth:'collide_detect' to determine whether the given two ellipsoid objects overlap using
-    the Algebraic separation condition developed by W. Wang et al. A detailed description is provided
-    therein.
-
-    Also calls the :meth:`collision_react` to evaluate the response after collision.     
-
-    :param E1: Ellipsoid :math:`i` 
-    :type E1: object :obj:`Ellipsoid`
-    :param E2: Ellipsoid :math:`j`
-    :type E2: object :obj:`Ellipsoid`
-
-    .. note:: 1. If both the particles to be tested for overlap are spheres, then the bounding sphere hierarchy is
-                 sufficient to determine whether they overlap.
-              2. Else, if either of them is an ellipsoid, then their coefficients, positions & rotation matrices are
-                 used to determine whether they overlap.
+    Detect and handle collision between two ellipsoid objects
+
+    Uses the algebraic separation condition by W. Wang et al. to detect overlap
+    between two ellipsoids, and if a collision occurs, computes the contact
+    response via the `collision_react` method.
+
+    Parameters
+    ----------
+    E1 : Ellipsoid
+        First ellipsoid object (particle i)
+    E2 : Ellipsoid
+        Second ellipsoid object (particle j)
+
+    Returns
+    -------
+    bool
+        True if overlap (collision) is detected, False otherwise
+
+    Notes
+    -----
+    - If both particles are spheres, the bounding sphere hierarchy alone
+      suffices to detect collision.
+    - If either particle is an ellipsoid, their coefficients, positions,
+      and rotation matrices are used in the overlap test.
     """
 
     # call the collision detection algorithm
@@ -31,44 +40,45 @@ def collision_routine(E1, E2):
 
 
 def collision_react(ell1, ell2):
-    r"""
-    Evaluates and modifies the magnitude and direction of the ellipsoid's velocity after collision.    
-
-    :param ell1: Ellipsoid :math:`i`
-    :type ell1: object :obj:`Ellipsoid`
-    :param ell2: Ellipsoid :math:`j`
-    :type ell2: object :obj:`Ellipsoid`
-
-    .. note:: Consider two ellipsoids :math:`i, j` at collision. Let them occupy certain positions in space
-              defined by the position vectors :math:`\mathbf{r}^{i}, \mathbf{r}^{j}` and have certain 
-              velocities represented by :math:`\mathbf{v}^{i}, \mathbf{v}^{j}` respectively. The objective
-              is to  find the velocity vectors after collision. The elevation angle :math:`\phi` between
-              the ellipsoids is determined by,      
-
-              .. image:: /figs/elevation_ell.png                        
-                :width: 200px
-                :height: 45px
-                :align: center                 
-
-              where :math:`dx, dy, dz` are defined as the distance between the two ellipsoid centers along
-                    :math:`x, y, z` directions given by,
-
-              .. image:: /figs/dist_ell.png                        
-                  :width: 110px
-                  :height: 75px
-                  :align: center
-
-              Depending on the magnitudes of :math:`dx, dz` as projected on the :math:`x-z` plane, the angle
-              :math:`\Theta` is computed.
-              The angles :math:`\Theta` and :math:`\phi` determine the in-plane and out-of-plane directions along which
-              the ellipsoid :math:`i` would bounce back after collision. Thus, the updated velocity vector components
-              along the :math:`x, y, z` directions are determined by,
-
-              .. image:: /figs/velocities_ell.png                        
-                  :width: 180px
-                  :height: 80px
-                  :align: center                        
-
+    """
+    Evaluates and modifies the magnitude and direction of the ellipsoid's velocity after collision
+
+    Parameters
+    ----------
+    ell1 : Ellipsoid
+        Ellipsoid i
+    ell2 : Ellipsoid
+        Ellipsoid j
+
+    Notes
+    -----
+    Consider two ellipsoids i, j at collision. Let them occupy certain positions in space
+    defined by the position vectors r^i, r^j and have certain velocities represented by v^i, v^j
+    respectively. The objective is to find the velocity vectors after collision. The elevation angle φ
+    between the ellipsoids is determined by:
+
+    .. image:: /figs/elevation_ell.png
+        :width: 200px
+        :height: 45px
+        :align: center
+
+    where dx, dy, dz are defined as the distance between the two ellipsoid centers along
+    x, y, z directions given by:
+
+    .. image:: /figs/dist_ell.png
+        :width: 110px
+        :height: 75px
+        :align: center
+
+    Depending on the magnitudes of dx, dz as projected on the x-z plane, the angle Θ is computed.
+    The angles Θ and φ determine the in-plane and out-of-plane directions along which
+    ellipsoid i would bounce back after collision. Thus, the updated velocity vector components
+    along the x, y, z directions are determined by:
+
+    .. image:: /figs/velocities_ell.png
+        :width: 180px
+        :height: 80px
+        :align: center
     """
     cdir = ell1.get_pos() - ell2.get_pos()
     dst = np.linalg.norm(cdir)
@@ -87,24 +97,37 @@ def collision_react(ell1, ell2):
 
 
 def collide_detect(coef_i, coef_j, r_i, r_j, A_i, A_j):
-    r"""Implementation of Algebraic separation condition developed by
-    W. Wang et al. 2001 for overlap detection between two static ellipsoids.
-    Kudos to ChatGPT for support with translation from C++ code.
-
-    :param coef_i: Coefficients of ellipsoid :math:`i`
-    :type coef_i: numpy array
-    :param coef_j: Coefficients of ellipsoid :math:`j`
-    :type coef_j: numpy array
-    :param r_i: Position of ellipsoid :math:`i`
-    :type r_i: numpy array
-    :param r_j: Position of ellipsoid :math:`j`
-    :type r_j: numpy array
-    :param A_i: Rotation matrix of ellipsoid :math:`i`
-    :type A_i: numpy array
-    :param A_j: Rotation matrix of ellipsoid :math:`j`
-    :type A_j: numpy array
-    :returns: **True** if ellipsoids :math:`i, j` overlap, else **False**
-    :rtype: boolean
+    """
+    Determines overlap between two static ellipsoids using the Algebraic Separation Condition
+    developed by W. Wang et al., 2001. This function implements the method for two ellipsoids
+    with given coefficients, positions, and rotation matrices
+
+    Parameters
+    ----------
+    coef_i : numpy array
+        Coefficients of ellipsoid i
+    coef_j : numpy array
+        Coefficients of ellipsoid j
+    r_i : numpy array
+        Position vector of ellipsoid i
+    r_j : numpy array
+        Position vector of ellipsoid j
+    A_i : numpy array
+        Rotation matrix of ellipsoid i
+    A_j : numpy array
+        Rotation matrix of ellipsoid j
+
+    Returns
+    -------
+    bool
+        True if ellipsoids i and j overlap, False otherwise
+
+    Notes
+    -----
+    The method calculates the characteristic polynomial based on the ellipsoid coefficients
+    and rigid body transformations. Roots of this polynomial are used with the Algebraic
+    Separation Condition to determine whether the ellipsoids intersect. Real roots with
+    negative values are analyzed to establish the overlap.
     """
     SMALL = 1.e-12