PyFiberModes 0.14.3__tar.gz → 0.15.0__tar.gz

{pyfibermodes-0.14.3 → pyfibermodes-0.15.0}/.zenodo.json

@@ -9,7 +9,7 @@
   "license": "MIT",
   "upload_type": "software",
   "access_right": "open",
-  "version": "0.14.3",
+  "version": "0.15.0",
   "publication_date": "2026-09-23",
   "keywords": [
     "optical fibers",

{pyfibermodes-0.14.3 → pyfibermodes-0.15.0}/CHANGELOG.md

@@ -6,6 +6,24 @@ use [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.15.0] - 2026-09-23
+
+### Added
+
+- Published the definitive 1.0 public API table with units, mutation rules,
+  failure semantics, compatibility names, and CI-enforced signatures/defaults.
+- Added ``UnsupportedGeometryError`` to distinguish valid but unsupported
+  calculations from invalid input and numerical non-convergence.
+
+### Changed
+
+- ``Mode`` accepts both strings and ``Family`` members, requires positive
+  radial order, and raises ``ValidationError`` instead of runtime assertions.
+- Standardized expected missing roots, unsupported geometry, invalid input,
+  derivative failures, and structured solver diagnostics across analysis APIs.
+- Completed two-layer and multilayer solver assumptions, characteristic
+  equation residual documentation, units, and primary-reference attribution.
+
 ## [0.14.3] - 2026-09-23
 
 ### Fixed
@@ -123,7 +141,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.14.3...HEAD
+[Unreleased]: https://github.com/MartinPdeS/PyFiberModes/compare/v0.15.0...HEAD
+[0.15.0]: https://github.com/MartinPdeS/PyFiberModes/releases/tag/v0.15.0
 [0.14.3]: https://github.com/MartinPdeS/PyFiberModes/releases/tag/v0.14.3
 [0.14.2]: https://github.com/MartinPdeS/PyFiberModes/releases/tag/v0.14.2
 [0.14.1]: https://github.com/MartinPdeS/PyFiberModes/releases/tag/v0.14.1

{pyfibermodes-0.14.3 → pyfibermodes-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyFiberModes
-Version: 0.14.3
+Version: 0.15.0
 Summary: Guided-mode analysis and design for circular optical fibers.
 Author-email: Martin Poinsinet de Sivry-Houle <martin.poinsinet.de.sivry@gmail.com>
 License:                     GNU GENERAL PUBLIC LICENSE

{pyfibermodes-0.14.3 → pyfibermodes-0.15.0}/PyFiberModes/__init__.py

@@ -26,7 +26,12 @@ 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.exceptions import (
+    ConvergenceError,
+    SolverError,
+    UnsupportedGeometryError,
+    ValidationError,
+)
 from PyFiberModes.models import LayerSpec, SolverSettings
 from PyFiberModes.solver.results import SolverResult
 from PyFiberModes.analysis import ModeSweepResult, find_modes, sweep_modes
@@ -57,7 +62,7 @@ __all__ = [
     'Field',
     'CartesianCoordinates', 'CylindricalCoordinates',
     'LayerSpec', 'SolverSettings', 'SolverResult',
-    'ValidationError', 'SolverError', 'ConvergenceError',
+    'ValidationError', 'SolverError', 'ConvergenceError', 'UnsupportedGeometryError',
     'ModeSweepResult', 'find_modes', 'sweep_modes',
     'DesignParameter', 'DesignResult', 'optimize_fiber',
     'CoupledModeSystem', 'PropagationResult', 'coupling_matrix', 'overlap',

{pyfibermodes-0.14.3 → pyfibermodes-0.15.0}/PyFiberModes/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.14.3'
-__version_tuple__ = version_tuple = (0, 14, 3)
+__version__ = version = '0.15.0'
+__version_tuple__ = version_tuple = (0, 15, 0)
 
 __commit_id__ = commit_id = None

{pyfibermodes-0.14.3 → pyfibermodes-0.15.0}/PyFiberModes/analysis.py

@@ -6,6 +6,7 @@ from typing import Callable, Iterable, Sequence
 
 import numpy as np
 
+from PyFiberModes.exceptions import ConvergenceError, ValidationError
 from PyFiberModes.mode import Mode
 
 
@@ -100,6 +101,8 @@ def candidate_modes(
     tuple of Mode
         Candidates ordered by family, azimuthal order, and radial order.
     """
+    if max_nu < 0 or max_m < 1:
+        raise ValidationError("max_nu must be non-negative and max_m must be positive")
     modes = []
     for family in families:
         nus = (0,) if family in ("TE", "TM") else range(max_nu + 1)
@@ -141,7 +144,7 @@ def find_modes(fiber, families=("LP",), max_nu=6, max_m=6) -> tuple[Mode, ...]:
             )
             if np.isfinite(effective_index) and guided:
                 found.append(mode)
-        except (ArithmeticError, AssertionError, RuntimeError, ValueError):
+        except ConvergenceError:
             continue
     return tuple(found)
 
@@ -226,6 +229,6 @@ def sweep_modes(
                 try:
                     value = metric_function(mode)
                     values[metric][i, j] = value if np.isfinite(value) else np.nan
-                except (ArithmeticError, AssertionError, RuntimeError, ValueError):
+                except ConvergenceError:
                     pass
     return ModeSweepResult(parameter_name, parameters, modes, values)

{pyfibermodes-0.14.3 → pyfibermodes-0.15.0}/PyFiberModes/exceptions.py

@@ -15,3 +15,7 @@ class SolverError(PyFiberModesError, RuntimeError):
 
 class ConvergenceError(SolverError):
     """Indicate that a numerical solver did not converge to a valid root."""
+
+
+class UnsupportedGeometryError(SolverError):
+    """Indicate that a requested calculation does not support the fiber geometry."""

{pyfibermodes-0.14.3 → pyfibermodes-0.15.0}/PyFiberModes/fiber.py

@@ -21,7 +21,7 @@ from PyFiberModes.fundamentals import (
 
 from PyFiberModes import loader
 from PyFiberModes.coordinates import CylindricalCoordinates
-from PyFiberModes.exceptions import ValidationError
+from PyFiberModes.exceptions import ConvergenceError, ValidationError
 from PyFiberModes.materials import DEFAULT_MATERIALS, MaterialRegistry
 from PyFiberModes.services import FieldAnalysis, ModalAnalysis
 
@@ -668,7 +668,10 @@ class Fiber(object):
             function_kwargs=dict(fiber=self, mode=mode)
         )
 
-        return derivative * constants.c
+        value = derivative * constants.c
+        if not numpy.isfinite(value):
+            raise ConvergenceError(f"group-index derivative failed for {mode}")
+        return value
 
     def get_group_velocity(self, mode: Mode) -> float:
         """Compute the correctly named modal group velocity.
@@ -712,6 +715,10 @@ class Fiber(object):
             function_kwargs=dict(fiber=self, mode=mode)
         )
 
+        if not numpy.isfinite(derivative):
+            raise ConvergenceError(
+                f"group-velocity-dispersion derivative failed for {mode}"
+            )
         return derivative
 
     def get_dispersion(self, mode: Mode) -> float:
@@ -778,6 +785,9 @@ class Fiber(object):
             function_kwargs=dict(fiber=self, mode=mode)
         )
 
+        if not numpy.isfinite(derivative):
+            raise ConvergenceError(f"dispersion-slope derivative failed for {mode}")
+
         factor = 2 * numpy.pi * constants.c / self.wavelength**2
 
         return 1e-3 * derivative * factor**2
@@ -965,7 +975,10 @@ class Fiber(object):
             print(first_line, "-" * len(first_line))
             for mode in mode_list:
                 data_type_string = f"get_{data_type.lower()}"
-                data = getattr(self, data_type_string)(mode=mode)
+                try:
+                    data = getattr(self, data_type_string)(mode=mode)
+                except ConvergenceError:
+                    data = numpy.nan
                 output_string = f"{mode = } \t {data_type}: {data}"
                 print(output_string)
 

{pyfibermodes-0.14.3 → pyfibermodes-0.15.0}/PyFiberModes/fundamentals.py

@@ -10,6 +10,7 @@ from PyFiberModes.mode_instances import HE11, LP01
 from scipy.constants import c
 
 from PyFiberModes.coordinates import CylindricalCoordinates
+from PyFiberModes.exceptions import ConvergenceError, UnsupportedGeometryError
 
 if TYPE_CHECKING:
     from PyFiberModes.solver.results import SolverResult
@@ -139,7 +140,10 @@ def get_U_parameter(
         The \(U\) parameter.
     """
     from PyFiberModes import solver
-    assert fiber.n_layer == 2, "U-parameter can only be calculated for two-layer fibers."
+    if fiber.n_layer != 2:
+        raise UnsupportedGeometryError(
+            "U-parameter calculations require exactly two fiber layers"
+        )
 
     effective_index_solver = solver.two_layer.EffectiveIndexSolver(
         fiber=fiber, wavelength=wavelength
@@ -253,7 +257,7 @@ def get_mode_cutoff_v0(
         case 3:
             cutoff_solver = solver.three_layer.CutoffSolver(fiber=fiber, wavelength=wavelength)
         case _:
-            raise NotImplementedError(
+            raise UnsupportedGeometryError(
                 "Cutoff calculations are currently available for two- and three-layer fibers"
             )
 
@@ -306,6 +310,8 @@ def get_radial_field(
         wavelength=fiber.wavelength,
         mode=mode
     )
+    if not numpy.isfinite(neff):
+        raise ConvergenceError(f"no guided effective-index solution for {mode}")
 
     kwargs = dict(
         nu=mode.nu,

{pyfibermodes-0.14.3 → pyfibermodes-0.15.0}/PyFiberModes/mode.py

@@ -3,7 +3,15 @@
 from enum import Enum
 from dataclasses import dataclass
 
-Family = Enum('Family', 'LP HE EH TE TM', module=__name__)
+
+class Family(str, Enum):
+    """Supported scalar and vector mode families."""
+
+    LP = "LP"
+    HE = "HE"
+    EH = "EH"
+    TE = "TE"
+    TM = "TM"
 
 
 @dataclass(frozen=True, eq=True)
@@ -19,7 +27,7 @@ class Mode():
     m : int
         Non-negative radial order.
     """
-    family: str
+    family: str | Family
     """ Family of the mode """
     nu: int
     """ Parameter of the mode. It often corresponds to the parameter of the radial Bessel functions. """
@@ -31,14 +39,25 @@ class Mode():
 
         Raises
         ------
-        AssertionError
-            If the family is unknown or either modal order is negative.
+        ValidationError
+            If the family is unknown, ``nu`` is negative, or ``m`` is not a
+            positive integer.
         """
-        assert self.family in ['LP', 'HE', 'EH', 'TE', 'TM'], f'Unexpected mode family: {self.family}'
+        from PyFiberModes.exceptions import ValidationError
 
-        assert self.nu >= 0, 'Unexpected negative nu value'
+        try:
+            family = self.family if isinstance(self.family, Family) else Family(self.family)
+        except (TypeError, ValueError) as error:
+            choices = ", ".join(member.value for member in Family)
+            raise ValidationError(
+                f"unknown mode family {self.family!r}; expected one of {choices}"
+            ) from error
+        if not isinstance(self.nu, int) or isinstance(self.nu, bool) or self.nu < 0:
+            raise ValidationError("nu must be a non-negative integer")
+        if not isinstance(self.m, int) or isinstance(self.m, bool) or self.m < 1:
+            raise ValidationError("m must be a positive integer")
 
-        assert self.m >= 0, 'Unexpected negative m value'
+        object.__setattr__(self, "family", family.value)
 
     def __repr__(self) -> str:
         """Return the compact family-and-order representation.

{pyfibermodes-0.14.3 → pyfibermodes-0.15.0}/PyFiberModes/services.py

@@ -2,7 +2,12 @@
 
 import numpy as np
 
-from PyFiberModes.exceptions import ConvergenceError
+from PyFiberModes.exceptions import (
+    ConvergenceError,
+    UnsupportedGeometryError,
+    ValidationError,
+)
+from PyFiberModes.mode import Mode
 from PyFiberModes.models import SolverSettings
 from PyFiberModes.solver.results import SolverResult
 
@@ -45,6 +50,8 @@ class ModalAnalysis:
         SolverResult[float]
             Cached value and convergence status.
         """
+        if not isinstance(mode, Mode):
+            raise ValidationError("mode must be a Mode instance")
         key = self._key("effective_index", mode)
         if key in self._cache:
             return self._cache[key]
@@ -58,6 +65,8 @@ class ModalAnalysis:
                 mode=mode,
                 delta_neff=self.settings.effective_index_step,
             )
+        except (ValidationError, UnsupportedGeometryError):
+            raise
         except (ArithmeticError, RuntimeError, ValueError) as error:
             result = SolverResult(value=None, converged=False, message=str(error))
 
@@ -100,7 +109,7 @@ class ModalAnalysis:
                     converged=converged,
                     message="converged" if converged else f"no cutoff solution for {mode}",
                 )
-            except (ArithmeticError, RuntimeError, ValueError) as error:
+            except (ArithmeticError, ValueError) as error:
                 self._cache[key] = SolverResult(
                     value=None, converged=False, message=str(error)
                 )
@@ -145,7 +154,7 @@ class FieldAnalysis:
         from PyFiberModes.field import Field
 
         if n_point < 2:
-            raise ValueError("n_point must be at least two")
+            raise ValidationError("n_point must be at least two")
         return Field(
             fiber=self.fiber,
             mode=mode,

{pyfibermodes-0.14.3 → pyfibermodes-0.15.0}/PyFiberModes/solver/multilayer/effective_index.py

@@ -1,4 +1,11 @@
-"""Effective-index solver for multilayer step-index fibers."""
+"""Transfer-matrix solver for isotropic concentric step-index fibers.
+
+Each homogeneous annulus is represented by cylindrical Bessel or modified
+Bessel solutions and tangential fields are matched at every interface. The
+model assumes circular symmetry, scalar real refractive indices, lossless
+materials, and a longitudinally invariant cross-section. See Snyder and Love,
+*Optical Waveguide Theory*, chapters 12 and 19.
+"""
 
 import numpy
 from scipy.special import kn, kvp, k0, k1, jn, jvp, yn, yvp, iv, ivp
@@ -20,6 +27,12 @@ class EffectiveIndexSolver(BaseSolver):
         Multilayer fiber to solve.
     wavelength : float
         Vacuum wavelength in meters.
+
+    Notes
+    -----
+    LP, TE, TM, HE, and EH families are supported. The solver does not model
+    anisotropy, material loss, stress birefringence, non-circular interfaces,
+    or longitudinal tapering within a solve.
     """
     def get_neff_lower_boundary(self, mode: Mode, delta_neff: float = 1e-6) -> float:
         """Gets the lower boundary for neff value.

{pyfibermodes-0.14.3 → pyfibermodes-0.15.0}/PyFiberModes/solver/three_layer/cutoff.py

@@ -1,4 +1,9 @@
-"""Modal cutoff solver for three-layer step-index fibers."""
+"""Cutoff solver for isotropic three-layer step-index fibers.
+
+The solver matches cylindrical solutions across two concentric interfaces and
+returns dimensionless normalized cutoff frequencies. It assumes homogeneous,
+lossless, isotropic layers with scalar real refractive indices.
+"""
 
 from PyFiberModes.mode import Mode
 from PyFiberModes.mode_instances import HE11, LP01, LP11, TE01
@@ -35,6 +40,11 @@ class CutoffSolver(BaseSolver):
         Three-layer fiber to solve.
     wavelength : float
         Reference vacuum wavelength in meters.
+
+    Notes
+    -----
+    Only cutoff calculations are provided by this backend. Effective indices
+    and fields for the same geometry are handled by the multilayer solver.
     """
 
     def get_lower_neff_mode(self, mode: Mode) -> Mode:

{pyfibermodes-0.14.3 → pyfibermodes-0.15.0}/PyFiberModes/solver/two_layer/cutoff.py

@@ -1,4 +1,9 @@
-"""Modal cutoff solver for two-layer step-index fibers."""
+"""Analytical cutoff solver for isotropic two-layer step-index fibers.
+
+Cutoffs are zeros of the appropriate cylindrical Bessel characteristic
+equation and are returned as dimensionless normalized frequencies. The
+formulation follows Snyder and Love, *Optical Waveguide Theory*, chapter 12.
+"""
 
 import numpy
 import logging
@@ -21,6 +26,11 @@ class CutoffSolver(BaseSolver):
         Standard step-index fiber.
     wavelength : float
         Reference vacuum wavelength in meters.
+
+    Notes
+    -----
+    The fiber must contain exactly one circular core and one homogeneous
+    exterior cladding. LP cutoffs use the weak-guidance approximation.
     """
     logger = logging.getLogger(__name__)
 

{pyfibermodes-0.14.3 → pyfibermodes-0.15.0}/PyFiberModes/solver/two_layer/effective_index.py

@@ -1,4 +1,11 @@
-"""Effective-index and radial-field solver for two-layer fibers."""
+"""Exact scalar and vector solver for isotropic two-layer step-index fibers.
+
+The implementation matches cylindrical Bessel solutions across one circular
+core-cladding interface. LP equations use the weak-guidance approximation;
+TE, TM, HE, and EH equations retain the vector boundary conditions. Material
+indices are real, lossless, and evaluated at one vacuum wavelength. See
+Snyder and Love, *Optical Waveguide Theory*, chapters 11--12.
+"""
 
 import numpy
 import logging
@@ -22,6 +29,12 @@ class EffectiveIndexSolver(BaseSolver):
         Standard step-index fiber.
     wavelength : float
         Vacuum wavelength in meters.
+
+    Notes
+    -----
+    The solver requires exactly two concentric, homogeneous, isotropic layers
+    with a higher-index inner core. Characteristic functions are dimensionless;
+    their roots give the dimensionless effective index.
     """
 
     def get_mode_with_lower_neff(self, mode: Mode) -> Mode:
@@ -542,10 +555,11 @@ class EffectiveIndexSolver(BaseSolver):
         return value
 
     def get_TE_equation(self, neff: float, nu: int) -> float:
-        """Return the value of the phase matching equation for TE mode.
+        r"""Return the TE characteristic-equation residual.
 
         .. math::
-            U * j_0(U) * k_1(W) + W * j_1(U) * k_0(W)
+
+           U J_0(U) K_1(W) + W J_1(U) K_0(W)
 
         Parameters
         ----------
@@ -557,17 +571,20 @@ class EffectiveIndexSolver(BaseSolver):
         Returns
         -------
         float
-            Dont know
+            Dimensionless boundary-condition residual. A guided TE solution
+            occurs at a root.
         """
         U, W, _ = self.get_U_W_V_parameter(neff=neff)
 
         return U * j0(U) * k1(W) + W * j1(U) * k0(W)
 
     def get_TM_equation(self, neff: float, nu: int) -> float:
-        """Return the value of the phase matching equation for TM mode.
+        r"""Return the TM characteristic-equation residual.
 
         .. math::
-            U * j_0(U) * k_1(W) * n_{clad}^2 + W * j_1(U) * k_0(W) * n_{core}^2
+
+           U J_0(U) K_1(W)n_\mathrm{clad}^2
+           + W J_1(U) K_0(W)n_\mathrm{core}^2
 
         Parameters
         ----------
@@ -579,7 +596,8 @@ class EffectiveIndexSolver(BaseSolver):
         Returns
         -------
         float
-            Dont know
+            Dimensionless boundary-condition residual. A guided TM solution
+            occurs at a root.
         """
         core, clad = self.fiber.layers
 
@@ -591,8 +609,8 @@ class EffectiveIndexSolver(BaseSolver):
 
         return U * j0(U) * k1(W) * n_clad**2 + W * j1(U) * k0(W) * n_core**2
 
-    def get_HE_EH_terms(self, neff, nu: int) -> float:
-        """Return the value of the terms for the equation for HE or EH mode.
+    def get_HE_EH_terms(self, neff, nu: int) -> tuple[float, float]:
+        """Return the common and splitting terms of the hybrid equations.
 
         Parameters
         ----------
@@ -603,8 +621,10 @@ class EffectiveIndexSolver(BaseSolver):
 
         Returns
         -------
-        float
-            Dont know
+        tuple of float
+            Dimensionless common boundary term and non-negative hybrid
+            splitting term. Their sum and difference form the HE and EH
+            characteristic residuals, respectively.
         """
         core, clad = self.fiber.layers
 
@@ -628,7 +648,7 @@ class EffectiveIndexSolver(BaseSolver):
         return term_0, term_4
 
     def get_HE_equation(self, neff: float, nu: int) -> float:
-        """Return the value of the phase matching equation for HE mode.
+        """Return the dimensionless HE characteristic-equation residual.
 
         Parameters
         ----------
@@ -640,7 +660,8 @@ class EffectiveIndexSolver(BaseSolver):
         Returns
         -------
         float
-            Dont know
+            Boundary-condition residual; a guided HE solution occurs at a
+            root.
         """
         term_0, term_1 = self.get_HE_EH_terms(
             neff=neff,
@@ -652,7 +673,7 @@ class EffectiveIndexSolver(BaseSolver):
         return value
 
     def get_EH_equation(self, neff: float, nu: int) -> float:
-        """Return the value of the phase matching equation for EH mode.
+        """Return the dimensionless EH characteristic-equation residual.
 
         Parameters
         ----------
@@ -664,7 +685,8 @@ class EffectiveIndexSolver(BaseSolver):
         Returns
         -------
         float
-            Dont know
+            Boundary-condition residual; a guided EH solution occurs at a
+            root.
         """
         term_0, term_1 = self.get_HE_EH_terms(
             neff=neff,

{pyfibermodes-0.14.3 → pyfibermodes-0.15.0}/PyFiberModes.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyFiberModes
-Version: 0.14.3
+Version: 0.15.0
 Summary: Guided-mode analysis and design for circular optical fibers.
 Author-email: Martin Poinsinet de Sivry-Houle <martin.poinsinet.de.sivry@gmail.com>
 License:                     GNU GENERAL PUBLIC LICENSE

{pyfibermodes-0.14.3 → pyfibermodes-0.15.0}/PyFiberModes.egg-info/SOURCES.txt

@@ -123,6 +123,7 @@ docs/source/getting_started.rst
 docs/source/index.rst
 docs/source/migration_guide.rst
 docs/source/performance.rst
+docs/source/public_api_contract.rst
 docs/source/references.rst
 docs/source/theory.rst
 docs/source/troubleshooting.rst

{pyfibermodes-0.14.3 → pyfibermodes-0.15.0}/conda.recipe/meta.yaml

@@ -1,6 +1,6 @@
 package:
   name: pyfibermodes
-  version: 0.14.3
+  version: 0.15.0
 
 source:
   path: ../

{pyfibermodes-0.14.3 → pyfibermodes-0.15.0}/docs/source/api_policy.rst

@@ -15,6 +15,11 @@ The public surface is stored in ``tests/api_snapshot.json`` and checked in CI.
 An intentional API change must update that snapshot, the changelog, and the
 :doc:`migration_guide` in the same pull request.
 
+The definitive object-by-object contract, including units, mutation, and
+failure behavior, is published in :doc:`public_api_contract`. CI freezes the
+parameter order and important defaults of the primary constructors, functions,
+and :class:`~PyFiberModes.fiber.Fiber` façade methods.
+
 Internal modules
 ----------------
 

{pyfibermodes-0.14.3 → pyfibermodes-0.15.0}/docs/source/code.rst

@@ -6,7 +6,7 @@ API reference
 The public API is grouped by task. NumPyDoc descriptions, signatures,
 inheritance, and source links are generated directly from the package.
 The supported import boundary and compatibility guarantees are defined in the
-:doc:`api_policy`; user-visible changes are collected in the
+:doc:`api_policy` and :doc:`public_api_contract`; user-visible changes are collected in the
 :doc:`migration_guide`.
 
 .. toctree::

{pyfibermodes-0.14.3 → pyfibermodes-0.15.0}/docs/source/index.rst

@@ -17,6 +17,7 @@
     Theory <theory.rst>
     Architecture <architecture.rst>
     API policy <api_policy.rst>
+    Public API contract <public_api_contract.rst>
     Migration <migration_guide.rst>
     Workflows <workflows.rst>
     Performance <performance.rst>

{pyfibermodes-0.14.3 → pyfibermodes-0.15.0}/docs/source/migration_guide.rst

@@ -10,6 +10,21 @@ even though those modules are outside the stable public API.
 Unreleased
 ----------
 
+Mode validation and failure semantics
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``Mode`` now accepts either strings or ``Family`` members and normalizes the
+stored family to its string value. Radial order ``m`` must be at least one;
+invalid families and orders raise ``ValidationError`` instead of relying on
+Python assertions.
+
+Unsupported cutoff or normalized-parameter geometries raise
+``UnsupportedGeometryError``. Non-finite wavelength derivatives raise
+``ConvergenceError``. Structured solver methods continue to represent an
+unguided or unconverged mode with ``SolverResult(converged=False)``; scalar
+effective-index and cutoff conveniences continue to return ``NaN`` for that
+expected absence.
+
 Material loading
 ~~~~~~~~~~~~~~~~