PyFiberModes 0.12.0__tar.gz → 0.13.0__tar.gz

{pyfibermodes-0.12.0 → pyfibermodes-0.13.0}/.zenodo.json

@@ -9,7 +9,7 @@
   "license": "MIT",
   "upload_type": "software",
   "access_right": "open",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "publication_date": "2026-09-22",
   "keywords": [
     "optical fibers",

{pyfibermodes-0.12.0 → pyfibermodes-0.13.0}/CHANGELOG.md

@@ -6,6 +6,20 @@ use [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-09-22
+
+### Changed
+
+- Replaced MPSPlots styling and colormaps with native Matplotlib equivalents,
+  removing MPSPlots from all runtime and documentation dependencies.
+- Field maps now share one radial solver pass across all electric and magnetic
+  components and cache interpolated, azimuthal, and batched component arrays.
+- Added NumPyDoc documentation across modules, public APIs, data models, and
+  numerical solver helpers, with structural coverage enforced by tests.
+- Reorganized the documentation into learning, theory, workflow, performance,
+  troubleshooting, gallery, and task-oriented API sections; added four new
+  example series and a unified logo and favicon identity.
+
 ## [0.12.0] - 2026-09-22
 
 ### Changed
@@ -41,7 +55,8 @@ use [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 - Established the current tagged baseline for subsequent documented releases.
 
-[Unreleased]: https://github.com/MartinPdeS/PyFiberModes/compare/v0.12.0...HEAD
+[Unreleased]: https://github.com/MartinPdeS/PyFiberModes/compare/v0.13.0...HEAD
+[0.13.0]: https://github.com/MartinPdeS/PyFiberModes/releases/tag/v0.13.0
 [0.12.0]: https://github.com/MartinPdeS/PyFiberModes/releases/tag/v0.12.0
 [0.11.0]: https://github.com/MartinPdeS/PyFiberModes/releases/tag/v0.11.0
 [0.10.0]: https://github.com/MartinPdeS/PyFiberModes/releases/tag/v0.10.0

{pyfibermodes-0.12.0 → pyfibermodes-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyFiberModes
-Version: 0.12.0
+Version: 0.13.0
 Summary: A package for light propagation in fiber optics.
 Author-email: Martin Poinsinet de Sivry-Houle <martin.poinsinet.de.sivry@gmail.com>
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -697,28 +697,34 @@ Requires-Python: >=3.10
 Description-Content-Type: text/x-rst
 License-File: LICENSE
 Requires-Dist: PyOptik<3,>=2
-Requires-Dist: MPSPlots
 Requires-Dist: PyFinitDiff
+Requires-Dist: matplotlib>=3.8
 Requires-Dist: pyyaml
 Requires-Dist: numpy
 Requires-Dist: scipy
 Provides-Extra: testing
-Requires-Dist: pytest<9.0,>=7.4; extra == "testing"
+Requires-Dist: pytest<10.0,>=7.4; extra == "testing"
 Requires-Dist: pytest-cov<8,>=2; extra == "testing"
 Requires-Dist: pytest-json-report~=1.5; extra == "testing"
 Requires-Dist: coverage~=7.6; extra == "testing"
 Requires-Dist: ruff<1,>=0.8; extra == "testing"
 Requires-Dist: tomli<3,>=2; python_version < "3.11" and extra == "testing"
 Provides-Extra: documentation
-Requires-Dist: numpydoc==1.9.0; extra == "documentation"
+Requires-Dist: numpydoc==1.10.0; extra == "documentation"
 Requires-Dist: sphinx>=5.1.1; extra == "documentation"
-Requires-Dist: sphinx-gallery==0.19.0; extra == "documentation"
+Requires-Dist: sphinx-gallery==0.21.0; extra == "documentation"
+Requires-Dist: sphinx-design<1,>=0.6; extra == "documentation"
 Requires-Dist: sphinx-rtd-theme==3.1.0; extra == "documentation"
-Requires-Dist: pydata-sphinx-theme==0.14.1; extra == "documentation"
+Requires-Dist: pydata-sphinx-theme==0.17.1; extra == "documentation"
 Provides-Extra: dev
 Requires-Dist: ruff<1,>=0.8; extra == "dev"
 Dynamic: license-file
 
+.. image:: https://raw.githubusercontent.com/MartinPdeS/PyFiberModes/master/docs/source/_static/logo.png
+   :width: 620
+   :align: center
+   :alt: PyFiberModes logo
+
 .. list-table::
    :widths: 35 65
    :header-rows: 1

{pyfibermodes-0.12.0 → pyfibermodes-0.13.0}/PyFiberModes/__future__.py

@@ -1,5 +1,4 @@
-#!/usr/bin/env python
-# -*- coding: utf-8 -*-
+"""Experimental field-normalization helpers retained for future APIs."""
 
 import numpy
 
@@ -7,20 +6,28 @@ from PyFiberModes import Mode
 
 
 def get_normalized_LP_coupling(fiber, mode_0: Mode, mode_1: Mode) -> float:
-    r"""
-    Gets the normalized coupling between two supermodes as defined in Equation 7.39 Jacques Bures.
+    r"""Calculate normalized coupling between two LP supermodes.
 
-    .. math::
+    Parameters
+    ----------
+    fiber : Fiber
+        Fiber providing propagation constants and interface fields.
+    mode_0, mode_1 : Mode
+        Linearly polarized modes to couple.
 
-        \tilde{C_{ij}} = \frac{0.5 k_0^2}{(\beta_0 - \beta_1) \sqrt{\beta_0 * \beta_1}} \sum_i r_i^2 \psi_0(r_i) * \psi_1(r_i)
+    Returns
+    -------
+    float
+        Normalized coupling coefficient.
 
-    :param      mode_0:  The mode 0
-    :type       mode_0:  Mode
-    :param      mode_1:  The mode 1
-    :type       mode_1:  Mode
+    Notes
+    -----
+    The calculation follows Equation 7.39 of Jacques Bures,
+    *Optical Fiber Theory*:
 
-    :returns:   The normalized coupling.
-    :rtype:     float
+    .. math::
+
+        \tilde{C_{ij}} = \frac{0.5 k_0^2}{(\beta_0 - \beta_1) \sqrt{\beta_0 * \beta_1}} \sum_i r_i^2 \psi_0(r_i) * \psi_1(r_i)
     """
     assert mode_0.family == 'LP' and mode_1.family == 'LP', "The normalized coupling equation are only valid for scalar [LP] modes"
 
@@ -56,6 +63,20 @@ def get_normalized_LP_coupling(fiber, mode_0: Mode, mode_1: Mode) -> float:
 
 
 def get_LP_mode_norm(fiber, mode: Mode) -> float:
+    """Calculate the radial normalization integral of an LP mode.
+
+    Parameters
+    ----------
+    fiber : Fiber
+        Fiber providing radial fields and outer radius.
+    mode : Mode
+        Linearly polarized mode to normalize.
+
+    Returns
+    -------
+    float
+        Scalar radial-field norm.
+    """
     radius_list = numpy.linspace(0, 2 * fiber.radius, 100)
 
     amplitudes = get_LP_mode_radial_field(
@@ -70,6 +91,24 @@ def get_LP_mode_norm(fiber, mode: Mode) -> float:
 
 
 def get_LP_mode_radial_normalized_field(fiber, mode: Mode, radius_list: numpy.ndarray = None) -> float:
+    """Sample and normalize the scalar radial field of an LP mode.
+
+    Parameters
+    ----------
+    fiber : Fiber
+        Fiber providing radial fields.
+    mode : Mode
+        Linearly polarized mode to sample.
+    radius_list : numpy.ndarray, optional
+        Radial sampling positions in meters.
+
+    Returns
+    -------
+    normalized_field : numpy.ndarray
+        Unit-normalized scalar field samples.
+    radius_list : numpy.ndarray
+        Radial positions associated with the samples.
+    """
     if radius_list is None:
         radius_list = numpy.linspace(0, 2 * fiber.radius, 200)
 
@@ -85,6 +124,22 @@ def get_LP_mode_radial_normalized_field(fiber, mode: Mode, radius_list: numpy.nd
 
 
 def get_LP_mode_radial_field(fiber, mode: Mode, radius_list: numpy.ndarray) -> float:
+    """Sample the scalar radial electric field of an LP mode.
+
+    Parameters
+    ----------
+    fiber : Fiber
+        Fiber providing radial fields.
+    mode : Mode
+        Linearly polarized mode to sample.
+    radius_list : numpy.ndarray
+        Radial sampling positions in meters.
+
+    Returns
+    -------
+    numpy.ndarray
+        Radial electric-field amplitude at each position.
+    """
     amplitudes = numpy.empty(radius_list.size)
 
     for idx, rho in enumerate(radius_list):
@@ -95,6 +150,20 @@ def get_LP_mode_radial_field(fiber, mode: Mode, radius_list: numpy.ndarray) -> f
 
 
 def get_scalar_field_norm(rho_list: numpy.ndarray, field: numpy.ndarray) -> float:
+    r"""Integrate the cylindrical norm of a scalar radial field.
+
+    Parameters
+    ----------
+    rho_list : numpy.ndarray
+        Uniform radial sampling positions.
+    field : numpy.ndarray
+        Scalar field amplitude at each radial position.
+
+    Returns
+    -------
+    float
+        Value of :math:`2\pi\int |E(\rho)|^2\rho\,d\rho`.
+    """
     rho_list = numpy.asarray(rho_list)
     field = numpy.asarray(field)
     dr = rho_list[1] - rho_list[0]

{pyfibermodes-0.12.0 → pyfibermodes-0.13.0}/PyFiberModes/__init__.py

@@ -1,3 +1,5 @@
+"""Public API for circular optical-fiber mode analysis."""
+
 from PyFiberModes.mode import Mode, Family  # noqa: F401
 from PyFiberModes.mode_instances import *  # noqa: F403
 from PyFiberModes.factory import FiberFactory

{pyfibermodes-0.12.0 → pyfibermodes-0.13.0}/PyFiberModes/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.12.0'
-__version_tuple__ = version_tuple = (0, 12, 0)
+__version__ = version = '0.13.0'
+__version_tuple__ = version_tuple = (0, 13, 0)
 
 __commit_id__ = commit_id = None

{pyfibermodes-0.12.0 → pyfibermodes-0.13.0}/PyFiberModes/analysis.py

@@ -11,10 +11,21 @@ from PyFiberModes.mode import Mode
 
 @dataclass(frozen=True)
 class ModeSweepResult:
-    """Dense, dependency-free result returned by :func:`sweep_modes`.
+    """Store modal quantities evaluated over a parameter sweep.
 
     Rows correspond to ``parameters`` and columns to ``modes``.  Missing or
     unguided solutions are represented by NaN.
+
+    Parameters
+    ----------
+    parameter_name : str
+        Name of the swept parameter.
+    parameters : numpy.ndarray
+        One-dimensional parameter values.
+    modes : tuple of Mode
+        Modes represented by the columns of every value array.
+    values : dict of str to numpy.ndarray
+        Modal metrics shaped ``(n_parameters, n_modes)``.
     """
 
     parameter_name: str
@@ -23,13 +34,44 @@ class ModeSweepResult:
     values: dict[str, np.ndarray]
 
     def __getitem__(self, metric: str) -> np.ndarray:
+        """Return the array associated with a metric name.
+
+        Parameters
+        ----------
+        metric : str
+            Metric key stored in :attr:`values`.
+
+        Returns
+        -------
+        numpy.ndarray
+            Metric values shaped ``(n_parameters, n_modes)``.
+        """
         return self.values[metric]
 
     def for_mode(self, mode: Mode) -> dict[str, np.ndarray]:
+        """Extract every metric for one mode.
+
+        Parameters
+        ----------
+        mode : Mode
+            Mode whose column is requested.
+
+        Returns
+        -------
+        dict of str to numpy.ndarray
+            Mapping from metric names to one-dimensional sweep values.
+        """
         index = self.modes.index(mode)
         return {name: value[:, index] for name, value in self.values.items()}
 
     def as_records(self) -> list[dict]:
+        """Convert the dense result into row-oriented records.
+
+        Returns
+        -------
+        list of dict
+            One record for every parameter and mode combination.
+        """
         return [
             {self.parameter_name: float(parameter), "mode": mode, **{
                 name: float(array[i, j]) for name, array in self.values.items()
@@ -42,7 +84,22 @@ class ModeSweepResult:
 def candidate_modes(
     families: Sequence[str] = ("LP",), max_nu: int = 6, max_m: int = 6
 ) -> tuple[Mode, ...]:
-    """Generate deterministic candidate modes for automatic discovery."""
+    """Generate a deterministic bounded set of mode candidates.
+
+    Parameters
+    ----------
+    families : sequence of str, optional
+        Mode families to enumerate.
+    max_nu : int, optional
+        Largest azimuthal order to include.
+    max_m : int, optional
+        Largest radial order to include.
+
+    Returns
+    -------
+    tuple of Mode
+        Candidates ordered by family, azimuthal order, and radial order.
+    """
     modes = []
     for family in families:
         nus = (0,) if family in ("TE", "TM") else range(max_nu + 1)
@@ -54,7 +111,25 @@ def candidate_modes(
 
 
 def find_modes(fiber, families=("LP",), max_nu=6, max_m=6) -> tuple[Mode, ...]:
-    """Return all guided modes among a bounded set of candidates."""
+    """Find guided modes supported by a fiber.
+
+    Parameters
+    ----------
+    fiber : Fiber
+        Fiber on which effective indices are evaluated.
+    families : sequence of str, optional
+        Mode families to search.
+    max_nu : int, optional
+        Largest azimuthal order to test.
+    max_m : int, optional
+        Largest radial order to test.
+
+    Returns
+    -------
+    tuple of Mode
+        Candidates with finite effective indices between the cladding and
+        maximum material indices.
+    """
     found = []
     for mode in candidate_modes(families, max_nu, max_m):
         try:
@@ -79,7 +154,40 @@ def sweep_modes(
     max_nu=6,
     max_m=6,
 ) -> ModeSweepResult:
-    """Track modes over wavelength or any parameter handled by ``setter``."""
+    """Evaluate modal metrics over wavelength or another scalar parameter.
+
+    Parameters
+    ----------
+    fiber : Fiber
+        Fiber used as the immutable sweep template.
+    parameters : iterable of float
+        Ordered parameter values.
+    modes : sequence of Mode, optional
+        Modes to evaluate. When omitted, modes are discovered automatically.
+    parameter_name : str, optional
+        Name recorded in the returned result.
+    setter : callable, optional
+        Function accepting ``(fiber, value)`` for non-wavelength sweeps.
+    metrics : sequence of str, optional
+        Suffixes of ``Fiber.get_<metric>`` methods to evaluate.
+    families : sequence of str, optional
+        Families used during automatic discovery.
+    max_nu : int, optional
+        Maximum discovered azimuthal order.
+    max_m : int, optional
+        Maximum discovered radial order.
+
+    Returns
+    -------
+    ModeSweepResult
+        Dense arrays for each requested metric.
+
+    Raises
+    ------
+    ValueError
+        If ``parameters`` is empty or not one-dimensional, or when a custom
+        parameter is requested without a setter.
+    """
     parameters = np.asarray(tuple(parameters), dtype=float)
     if parameters.ndim != 1 or not len(parameters):
         raise ValueError("parameters must be a non-empty one-dimensional sequence")
@@ -89,6 +197,7 @@ def sweep_modes(
             raise ValueError("a setter is required for non-wavelength sweeps")
 
         def setter(current_fiber, value):
+            """Update wavelength for the default sweep behavior."""
             current_fiber.update_wavelength(value)
     if modes is None:
         discovered = []

{pyfibermodes-0.12.0 → pyfibermodes-0.13.0}/PyFiberModes/coordinates.py

@@ -1,3 +1,5 @@
+"""Cartesian and cylindrical sampling-grid definitions."""
+
 import numpy as np
 from dataclasses import dataclass
 from typing import Tuple
@@ -8,7 +10,7 @@ class CylindricalCoordinates:
     """
     Represents a set of points in cylindrical coordinates.
 
-    Attributes
+    Parameters
     ----------
     rho : np.ndarray
         Radial distance from the z-axis.
@@ -51,7 +53,7 @@ class CartesianCoordinates:
     """
     Represents a set of points in cartesian coordinates.
 
-    Attributes
+    Parameters
     ----------
     x : np.ndarray
         x-coordinates (must be a 1D array).
@@ -71,6 +73,7 @@ class CartesianCoordinates:
     is_3D: bool = False
 
     def __post_init__(self) -> None:
+        """Convert all coordinate arrays to floating-point arrays."""
         self.x = self.x.astype(float)
         self.y = self.y.astype(float)
         self.z = self.z.astype(float)

{pyfibermodes-0.12.0 → pyfibermodes-0.13.0}/PyFiberModes/factory.py

@@ -1,5 +1,4 @@
-#!/usr/bin/env python
-# -*- coding: utf-8 -*-
+"""Factories for constructing parameterized multilayer fibers."""
 
 from itertools import product
 from dataclasses import dataclass, field
@@ -12,7 +11,7 @@ class ProxyLayer:
     """
     Represents a layer configuration in a fiber, with name, radius, and refractive index.
 
-    Attributes
+    Parameters
     ----------
     name : str
         Name of the layer.
@@ -26,6 +25,7 @@ class ProxyLayer:
     index: list = field(default_factory=list)
 
     def __post_init__(self):
+        """Normalize scalar layer parameters into one-dimensional arrays."""
         self.name = [self.name]
         self.radius = np.atleast_1d(self.radius)
         self.index = np.atleast_1d(self.index)
@@ -64,6 +64,13 @@ class FiberFactory:
     """
 
     def __init__(self, wavelength: float):
+        """Initialize an empty fiber-configuration factory.
+
+        Parameters
+        ----------
+        wavelength : float
+            Vacuum wavelength in meters for generated fibers.
+        """
         self.layers_list = []
         self.neff_solver = None
         self.cutoff_solver = None