PyFiberModes 0.14.0__tar.gz → 0.14.2__tar.gz

{pyfibermodes-0.14.0 → pyfibermodes-0.14.2}/.zenodo.json

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

{pyfibermodes-0.14.0 → pyfibermodes-0.14.2}/CHANGELOG.md

@@ -6,6 +6,20 @@ use [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.14.2] - 2026-09-23
+
+### Changed
+
+- Rebuilt the documentation around a connected user guide covering units and
+  conventions, fiber and material definitions, mode selection, field
+  convergence, parameter sweeps, inverse design, coupled-mode propagation,
+  validation, and reproducibility.
+- Expanded the getting-started and theory pages with installation variants,
+  numerical checks, normalized propagation quantities, and guidance near
+  cutoff.
+
+## [0.14.1] - 2026-09-23
+
 ## [0.14.0] - 2026-09-23
 
 ### Added
@@ -101,7 +115,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.14.0...HEAD
+[Unreleased]: https://github.com/MartinPdeS/PyFiberModes/compare/v0.14.2...HEAD
+[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
 [0.14.0]: https://github.com/MartinPdeS/PyFiberModes/releases/tag/v0.14.0
 [0.13.2]: https://github.com/MartinPdeS/PyFiberModes/releases/tag/v0.13.2
 [0.13.1]: https://github.com/MartinPdeS/PyFiberModes/releases/tag/v0.13.1

{pyfibermodes-0.14.0 → pyfibermodes-0.14.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyFiberModes
-Version: 0.14.0
+Version: 0.14.2
 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.0 → pyfibermodes-0.14.2}/PyFiberModes/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.14.0'
-__version_tuple__ = version_tuple = (0, 14, 0)
+__version__ = version = '0.14.2'
+__version_tuple__ = version_tuple = (0, 14, 2)
 
 __commit_id__ = commit_id = None

{pyfibermodes-0.14.0 → pyfibermodes-0.14.2}/PyFiberModes/solver/two_layer/effective_index.py

@@ -515,14 +515,12 @@ class EffectiveIndexSolver(BaseSolver):
         return U, W, V
 
     def get_LP_equation(self, neff: float, nu: int) -> float:
-        """        Return the value of the phase matching equation for LP mode.
+        r"""Return the LP-mode characteristic equation residual.
 
-                .. math::
-                    U * j_{
-        u -1}(U) * k_{
-        u}(W) + W * j_{
-        u}(U) * k_{
-        u - 1}(W)
+        .. math::
+
+           U J_{\nu-1}(U) K_{\nu}(W)
+           + W J_{\nu}(U) K_{\nu-1}(W)
 
         Parameters
         ----------
@@ -534,7 +532,8 @@ class EffectiveIndexSolver(BaseSolver):
         Returns
         -------
         float
-            Dont know
+            Characteristic-equation residual; a mode solution occurs at a
+            root.
         """
         u, w, _ = self.get_U_W_V_parameter(neff=neff)
 

{pyfibermodes-0.14.0 → pyfibermodes-0.14.2}/PyFiberModes.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyFiberModes
-Version: 0.14.0
+Version: 0.14.2
 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.0 → pyfibermodes-0.14.2}/PyFiberModes.egg-info/SOURCES.txt

@@ -135,6 +135,13 @@ docs/source/code/analysis.rst
 docs/source/code/fibers.rst
 docs/source/code/fields.rst
 docs/source/code/fundamentals.rst
+docs/source/user_guide/fibers.rst
+docs/source/user_guide/fields.rst
+docs/source/user_guide/index.rst
+docs/source/user_guide/modes.rst
+docs/source/user_guide/reproducibility.rst
+docs/source/user_guide/sweeps.rst
+docs/source/user_guide/units.rst
 tests/__init__.py
 tests/api_snapshot.json
 tests/helpers.py

{pyfibermodes-0.14.0 → pyfibermodes-0.14.2}/conda.recipe/meta.yaml

@@ -1,6 +1,6 @@
 package:
   name: pyfibermodes
-  version: 0.14.0
+  version: 0.14.2
 
 source:
   path: ../

{pyfibermodes-0.14.0 → pyfibermodes-0.14.2}/docs/source/_static/default.css

@@ -37,3 +37,10 @@ div.highlight a {
 .bd-content img[alt="PyFiberModes logo"] {
   filter: drop-shadow(0 0.7rem 1rem rgb(20 217 255 / 20%));
 }
+
+/* Keep desktop navigation labels compact and on a single line. */
+@media (min-width: 960px) {
+  .bd-header .navbar-nav .nav-link {
+    white-space: nowrap;
+  }
+}

{pyfibermodes-0.14.0 → pyfibermodes-0.14.2}/docs/source/conf.py

@@ -99,6 +99,10 @@ language = "en"
 highlight_language = "python3"
 html_theme = "pydata_sphinx_theme"
 
+# ``sphinx_gallery_conf`` intentionally contains the ``reset_mpl`` callback,
+# which cannot be pickled into Sphinx's environment cache.
+suppress_warnings = ["config.cache"]
+
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 

pyfibermodes-0.14.2/docs/source/getting_started.rst

@@ -0,0 +1,69 @@
+Getting started
+===============
+
+PyFiberModes requires Python 3.11 or newer. Create an isolated environment,
+install the package from PyPI, and verify the interpreter that will run your
+analysis:
+
+.. code-block:: bash
+
+   python -m pip install PyFiberModes
+   python -c "import PyFiberModes; print(PyFiberModes.__version__)"
+
+Install the optional plotting dependency if you intend to render field maps:
+
+.. code-block:: bash
+
+   python -m pip install "PyFiberModes[plotting]"
+
+Your first guided mode
+----------------------
+
+Fiber dimensions and wavelengths use SI units. Load a bundled definition,
+solve the fundamental LP mode, and inspect its effective index:
+
+.. code-block:: python
+
+   from PyFiberModes import LP01
+   from PyFiberModes.fiber import load_fiber
+
+   fiber = load_fiber("SMF28", wavelength=1550e-9)
+   neff = fiber.get_effective_index(LP01)
+   field = fiber.get_mode_field(LP01, limit=15e-6, n_point=151)
+
+   print(neff)
+   print(field.get_effective_area())
+
+``LP01`` identifies the scalar fundamental mode. ``limit`` is the positive
+half-width of the square sampling window in metres, and ``n_point`` is the
+number of samples along each Cartesian axis.
+
+Check the result
+----------------
+
+A useful calculation includes a physical and a numerical check:
+
+.. code-block:: python
+
+   n_cladding = fiber.last_layer.refractive_index
+   n_core = fiber.maximum_index
+   assert n_cladding < neff < n_core
+
+   coarse = fiber.get_mode_field(LP01, limit=15e-6, n_point=151)
+   fine = fiber.get_mode_field(LP01, limit=20e-6, n_point=251)
+   relative_change = abs(
+       fine.get_effective_area() / coarse.get_effective_area() - 1
+   )
+   print(f"effective-area change: {relative_change:.2%}")
+
+Increase the window until the field decays before its boundary, then increase
+the resolution until the derived quantity changes less than the accuracy your
+application requires.
+
+Where to go next
+----------------
+
+Continue with :doc:`user_guide/fibers` to define a fiber,
+:doc:`user_guide/modes` to calculate modal properties, or
+:doc:`user_guide/fields` to analyze vector fields. Use :doc:`examples` for
+downloadable examples and :doc:`code` for the complete API.

pyfibermodes-0.14.2/docs/source/index.rst

@@ -0,0 +1,57 @@
+**Date**: |today|, **Version**: |version|
+
+.. image:: _static/logo.png
+   :width: 620
+   :align: center
+   :alt: PyFiberModes logo
+
+.. include:: ../../README.rst
+    :start-line: 5
+
+.. toctree::
+    :maxdepth: 2
+    :hidden:
+
+    Getting started <getting_started.rst>
+    User guide <user_guide/index.rst>
+    Theory <theory.rst>
+    Architecture <architecture.rst>
+    API policy <api_policy.rst>
+    Migration <migration_guide.rst>
+    Workflows <workflows.rst>
+    Performance <performance.rst>
+    Troubleshooting <troubleshooting.rst>
+    Examples <examples.rst>
+    API reference <code.rst>
+    References <references.rst>
+
+Choose your path
+----------------
+
+.. grid:: 3
+   :gutter: 2
+
+   .. grid-item-card:: New to PyFiberModes?
+      :link: getting_started
+      :link-type: doc
+
+      Install the package and complete a guided mode calculation in a few
+      minutes.
+
+   .. grid-item-card:: Solving a real problem?
+      :link: user_guide/index
+      :link-type: doc
+
+      Follow task-oriented guides for fiber models, modal properties, fields,
+      sweeps, optimization, and propagation.
+
+   .. grid-item-card:: Looking up an object?
+      :link: code
+      :link-type: doc
+
+      Browse the generated API reference, signatures, and source links.
+
+PyFiberModes uses SI units throughout. Wavelengths and radii are in metres,
+propagation constants are in radians per metre, and the dispersion helper
+returns ps/(nm km). See :doc:`user_guide/units` for a complete conventions
+table.

{pyfibermodes-0.14.0 → pyfibermodes-0.14.2}/docs/source/theory.rst

@@ -13,6 +13,16 @@ Mode families
 vector modes, while ``TE`` and ``TM`` are the transverse families. A mode is
 identified by its family, azimuthal order ``nu``, and radial order ``m``.
 
+The effective index and propagation constant are related by
+
+.. math::
+
+   \beta = k_0 n_\mathrm{eff}, \qquad k_0 = \frac{2\pi}{\lambda}.
+
+Under weak guidance, a vector-mode group may be represented by one LP mode.
+LP labels are consequently an approximation and not an additional independent
+set of physical solutions alongside HE, EH, TE, and TM labels.
+
 Normalized frequency
 --------------------
 
@@ -25,6 +35,26 @@ For a two-layer fiber, the normalized frequency is
 where :math:`a` is the core radius and :math:`k_0=2\pi/\lambda`. Guided
 solutions satisfy :math:`n_\mathrm{clad} < n_\mathrm{eff} < n_\mathrm{core}`.
 
+The normalized propagation constant is commonly written
+
+.. math::
+
+   b = \frac{n_\mathrm{eff}^2-n_\mathrm{clad}^2}
+            {n_\mathrm{core}^2-n_\mathrm{clad}^2},
+
+so guided two-layer solutions lie between zero and one. Multilayer fibers use
+the actual ordered interfaces and do not in general reduce to a single
+core-cladding :math:`V` value.
+
+Wavelength derivatives
+----------------------
+
+Group index, group-velocity dispersion, chromatic dispersion, and dispersion
+slope depend on numerical derivatives of the solved propagation constant.
+They are less robust than a single effective-index evaluation near cutoff or
+an avoided crossing. Validate them by changing the wavelength sampling and by
+checking that the same modal branch is followed.
+
 Field normalization
 -------------------
 

pyfibermodes-0.14.2/docs/source/user_guide/fibers.rst

@@ -0,0 +1,78 @@
+Defining fibers and materials
+=============================
+
+Bundled definitions
+-------------------
+
+The simplest route is :func:`~PyFiberModes.fiber.load_fiber`. Pass a bundled
+YAML filename without its extension and always provide the wavelength when a
+layer uses a dispersive material:
+
+.. code-block:: python
+
+   from PyFiberModes import load_fiber
+
+   fiber = load_fiber("SMF28", wavelength=1.55e-6)
+   for layer in fiber.layers:
+       print(layer.name, layer.radius_in, layer.radius_out, layer.refractive_index)
+
+The bundled catalog lives in ``PyFiberModes/fiber_files``. Definitions may use
+an explicit ``index``, a registered ``material``, or a numerical aperture
+relative to the adjacent outer layer. A compact two-layer definition is:
+
+.. code-block:: yaml
+
+   # Layers are listed from outside to inside.
+   layers:
+     cladding:
+       name: cladding
+       radius: 62.5e-6
+       material: fused_silica
+     core:
+       name: core
+       radius: 4.1e-6
+       NA: 0.14
+
+Custom material models
+----------------------
+
+Use :class:`~PyFiberModes.materials.MaterialRegistry` when a definition names a
+material that is not built in. A model can be any callable receiving wavelength
+in metres and returning refractive index:
+
+.. code-block:: python
+
+   from PyFiberModes import MaterialRegistry, load_fiber
+
+   materials = MaterialRegistry({
+       "my_glass": lambda wavelength: 1.46 - 0.003 * (wavelength / 1e-6 - 1.0),
+   })
+   fiber = load_fiber("my_fiber", wavelength=1.55e-6, materials=materials)
+
+Programmatic construction
+--------------------------
+
+For a single structure, create a :class:`~PyFiberModes.fiber.Fiber`, add layers
+from the center outward, and initialize it once all interfaces are defined:
+
+.. code-block:: python
+
+   from PyFiberModes import Fiber
+
+   fiber = Fiber(wavelength=1.55e-6)
+   fiber.add_layer(name="core", radius=4.1e-6, index=1.450)
+   fiber.add_layer(name="cladding", radius=62.5e-6, index=1.444)
+   fiber.initialize_layers()
+
+Use :class:`~PyFiberModes.factory.FiberFactory` when radii or indices are
+iterables and you want the Cartesian product of several designs.
+
+Mutation and caches
+-------------------
+
+Call :meth:`~PyFiberModes.fiber.Fiber.update_wavelength` when changing
+wavelength; it updates dependent state and clears cached modal and radial-field
+solutions. After directly changing a layer radius or refractive index, call
+:meth:`~PyFiberModes.fiber.Fiber.clear_caches`. Prefer
+:meth:`~PyFiberModes.fiber.Fiber.sweep` or the optimization helpers for repeated
+calculations because they work on copies and keep the input fiber unchanged.

pyfibermodes-0.14.2/docs/source/user_guide/fields.rst

@@ -0,0 +1,71 @@
+Fields, power, and overlap
+==========================
+
+Sampling a field
+----------------
+
+A :class:`~PyFiberModes.field.Field` samples an analytical radial solution on a
+square Cartesian grid:
+
+.. code-block:: python
+
+   from PyFiberModes import LP01, load_fiber
+
+   fiber = load_fiber("SMF28", wavelength=1.55e-6)
+   field = fiber.get_mode_field(LP01, limit=20e-6, n_point=251)
+   components = field.get_components(("Ex", "Ey", "Ez", "Hx", "Hy", "Hz"))
+
+Use an odd ``n_point`` to include the fiber axis. ``limit`` is the positive
+half-width, so the full domain is twice that value. Request related components
+together with ``get_components`` and reuse the same ``Field`` instance; radial
+solutions and interpolated arrays are cached.
+
+Derived quantities
+------------------
+
+.. code-block:: python
+
+   area_um2 = field.get_effective_area() * 1e12
+   core_fraction = field.get_confinement_factor(radius=4.1e-6)
+   sx, sy, sz = field.get_poynting_vector()
+   guided_power = field.get_power()
+
+Field amplitudes represent modal shapes rather than a launched absolute power.
+Normalized overlap and confinement are therefore usually more portable than
+raw amplitudes. Power-like integrals depend on the sampled window and grid.
+
+Convergence procedure
+---------------------
+
+For any reported field integral:
+
+#. Increase ``limit`` until the field is negligible at all four boundaries.
+#. Hold that window fixed and increase ``n_point``.
+#. Compare the final quantity, not only the image, between refinements.
+#. Apply the same grid to both fields in an overlap calculation.
+
+A smooth-looking plot can still have a biased integral if the domain clips the
+evanescent tail. Near a material interface, resolution must also be sufficient
+to represent the discontinuity.
+
+Overlap and coupling
+--------------------
+
+The convenience method ``field_a.overlap(field_b)`` returns normalized complex
+electric-field overlap. The standalone :func:`~PyFiberModes.propagation.overlap`
+also supports an unnormalized result. Both fields must have identical grid
+shapes and spacing. :func:`~PyFiberModes.propagation.coupling_matrix` constructs
+a Hermitian matrix from several fields and accepts an optional scalar or
+sampled spatial perturbation.
+
+Plotting
+--------
+
+Install the ``plotting`` extra, then render one or more named components:
+
+.. code-block:: python
+
+   figure = field.plot(plot_type=["Ex", "Ey", "Emod"], show=False)
+   figure.savefig("mode-field.png", dpi=200, bbox_inches="tight")
+
+Use ``show=False`` in scripts, tests, and headless environments.

pyfibermodes-0.14.2/docs/source/user_guide/index.rst

@@ -0,0 +1,24 @@
+User guide
+==========
+
+This guide connects the short examples to the complete API reference. It
+follows the lifecycle of a fiber calculation: define the structure, choose and
+solve modes, validate sampled fields, explore parameters, and preserve enough
+context to reproduce the result.
+
+.. toctree::
+   :maxdepth: 2
+
+   units
+   fibers
+   modes
+   fields
+   sweeps
+   reproducibility
+
+The package is designed for circularly symmetric, concentric step-index
+structures. It is not a general-purpose solver for non-circular cores,
+longitudinally varying cross-sections, stress birefringence, or arbitrary
+anisotropic materials. Those cases require a numerical full-vector solver;
+PyFiberModes can still provide reference solutions or input modes for a larger
+workflow.

pyfibermodes-0.14.2/docs/source/user_guide/modes.rst

@@ -0,0 +1,70 @@
+Modes and modal properties
+==========================
+
+Choosing a family
+-----------------
+
+LP modes are appropriate for weakly guiding fibers, where the refractive-index
+contrast is small and a scalar description is sufficient. HE, EH, TE, and TM
+modes retain the vector family structure and are the better choice for higher
+contrast or when longitudinal field components matter.
+
+Create arbitrary identifiers with :class:`~PyFiberModes.mode.Mode`, or import
+common instances from the package root:
+
+.. code-block:: python
+
+   from PyFiberModes import HE11, LP01, Mode
+
+   lp21 = Mode("LP", nu=2, m=1)
+   assert LP01.nu == 0
+
+Solving one mode
+----------------
+
+The effective index is the central solved quantity. Other longitudinal modal
+properties derive from it and its wavelength dependence:
+
+.. code-block:: python
+
+   from PyFiberModes import LP01, load_fiber
+
+   fiber = load_fiber("SMF28", wavelength=1.55e-6)
+   values = {
+       "effective index": fiber.get_effective_index(LP01),
+       "propagation constant": fiber.get_propagation_constant(LP01),
+       "group index": fiber.get_group_index(LP01),
+       "dispersion": fiber.get_dispersion(LP01),
+   }
+
+A guided solution should have an effective index between the exterior index
+and the largest layer index. Close to cutoff, repeat the calculation at nearby
+wavelengths because derivative-based group and dispersion quantities become
+sensitive to step size and a mode may disappear.
+
+Discovering supported modes
+---------------------------
+
+Use :meth:`~PyFiberModes.fiber.Fiber.find_modes` when the supported set is not
+known in advance:
+
+.. code-block:: python
+
+   modes = fiber.find_modes(families=("LP",), max_nu=4, max_m=3)
+   for mode in modes:
+       print(mode, fiber.get_effective_index(mode))
+
+The bounds describe candidate orders, not the number of returned modes. Keep
+them close to the physical range of interest: every candidate requires a root
+search. Search scalar and vector families separately to avoid interpreting two
+representations of the same weak-guidance mode as independent solutions.
+
+Cutoff and normalized quantities
+--------------------------------
+
+For two-layer fibers, :meth:`~PyFiberModes.fiber.Fiber.V_number` describes the
+normalized frequency and :meth:`~PyFiberModes.fiber.Fiber.get_normalized_beta`
+places the propagation constant between the core and cladding limits.
+``get_mode_cutoff_v0`` and ``get_mode_cutoff_wavelength`` expose the analytical
+cutoff supported by the applicable solver. See :doc:`../theory` for equations
+and assumptions.

pyfibermodes-0.14.2/docs/source/user_guide/reproducibility.rst

@@ -0,0 +1,53 @@
+Validation and reproducibility
+==============================
+
+Numerical output is most useful when its assumptions can be reconstructed.
+Record the following with published or shared results:
+
+* the exact PyFiberModes version and Python version;
+* the fiber YAML file or every layer radius, index, and material model;
+* vacuum wavelength and selected mode family and orders;
+* field window, grid resolution, and polarization angles;
+* sweep spacing or derivative settings near cutoff;
+* optimization method, bounds, constraints, seed, and termination message.
+
+Minimum validation checklist
+----------------------------
+
+#. Confirm ``n_cladding < n_effective <= n_max`` for every guided mode.
+#. Repeat field integrals with a larger window and a finer grid.
+#. Repeat derivative-based quantities with a different wavelength sampling.
+#. Check expected limiting behavior, symmetry, and conservation laws.
+#. Compare a simple two-layer case with an analytical reference before using a
+   complicated multilayer structure.
+
+Failure handling
+----------------
+
+Automatic discovery and sweeps represent unavailable modes with omission or
+``NaN`` so that a broad exploration can continue. A single requested mode may
+instead raise :class:`~PyFiberModes.exceptions.SolverError` or
+:class:`~PyFiberModes.exceptions.ConvergenceError`. Catch these specific
+exceptions only when a missing point is an expected outcome:
+
+.. code-block:: python
+
+   import numpy as np
+   from PyFiberModes import ConvergenceError, SolverError
+
+   try:
+       effective_index = fiber.get_effective_index(mode)
+   except (SolverError, ConvergenceError):
+       effective_index = np.nan
+
+Do not replace all exceptions with ``NaN``: invalid geometry, units, or array
+shapes should remain visible and be corrected.
+
+Archiving results
+-----------------
+
+``ModeSweepResult.as_records`` produces plain row-oriented dictionaries useful
+for CSV or dataframe export. Preserve the original parameter array as well as
+the records, and save configuration and environment metadata beside numerical
+data. Cite the software using :doc:`../references` and use a tagged release,
+not a moving branch, when preparing long-lived results.