PyFiberModes 0.12.0__tar.gz → 0.13.1__tar.gz

{pyfibermodes-0.12.0 → pyfibermodes-0.13.1}/.gitignore

@@ -8,6 +8,8 @@
 !development
 !docs
 !tests
+!benchmarks/
+!benchmarks/**
 !.flake8
 !.gitignore
 !.pre-commit-config.yaml

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

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

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

@@ -6,6 +6,39 @@ use [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.13.1] - 2026-09-22
+
+### Added
+
+- Added validated immutable layer and solver settings, structural solver
+  protocols, domain-specific exceptions, and structured solver diagnostics.
+- Added deterministic physical-reference, convergence, caching, architecture,
+  and opt-in `pytest-benchmark` performance suites.
+
+### Changed
+
+- Unified cylindrical coordinates under one canonical model, split modal and
+  field orchestration into focused services, and added geometry-aware caching.
+- Vectorized radial index lookup and routed field construction through a
+  single batched radial-field interface.
+- Standardized the group-velocity API on `get_group_velocity` and removed
+  unreferenced experimental modules, unfinished solver branches, misspelled
+  methods, lowercase directory aliases, and obsolete compatibility wrappers.
+
+## [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 +74,9 @@ 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.1...HEAD
+[0.13.1]: https://github.com/MartinPdeS/PyFiberModes/releases/tag/v0.13.1
+[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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyFiberModes
-Version: 0.12.0
+Version: 0.13.1
 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,36 @@ 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: benchmarking
+Requires-Dist: pytest-benchmark<6,>=5; extra == "benchmarking"
 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
@@ -769,6 +777,9 @@ Features
 * Constrained optimization of layer radii, refractive indices, and custom parameters.
 * Constant or longitudinally varying coupled-mode propagation.
 * A catalog of common and example fiber definitions stored as readable YAML files.
+* Structured solver diagnostics, validated configuration models, and explicit
+  solver protocols for extending numerical backends.
+* Geometry-aware modal caching and vectorized radial index and field workflows.
 
 Installation
 ------------

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

@@ -1,7 +1,14 @@
+"""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
+from PyFiberModes.fiber import Fiber, load_fiber
 from PyFiberModes.field import Field
+from PyFiberModes.coordinates import CartesianCoordinates, CylindricalCoordinates
+from PyFiberModes.exceptions import ConvergenceError, SolverError, ValidationError
+from PyFiberModes.models import LayerSpec, SolverSettings
+from PyFiberModes.solver.results import SolverResult
 from PyFiberModes.analysis import ModeSweepResult, find_modes, sweep_modes
 from PyFiberModes.optimization import DesignParameter, DesignResult, optimize_fiber
 from PyFiberModes.propagation import CoupledModeSystem, PropagationResult, coupling_matrix, overlap
@@ -15,11 +22,15 @@ except ImportError:
 
 
 __all__ = [  # noqa: F405
-    'Wavelength',
     'Mode',
-    'ModeFamily',
+    'Family',
+    'Fiber',
+    'load_fiber',
     'FiberFactory',
     'Field',
+    'CartesianCoordinates', 'CylindricalCoordinates',
+    'LayerSpec', 'SolverSettings', 'SolverResult',
+    'ValidationError', 'SolverError', 'ConvergenceError',
     'ModeSweepResult', 'find_modes', 'sweep_modes',
     'DesignParameter', 'DesignResult', 'optimize_fiber',
     'CoupledModeSystem', 'PropagationResult', 'coupling_matrix', 'overlap',

{pyfibermodes-0.12.0 → pyfibermodes-0.13.1}/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.1'
+__version_tuple__ = version_tuple = (0, 13, 1)
 
 __commit_id__ = commit_id = None

{pyfibermodes-0.12.0 → pyfibermodes-0.13.1}/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.1}/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,9 +73,10 @@ class CartesianCoordinates:
     is_3D: bool = False
 
     def __post_init__(self) -> None:
-        self.x = self.x.astype(float)
-        self.y = self.y.astype(float)
-        self.z = self.z.astype(float)
+        """Convert all coordinate arrays to floating-point arrays."""
+        self.x = np.asarray(self.x, dtype=float)
+        self.y = np.asarray(self.y, dtype=float)
+        self.z = np.asarray(self.z, dtype=float)
 
     @property
     def x_boundaries(self) -> Tuple[float, float]:
@@ -116,7 +119,8 @@ class CartesianCoordinates:
         """
         if self.is_structured:
             x_min, x_max = self.x_boundaries
-            return (x_max - x_min) / len(self.x)
+            unique_x = np.unique(self.x)
+            return float(unique_x[1] - unique_x[0])
         raise ValueError("dx value cannot be inferred from an unstructured mesh.")
 
     @property
@@ -136,7 +140,8 @@ class CartesianCoordinates:
         """
         if self.is_structured:
             y_min, y_max = self.y_boundaries
-            return (y_max - y_min) / len(self.y)
+            unique_y = np.unique(self.y)
+            return float(unique_y[1] - unique_y[0])
         raise ValueError("dx value cannot be inferred from an unstructured mesh.")
 
     @classmethod

{pyfibermodes-0.12.0 → pyfibermodes-0.13.1}/PyFiberModes/directories.py

@@ -9,11 +9,6 @@ __all__ = [
     "DOCS_PATH",
     "EXAMPLES_PATH",
     "DOC_CSS_PATH",
-    "root_path",
-    "project_path",
-    "examples_path",
-    "doc_path",
-    "doc_css_path",
 ]
 
 PACKAGE_PATH = Path(__file__).resolve().parent
@@ -21,10 +16,3 @@ PROJECT_PATH = PACKAGE_PATH.parent
 DOCS_PATH = PROJECT_PATH / "docs"
 EXAMPLES_PATH = DOCS_PATH / "examples"
 DOC_CSS_PATH = DOCS_PATH / "source" / "_static" / "default.css"
-
-# Backwards-compatible aliases for the original public names.
-root_path = PACKAGE_PATH
-project_path = PROJECT_PATH
-doc_path = DOCS_PATH
-examples_path = EXAMPLES_PATH
-doc_css_path = DOC_CSS_PATH

pyfibermodes-0.13.1/PyFiberModes/exceptions.py

@@ -0,0 +1,17 @@
+"""Domain-specific exceptions raised by PyFiberModes."""
+
+
+class PyFiberModesError(Exception):
+    """Base class for package-specific errors."""
+
+
+class ValidationError(PyFiberModesError, ValueError):
+    """Indicate invalid physical geometry or solver configuration."""
+
+
+class SolverError(PyFiberModesError, RuntimeError):
+    """Indicate that a modal solver could not complete normally."""
+
+
+class ConvergenceError(SolverError):
+    """Indicate that a numerical solver did not converge to a valid root."""

{pyfibermodes-0.12.0 → pyfibermodes-0.13.1}/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