Merge pull request #66 from underworldcode/fix/sphinx-doc-warnings

Fix all Sphinx doc build warnings

Author: lmoresi

docs/beginner/parameters.md

@@ -50,6 +50,35 @@ python script.py -uw_resolution 0.025 -uw_solver superlu_dist
 mpirun -np 4 python script.py -uw_resolution 0.01
 ```
 
+### Why Single-Dash Options?
+
+Underworld uses **PETSc-style** command-line options, not Python's standard `argparse`
+conventions. The key differences:
+
+| Convention | Long option | Short option | Word separator |
+|------------|-------------|--------------|----------------|
+| **PETSc** (Underworld) | `-uw_resolution` | — | underscore `_` |
+| **argparse** (Python) | `--resolution` | `-r` | hyphen `-` |
+
+Underworld inherits PETSc's options database, which uses a **single dash** followed
+by a descriptive name with **underscores**. This is by design:
+
+- PETSc solver options (e.g., `-ksp_type gmres`, `-pc_type lu`) use this format
+- Underworld user parameters share the same options database
+- The `uw_` prefix prevents collisions with PETSc's own options
+
+This means standard Python option parsers (argparse, click) do **not** support this
+style of options by default and may require custom handling if you try to parse
+`-uw_*` flags yourself. Use `uw.Params` instead — it reads from PETSc's options
+database automatically.
+
+```{tip}
+If you're writing a wrapper script that also needs argparse-style options,
+parse those with argparse first (for example using `parse_known_args`),
+then pass only the remaining/unparsed arguments to PETSc via
+`petsc4py.init(remaining_argv)` before importing underworld.
+```
+
 ### Notebook Override
 
 ```python

docs/beginner/quickstart.md

@@ -45,7 +45,7 @@ Or using the `./uw` wrapper for local parallel runs:
 ./uw mpirun -np 4 python3 Modelling_Script.py
 ```
 
-The main difference between notebook development and HPC is interactivity—particularly sending parameters at launch time. We use PETSc's command line parsing so notebooks can ingest runtime parameters when run as scripts.
+The main difference between notebook development and HPC is interactivity—particularly sending parameters at launch time. We use PETSc's command line parsing (single-dash options like `-uw_resolution`) so notebooks can ingest runtime parameters when run as scripts. See the [Parameters Guide](parameters.md) for details on the CLI convention.
 
 #### Parallel scaling / performance
 

docs/conf.py

@@ -188,6 +188,8 @@
     'developer/ai-notes/**',
     # Skip examples (not needed for main docs)
     'examples/**',
+    # Skip myst_nb execution artifacts (regenerated each build)
+    'jupyter_execute/**',
 ]
 
 # =============================================================================

src/underworld3/constitutive_models.py

@@ -620,18 +620,6 @@ class ViscousFlowModel(Constitutive_Model):
     material_name : str, optional
         Name identifier for this material (used in multi-material setups).
 
-    Attributes
-    ----------
-    Parameters : _Parameters
-        Material parameters container. Set ``Parameters.shear_viscosity_0``
-        to define the viscosity.
-    flux : sympy.Matrix
-        The computed deviatoric stress tensor :math:`\boldsymbol{\tau}`.
-    C : sympy.Matrix
-        Mandel form of the constitutive tensor :math:`\eta_{IJ}`.
-    c : sympy.Array
-        Rank-4 tensor form :math:`\eta_{ijkl}`.
-
     Examples
     --------
     >>> import underworld3 as uw
@@ -856,17 +844,6 @@ class ViscoPlasticFlowModel(ViscousFlowModel):
     material_name : str, optional
         Name identifier for this material.
 
-    Attributes
-    ----------
-    Parameters : _Parameters
-        Material parameters including:
-
-        - ``shear_viscosity_0``: Background viscosity :math:`\eta_0`
-        - ``yield_stress``: Yield stress :math:`\tau_y`
-
-    viscosity : UWexpression
-        The effective (possibly yielded) viscosity.
-
     Notes
     -----
     If yield stress is not defined, this model behaves identically to
@@ -1659,18 +1636,6 @@ class DiffusionModel(Constitutive_Model):
     material_name : str, optional
         Name identifier for this material.
 
-    Attributes
-    ----------
-    Parameters : _Parameters
-        Material parameters container. Set ``Parameters.diffusivity``
-        to define :math:`\kappa`.
-    flux : sympy.Matrix
-        The computed diffusive flux vector.
-    diffusivity : UWexpression
-        Shortcut to ``Parameters.diffusivity``.
-    K : UWexpression
-        Alias for ``diffusivity``.
-
     Examples
     --------
     >>> diffusion = uw.constitutive_models.DiffusionModel(poisson.Unknowns)
@@ -1928,19 +1893,6 @@ class DarcyFlowModel(Constitutive_Model):
     material_name : str, optional
         Name identifier for this material.
 
-    Attributes
-    ----------
-    Parameters : _Parameters
-        Material parameters container:
-
-        - ``permeability``: Intrinsic permeability :math:`\kappa` [m²]
-        - ``s``: Body force vector (e.g., gravity term)
-
-    flux : sympy.Matrix
-        The computed Darcy flux vector.
-    permeability : UWexpression
-        Shortcut to ``Parameters.permeability``.
-
     Examples
     --------
     >>> darcy = uw.constitutive_models.DarcyFlowModel(solver.Unknowns)

src/underworld3/coordinates.py

@@ -305,22 +305,6 @@ class CoordinateSystemType(Enum):
     system type determines how vector calculus operators (gradient, divergence,
     curl) are computed.
 
-    Attributes
-    ----------
-    CARTESIAN : int
-        Standard Cartesian coordinates (x, y, z).
-    CYLINDRICAL2D : int
-        2D cylindrical/polar coordinates (r, theta).
-    POLAR : int
-        Alias for CYLINDRICAL2D.
-    CYLINDRICAL3D : int
-        3D cylindrical coordinates (r, theta, z).
-    SPHERICAL : int
-        Spherical coordinates (r, theta, phi).
-    GEOGRAPHIC : int
-        Ellipsoidal geographic coordinates (lon, lat, depth) for
-        Earth and planetary modeling.
-
     See Also
     --------
     underworld3.maths.vector_calculus : Operators for each coordinate system.
@@ -500,17 +484,6 @@ class GeographicCoordinateAccessor:
     Access via ``mesh.X.geo`` on GEOGRAPHIC meshes. Use ``.view()`` for a
     complete summary of available properties and methods.
 
-    Attributes
-    ----------
-    lon : ndarray
-        Longitude in degrees East (-180 to 180)
-    lat : ndarray
-        Geodetic latitude in degrees North (-90 to 90)
-    depth : ndarray
-        Depth below ellipsoid surface in km (positive downward)
-    coords : ndarray
-        Combined (N, 3) array: [lon, lat, depth]
-
     Examples
     --------
     >>> geo = mesh.X.geo
@@ -953,19 +926,6 @@ class SphericalCoordinateAccessor:
     Access via ``mesh.X.spherical`` on SPHERICAL or CYLINDRICAL2D meshes.
     Use ``.view()`` for a complete summary of available properties and methods.
 
-    Attributes
-    ----------
-    r : ndarray
-        Radial distance from origin
-    theta : ndarray
-        Angle in radians:
-        - 3D: Colatitude (0 at north pole, π at south pole)
-        - 2D: Polar angle from x-axis (standard θ)
-    phi : ndarray (3D only)
-        Longitude/azimuth in radians (-π to π). Not available for 2D meshes.
-    coords : ndarray
-        Combined array: [r, θ, φ] for 3D, [r, θ] for 2D
-
     Examples
     --------
     >>> sph = mesh.X.spherical

src/underworld3/discretisation/discretisation_mesh.py

@@ -176,17 +176,6 @@ class Mesh(Stateful, uw_object):
     verbose : bool, optional
         Print mesh construction information.
 
-    Attributes
-    ----------
-    N : sympy.vector.CoordSys3D
-        SymPy coordinate system for symbolic expressions.
-    X : UWCoordinate tuple
-        Coordinate variables (x, y, z) for use in expressions.
-    dim : int
-        Spatial dimension of the mesh.
-    dm : PETSc.DMPlex
-        Underlying PETSc distributed mesh object.
-
     Examples
     --------
     Meshes are typically created via the meshing module::

src/underworld3/meshing/faults.py

@@ -97,10 +97,8 @@ def __init__(self, name: str, points: np.ndarray = None):
         """Create a fault surface.
 
         Args:
-            name: Identifier for this fault segment
-            points: (N, 3) array of 3D points defining the fault surface.
-                   If None, the fault is empty and must be loaded or
-                   have points added later.
+            name: Identifier for this fault segment.
+            points: (N, 3) array of 3D points, or None for an empty fault.
         """
         self.name = name
         self._points = None

src/underworld3/meshing/surfaces.py

@@ -890,8 +890,7 @@ def discretize(self, offset: float = 0.01, n_segments: int = None) -> None:
 
         Args:
             offset: (3D only) Height offset for delaunay_2d (controls curvature tolerance).
-            n_segments: (2D only) Number of line segments. If None, uses number
-                       of control points minus 1.
+            n_segments: (2D only) Number of line segments, or None for auto.
 
         Raises:
             ImportError: If pyvista not available

src/underworld3/swarm.py

@@ -112,13 +112,6 @@ class SwarmVariable(DimensionalityMixin, MathematicalMixin, Stateful, uw_object)
         Physical units for this variable (e.g., 'kelvin', 'Pa').
         Requires reference quantities to be set on the model.
 
-    Attributes
-    ----------
-    data : numpy.ndarray
-        Direct access to variable values at particle locations.
-    sym : sympy.Matrix
-        Symbolic representation for use in expressions.
-
     See Also
     --------
     MeshVariable : Variable supported by mesh nodes.
@@ -1975,11 +1968,6 @@ class IndexSwarmVariable(SwarmVariable):
     proxy_continuous : bool
         Whether mesh proxy is continuous (default True).
 
-    Attributes
-    ----------
-    sym : list of sympy.Expr
-        Symbolic mask expressions for each material index.
-
     Examples
     --------
     >>> material = IndexSwarmVariable("M", swarm, indices=3)
@@ -2375,44 +2363,6 @@ class Swarm(Stateful, uw_object):
         Enable verbose output for debugging and monitoring particle operations.
         Default is False.
 
-    Attributes
-    ----------
-    mesh : uw.discretisation.Mesh
-        Reference to the associated mesh object.
-    dim : int
-        Spatial dimension of the mesh (2D or 3D).
-    cdim : int
-        Coordinate dimension of the mesh.
-    data : numpy.ndarray
-        Direct access to particle coordinate data.
-    particle_coordinates : SwarmVariable
-        SwarmVariable containing particle coordinate information.
-    recycle_rate : int
-        Current recycle rate for streak management.
-    cycle : int
-        Current cycle number for streak particles.
-
-    Methods
-    -------
-    populate(fill_param=1)
-        Populate the swarm with particles throughout the domain.
-    migrate(remove_sent_points=True, delete_lost_points=True, max_its=10)
-        Manually migrate particles across MPI processes after coordinate updates.
-    add_particles_with_coordinates(coords)
-        Add new particles at specified coordinate locations.
-    add_particles_with_global_coordinates(coords)
-        Add particles using global coordinate system.
-    add_variable(name, size, dtype=float)
-        Add a new variable to track additional particle properties.
-    save(filename, meshUnits=1.0, swarmUnits=1.0, units="dimensionless")
-        Save swarm data to file.
-    read_timestep(filename, step_name, outputPath="./output/")
-        Read swarm data from a specific timestep file.
-    advection(V_fn, delta_t, evalf=False, corrector=True, restore_points_func=None)
-        Advect particles using a velocity field.
-    estimate_dt(V_fn, dt_min=1.0e-15, dt_max=1.0)
-        Estimate appropriate timestep for particle advection.
-
     Examples
     --------
     Create a basic swarm and populate with particles:
@@ -3360,27 +3310,26 @@ def _force_migration_after_mesh_change(self):
 
     @timing.routine_timer_decorator
     def add_particles_with_coordinates(self, coordinatesArray) -> int:
-        """
-        Add particles to the swarm using particle coordinates provided
-        using a numpy array.
+        """Add particles at given coordinates, keeping only locally-owned points.
 
-        Note that particles with coordinates NOT local to the current processor will
-        be rejected / ignored.
+        Each rank filters the input array and adds only the points that fall
+        within its local domain partition. Non-local points are silently
+        ignored, so it is safe to pass the same global coordinate array to
+        every rank — no duplicates will be created.
 
-        Either include an array with all coordinates to all processors
-        or an array with the local coordinates.
+        This is the recommended method for user code.  For pre-partitioned
+        data where each rank already holds only its own points, this method
+        also works correctly.
 
         Parameters
         ----------
         coordinatesArray : numpy.ndarray
-            The numpy array containing the coordinate of the new particles. Array is
-            expected to take shape n*dim, where n is the number of new particles, and
-            dim is the dimensionality of the swarm's supporting mesh.
+            Coordinates of new particles, shape ``(n, dim)``.
 
         Returns
         --------
-        npoints: int
-            The number of points added to the local section of the swarm.
+        npoints : int
+            Number of points actually added on this rank.
         """
 
         if not isinstance(coordinatesArray, np.ndarray):
@@ -3440,23 +3389,33 @@ def add_particles_with_global_coordinates(
         migrate=True,
         delete_lost_points=True,
     ) -> int:
-        """
-        Add particles to the swarm using particle coordinates provided
-        using a numpy array.
+        """Add particles on every rank, then migrate to correct owners.
+
+        Every rank inserts **all** supplied points into the local swarm, then
+        ``dm.migrate()`` moves each particle to the rank that owns its
+        spatial location.  If the same array is passed on every rank, this
+        produces one copy of each point in the correct partition — but calling
+        it with *different* arrays per rank will accumulate all of them.
 
-        global coordinates: particles will be appropriately migrated
+        This is primarily an internal method used by global-evaluation and
+        mesh-transfer utilities.  For general use, prefer
+        :meth:`add_particles_with_coordinates`, which filters non-local
+        points automatically and never creates duplicates.
 
         Parameters
         ----------
         globalCoordinatesArray : numpy.ndarray
-            The numpy array containing the coordinate of the new particles. Array is
-            expected to take shape n*dim, where n is the number of new particles, and
-            dim is the dimensionality of the swarm's supporting mesh.
+            Coordinates of new particles, shape ``(n, dim)``.
+        migrate : bool
+            Run PETSc swarm migration after insertion (default True).
+        delete_lost_points : bool
+            Remove particles that fall outside any rank's domain
+            during migration (default True).
 
         Returns
         --------
-        npoints: int
-            The number of points added to the local section of the swarm.
+        npoints : int
+            Number of points added on this rank before migration.
         """
 
         if not isinstance(globalCoordinatesArray, np.ndarray):