PyFiberModes 0.13.0__tar.gz → 0.13.1__tar.gz

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

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

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

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

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

@@ -6,6 +6,25 @@ 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
@@ -55,7 +74,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.13.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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyFiberModes
-Version: 0.13.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
@@ -709,6 +709,8 @@ 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.10.0; extra == "documentation"
 Requires-Dist: sphinx>=5.1.1; extra == "documentation"
@@ -775,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.13.0 → pyfibermodes-0.13.1}/PyFiberModes/__init__.py

@@ -3,7 +3,12 @@
 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
@@ -17,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.13.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.13.0'
-__version_tuple__ = version_tuple = (0, 13, 0)
+__version__ = version = '0.13.1'
+__version_tuple__ = version_tuple = (0, 13, 1)
 
 __commit_id__ = commit_id = None

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

@@ -74,9 +74,9 @@ class CartesianCoordinates:
 
     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)
+        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]:
@@ -119,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
@@ -139,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.13.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.13.0 → pyfibermodes-0.13.1}/PyFiberModes/fiber.py

@@ -15,14 +15,14 @@ from PyFinitDiff.finite_difference_1D import get_function_derivative
 from PyFiberModes.field import Field
 
 from PyFiberModes.fundamentals import (
-    get_effective_index,
-    get_mode_cutoff_v0,
     get_radial_field,
     get_propagation_constant_from_omega
 )
 
 from PyFiberModes import loader
 from PyFiberModes.coordinates import CylindricalCoordinates
+from PyFiberModes.exceptions import ValidationError
+from PyFiberModes.services import FieldAnalysis, ModalAnalysis
 
 
 @dataclass
@@ -55,9 +55,62 @@ class Fiber(object):
 
     def __post_init__(self):
         """Initialize mutable layer and solver state after construction."""
+        if self.wavelength is not None and (
+            not numpy.isfinite(self.wavelength) or self.wavelength <= 0
+        ):
+            raise ValidationError("wavelength must be positive and finite")
         self.layers_parameters = []
         self.radius_in = 0
         self.layers = []
+        self._analysis_service = None
+        self._field_service = None
+
+    @property
+    def geometry_signature(self) -> tuple:
+        """Return an immutable signature of all solver-relevant fiber state.
+
+        Returns
+        -------
+        tuple
+            Wavelength and ordered layer geometry/index values.
+        """
+        layers = tuple(
+            (layer.radius_in, layer.radius_out, layer.refractive_index)
+            for layer in self.layers
+        )
+        return self.wavelength, layers
+
+    @property
+    def analysis(self) -> ModalAnalysis:
+        """Return the focused modal-analysis service.
+
+        Returns
+        -------
+        ModalAnalysis
+            Geometry-aware cached analysis service.
+        """
+        if self._analysis_service is None:
+            self._analysis_service = ModalAnalysis(self)
+        return self._analysis_service
+
+    @property
+    def fields(self) -> FieldAnalysis:
+        """Return the focused field-construction service.
+
+        Returns
+        -------
+        FieldAnalysis
+            Field orchestration service.
+        """
+        if self._field_service is None:
+            self._field_service = FieldAnalysis(self)
+        return self._field_service
+
+    def clear_caches(self) -> None:
+        """Clear modal and radial-field caches after a physical mutation."""
+        if self._analysis_service is not None:
+            self._analysis_service.clear()
+        self.get_radial_field.cache_clear()
 
     def scale(self, factor: float) -> None:
         """
@@ -195,7 +248,7 @@ class Fiber(object):
         self.wavelength = wavelength
         for layer in self.layers:
             layer.wavelength = wavelength
-        self.get_radial_field.cache_clear()
+        self.clear_caches()
 
     def add_layer(self, name: str, radius: float, index: float) -> None:
         """
@@ -214,6 +267,16 @@ class Fiber(object):
         -----
         Layers should be added in order, starting with the innermost layer (core).
         """
+        if not name:
+            raise ValidationError("layer name must not be empty")
+        if not numpy.isfinite(index) or index <= 0:
+            raise ValidationError("refractive index must be positive and finite")
+        radius = float(radius)
+        if radius <= 0:
+            radius = numpy.inf
+        if radius <= self.radius_in:
+            raise ValidationError("layer radii must be strictly increasing")
+
         self.layer_names.append(name)
         self.index_list.append(index)
 
@@ -231,6 +294,7 @@ class Fiber(object):
         self.layers.append(layer)
 
         self.radius_in = radius
+        self.clear_caches()
 
     def initialize_layers(self) -> None:
         """Initializes the layers.
@@ -240,6 +304,8 @@ class Fiber(object):
         None
             No returns
         """
+        if not self.layers:
+            raise ValidationError("a fiber must contain at least one layer")
         self.layers[-1].is_last_layer = True
         self.layers[0].is_first_layer = True
 
@@ -247,6 +313,7 @@ class Fiber(object):
 
         for position, layer in enumerate(self.layers):
             layer.position = position
+        self.clear_caches()
 
     def get_layer_at_radius(self, radius: float) -> StepIndex:
         """Gets the layer that is associated to a given radius.
@@ -263,8 +330,29 @@ class Fiber(object):
         """
         radius = abs(radius)
         for layer in self.layers:
-            if (radius > layer.radius_in) and (radius < layer.radius_out):
+            if layer.radius_in <= radius <= layer.radius_out:
                 return layer
+        raise ValidationError(f"radius {radius} lies outside the fiber geometry")
+
+    def get_index_profile(self, radius) -> numpy.ndarray:
+        """Evaluate the refractive-index profile for many radii at once.
+
+        Parameters
+        ----------
+        radius : array-like
+            Scalar or array of radial positions in meters.
+
+        Returns
+        -------
+        numpy.ndarray
+            Refractive indices with the same shape as ``radius``.
+        """
+        radii = numpy.abs(numpy.asarray(radius, dtype=float))
+        boundaries = numpy.asarray([layer.radius_out for layer in self.layers])
+        indices = numpy.asarray([layer.refractive_index for layer in self.layers])
+        positions = numpy.searchsorted(boundaries, radii, side="left")
+        positions = numpy.clip(positions, 0, len(indices) - 1)
+        return indices[positions]
 
     @property
     def radius(self) -> float:
@@ -417,13 +505,8 @@ class Fiber(object):
         float
             The cutoff wavelength.
         """
-        cutoff_V0 = get_mode_cutoff_v0(
-            mode=mode,
-            fiber=self,
-            wavelength=self.wavelength
-        )
-
-        return cutoff_V0
+        result = self.analysis.cutoff_result(mode)
+        return result.value if result.converged else numpy.nan
 
     def get_mode_cutoff_wavelength(self, mode: Mode) -> float:
         """
@@ -472,13 +555,22 @@ class Fiber(object):
         float
             The effective index.
         """
-        neff = get_effective_index(
-            fiber=self,
-            wavelength=self.wavelength,
-            mode=mode
-        )
+        return self.analysis.effective_index(mode)
+
+    def solve_effective_index(self, mode: Mode):
+        """Return a structured effective-index solver result.
 
-        return neff
+        Parameters
+        ----------
+        mode : Mode
+            Mode to solve.
+
+        Returns
+        -------
+        SolverResult[float]
+            Value and explicit convergence diagnostics.
+        """
+        return self.analysis.effective_index_result(mode)
 
     def get_normalized_beta(self, mode: Mode) -> float:
         """Gets the normalized propagation constant [beta].
@@ -493,11 +585,7 @@ class Fiber(object):
         float
             The normalized propagation constant.
         """
-        neff = get_effective_index(
-            fiber=self,
-            wavelength=self.wavelength,
-            mode=mode,
-        )
+        neff = self.get_effective_index(mode)
 
         n_max = self.maximum_index
 
@@ -522,11 +610,7 @@ class Fiber(object):
         float
             The propagation constant [:math:`beta`].
         """
-        neff = get_effective_index(
-            fiber=self,
-            wavelength=self.wavelength,
-            mode=mode,
-        )
+        neff = self.get_effective_index(mode)
 
         beta = neff * (2 * numpy.pi / self.wavelength)
 
@@ -555,11 +639,7 @@ class Fiber(object):
 
         where :math:`n_{eff}` is the effective refractive index.
         """
-        n_eff = get_effective_index(
-            fiber=self,
-            wavelength=self.wavelength,
-            mode=mode,
-        )
+        n_eff = self.get_effective_index(mode)
 
         return constants.c / n_eff
 
@@ -589,34 +669,20 @@ class Fiber(object):
 
         return derivative * constants.c
 
-    def get_groupe_velocity(self, mode: Mode) -> float:
-        r"""Gets the groupe velocity defined as:
-
-        .. math::
-            \left( \frac{\partial \beta}{\partial \omega} \right)^{-1}
+    def get_group_velocity(self, mode: Mode) -> float:
+        """Compute the correctly named modal group velocity.
 
         Parameters
         ----------
         mode : Mode
-            The mode to consider
+            Mode to evaluate.
 
         Returns
         -------
         float
-            The groupe velocity.
+            Group velocity in meters per second.
         """
-        omega = c * 2 * numpy.pi / self.wavelength
-
-        derivative = get_function_derivative(
-            function=get_propagation_constant_from_omega,
-            x_eval=omega,
-            derivative=1,
-            accuracy=4,
-            delta=1e12,  # This value is critical for accurate computation
-            function_kwargs=dict(fiber=self, mode=mode)
-        )
-
-        return 1 / derivative
+        return constants.c / self.get_group_index(mode)
 
     def get_group_velocity_dispersion(self, mode: Mode) -> float:
         r"""Gets the fiber group velocity dispersion defined as:
@@ -736,20 +802,12 @@ class Fiber(object):
         Field
             The field instance of the mode.
         """
-        if limit is None:
-            limit = self.radius * 5.5
-
-        field = Field(
-            fiber=self,
-            mode=mode,
-            limit=limit,
-            n_point=n_point
-        )
-
-        return field
+        return self.fields.mode_field(mode=mode, limit=limit, n_point=n_point)
 
     @cache
-    def get_radial_field(self, mode: Mode, radius: float) -> CylindricalCoordinates:
+    def get_radial_field(
+        self, mode: Mode, radius: float
+    ) -> tuple[CylindricalCoordinates, CylindricalCoordinates]:
         r"""Gets the mode field without the azimuthal component.
         Tuple structure is [:math:`E_{r}`, :math:`E_{\phi}`, :math:`E_{z}`], [:math:`H_{r}`, :math:`H_{\phi}`, :math:`H_{z}`]
 
@@ -762,8 +820,8 @@ class Fiber(object):
 
         Returns
         -------
-        PyFiberModes.coordinates.CylindricalCoordinates
-            The radial field.
+        tuple[CylindricalCoordinates, CylindricalCoordinates]
+            Electric and magnetic radial fields.
         """
         radial_field = get_radial_field(
             fiber=self,
@@ -774,6 +832,35 @@ class Fiber(object):
 
         return radial_field
 
+    def get_radial_fields(self, mode: Mode, radius) -> tuple[CylindricalCoordinates, CylindricalCoordinates]:
+        """Evaluate radial electric and magnetic fields over an array.
+
+        Parameters
+        ----------
+        mode : Mode
+            Mode to evaluate.
+        radius : array-like
+            Radial sampling positions.
+
+        Returns
+        -------
+        tuple[CylindricalCoordinates, CylindricalCoordinates]
+            Electric and magnetic cylindrical components as arrays.
+        """
+        radii = numpy.asarray(radius, dtype=float)
+        flat = radii.ravel()
+        solved = [self.get_radial_field(mode, float(value)) for value in flat]
+
+        def assemble(position):
+            """Assemble one electric or magnetic coordinate container."""
+            values = [item[position] for item in solved]
+            return CylindricalCoordinates(*(
+                numpy.asarray([getattr(value, name) for value in values]).reshape(radii.shape)
+                for name in ("rho", "phi", "z")
+            ))
+
+        return assemble(0), assemble(1)
+
     def get_radial_field_norm(self, mode: Mode, radius: float) -> float:
         r"""Gets the norm of the mode field without the azimuthal component.
         Tuple structure is [:math:`E_{r}`, :math:`E_{\phi}`, :math:`E_{z}`], [:math:`H_{r}`, :math:`H_{\phi}`, :math:`H_{z}`]
@@ -790,12 +877,7 @@ class Fiber(object):
         float
             The radial field.
         """
-        e_field, h_field = get_radial_field(
-            fiber=self,
-            mode=mode,
-            wavelength=self.wavelength,
-            radius=radius
-        )
+        e_field, h_field = self.get_radial_field(mode=mode, radius=radius)
 
         norm = numpy.sqrt(e_field.rho**2 + e_field.phi**2 + e_field.z**2)
 
@@ -817,7 +899,7 @@ class Fiber(object):
         mode_exist = []
         for mode in mode_list:
             neff = self.get_effective_index(mode=mode)
-            if neff is numpy.nan:
+            if not numpy.isfinite(neff):
                 mode_exist.append(False)
             else:
                 mode_exist.append(True)

{pyfibermodes-0.13.0 → pyfibermodes-0.13.1}/PyFiberModes/field.py

@@ -10,6 +10,7 @@ from dataclasses import dataclass
 import matplotlib.pyplot as plt
 from matplotlib.colors import LinearSegmentedColormap
 from PyFiberModes.coordinates import CartesianCoordinates
+from PyFiberModes.coordinates import CylindricalCoordinates as CylindricalCoordinates  # noqa: F401
 
 
 BLUE_BLACK_RED = LinearSegmentedColormap.from_list(
@@ -18,50 +19,6 @@ BLUE_BLACK_RED = LinearSegmentedColormap.from_list(
 )
 
 
-@dataclass
-class CylindricalCoordinates:
-    """Store cylindrical coordinate arrays used by a field grid.
-
-    Parameters
-    ----------
-    rho : numpy.ndarray
-        Radial distances.
-    phi : numpy.ndarray
-        Azimuthal angles in radians.
-    z : numpy.ndarray
-        Longitudinal positions.
-    """
-    rho: numpy.ndarray
-    phi: numpy.ndarray
-    z: numpy.ndarray
-
-    def to_cartesian(self) -> object:
-        """Convert the coordinate arrays to Cartesian form.
-
-        Returns
-        -------
-        CartesianCoordinates
-            Equivalent Cartesian coordinate arrays.
-        """
-        x = self.rho * numpy.cos(self.phi)
-        y = self.rho * numpy.sin(self.phi)
-        z = self.z
-
-        cartesian_coordinate = CartesianCoordinates(x=x, y=y, z=z)
-
-        return cartesian_coordinate
-
-    def to_cylindrical(self):
-        """Return this already-cylindrical coordinate object.
-
-        Returns
-        -------
-        CylindricalCoordinates
-            The current object.
-        """
-        return self
-
-
 @dataclass
 class Field:
     """
@@ -123,23 +80,15 @@ class Field:
 
         count = max(257, 2 * self.n_point)
         radii = np.linspace(0.0, np.sqrt(2.0) * self.limit, count)
-        component_names = ("rho", "phi", "z")
+        electric, magnetic = self.fiber.get_radial_fields(
+            mode=self.mode, radius=radii
+        )
         values = {
-            (field_name, component): np.empty(count, dtype=complex)
-            for field_name in ("E", "H")
-            for component in component_names
+            (field_name, component): np.asarray(getattr(vector, component), dtype=complex)
+            for field_name, vector in (("E", electric), ("H", magnetic))
+            for component in ("rho", "phi", "z")
         }
 
-        for index, radius in enumerate(radii):
-            electric, magnetic = self.fiber.get_radial_field(
-                mode=self.mode, radius=float(radius)
-            )
-            for field_name, vector in (("E", electric), ("H", magnetic)):
-                for component in component_names:
-                    values[field_name, component][index] = complex(
-                        getattr(vector, component)
-                    )
-
         self._radial_cache = {
             key: (radii, component_values)
             for key, component_values in values.items()