solprop 0.1.0__py3-none-any.whl

solprop/__init__.py

@@ -0,0 +1,121 @@
+# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Ultrafast nonlinear pulse propagation.
+
+solprop models ultrafast pulse propagation with the unidirectional pulse propagation
+equation (UPPE) and the generalised nonlinear Schrödinger equation (GNLSE), for the full
+electric field or a complex envelope, in one mode, in many modes of a waveguide and
+in radial or Cartesian free space. The design is described under ``docs/dev/`` and the
+manual under ``docs/``.
+
+The package installs a :class:`logging.NullHandler`; call
+:func:`solprop.log.configure_logging` from a script to see progress and diagnostics.
+
+Every submodule is an attribute of the package -- ``solprop.grid``, ``solprop.driver``,
+``solprop.plotting`` -- loaded on first access (:pep:`562`), so ``dir(solprop)`` and tab
+completion list them while ``import solprop`` stays within its import-time budget: the
+modules that pull in h5py, matplotlib or a compiled backend are not imported until they
+are used.
+"""
+
+import importlib
+import logging
+from importlib.metadata import PackageNotFoundError, version
+from types import ModuleType
+from typing import Final
+
+# The scheduler's CPU grant, read before any OpenMP runtime binds the main thread.
+import solprop._process  # noqa: F401  # pyright: ignore[reportUnusedImport]
+from solprop.exceptions import SolpropError
+from solprop.log import configure_logging
+
+__all__ = ["SolpropError", "__version__", "configure_logging"]
+
+_SUBMODULES: Final = (
+    "adiabatic",
+    "backends",
+    "boundaries",
+    "constants",
+    "coupling",
+    "driver",
+    "exceptions",
+    "fourier",
+    "gasflow",
+    "grid",
+    "hankel",
+    "linear",
+    "log",
+    "modes",
+    "monitor",
+    "noise",
+    "nonlinear",
+    "optics",
+    "output",
+    "physdata",
+    "plotting",
+    "polarisation",
+    "processing",
+    "profiles",
+    "pulses",
+    "scan",
+    "sol",
+    "spatial",
+    "stats",
+    "stepper",
+    "tools",
+    "translate",
+)
+"""The submodules reachable as attributes; a test keeps it equal to what is on disk."""
+
+
+def __getattr__(name: str) -> ModuleType:
+    """Import a submodule the first time it is asked for as an attribute.
+
+    Parameters
+    ----------
+    name : str
+        The attribute looked up on the package.
+
+    Returns
+    -------
+    types.ModuleType
+        The submodule, imported now and cached by the import system.
+
+    Raises
+    ------
+    AttributeError
+        If `name` is not a submodule of the package.
+    """
+    if name in _SUBMODULES:
+        return importlib.import_module(f"{__name__}.{name}")
+    msg = f"module {__name__!r} has no attribute {name!r}"
+    raise AttributeError(msg)
+
+
+def __dir__() -> list[str]:
+    """List the package's public surface, the submodules included whether or not loaded.
+
+    The names in ``__all__``, the submodules and the dunders; not the imports this
+    module happens to make, which are implementation and not part of the package.
+
+    Returns
+    -------
+    list of str
+        The sorted names ``dir`` and tab completion show.
+    """
+    names = {*globals(), *_SUBMODULES}
+    return sorted(
+        name
+        for name in names
+        if name.startswith("__") or name in __all__ or name in _SUBMODULES
+    )
+
+
+try:
+    __version__ = version("solprop")
+except PackageNotFoundError:  # pragma: no cover - only when run from a source checkout
+    __version__ = "0.0.0"
+
+logging.getLogger(__name__).addHandler(logging.NullHandler())

solprop/_display.py

@@ -0,0 +1,361 @@
+# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Format objects for a person reading them at a prompt.
+
+The package's printing rule, in one place: ``repr(x)`` is one line and never holds an
+array, so that it is safe in a log record or an error message; ``str(x)`` is a short
+aligned block in the units people quote (nm, fs, uJ, um, bar); and IPython and Jupyter
+show that block when the object is the last expression of a cell, through
+:meth:`Displayed._repr_pretty_`.
+
+Printing never evaluates physics, never warns and never touches a file it does not
+already own: a block is built from numbers the object already holds.
+
+This module imports nothing from the rest of the package, and NumPy only where an array
+is actually summarised, so that any module may use it.
+"""
+
+import math
+import textwrap
+from collections.abc import Iterable, Sequence
+from typing import Protocol, runtime_checkable
+
+__all__ = [
+    "Displayed",
+    "block",
+    "engineering",
+    "line",
+    "phase_text",
+    "summarise",
+    "tail",
+]
+
+_PREFIXES = {
+    -18: "a",
+    -15: "f",
+    -12: "p",
+    -9: "n",
+    -6: "u",
+    -3: "m",
+    0: "",
+    3: "k",
+    6: "M",
+    9: "G",
+    12: "T",
+    15: "P",
+    18: "E",
+}
+"""SI prefixes by decimal exponent. ``u`` stands for micro: the package's text is ASCII
+wherever a terminal, a log file or an HDF5 attribute may have to carry it."""
+
+_WIDTH = 88
+"""Longest line of a block, the package's line length."""
+
+_WRAPPED = 4
+"""Most lines a wrapped value takes in a block; a longer one ends with an ellipsis."""
+
+
+@runtime_checkable
+class _Printer(Protocol):
+    """The part of IPython's pretty printer that :class:`Displayed` uses."""
+
+    def text(self, value: str) -> None:
+        """Write text.
+
+        Parameters
+        ----------
+        value : str
+            The text.
+        """
+        ...
+
+
+def engineering(value: float | None, unit: str = "", digits: int = 4) -> str:
+    """Return a number with an SI prefix, as a person would write it.
+
+    Parameters
+    ----------
+    value : float or None
+        The number, in the SI unit named by `unit`.
+    unit : str, optional
+        The unit's symbol, without a prefix: ``"m"``, ``"s"``, ``"J"``, ``"W"``.
+        With an empty unit no prefix is used and the number is written plainly.
+    digits : int, optional
+        Significant figures.
+
+    Returns
+    -------
+    str
+        For example ``"800 nm"``, ``"30 fs"``, ``"1.5 m"``; ``"none"`` for ``None``
+        and ``"nan"``, ``"inf"`` or ``"-inf"`` for a value that is not finite.
+
+    Examples
+    --------
+    >>> from solprop._display import engineering
+    >>> engineering(800e-9, "m"), engineering(1.5, "m"), engineering(275e-6, "J")
+    ('800 nm', '1.5 m', '275 uJ')
+    >>> engineering(float("nan"), "s"), engineering(None, "s"), engineering(0.0, "W")
+    ('nan', 'none', '0 W')
+    """
+    if value is None:
+        return "none"
+    number = float(value)
+    if not math.isfinite(number):
+        return str(number)
+    if not unit:
+        return f"{number:.{digits}g}"
+    if number == 0.0:
+        return f"0 {unit}"
+    exponent = 3 * math.floor(math.log10(abs(number)) / 3.0)
+    exponent = min(max(exponent, min(_PREFIXES)), max(_PREFIXES))
+    scaled = number / 10.0**exponent
+    # Rounding to the requested figures can carry 999.96 over to 1000.
+    if abs(float(f"{scaled:.{digits}g}")) >= 1000.0 and exponent < max(_PREFIXES):
+        exponent += 3
+        scaled = number / 10.0**exponent
+    return f"{scaled:.{digits}g} {_PREFIXES[exponent]}{unit}"
+
+
+def summarise(values: object, unit: str = "") -> str:
+    """Return a one-phrase summary of an array, never its contents.
+
+    Parameters
+    ----------
+    values : array_like
+        The array.
+    unit : str, optional
+        SI unit of the values, for the range; empty to give the shape alone.
+
+    Returns
+    -------
+    str
+        For example ``"<201 values, 0 m to 1.5 m>"`` or ``"<2x1x8192 complex>"``.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from solprop._display import summarise
+    >>> summarise(np.linspace(0.0, 1.5, 201), "m")
+    '<201 values, 0 m to 1.5 m>'
+    >>> summarise(np.zeros((2, 1, 8), dtype=complex))
+    '<2x1x8 complex>'
+    """
+    import numpy as np  # noqa: PLC0415 - kept out of the import of modules that only format scalars
+
+    array = np.asarray(values)
+    if array.ndim != 1 or not unit or array.size == 0 or np.iscomplexobj(array):
+        shape = "x".join(str(size) for size in array.shape) or "scalar"
+        kind = "complex" if np.iscomplexobj(array) else "values"
+        return f"<{shape} {kind}>"
+    low, high = float(np.min(array)), float(np.max(array))
+    return (
+        f"<{array.size} values, {engineering(low, unit)} to {engineering(high, unit)}>"
+    )
+
+
+_PHASE_NAMES = ("CEP", "delay", "GDD", "TOD", "FOD")
+"""What the first Taylor coefficients of a spectral phase are called."""
+
+
+def phase_text(coefficients: Iterable[float]) -> str:
+    """Return Taylor spectral-phase coefficients as people quote them.
+
+    Parameters
+    ----------
+    coefficients : iterable of float
+        ``c_0, c_1, ...`` in ``s**n``; a tuple or an array.
+
+    Returns
+    -------
+    str
+        For example ``"CEP 0.3 rad, GDD 250 fs^2"``: zero coefficients are left out,
+        order ``n`` is in ``fs^n``, and ``"none"`` stands for no phase at all.
+
+    Examples
+    --------
+    >>> from solprop._display import phase_text
+    >>> phase_text((0.3, 0.0, 250e-30, -4000e-45))
+    'CEP 0.3 rad, GDD 250 fs^2, TOD -4000 fs^3'
+    >>> phase_text(())
+    'none'
+    """
+    parts = []
+    for order, value in enumerate(coefficients):
+        if float(value) == 0.0:
+            continue
+        name = _PHASE_NAMES[order] if order < len(_PHASE_NAMES) else f"order {order}"
+        unit = "rad" if order == 0 else ("fs" if order == 1 else f"fs^{order}")
+        parts.append(f"{name} {float(value) * 1e15**order:.4g} {unit}")
+    return ", ".join(parts) or "none"
+
+
+def tail(text: str, width: int = 68) -> str:
+    """Return the end of a long text, which for a path is the part that matters.
+
+    Parameters
+    ----------
+    text : str
+        The text, typically a file path.
+    width : int, optional
+        Longest result, in characters.
+
+    Returns
+    -------
+    str
+        The text itself, or an ellipsis and its last ``width - 3`` characters.
+
+    Examples
+    --------
+    >>> from solprop._display import tail
+    >>> tail("/a/very/long/path/to/run.h5", 12)
+    '...to/run.h5'
+    """
+    return text if len(text) <= width else "..." + text[-(width - 3) :]
+
+
+def line(name: str, fields: Iterable[tuple[str, object]]) -> str:
+    """Return a one-line ``Name(key=value, ...)`` description.
+
+    Parameters
+    ----------
+    name : str
+        The class name.
+    fields : iterable of tuple
+        ``(key, value)`` pairs; a value is written with ``str``, and a pair whose key
+        is empty is written as the value alone.
+
+    Returns
+    -------
+    str
+        The line.
+
+    Examples
+    --------
+    >>> from solprop._display import line
+    >>> line("Grid", [("n_t", 8192), ("", "field")])
+    'Grid(n_t=8192, field)'
+    """
+    parts = [f"{key}={value}" if key else str(value) for key, value in fields]
+    return f"{name}({', '.join(parts)})"
+
+
+def block(title: str, rows: Sequence[tuple[str, object]]) -> str:
+    """Return an aligned multi-line description.
+
+    Parameters
+    ----------
+    title : str
+        The first line: the class and its headline.
+    rows : sequence of tuple
+        ``(key, value)`` pairs, one line each. A value holding newlines is indented
+        under its key; a line longer than the package's 88 columns is wrapped at a
+        space, its continuation indented under its value, over at most four lines,
+        and what is left over, or a single word too long for a line, is cut with an
+        ellipsis, so that a block is always safe to paste into a page.
+
+    Returns
+    -------
+    str
+        The block, without a trailing newline.
+
+    Examples
+    --------
+    >>> from solprop._display import block
+    >>> print(block("Pulse", [("energy", "275 uJ"), ("duration", "7.5 fs")]))
+    Pulse
+      energy:   275 uJ
+      duration: 7.5 fs
+    """
+    width = max((len(key) for key, _ in rows), default=0) + 1
+    under = " " * (width + 3)
+    # A long title continues deeper than the rows, so it cannot be read as one.
+    lines = _fitted("", title, "    ")
+    for key, value in rows:
+        first, *rest = str(value).split("\n")
+        lines.extend(_fitted(f"  {key + ':':<{width}} ", first, under))
+        for extra in rest:
+            deeper = extra[: len(extra) - len(extra.lstrip())]
+            lines.extend(_fitted(under + deeper, extra.lstrip(), under + deeper))
+    return "\n".join(lines)
+
+
+def _fitted(lead: str, value: str, indent: str) -> list[str]:
+    """Return one line of a block within the package's width.
+
+    Parameters
+    ----------
+    lead : str
+        What precedes the value on its first line: the key's column, or the
+        indentation of a continuation.
+    value : str
+        The text, wrapped at its spaces when the line is too long.
+    indent : str
+        The indentation of each wrapped continuation, under the value.
+
+    Returns
+    -------
+    list of str
+        The line or its wrapped pieces, at most :data:`_WRAPPED` of them; the last
+        kept piece of a longer value, and a piece holding a single word too long for
+        the width, end with an ellipsis.
+    """
+    if len(lead) + len(value) <= _WIDTH:
+        return [lead + value]
+    pieces = textwrap.wrap(
+        value,
+        _WIDTH,
+        initial_indent=lead,
+        subsequent_indent=indent,
+        break_long_words=False,
+        break_on_hyphens=False,
+    ) or [lead]
+    if len(pieces) > _WRAPPED:
+        pieces = [*pieces[: _WRAPPED - 1], pieces[_WRAPPED - 1][: _WIDTH - 4] + " ..."]
+    return [
+        piece if len(piece) <= _WIDTH else piece[: _WIDTH - 3] + "..."
+        for piece in pieces
+    ]
+
+
+class Displayed:
+    """Give a class the package's printing: a block for ``str`` and for IPython.
+
+    A class provides ``_describe()`` returning its title and its rows, and its own
+    one-line ``__repr__``; this mixin turns the first into ``__str__`` and into the
+    text IPython and Jupyter show for the last expression of a cell. The plain Python
+    prompt, log records and error messages keep the one-line ``repr``.
+    """
+
+    def _describe(self) -> tuple[str, Sequence[tuple[str, object]]]:
+        """Return the title and the rows of the block.
+
+        Returns
+        -------
+        tuple
+            The first line, and ``(key, value)`` pairs for the rest.
+        """
+        return repr(self), ()
+
+    def __str__(self) -> str:
+        """Return the aligned block.
+
+        Returns
+        -------
+        str
+            The title and one line per row.
+        """
+        return block(*self._describe())
+
+    def _repr_pretty_(self, printer: _Printer, cycle: bool) -> None:
+        """Write the block for IPython's pretty printer.
+
+        Parameters
+        ----------
+        printer : object
+            IPython's printer.
+        cycle : bool
+            Whether the object was met again while printing itself.
+        """
+        printer.text(repr(self) if cycle else str(self))

solprop/_helpers.py

@@ -0,0 +1,223 @@
+# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""The evaluations a backend supplies to solprop's shared per-stage and per-step code.
+
+Two small scalar computations run on every backend's path: a scalar table's Chebyshev
+rows at a step's positions (behind every stage bundle and anchor, and an expansion's
+rate rows; :meth:`solprop.translate.chebyshev.PiecewiseChebyshev.at_positions`) and
+the Lagrange basis of an Adams formula on its actual nodes
+(:func:`solprop.stepper.multistep.integrated_weights` and
+:func:`~solprop.stepper.multistep.lagrange_coefficients`). The code around them is
+shared, but **which implementation evaluates them belongs to the backend that runs the
+stage** (SEP 29 section 6.6, R16), never to a process-wide switch or to what happens
+to be installed: the NumPy reference must not run compiled code it exists to check,
+and one simulation must not change another's arithmetic.
+
+A backend names its record in ``StepDriver.helpers`` and the shared driver, march and
+engines pass it down: ``numpy_ref`` takes :data:`PLAIN`, the uncompiled Python forms;
+``numba_cpu`` takes :data:`NUMBA`, the same functions compiled; the native backend
+takes its own record of C++ bindings, defined in its package. All three perform the
+same IEEE operations in the same order, strict (no contraction, no reassociation;
+SEP 25 section 4.2), so they agree to the last bit wherever their arithmetic is IEEE.
+A record may also form a whole exponential Adams trial's coefficient tables in one
+call (:attr:`Helpers.tables`), the composition of
+:func:`solprop.backends.multistep.trial_tables` over its own basis, which its
+resident engine reads every trial; the others compose them from the basis.
+
+Translation is not a backend's: it runs before any backend exists and builds the
+problem every backend receives, so it keeps the shared reference compiled by Numba
+(:func:`solprop.translate.chebyshev.clenshaw`, and a table called without a record),
+and the shared functions' defaults are :data:`NUMBA` for callers outside a backend. A
+z table's state-sized evaluation is not a stage scalar and stays on that shared pass.
+
+Like ``_display`` and ``_numba_cache``, this module imports nothing from the rest of
+the package at import time, so any layer may use it; each record imports its
+functions from where they live at the first evaluation.
+"""
+
+import functools
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+import numpy as np
+
+__all__ = [
+    "NUMBA",
+    "PLAIN",
+    "BasisFunction",
+    "Helpers",
+    "PointsFunction",
+    "TablesFunction",
+]
+
+PointsFunction = Callable[
+    [np.ndarray, np.ndarray, float, float, np.ndarray, np.ndarray], int
+]
+"""``points(z, edges, lower, upper, c, out) -> int``: a table's rows at positions.
+
+The contract of :func:`solprop.translate.chebyshev._clenshaw_points`: ``z`` float64
+``(n_points,)``, ``edges`` float64 ``(n_intervals + 1,)``, ``c`` float64 or complex128
+``(n_intervals, n_deg, n_values)`` and ``out`` of ``c``'s dtype ``(n_points,
+n_values)``, all C-contiguous; the result is the first position outside ``[lower,
+upper]`` or ``-1``.
+"""
+
+BasisFunction = Callable[[np.ndarray, float, bool], tuple[np.ndarray, np.ndarray]]
+"""``basis(points, upper, integrate) -> (rows, weights)``: an Adams formula's basis.
+
+The contract of :func:`solprop.stepper.multistep._basis_rows`: ``points`` float64
+``(n,)`` and C-contiguous; ``rows`` ``(n, n)`` (zero when integrating) and ``weights``
+``(n,)`` (unset when not).
+"""
+
+TablesFunction = Callable[
+    [np.ndarray, int, list[int], bool],
+    tuple[
+        np.ndarray,
+        np.ndarray,
+        np.ndarray,
+        np.ndarray,
+        np.ndarray,
+        np.ndarray,
+        np.ndarray,
+    ],
+]
+"""``tables(nodes, order, orders, compensated) -> tables``: a trial's tables at once.
+
+The contract of :func:`solprop.backends.multistep.trial_tables`, whose composition over
+the record's own basis it performs in one call, with the same operations in the same
+order: ``nodes`` float64 ``(n,)`` and C-contiguous, newest first; the result is that
+function's seven arrays.
+"""
+
+
+@dataclass(frozen=True)
+class Helpers:
+    """The per-stage and per-step evaluations of one backend.
+
+    Each operation is loaded at its first use and kept: a record names its functions
+    without importing them, so constructing or importing one loads nothing (the Numba
+    record compiles at its first evaluation, exactly as the cached dispatchers it
+    holds always have).
+
+    Attributes
+    ----------
+    name : str
+        What the record is, for messages and tests.
+    load_points : collections.abc.Callable
+        Returns the :data:`PointsFunction`.
+    load_basis : collections.abc.Callable
+        Returns the :data:`BasisFunction`.
+    load_tables : collections.abc.Callable or None, optional
+        Returns the :data:`TablesFunction`, for a record that forms an exponential
+        Adams trial's tables in one call; ``None``, the default, composes them from
+        the basis.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> from solprop._helpers import PLAIN
+    >>> rows, weights = PLAIN.basis(np.array([1.0, 0.0]), 1.0, True)
+    >>> weights.tolist()
+    [0.5, 0.5]
+    """
+
+    name: str
+    load_points: Callable[[], PointsFunction] = field(repr=False)
+    load_basis: Callable[[], BasisFunction] = field(repr=False)
+    load_tables: Callable[[], TablesFunction] | None = field(default=None, repr=False)
+
+    @functools.cached_property
+    def points(self) -> PointsFunction:
+        """Return the Chebyshev rows at several positions.
+
+        Returns
+        -------
+        collections.abc.Callable
+            The :data:`PointsFunction`.
+        """
+        return self.load_points()
+
+    @functools.cached_property
+    def basis(self) -> BasisFunction:
+        """Return the Lagrange basis on an Adams formula's nodes.
+
+        Returns
+        -------
+        collections.abc.Callable
+            The :data:`BasisFunction`.
+        """
+        return self.load_basis()
+
+    @functools.cached_property
+    def tables(self) -> TablesFunction | None:
+        """Return an exponential Adams trial's tables in one call, if the record has it.
+
+        Returns
+        -------
+        collections.abc.Callable or None
+            The :data:`TablesFunction`, or ``None``: the tables are then composed from
+            :attr:`basis`.
+        """
+        return None if self.load_tables is None else self.load_tables()
+
+
+def _plain_points() -> PointsFunction:
+    """Return the Chebyshev rows' Python form.
+
+    Returns
+    -------
+    collections.abc.Callable
+        :func:`solprop.translate.chebyshev._clenshaw_points`.
+    """
+    from solprop.translate import chebyshev  # noqa: PLC0415 - where it lives
+
+    return chebyshev._clenshaw_points
+
+
+def _plain_basis() -> BasisFunction:
+    """Return the Adams basis' Python form.
+
+    Returns
+    -------
+    collections.abc.Callable
+        :func:`solprop.stepper.multistep._basis_rows`.
+    """
+    from solprop.stepper import multistep  # noqa: PLC0415 - where it lives
+
+    return multistep._basis_rows
+
+
+def _numba_points() -> PointsFunction:
+    """Return the Chebyshev rows compiled by Numba.
+
+    Returns
+    -------
+    collections.abc.Callable
+        The cached dispatcher of :func:`solprop.translate.chebyshev._clenshaw_batch`.
+    """
+    from solprop.translate import chebyshev  # noqa: PLC0415 - numba on first use
+
+    return chebyshev._clenshaw_batch()
+
+
+def _numba_basis() -> BasisFunction:
+    """Return the Adams basis compiled by Numba.
+
+    Returns
+    -------
+    collections.abc.Callable
+        The cached dispatcher of :func:`solprop.stepper.multistep._basis`.
+    """
+    from solprop.stepper import multistep  # noqa: PLC0415 - numba on first use
+
+    return multistep._basis()
+
+
+PLAIN = Helpers("plain", _plain_points, _plain_basis)
+"""The uncompiled Python forms: the NumPy reference backend's."""
+
+NUMBA = Helpers("numba", _numba_points, _numba_basis)
+"""The same forms compiled by Numba: ``numba_cpu``'s, and the shared default."""