PyFiberModes 0.17.7__tar.gz → 1.0.0__tar.gz

{pyfibermodes-0.17.7 → pyfibermodes-1.0.0}/.zenodo.json

@@ -9,7 +9,7 @@
   "license": "MIT",
   "upload_type": "software",
   "access_right": "open",
-  "version": "0.17.7",
+  "version": "1.0.0",
   "publication_date": "2026-10-23",
   "keywords": [
     "optical fibers",

{pyfibermodes-0.17.7 → pyfibermodes-1.0.0}/CHANGELOG.md

@@ -6,6 +6,10 @@ use [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [1.0.0] - 2026-10-23
+
+- Require TypedUnit/Pint quantities for physical inputs and return unit-bearing fiber, field, sweep, material, design and propagation results. Numerical solvers continue to operate in SI internally.
+
 ## [0.17.7] - 2026-10-23
 
 ## [0.17.6] - 2026-10-22
@@ -175,7 +179,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.17.7...HEAD
+[Unreleased]: https://github.com/MartinPdeS/PyFiberModes/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/MartinPdeS/PyFiberModes/releases/tag/v1.0.0
 [0.17.7]: https://github.com/MartinPdeS/PyFiberModes/releases/tag/v0.17.7
 [0.17.6]: https://github.com/MartinPdeS/PyFiberModes/releases/tag/v0.17.6
 [0.17.5]: https://github.com/MartinPdeS/PyFiberModes/releases/tag/v0.17.5

{pyfibermodes-0.17.7 → pyfibermodes-1.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyFiberModes
-Version: 0.17.7
+Version: 1.0.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
@@ -699,6 +699,8 @@ Requires-Python: >=3.11
 Description-Content-Type: text/x-rst
 License-File: LICENSE
 Requires-Dist: PyFinitDiff
+Requires-Dist: TypedUnit>=0.2.9
+Requires-Dist: pint<0.26,>=0.24
 Requires-Dist: pyyaml
 Requires-Dist: numpy
 Requires-Dist: scipy
@@ -818,22 +820,25 @@ First mode calculation
 ----------------------
 
 Load the bundled SMF-28 definition at 1550 nm and solve its fundamental LP
-mode. Lengths and wavelengths are expressed in SI units.
+mode. Physical inputs require Pint quantities; lengths may use any compatible unit.
+Results also carry units, using the shared TypedUnit registry as in PyMieSim.
 
 .. code-block:: python
 
+   from PyFiberModes.units import ureg
+
    from PyFiberModes import LP01
    from PyFiberModes.fiber import load_fiber
 
-   fiber = load_fiber("SMF28", wavelength=1550e-9)
+   fiber = load_fiber("SMF28", wavelength=1550e-9 * ureg.meter)
 
    effective_index = fiber.get_effective_index(LP01)
    propagation_constant = fiber.get_propagation_constant(LP01)
    dispersion = fiber.get_dispersion(LP01)
 
    print(f"n_eff = {effective_index:.9f}")
-   print(f"beta  = {propagation_constant:.6e} rad/m")
-   print(f"D     = {dispersion:.3f} ps/(nm km)")
+   print(f"beta  = {propagation_constant:.6e}")
+   print(f"D     = {dispersion:.3f}")
 
 ``load_fiber`` accepts the stem of any YAML definition in
 ``PyFiberModes/fiber_files``. A fiber can also be assembled programmatically
@@ -848,6 +853,8 @@ fiber index:
 
 .. code-block:: python
 
+   from PyFiberModes.units import ureg
+
    modes = fiber.find_modes(
        families=("LP",),
        max_nu=4,
@@ -869,9 +876,11 @@ values and whose columns correspond to modes.
 
 .. code-block:: python
 
+   from PyFiberModes.units import ureg
+
    import numpy as np
 
-   wavelengths = np.linspace(1260e-9, 1650e-9, 101)
+   wavelengths = np.linspace(1260e-9, 1650e-9, 101) * ureg.meter
    result = fiber.sweep(
        wavelengths,
        modes=modes,
@@ -892,16 +901,18 @@ Create a two-dimensional field grid from a solved mode:
 
 .. code-block:: python
 
+   from PyFiberModes.units import ureg
+
    field = fiber.get_mode_field(
        mode=LP01,
-       limit=20e-6,
+       limit=20e-6 * ureg.meter,
        n_point=201,
    )
 
    electric_x = field.Ex()
    intensity = field.Emod() ** 2
    effective_area = field.get_effective_area()
-   confinement = field.get_confinement_factor(radius=4.1e-6)
+   confinement = field.get_confinement_factor(radius=4.1e-6 * ureg.meter)
    power = field.get_power()
    sx, sy, sz = field.get_poynting_vector()
 
@@ -921,17 +932,19 @@ scalar value to minimize.
 
 .. code-block:: python
 
+   from PyFiberModes.units import ureg
+
    from PyFiberModes import DesignParameter, optimize_fiber
 
    core_radius = DesignParameter.layer_radius(
        layer=0,
-       bounds=(3.0e-6, 6.0e-6),
+       bounds=(3.0e-6 * ureg.meter, 6.0e-6 * ureg.meter),
    )
 
    design = optimize_fiber(
        fiber,
        parameters=[core_radius],
-       objective=lambda candidate: abs(candidate.get_dispersion(LP01)),
+       objective=lambda candidate: abs(candidate.get_dispersion(LP01).to("ps / nm / km").magnitude),
        constraints=(
            lambda candidate: candidate.get_effective_index(LP01)
            - candidate.last_layer.refractive_index,
@@ -956,10 +969,12 @@ electric field. Modal amplitudes then evolve according to
 
 .. code-block:: python
 
+   from PyFiberModes.units import ureg
+
    import numpy as np
    from PyFiberModes import CoupledModeSystem
 
-   multimode_fiber = load_fiber("test_multimode_fiber", wavelength=1550e-9)
+   multimode_fiber = load_fiber("test_multimode_fiber", wavelength=1550e-9 * ureg.meter)
    multimode_modes = multimode_fiber.find_modes(
        families=("LP",),
        max_nu=3,
@@ -968,16 +983,16 @@ electric field. Modal amplitudes then evolve according to
    selected_modes = multimode_modes[:2]
    fields = [multimode_fiber.get_mode_field(mode, n_point=151) for mode in selected_modes]
    betas = [multimode_fiber.get_propagation_constant(mode) for mode in selected_modes]
-   relative_betas = np.asarray(betas) - betas[0]
+   relative_betas = ureg.Quantity.from_list(betas) - betas[0]
    mode_overlap = fields[0].overlap(fields[1])
 
    coupling = np.array([
        [0.0, 0.25],
        [0.25, 0.0],
-   ])
+   ]) / ureg.meter
    system = CoupledModeSystem(betas=relative_betas, coupling=coupling)
 
-   z = np.linspace(0, 20, 500)
+   z = np.linspace(0, 20, 500) * ureg.meter
    propagation = system.propagate(initial=[1.0, 0.0], z=z)
    modal_power = propagation.powers
 

pyfibermodes-0.17.7/PyFiberModes/fiber.py → pyfibermodes-1.0.0/PyFiberModes/_fiber.py

@@ -12,7 +12,7 @@ from scipy.constants import c
 from PyFiberModes.stepindex import StepIndex
 from PyFiberModes import Mode
 from PyFinitDiff.finite_difference_1D import get_function_derivative
-from PyFiberModes.field import Field
+from PyFiberModes._field import Field
 
 from PyFiberModes.fundamentals import (
     get_radial_field,
@@ -20,7 +20,7 @@ from PyFiberModes.fundamentals import (
 )
 
 from PyFiberModes import loader
-from PyFiberModes.coordinates import CylindricalCoordinates
+from PyFiberModes._coordinates import CylindricalCoordinates
 from PyFiberModes.exceptions import ConvergenceError, ValidationError
 from PyFiberModes.materials import DEFAULT_MATERIALS, MaterialRegistry
 from PyFiberModes.services import FieldAnalysis, ModalAnalysis

pyfibermodes-0.17.7/PyFiberModes/field.py → pyfibermodes-1.0.0/PyFiberModes/_field.py

@@ -7,8 +7,8 @@ import numpy as np
 from PyFiberModes.mode_instances import HE11
 from PyFiberModes.mode import Mode
 from dataclasses import dataclass
-from PyFiberModes.coordinates import CartesianCoordinates
-from PyFiberModes.coordinates import CylindricalCoordinates as CylindricalCoordinates  # noqa: F401
+from PyFiberModes._coordinates import CartesianCoordinates
+from PyFiberModes._coordinates import CylindricalCoordinates as CylindricalCoordinates  # noqa: F401
 
 
 @dataclass

{pyfibermodes-0.17.7 → pyfibermodes-1.0.0}/PyFiberModes/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.17.7'
-__version_tuple__ = version_tuple = (0, 17, 7)
+__version__ = version = '1.0.0'
+__version_tuple__ = version_tuple = (1, 0, 0)
 
 __commit_id__ = commit_id = None

{pyfibermodes-0.17.7 → pyfibermodes-1.0.0}/PyFiberModes/analysis.py

@@ -8,6 +8,7 @@ import numpy as np
 
 from PyFiberModes.exceptions import ConvergenceError, ValidationError
 from PyFiberModes.mode import Mode
+from PyFiberModes.units import MODAL_UNITS, Quantity, magnitude, quantity
 
 
 @dataclass(frozen=True)
@@ -30,9 +31,9 @@ class ModeSweepResult:
     """
 
     parameter_name: str
-    parameters: np.ndarray
+    parameters: np.ndarray | Quantity
     modes: tuple[Mode, ...]
-    values: dict[str, np.ndarray]
+    values: dict[str, np.ndarray | Quantity]
 
     def __getitem__(self, metric: str) -> np.ndarray:
         """Return the array associated with a metric name.
@@ -74,9 +75,11 @@ class ModeSweepResult:
             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()
-            }}
+            {
+                self.parameter_name: parameter,
+                "mode": mode,
+                **{name: array[i, j] for name, array in self.values.items()},
+            }
             for i, parameter in enumerate(self.parameters)
             for j, mode in enumerate(self.modes)
         ]
@@ -137,11 +140,7 @@ def find_modes(fiber, families=("LP",), max_nu=6, max_m=6) -> tuple[Mode, ...]:
     for mode in candidate_modes(families, max_nu, max_m):
         try:
             effective_index = fiber.get_effective_index(mode)
-            guided = (
-                fiber.last_layer.refractive_index
-                < effective_index
-                <= fiber.maximum_index
-            )
+            guided = fiber.last_layer.refractive_index < effective_index <= fiber.maximum_index
             if np.isfinite(effective_index) and guided:
                 found.append(mode)
         except ConvergenceError:
@@ -167,8 +166,8 @@ def sweep_modes(
     ----------
     fiber : Fiber
         Fiber used as the immutable sweep template.
-    parameters : iterable of float
-        Ordered parameter values.
+    parameters : pint.Quantity or iterable of pint.Quantity
+        Ordered parameter values with explicit units for public fibers.
     modes : sequence of Mode, optional
         Modes to evaluate. When omitted, modes are discovered automatically.
     parameter_name : str, optional
@@ -195,7 +194,26 @@ def sweep_modes(
         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)
+    unit_aware = hasattr(fiber, "_si")
+    parameter_unit = None
+    if unit_aware:
+        if isinstance(parameters, Quantity):
+            parameter_unit = parameters.units
+            if setter is None:
+                magnitude(parameters, "meter", "parameters")
+            parameters = np.asarray(parameters.magnitude, dtype=float)
+        else:
+            items = tuple(parameters)
+            if not items:
+                raise ValueError("parameters must be a non-empty one-dimensional sequence")
+            parameter_unit = items[0].units if isinstance(items[0], Quantity) else "meter"
+            parameters = np.asarray(
+                [magnitude(item, parameter_unit, "parameters") for item in items], dtype=float
+            )
+            if setter is None:
+                quantity(parameters, parameter_unit).to("meter")
+    else:
+        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")
     if setter is None:
@@ -205,11 +223,14 @@ def sweep_modes(
         def setter(current_fiber, value):
             """Update wavelength for the default sweep behavior."""
             current_fiber.update_wavelength(value)
+
     if modes is None:
         discovered = []
         for parameter in parameters:
             parameter_fiber = deepcopy(fiber)
-            setter(parameter_fiber, float(parameter))
+            setter(
+                parameter_fiber, quantity(parameter, parameter_unit) if unit_aware else parameter
+            )
             for mode in find_modes(parameter_fiber, families, max_nu, max_m):
                 if mode not in discovered:
                     discovered.append(mode)
@@ -218,17 +239,22 @@ def sweep_modes(
     values = {metric: np.full((len(parameters), len(modes)), np.nan) for metric in metrics}
     parameter_fibers = tuple(deepcopy(fiber) for _ in parameters)
     for parameter_fiber, parameter in zip(parameter_fibers, parameters, strict=True):
-        setter(parameter_fiber, float(parameter))
+        setter(parameter_fiber, quantity(parameter, parameter_unit) if unit_aware else parameter)
 
     for i, parameter_fiber in enumerate(parameter_fibers):
-        metric_functions = {
-            metric: getattr(parameter_fiber, f"get_{metric}") for metric in metrics
-        }
+        metric_functions = {metric: getattr(parameter_fiber, f"get_{metric}") for metric in metrics}
         for metric, metric_function in metric_functions.items():
             for j, mode in enumerate(modes):
                 try:
                     value = metric_function(mode)
-                    values[metric][i, j] = value if np.isfinite(value) else np.nan
+                    values[metric][i, j] = (
+                        (value.to(MODAL_UNITS[metric]).magnitude if unit_aware else value)
+                        if np.isfinite(value)
+                        else np.nan
+                    )
                 except ConvergenceError:
                     pass
+    if unit_aware:
+        parameters = quantity(parameters, parameter_unit)
+        values = {metric: quantity(array, MODAL_UNITS[metric]) for metric, array in values.items()}
     return ModeSweepResult(parameter_name, parameters, modes, values)

pyfibermodes-1.0.0/PyFiberModes/coordinates.py

@@ -0,0 +1,153 @@
+"""Length-valued Cartesian and cylindrical coordinate grids."""
+
+from dataclasses import dataclass
+import numpy as np
+
+from PyFiberModes import _coordinates
+from PyFiberModes.units import Angle, Length, magnitude, quantity
+
+
+@dataclass
+class CylindricalCoordinates:
+    """Cylindrical positions with length-valued rho/z and angle-valued phi."""
+
+    rho: Length
+    phi: Angle
+    z: Length
+
+    def __post_init__(self):
+        """Validate and normalize coordinate quantities."""
+        self.rho = quantity(magnitude(self.rho, "meter", "rho"), "meter")
+        self.phi = quantity(magnitude(self.phi, "radian", "phi"), "radian")
+        self.z = quantity(magnitude(self.z, "meter", "z"), "meter")
+
+    def to_cartesian(self):
+        """Convert cylindrical positions to Cartesian positions."""
+        return CartesianCoordinates(
+            x=self.rho * np.cos(self.phi),
+            y=self.rho * np.sin(self.phi),
+            z=self.z,
+        )
+
+    def to_cylindrical(self):
+        """Return these cylindrical positions."""
+        return self
+
+
+@dataclass
+class CartesianCoordinates:
+    """Cartesian positions with explicit length units on every axis."""
+
+    x: Length
+    y: Length
+    z: Length
+    is_structured: bool = False
+    is_3D: bool = False
+
+    def __post_init__(self):
+        """Validate lengths and normalize numerical coordinate arrays to meters."""
+        for name in ("x", "y", "z"):
+            setattr(
+                self,
+                name,
+                quantity(
+                    np.asarray(magnitude(getattr(self, name), "meter", name), dtype=float), "meter"
+                ),
+            )
+
+    @classmethod
+    def _from_si(cls, coordinates):
+        """Attach length units to a numerical coordinate grid."""
+        return cls(
+            x=quantity(coordinates.x, "meter"),
+            y=quantity(coordinates.y, "meter"),
+            z=quantity(coordinates.z, "meter"),
+            is_structured=coordinates.is_structured,
+            is_3D=coordinates.is_3D,
+        )
+
+    @property
+    def x_boundaries(self):
+        """Minimum and maximum x positions."""
+        return self.x.min(), self.x.max()
+
+    @property
+    def y_boundaries(self):
+        """Minimum and maximum y positions."""
+        return self.y.min(), self.y.max()
+
+    @property
+    def dx(self):
+        """Structured grid spacing along x."""
+        if not self.is_structured:
+            raise ValueError("dx value cannot be inferred from an unstructured mesh")
+        return quantity(np.diff(np.unique(self.x.magnitude))[0], self.x.units)
+
+    @property
+    def dy(self):
+        """Structured grid spacing along y."""
+        if not self.is_structured:
+            raise ValueError("dy value cannot be inferred from an unstructured mesh")
+        return quantity(np.diff(np.unique(self.y.magnitude))[0], self.y.units)
+
+    @classmethod
+    def generate_from_square(cls, length: Length, center=None, n_points: int = 100):
+        """Generate a square grid with a length-valued side and center."""
+        center_si = (
+            (0.0, 0.0)
+            if center is None
+            else tuple(magnitude(item, "meter", "center") for item in center)
+        )
+        return cls._from_si(
+            _coordinates.CartesianCoordinates.generate_from_square(
+                length=magnitude(length, "meter", "length"),
+                center=center_si,
+                n_points=n_points,
+            )
+        )
+
+    @classmethod
+    def generate_from_boundaries(cls, x_limits, y_limits, z_limits, x_points, y_points, z_points):
+        """Generate a structured grid from length-valued axis limits."""
+        limits = [
+            tuple(magnitude(item, "meter", "limits") for item in axis)
+            for axis in (x_limits, y_limits, z_limits)
+        ]
+        return cls._from_si(
+            _coordinates.CartesianCoordinates.generate_from_boundaries(
+                x_limits=limits[0],
+                y_limits=limits[1],
+                z_limits=limits[2],
+                x_points=x_points,
+                y_points=y_points,
+                z_points=z_points,
+            )
+        )
+
+    def to_cylindrical(self):
+        """Convert positions to cylindrical coordinates."""
+        return CylindricalCoordinates(
+            rho=np.sqrt(self.x**2 + self.y**2),
+            phi=np.arctan2(self.y, self.x),
+            z=self.z,
+        )
+
+    def centering(self):
+        """Center each axis in place."""
+        self.x -= self.x.mean()
+        self.y -= self.y.mean()
+        self.z -= self.z.mean()
+
+    def shift_coordinates(self, shift):
+        """Shift the grid by three length-valued displacements."""
+        # Validate all inputs before mutating the grid.
+        values = [quantity(magnitude(item, "meter", "shift"), "meter") for item in shift]
+        self.x += values[0]
+        self.y += values[1]
+        self.z += values[2]
+
+    def scale_coordinates(self, scale):
+        """Scale axes by dimensionless factors."""
+        self.x *= float(scale[0])
+        self.y *= float(scale[1])
+        self.z *= float(scale[2])

{pyfibermodes-0.17.7 → pyfibermodes-1.0.0}/PyFiberModes/factory.py

@@ -4,6 +4,7 @@ from itertools import product
 from dataclasses import dataclass, field
 import numpy as np
 from PyFiberModes.fiber import Fiber
+from PyFiberModes.units import Length, RefractiveIndex, magnitude, quantity, ureg
 
 
 @dataclass
@@ -15,9 +16,9 @@ class ProxyLayer:
     ----------
     name : str
         Name of the layer.
-    radius : list[float]
+    radius : pint.Quantity
         Radius values for the layer (in meters).
-    index : list[float]
+    index : pint.Quantity
         Refractive index values for the layer.
     """
     name: str
@@ -27,8 +28,8 @@ class ProxyLayer:
     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)
+        self.radius = quantity(np.atleast_1d(magnitude(self.radius, "meter", "radius")), "meter")
+        self.index = quantity(np.atleast_1d(magnitude(self.index, "dimensionless", "index")), "dimensionless")
 
     def get_generator(self):
         """
@@ -48,40 +49,40 @@ class FiberFactory:
 
     Parameters
     ----------
-    wavelength : float
+    wavelength : TypedUnit.Length
         Wavelength (in meters) used for fiber simulations.
 
     Attributes
     ----------
     layers_list : list[ProxyLayer]
         List of ProxyLayer objects representing the layers of the fiber.
-    wavelength : float
+    wavelength : TypedUnit.Length
         Wavelength used in simulations.
     """
 
-    def __init__(self, wavelength: float):
+    def __init__(self, wavelength: Length):
         """Initialize an empty fiber-configuration factory.
 
         Parameters
         ----------
-        wavelength : float
+        wavelength : TypedUnit.Length
             Vacuum wavelength in meters for generated fibers.
         """
         self.layers_list = []
-        self.wavelength = wavelength
+        self.wavelength = quantity(magnitude(wavelength, "meter", "wavelength"), "meter")
 
-    def add_layer(self, index: float, name: str = "", radius: float = 0.0):
+    def add_layer(self, index: RefractiveIndex, name: str = "", radius: Length = np.inf * ureg.meter):
         """
         Add a new layer to the fiber factory.
 
         Parameters
         ----------
-        index : float
+        index : TypedUnit.RefractiveIndex
             Refractive index of the layer.
         name : str, optional
             Name of the layer (default is an empty string).
-        radius : float, optional
-            Radius of the layer (default is 0.0 meters).
+        radius : TypedUnit.Length, optional
+            Radius of the layer (defaults to an unbounded outer layer).
         """
         layer = ProxyLayer(name=name, radius=radius, index=index)
         self.layers_list.append(layer)