mbsolver 0.2.0__tar.gz

mbsolver-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vahid Anari
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mbsolver-0.2.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: mbsolver
+Version: 0.2.0
+Summary: Fast Maxwell-Bloch solvers for masers, superradiance and coherent pulse propagation
+Author-email: Vahid Anari <vahid.anari8@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/vahid-anari/mbsolver
+Project-URL: Repository, https://github.com/vahid-anari/mbsolver
+Project-URL: Issues, https://github.com/vahid-anari/mbsolver/issues
+Keywords: maxwell-bloch,maser,superradiance,physics,astrophysics,numba,simulation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: numba>=0.58
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# mbsolver
+
+Fast Maxwell-Bloch solvers in Python (numpy + numba) for astrophysical masers,
+superradiance and coherent pulse propagation. Use them from scripts,
+notebooks or cluster jobs; the
+[Maxwell Bloch Studio](https://github.com/vahid-anari/maxwell-bloch-studio)
+desktop app runs on the same code.
+
+```
+pip install mbsolver
+```
+
+## Two-level model in one dimension
+
+Dimensionless equations for the population inversion `w`, the coherence `R`
+and the field `A` along a medium `0 ≤ z ≤ 1`:
+
+```
+dw/dt = A R − (w − w0) / T1 + Λ(t)
+dR/dt = −A w − (R − R0) / T2
+dA/dz = −η R
+```
+
+The field `A(t)` entering at `z = 0` is given; population and coherence are
+advanced with fourth-order Runge-Kutta in time, the field step by step in `z`.
+
+```python
+import matplotlib.pyplot as plt
+from mbsolver import Pulse, Steps
+from mbsolver.two_level import solve_1d
+
+res = solve_1d(
+    t_max=300, nt=3001, nz=121, eta=40.0,
+    theta0=0.003,                                  # or w0=..., R0=...
+    pump=[Pulse(a=[2e-3, 1e-3], x0=[60, 180], w=[15, 25])],
+    field_in=Pulse(a=1e-3, x0=30, w=5),            # A(t) at z = 0
+    t1=Steps(y=[80, 40, 60], x0=[100, 200], w=[10, 0]),
+    t2=5.0,
+    n_planes=7,                                    # stored z planes, 0 ... 1
+)
+
+plt.plot(res.time, res.intensity[-1])              # intensity leaving the medium
+plt.show()
+```
+
+### Arguments
+
+| Argument | Meaning |
+|----------|---------|
+| `t_max`, `nt` | time grid from 0 to `t_max` with `nt` points |
+| `nz` | number of z points |
+| `eta` | coupling coefficient η |
+| `theta0`, or `w0` and `R0` | initial state (`w0 = cos θ0`, `R0 = sin θ0`); the medium also relaxes towards it |
+| `t1`, `t2` | relaxation times: a number or `Steps` (> 0, `math.inf` for none) |
+| `pump` | Λ(t): a `Pulse`, a number, or a list of them (summed) |
+| `field_in` | A(t) at z = 0: a `Pulse`, a number, or `None` |
+| `n_planes` | number of evenly spaced z planes returned (default 2: entrance and exit) |
+
+### Result
+
+`res.time`, `res.z` (positions of the stored planes), `res.intensity` and
+`res.w` (shape `(n_planes, nt)`), `res.pump`, `res.field_in`, `res.t1`, `res.t2`.
+
+## Profiles
+
+`Pulse(a, x0, w)` is a sum of sech² pulses, `a_i sech²((t − x0_i) / w_i)`.
+Give `wl` and `wr` instead of `w` for a different width on each side.
+
+`Steps(y, x0, w)` goes from level `y[0]` to `y[1]` around `x0[0]`, then to
+`y[2]` around `x0[1]`, and so on, each step smoothed as `(1 + tanh)/2` with
+width `w` (0 for a sharp step). `x0` and `w` have one value fewer than `y`.
+
+A zero width gives a single point (pulse) or a sharp step; an infinite width
+a constant. `profile.evaluate(t)` returns the values on any grid.
+
+## Tests
+
+```
+pip install -e ".[dev]"
+pytest
+```
+
+The tests include a reference run that must match the solver of the Maxwell
+Bloch app (version 8.13) exactly, and physics checks (Bloch rotation at the
+entrance, relaxation balance, uncoupled propagation).
+
+## Earlier name
+
+Up to 0.1.0 this package was called `maxbloch`; 0.2.0 is the same code under
+the new name. `maxbloch` stays on PyPI unchanged (0.1.1 only adds a
+deprecation warning) but gets no updates; change `maxbloch` to `mbsolver` in
+your imports.
+
+## License
+
+MIT

mbsolver-0.2.0/README.md

@@ -0,0 +1,96 @@
+# mbsolver
+
+Fast Maxwell-Bloch solvers in Python (numpy + numba) for astrophysical masers,
+superradiance and coherent pulse propagation. Use them from scripts,
+notebooks or cluster jobs; the
+[Maxwell Bloch Studio](https://github.com/vahid-anari/maxwell-bloch-studio)
+desktop app runs on the same code.
+
+```
+pip install mbsolver
+```
+
+## Two-level model in one dimension
+
+Dimensionless equations for the population inversion `w`, the coherence `R`
+and the field `A` along a medium `0 ≤ z ≤ 1`:
+
+```
+dw/dt = A R − (w − w0) / T1 + Λ(t)
+dR/dt = −A w − (R − R0) / T2
+dA/dz = −η R
+```
+
+The field `A(t)` entering at `z = 0` is given; population and coherence are
+advanced with fourth-order Runge-Kutta in time, the field step by step in `z`.
+
+```python
+import matplotlib.pyplot as plt
+from mbsolver import Pulse, Steps
+from mbsolver.two_level import solve_1d
+
+res = solve_1d(
+    t_max=300, nt=3001, nz=121, eta=40.0,
+    theta0=0.003,                                  # or w0=..., R0=...
+    pump=[Pulse(a=[2e-3, 1e-3], x0=[60, 180], w=[15, 25])],
+    field_in=Pulse(a=1e-3, x0=30, w=5),            # A(t) at z = 0
+    t1=Steps(y=[80, 40, 60], x0=[100, 200], w=[10, 0]),
+    t2=5.0,
+    n_planes=7,                                    # stored z planes, 0 ... 1
+)
+
+plt.plot(res.time, res.intensity[-1])              # intensity leaving the medium
+plt.show()
+```
+
+### Arguments
+
+| Argument | Meaning |
+|----------|---------|
+| `t_max`, `nt` | time grid from 0 to `t_max` with `nt` points |
+| `nz` | number of z points |
+| `eta` | coupling coefficient η |
+| `theta0`, or `w0` and `R0` | initial state (`w0 = cos θ0`, `R0 = sin θ0`); the medium also relaxes towards it |
+| `t1`, `t2` | relaxation times: a number or `Steps` (> 0, `math.inf` for none) |
+| `pump` | Λ(t): a `Pulse`, a number, or a list of them (summed) |
+| `field_in` | A(t) at z = 0: a `Pulse`, a number, or `None` |
+| `n_planes` | number of evenly spaced z planes returned (default 2: entrance and exit) |
+
+### Result
+
+`res.time`, `res.z` (positions of the stored planes), `res.intensity` and
+`res.w` (shape `(n_planes, nt)`), `res.pump`, `res.field_in`, `res.t1`, `res.t2`.
+
+## Profiles
+
+`Pulse(a, x0, w)` is a sum of sech² pulses, `a_i sech²((t − x0_i) / w_i)`.
+Give `wl` and `wr` instead of `w` for a different width on each side.
+
+`Steps(y, x0, w)` goes from level `y[0]` to `y[1]` around `x0[0]`, then to
+`y[2]` around `x0[1]`, and so on, each step smoothed as `(1 + tanh)/2` with
+width `w` (0 for a sharp step). `x0` and `w` have one value fewer than `y`.
+
+A zero width gives a single point (pulse) or a sharp step; an infinite width
+a constant. `profile.evaluate(t)` returns the values on any grid.
+
+## Tests
+
+```
+pip install -e ".[dev]"
+pytest
+```
+
+The tests include a reference run that must match the solver of the Maxwell
+Bloch app (version 8.13) exactly, and physics checks (Bloch rotation at the
+entrance, relaxation balance, uncoupled propagation).
+
+## Earlier name
+
+Up to 0.1.0 this package was called `maxbloch`; 0.2.0 is the same code under
+the new name. `maxbloch` stays on PyPI unchanged (0.1.1 only adds a
+deprecation warning) but gets no updates; change `maxbloch` to `mbsolver` in
+your imports.
+
+## License
+
+MIT

mbsolver-0.2.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mbsolver"
+version = "0.2.0"
+description = "Fast Maxwell-Bloch solvers for masers, superradiance and coherent pulse propagation"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Vahid Anari", email = "vahid.anari8@gmail.com" }]
+keywords = [
+    "maxwell-bloch", "maser", "superradiance", "physics",
+    "astrophysics", "numba", "simulation",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Physics",
+    "Topic :: Scientific/Engineering :: Astronomy",
+]
+dependencies = [
+    "numpy>=1.24",
+    "numba>=0.58",
+]
+
+[project.optional-dependencies]
+dev = ["build", "twine", "pytest"]
+
+[project.urls]
+Homepage = "https://github.com/vahid-anari/mbsolver"
+Repository = "https://github.com/vahid-anari/mbsolver"
+Issues = "https://github.com/vahid-anari/mbsolver/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

mbsolver-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mbsolver-0.2.0/src/mbsolver/__init__.py

@@ -0,0 +1,17 @@
+"""Maxwell-Bloch solvers.
+
+Profiles (pump pulses, boundary fields, relaxation-time schedules) are built
+with :class:`Pulse` and :class:`Steps`; the solvers live in model subpackages,
+e.g. ``mbsolver.two_level.solve_1d``.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from mbsolver.profiles import Pulse, Steps
+
+try:
+    __version__ = version("mbsolver")
+except PackageNotFoundError:  # running from a source tree without install
+    __version__ = "0+unknown"
+
+__all__ = ["Pulse", "Steps", "__version__"]

mbsolver-0.2.0/src/mbsolver/grids.py

@@ -0,0 +1,16 @@
+"""Simulation grids."""
+
+from __future__ import annotations
+
+import numpy as np
+from numba import njit
+
+
+@njit(inline="always", nogil=True, cache=True)
+def grids_1d(t_max: float, nt: int, nz: int):
+    """Return ``(t, dt, z, dz)``: ``nt`` times from 0 to ``t_max``, ``nz`` positions from 0 to 1."""
+    t = np.linspace(0.0, t_max, nt)
+    dt = t_max / (nt - 1)
+    z = np.linspace(0.0, 1.0, nz)
+    dz = 1.0 / (nz - 1)
+    return t, dt, z, dz

mbsolver-0.2.0/src/mbsolver/profiles.py

@@ -0,0 +1,237 @@
+"""Time profiles: sums of sech² pulses and smoothed steps.
+
+``Pulse`` describes pump pulses and boundary fields, ``Steps`` describes
+quantities that change between levels, such as relaxation times. Both are
+evaluated on a grid with numba.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Sequence, Union
+
+import numpy as np
+from numba import njit
+
+ArrayLike = Union[float, Sequence[float], np.ndarray]
+
+
+def _array(name: str, values: Optional[ArrayLike]) -> Optional[np.ndarray]:
+    """Return ``values`` as a 1-D float array (``None`` stays ``None``)."""
+    if values is None:
+        return None
+    arr = np.atleast_1d(np.asarray(values, dtype=np.float64))
+    if arr.ndim != 1:
+        raise ValueError(f"{name} must be a number or a 1-D sequence")
+    return arr
+
+
+def _widths(n: int, w, wl, wr) -> tuple[bool, np.ndarray, np.ndarray, np.ndarray]:
+    """Check the width arguments and return ``(symmetric, w, wl, wr)`` arrays of length ``n``."""
+    w, wl, wr = _array("w", w), _array("wl", wl), _array("wr", wr)
+    if w is not None:
+        if wl is not None or wr is not None:
+            raise ValueError("give either w, or wl and wr, not both")
+        symmetric, wl, wr = True, w, w
+    elif wl is not None and wr is not None:
+        symmetric, w = False, wl
+    else:
+        raise ValueError("give either w, or both wl and wr")
+    for name, arr in (("w", w), ("wl", wl), ("wr", wr)):
+        if arr.shape[0] != n:
+            raise ValueError(f"{name} must have {n} values, got {arr.shape[0]}")
+        if np.any(arr < 0):
+            raise ValueError(f"{name} must not be negative")
+    return symmetric, w, wl, wr
+
+
+@dataclass(frozen=True, init=False)
+class Pulse:
+    """A sum of sech² pulses.
+
+    ``y(x) = sum_i a_i * sech²((x - x0_i) / w_i)``; with ``wl`` and ``wr``
+    instead of ``w``, each pulse has its own width on each side of ``x0_i``.
+    A zero width gives ``a_i`` only at ``x0_i``; an infinite width a constant.
+
+    Args:
+        a: Amplitudes.
+        x0: Centres.
+        w: Widths (symmetric pulses).
+        wl, wr: Left and right widths (asymmetric pulses).
+
+    Example:
+        ``Pulse(a=[0.1, 0.05], x0=[50, 120], w=[10, 20])``
+    """
+
+    a: np.ndarray
+    x0: np.ndarray
+    w: np.ndarray
+    wl: np.ndarray
+    wr: np.ndarray
+    symmetric: bool
+
+    def __init__(self, a: ArrayLike, x0: ArrayLike, w: Optional[ArrayLike] = None,
+                 wl: Optional[ArrayLike] = None, wr: Optional[ArrayLike] = None) -> None:
+        a, x0 = _array("a", a), _array("x0", x0)
+        n = a.shape[0]
+        if x0.shape[0] != n:
+            raise ValueError(f"x0 must have {n} values (one per amplitude), got {x0.shape[0]}")
+        symmetric, w, wl, wr = _widths(n, w, wl, wr)
+        for name, value in (("a", a), ("x0", x0), ("w", w), ("wl", wl), ("wr", wr),
+                            ("symmetric", symmetric)):
+            object.__setattr__(self, name, value)
+
+    def evaluate(self, x: ArrayLike) -> np.ndarray:
+        """Return the profile on the coordinates ``x``."""
+        x = np.asarray(x, dtype=np.float64)
+        return pulse_func(self.symmetric, x, self.a, self.x0, self.w, self.wl, self.wr)
+
+
+@dataclass(frozen=True, init=False)
+class Steps:
+    """Smoothed steps between levels.
+
+    Starts at ``y[0]`` and changes to ``y[i]`` around ``x0[i-1]``:
+    ``y(x) = y_0 + sum_i (y_i - y_{i-1}) * (1 + tanh((x - x0_i) / w_i)) / 2``.
+    A zero width gives a sharp step; one level gives a constant.
+
+    Args:
+        y: Levels (``N`` values).
+        x0: Step positions (``N - 1`` values).
+        w: Step widths (``N - 1`` values, symmetric steps).
+        wl, wr: Left and right widths (asymmetric steps).
+
+    Example:
+        ``Steps(y=[0.5, 0.2], x0=[100], w=[10])``: 0.5 before t = 100, 0.2 after.
+    """
+
+    y: np.ndarray
+    x0: np.ndarray
+    w: np.ndarray
+    wl: np.ndarray
+    wr: np.ndarray
+    symmetric: bool
+
+    def __init__(self, y: ArrayLike, x0: ArrayLike = (), w: Optional[ArrayLike] = None,
+                 wl: Optional[ArrayLike] = None, wr: Optional[ArrayLike] = None) -> None:
+        y, x0 = _array("y", y), _array("x0", x0)
+        n = y.shape[0] - 1
+        if n < 0:
+            raise ValueError("y must contain at least one level")
+        if x0.shape[0] != n:
+            raise ValueError(f"x0 must have {n} values (one per step), got {x0.shape[0]}")
+        if n == 0 and w is None and wl is None and wr is None:
+            w = ()
+        symmetric, w, wl, wr = _widths(n, w, wl, wr)
+        for name, value in (("y", y), ("x0", x0), ("w", w), ("wl", wl), ("wr", wr),
+                            ("symmetric", symmetric)):
+            object.__setattr__(self, name, value)
+
+    def evaluate(self, x: ArrayLike) -> np.ndarray:
+        """Return the profile on the coordinates ``x``."""
+        x = np.asarray(x, dtype=np.float64)
+        pad = np.zeros(1)
+        return step_func(self.symmetric, x, self.y,
+                         np.concatenate((pad, self.x0)), np.concatenate((pad, self.w)),
+                         np.concatenate((pad, self.wl)), np.concatenate((pad, self.wr)))
+
+
+def evaluate(profile: Union[None, float, Pulse, Steps], x: np.ndarray) -> np.ndarray:
+    """Evaluate a profile argument of a solver on the grid ``x``.
+
+    ``None`` gives zeros, a number a constant, a ``Pulse`` or ``Steps`` its values.
+    """
+    if profile is None:
+        return np.zeros(np.shape(x), dtype=np.float64)
+    if isinstance(profile, (Pulse, Steps)):
+        return profile.evaluate(x)
+    if isinstance(profile, (int, float, np.integer, np.floating)) and not isinstance(profile, bool):
+        return np.full(np.shape(x), float(profile), dtype=np.float64)
+    raise TypeError(f"expected None, a number, Pulse or Steps, got {type(profile).__name__}")
+
+
+# -----------------------------------------------------------------------------
+# numba kernels (arguments as in MB Solver's widgets)
+# -----------------------------------------------------------------------------
+@njit(nogil=True, cache=True)
+def pulse_func(symmetric, x, a, x0, w, wl, wr):
+    """Sum of sech² components ``a_i sech²((x - x0_i) / w_i)`` on ``x``.
+
+    All of ``a, x0, w, wl, wr`` have length N; ``w`` is used when
+    ``symmetric``, otherwise ``wl`` left and ``wr`` right of ``x0_i``.
+    """
+    n = a.shape[0]
+    m = x.shape[0]
+    if x0.shape[0] != n or w.shape[0] != n or wl.shape[0] != n or wr.shape[0] != n:
+        raise ValueError("x0, w, wl and wr must have the same length as a")
+
+    y = np.zeros(m, dtype=np.float64)
+
+    for i in range(n):
+        ai = a[i]
+        if ai == 0.0:
+            continue
+
+        x0i = x0[i]
+        wi = w[i]
+        wli = wl[i]
+        wri = wr[i]
+
+        for j in range(m):
+            dx = x[j] - x0i
+            width = wi if symmetric else wli if dx < 0.0 else wri
+
+            if width == 0.0:
+                if dx == 0.0:
+                    y[j] += ai
+            elif np.isinf(width):
+                y[j] += ai
+            else:
+                t = np.tanh(dx / width)
+                y[j] += ai * (1.0 - t * t)
+
+    return y
+
+
+@njit(nogil=True, cache=True)
+def step_func(symmetric, x, levels, x0, w, wl, wr):
+    """Smoothed steps between ``levels`` on ``x``.
+
+    ``levels`` has length N; ``x0, w, wl, wr`` also have length N with
+    index 0 unused (the layout of MB Solver's step widgets).
+    """
+    n = levels.shape[0]
+    m = x.shape[0]
+    if n == 0:
+        raise ValueError("levels must contain at least y^0")
+    if x0.shape[0] != n or w.shape[0] != n or wl.shape[0] != n or wr.shape[0] != n:
+        raise ValueError("x0, w, wl and wr must have the same length as levels")
+
+    y = np.empty(m, dtype=np.float64)
+    y[:] = levels[0]
+
+    for i in range(1, n):
+        di = levels[i] - levels[i - 1]
+        if di == 0.0:
+            continue
+
+        x0i = x0[i]
+        wi = w[i]
+        wli = wl[i]
+        wri = wr[i]
+
+        for j in range(m):
+            dx = x[j] - x0i
+            width = wi if symmetric else wli if dx < 0.0 else wri
+
+            if width == 0.0:
+                if dx > 0.0:
+                    y[j] += di
+                elif dx == 0.0:
+                    y[j] += 0.5 * di
+            elif np.isinf(width):
+                y[j] += 0.5 * di
+            else:
+                y[j] += 0.5 * di * (1.0 + np.tanh(dx / width))
+
+    return y

mbsolver-0.2.0/src/mbsolver/two_level/__init__.py

@@ -0,0 +1,131 @@
+"""Two-level Maxwell-Bloch model.
+
+Dimensionless equations for population inversion ``w``, coherence ``R`` and
+field ``A`` along a 1-D medium ``0 <= z <= 1``::
+
+    dw/dt = A R - (w - w0) / T1 + Λ(t)
+    dR/dt = -A w - (R - R0) / T2
+    dA/dz = -η R
+
+with the field ``A(t, z=0)`` given at the entrance.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Optional, Sequence, Union
+
+import numpy as np
+
+from mbsolver.grids import grids_1d
+from mbsolver.profiles import Pulse, Steps, evaluate
+from mbsolver.two_level._kernel_1d import solve_kernel
+
+__all__ = ["Result", "solve_1d"]
+
+
+@dataclass(frozen=True)
+class Result:
+    """Output of :func:`solve_1d`.
+
+    Attributes:
+        time: Time grid, shape ``(nt,)``.
+        z: Positions of the stored planes, shape ``(n_planes,)``, from 0 to 1.
+        intensity: ``A²`` on the stored planes, shape ``(n_planes, nt)``.
+        w: Population inversion on the stored planes, shape ``(n_planes, nt)``.
+        pump: Total pump ``Λ(t)``.
+        field_in: Boundary field ``A(t, z=0)``.
+        t1, t2: Relaxation times on the time grid.
+    """
+
+    time: np.ndarray
+    z: np.ndarray
+    intensity: np.ndarray
+    w: np.ndarray
+    pump: np.ndarray
+    field_in: np.ndarray
+    t1: np.ndarray
+    t2: np.ndarray
+
+
+Profile = Union[None, float, Pulse, Steps]
+
+
+def solve_1d(
+        *,
+        t_max: float,
+        nt: int,
+        nz: int,
+        eta: float,
+        t1: Union[float, Steps],
+        t2: Union[float, Steps],
+        theta0: Optional[float] = None,
+        w0: Optional[float] = None,
+        R0: Optional[float] = None,
+        pump: Union[Profile, Sequence[Profile]] = None,
+        field_in: Profile = None,
+        n_planes: int = 2,
+) -> Result:
+    """Solve the two-level Maxwell-Bloch equations in one dimension.
+
+    Args:
+        t_max: Duration; the time grid runs from 0 to ``t_max``.
+        nt: Number of time points (>= 2).
+        nz: Number of z points (>= 2).
+        eta: Coupling coefficient ``η``.
+        t1: Population relaxation time, a number or :class:`Steps` (> 0; ``inf`` = none).
+        t2: Coherence relaxation time, a number or :class:`Steps` (> 0; ``inf`` = none).
+        theta0: Initial Bloch angle: ``w0 = cos θ0``, ``R0 = sin θ0``.
+        w0, R0: Initial population and coherence, instead of ``theta0``.
+            The medium also relaxes towards these values.
+        pump: Pump ``Λ(t)``: a :class:`Pulse`, a number, or a list of them (summed).
+        field_in: Field ``A(t)`` entering at ``z = 0``: a :class:`Pulse`, a number or ``None``.
+        n_planes: Number of evenly spaced z planes to return, from 0 to 1 (<= ``nz``).
+
+    Returns:
+        A :class:`Result`.
+
+    Example:
+        >>> res = solve_1d(t_max=200, nt=4000, nz=200, eta=5.0, theta0=0.01,
+        ...                t1=1.0, t2=0.5, pump=Pulse(a=0.1, x0=50, w=10))
+        >>> exit_intensity = res.intensity[-1]
+    """
+    nt, nz, n_planes = int(nt), int(nz), int(n_planes)
+    if nt < 2 or nz < 2:
+        raise ValueError("nt and nz must be at least 2")
+    if not 1 <= n_planes <= nz:
+        raise ValueError(f"n_planes must be between 1 and nz ({nz}), got {n_planes}")
+    if not t_max > 0:
+        raise ValueError("t_max must be positive")
+
+    if theta0 is not None:
+        if w0 is not None or R0 is not None:
+            raise ValueError("give either theta0, or w0 and R0, not both")
+        w_init, R_init = math.cos(theta0), math.sin(theta0)
+    elif w0 is not None and R0 is not None:
+        w_init, R_init = float(w0), float(R0)
+    else:
+        raise ValueError("give the initial state as theta0, or as w0 and R0")
+
+    t, dt, z, dz = grids_1d(float(t_max), nt, nz)
+
+    pumps = pump if isinstance(pump, (list, tuple)) else [pump]
+    pump_t = np.zeros_like(t)
+    for p in pumps:
+        pump_t = pump_t + evaluate(p, t)
+    field_t = evaluate(field_in, t)
+    t1_t = evaluate(t1, t)
+    t2_t = evaluate(t2, t)
+    for name, arr in (("t1", t1_t), ("t2", t2_t)):
+        if np.any(arr <= 0):
+            raise ValueError(f"{name} must be positive")
+
+    w_z = np.full_like(z, w_init)
+    R_z = np.full_like(z, R_init)
+    w, intensity = solve_kernel(t, dt, z, dz, n_planes, w_z, R_z, field_t, pump_t,
+                                t1_t, t2_t, float(eta))
+
+    planes = z[np.rint(np.linspace(0.0, 1.0, n_planes) * (nz - 1)).astype(np.int64)]
+    return Result(time=t, z=planes, intensity=intensity, w=w, pump=pump_t,
+                  field_in=field_t, t1=t1_t, t2=t2_t)

mbsolver-0.2.0/src/mbsolver/two_level/_kernel_1d.py

@@ -0,0 +1,138 @@
+"""Two-level Maxwell-Bloch equations in one dimension (numba kernel).
+
+Moved unchanged from MB Solver 8.13 (``solver/maxwell_bloch.py``):
+RK4 in time for the population and coherence, explicit step in z for the field.
+
+    dw/dt = A R - (w - w0) / T1 + Λ
+    dR/dt = -A w - (R - R0) / T2
+    dA/dz = -η R
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from numba import njit
+
+
+@njit(inline="always", nogil=True, cache=True)
+def _dw_dt(w, R, A, kw, kR, w0, inv_t1, lambda_n):
+    """Population derivative for one RK stage."""
+    return A * (R + kR) - (w + kw - w0) * inv_t1 + lambda_n
+
+
+@njit(inline="always", nogil=True, cache=True)
+def _dR_dt(w, R, A, kw, kR, R0, inv_t2):
+    """Coherence derivative for one RK stage."""
+    return -A * (w + kw) - (R + kR - R0) * inv_t2
+
+
+@njit(inline="always", nogil=True, cache=True)
+def _dA_dz(eta, R, dz):
+    """Field increment across one spatial step."""
+    return -eta * R * dz
+
+
+@njit(inline="always", nogil=True, cache=True)
+def _rk4_dn_dR(w, R, A, inv_t1, inv_t2, w0, R0, lambda_n, dt, half_dt, dt6):
+    """One RK4 step for population and coherence; returns ``(dw, dR)``."""
+    kw_1 = _dw_dt(w, R, A, 0, 0, w0, inv_t1, lambda_n)
+    kR_1 = _dR_dt(w, R, A, 0, 0, R0, inv_t2)
+
+    kw_2 = _dw_dt(w, R, A, half_dt * kw_1, half_dt * kR_1, w0, inv_t1, lambda_n)
+    kR_2 = _dR_dt(w, R, A, half_dt * kw_1, half_dt * kR_1, R0, inv_t2)
+
+    kw_3 = _dw_dt(w, R, A, half_dt * kw_2, half_dt * kR_2, w0, inv_t1, lambda_n)
+    kR_3 = _dR_dt(w, R, A, half_dt * kw_2, half_dt * kR_2, R0, inv_t2)
+
+    kw_4 = _dw_dt(w, R, A, dt * kw_3, dt * kR_3, w0, inv_t1, lambda_n)
+    kR_4 = _dR_dt(w, R, A, dt * kw_3, dt * kR_3, R0, inv_t2)
+
+    dw = dt6 * (kw_1 + 2.0 * kw_2 + 2.0 * kw_3 + kw_4)
+    dR = dt6 * (kR_1 + 2.0 * kR_2 + 2.0 * kR_3 + kR_4)
+
+    return dw, dR
+
+
+@njit(nogil=True, cache=True)
+def solve_kernel(t, dt, z, dz, n_z_planes, w0, R0, A0, lambda_n, t1, t2, eta):
+    """Advance the system over the grid.
+
+    Args:
+        t, dt: Time grid and step.
+        z, dz: Spatial grid and step.
+        n_z_planes: Number of evenly spaced z planes to store (<= len(z)).
+        w0, R0: Initial (and equilibrium) population and coherence along z.
+        A0: Boundary field at z = 0 on the time grid.
+        lambda_n: Pump on the time grid.
+        t1, t2: Relaxation times on the time grid (> 0, may be inf).
+        eta: Coupling coefficient.
+
+    Returns:
+        ``(w, I)``, each of shape ``(n_z_planes, len(t))``.
+    """
+    nt = len(t)
+    nz = len(z)
+    z_planes = np.linspace(0.0, 1.0, n_z_planes)
+    z_plane_indices = np.rint(z_planes * (nz - 1)).astype(np.int64)
+
+    inv_t1 = 1.0 / t1
+    inv_t2 = 1.0 / t2
+    half_dt = 0.5 * dt
+    dt6 = dt / 6.0
+
+    w_old = np.empty(nt, dtype=np.float64)
+    R_old = np.empty(nt, dtype=np.float64)
+    A_old = np.empty(nt, dtype=np.float64)
+
+    w_new = np.empty_like(w_old)
+    R_new = np.empty_like(R_old)
+    A_new = np.empty_like(A_old)
+
+    w_result = np.empty((n_z_planes, nt), dtype=np.float64)
+    I_result = np.empty((n_z_planes, nt), dtype=np.float64)
+
+    w_old[0], R_old[0] = w0[0], R0[0]
+    A_old[0] = A0[0]
+    w0_0 = w0[0]
+    R0_0 = R0[0]
+
+    for t_idx in range(1, nt):
+        dw, dR = _rk4_dn_dR(
+            w_old[t_idx - 1], R_old[t_idx - 1], A_old[t_idx - 1],
+            inv_t1[t_idx - 1], inv_t2[t_idx - 1], w0_0, R0_0,
+            lambda_n[t_idx - 1], dt, half_dt, dt6,
+        )
+        w_old[t_idx] = w_old[t_idx - 1] + dw
+        R_old[t_idx] = R_old[t_idx - 1] + dR
+        A_old[t_idx] = A0[t_idx]
+
+    w_result[0, :] = w_old
+    I_result[0, :] = A_old * A_old
+    i = 1
+
+    for z_idx in range(1, nz):
+        w_new[0], R_new[0] = w0[z_idx], R0[z_idx]
+        A_new[0] = A_old[0] + _dA_dz(eta, R_old[0], dz)
+        w0_i = w0[z_idx]
+        R0_i = R0[z_idx]
+
+        for t_idx in range(1, nt):
+            dw, dR = _rk4_dn_dR(
+                w_new[t_idx - 1], R_new[t_idx - 1], A_new[t_idx - 1],
+                inv_t1[t_idx - 1], inv_t2[t_idx - 1], w0_i, R0_i,
+                lambda_n[t_idx - 1], dt, half_dt, dt6,
+            )
+            w_new[t_idx] = w_new[t_idx - 1] + dw
+            R_new[t_idx] = R_new[t_idx - 1] + dR
+            A_new[t_idx] = A_old[t_idx] + _dA_dz(eta, R_old[t_idx], dz)
+
+        if i < n_z_planes and z_plane_indices[i] == z_idx:
+            w_result[i, :] = w_new
+            I_result[i, :] = A_new * A_new
+            i += 1
+
+        w_old, w_new = w_new, w_old
+        R_old, R_new = R_new, R_old
+        A_old, A_new = A_new, A_old
+
+    return w_result, I_result

mbsolver-0.2.0/src/mbsolver.egg-info/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: mbsolver
+Version: 0.2.0
+Summary: Fast Maxwell-Bloch solvers for masers, superradiance and coherent pulse propagation
+Author-email: Vahid Anari <vahid.anari8@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/vahid-anari/mbsolver
+Project-URL: Repository, https://github.com/vahid-anari/mbsolver
+Project-URL: Issues, https://github.com/vahid-anari/mbsolver/issues
+Keywords: maxwell-bloch,maser,superradiance,physics,astrophysics,numba,simulation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: numba>=0.58
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# mbsolver
+
+Fast Maxwell-Bloch solvers in Python (numpy + numba) for astrophysical masers,
+superradiance and coherent pulse propagation. Use them from scripts,
+notebooks or cluster jobs; the
+[Maxwell Bloch Studio](https://github.com/vahid-anari/maxwell-bloch-studio)
+desktop app runs on the same code.
+
+```
+pip install mbsolver
+```
+
+## Two-level model in one dimension
+
+Dimensionless equations for the population inversion `w`, the coherence `R`
+and the field `A` along a medium `0 ≤ z ≤ 1`:
+
+```
+dw/dt = A R − (w − w0) / T1 + Λ(t)
+dR/dt = −A w − (R − R0) / T2
+dA/dz = −η R
+```
+
+The field `A(t)` entering at `z = 0` is given; population and coherence are
+advanced with fourth-order Runge-Kutta in time, the field step by step in `z`.
+
+```python
+import matplotlib.pyplot as plt
+from mbsolver import Pulse, Steps
+from mbsolver.two_level import solve_1d
+
+res = solve_1d(
+    t_max=300, nt=3001, nz=121, eta=40.0,
+    theta0=0.003,                                  # or w0=..., R0=...
+    pump=[Pulse(a=[2e-3, 1e-3], x0=[60, 180], w=[15, 25])],
+    field_in=Pulse(a=1e-3, x0=30, w=5),            # A(t) at z = 0
+    t1=Steps(y=[80, 40, 60], x0=[100, 200], w=[10, 0]),
+    t2=5.0,
+    n_planes=7,                                    # stored z planes, 0 ... 1
+)
+
+plt.plot(res.time, res.intensity[-1])              # intensity leaving the medium
+plt.show()
+```
+
+### Arguments
+
+| Argument | Meaning |
+|----------|---------|
+| `t_max`, `nt` | time grid from 0 to `t_max` with `nt` points |
+| `nz` | number of z points |
+| `eta` | coupling coefficient η |
+| `theta0`, or `w0` and `R0` | initial state (`w0 = cos θ0`, `R0 = sin θ0`); the medium also relaxes towards it |
+| `t1`, `t2` | relaxation times: a number or `Steps` (> 0, `math.inf` for none) |
+| `pump` | Λ(t): a `Pulse`, a number, or a list of them (summed) |
+| `field_in` | A(t) at z = 0: a `Pulse`, a number, or `None` |
+| `n_planes` | number of evenly spaced z planes returned (default 2: entrance and exit) |
+
+### Result
+
+`res.time`, `res.z` (positions of the stored planes), `res.intensity` and
+`res.w` (shape `(n_planes, nt)`), `res.pump`, `res.field_in`, `res.t1`, `res.t2`.
+
+## Profiles
+
+`Pulse(a, x0, w)` is a sum of sech² pulses, `a_i sech²((t − x0_i) / w_i)`.
+Give `wl` and `wr` instead of `w` for a different width on each side.
+
+`Steps(y, x0, w)` goes from level `y[0]` to `y[1]` around `x0[0]`, then to
+`y[2]` around `x0[1]`, and so on, each step smoothed as `(1 + tanh)/2` with
+width `w` (0 for a sharp step). `x0` and `w` have one value fewer than `y`.
+
+A zero width gives a single point (pulse) or a sharp step; an infinite width
+a constant. `profile.evaluate(t)` returns the values on any grid.
+
+## Tests
+
+```
+pip install -e ".[dev]"
+pytest
+```
+
+The tests include a reference run that must match the solver of the Maxwell
+Bloch app (version 8.13) exactly, and physics checks (Bloch rotation at the
+entrance, relaxation balance, uncoupled propagation).
+
+## Earlier name
+
+Up to 0.1.0 this package was called `maxbloch`; 0.2.0 is the same code under
+the new name. `maxbloch` stays on PyPI unchanged (0.1.1 only adds a
+deprecation warning) but gets no updates; change `maxbloch` to `mbsolver` in
+your imports.
+
+## License
+
+MIT

mbsolver-0.2.0/src/mbsolver.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/mbsolver/__init__.py
+src/mbsolver/grids.py
+src/mbsolver/profiles.py
+src/mbsolver.egg-info/PKG-INFO
+src/mbsolver.egg-info/SOURCES.txt
+src/mbsolver.egg-info/dependency_links.txt
+src/mbsolver.egg-info/requires.txt
+src/mbsolver.egg-info/top_level.txt
+src/mbsolver/two_level/__init__.py
+src/mbsolver/two_level/_kernel_1d.py
+tests/test_profiles.py
+tests/test_two_level.py

mbsolver-0.2.0/src/mbsolver.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mbsolver-0.2.0/src/mbsolver.egg-info/requires.txt

@@ -0,0 +1,7 @@
+numpy>=1.24
+numba>=0.58
+
+[dev]
+build
+twine
+pytest

mbsolver-0.2.0/src/mbsolver.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+maxbloch
+mbsolver

mbsolver-0.2.0/tests/test_profiles.py

@@ -0,0 +1,58 @@
+"""Tests for Pulse and Steps."""
+
+import math
+
+import numpy as np
+import pytest
+
+from mbsolver import Pulse, Steps
+
+X = np.linspace(-10, 10, 201)
+
+
+def test_pulse_symmetric():
+    y = Pulse(a=2.0, x0=1.0, w=3.0).evaluate(X)
+    np.testing.assert_allclose(y, 2.0 / np.cosh((X - 1.0) / 3.0) ** 2)
+
+
+def test_pulse_sum_and_asymmetric():
+    p = Pulse(a=[1.0, 0.5], x0=[-2.0, 4.0], wl=[1.0, 2.0], wr=[3.0, 0.5])
+    left = X < -2.0
+    y = p.evaluate(X)
+    expected_first = np.where(left, 1 / np.cosh((X + 2) / 1.0) ** 2, 1 / np.cosh((X + 2) / 3.0) ** 2)
+    expected_second = 0.5 * np.where(X < 4.0, 1 / np.cosh((X - 4) / 2.0) ** 2,
+                                     1 / np.cosh((X - 4) / 0.5) ** 2)
+    np.testing.assert_allclose(y, expected_first + expected_second)
+
+
+def test_pulse_limits():
+    assert np.all(Pulse(a=3.0, x0=0.0, w=math.inf).evaluate(X) == 3.0)
+    y = Pulse(a=3.0, x0=0.0, w=0.0).evaluate(X)
+    assert y[100] == 3.0 and np.count_nonzero(y) == 1
+
+
+def test_steps():
+    s = Steps(y=[1.0, 3.0, 2.0], x0=[-5.0, 5.0], w=[0.0, 2.0])
+    y = s.evaluate(X)
+    assert y[0] == pytest.approx(1.0, abs=1e-6)
+    assert y[50] == pytest.approx(2.0, abs=1e-3)  # sharp step at x = -5 is halfway
+    assert y[80] == pytest.approx(3.0, abs=1e-3)
+    assert y[150] == pytest.approx(2.5)         # smooth step at x = 5 is halfway
+    assert y[-1] == pytest.approx(2.0 + 0.5 * (1 - math.tanh(2.5)))
+
+
+def test_single_level_is_constant():
+    assert np.all(Steps(y=4.0).evaluate(X) == 4.0)
+
+
+@pytest.mark.parametrize("make, message", [
+    (lambda: Pulse(a=[1, 2], x0=[0], w=[1, 1]), "x0 must have 2"),
+    (lambda: Pulse(a=1, x0=0), "either w"),
+    (lambda: Pulse(a=1, x0=0, w=1, wl=1, wr=1), "not both"),
+    (lambda: Pulse(a=1, x0=0, w=-1), "negative"),
+    (lambda: Steps(y=[1, 2], x0=[0, 1], w=[1, 1]), "x0 must have 1"),
+    (lambda: Steps(y=[]), "at least one level"),
+])
+def test_invalid(make, message):
+    with pytest.raises(ValueError, match=message):
+        make()

mbsolver-0.2.0/tests/test_two_level.py

@@ -0,0 +1,92 @@
+"""Tests for mbsolver.two_level.solve_1d."""
+
+import json
+import math
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+from mbsolver import Pulse, Steps
+from mbsolver.two_level import solve_1d
+
+DATA = Path(__file__).parent / "data"
+
+
+def _pulse(p):
+    """MB Solver widget value -> Pulse."""
+    if p["symmetric"]:
+        return Pulse(a=p["a"], x0=p["x0"], w=p["w"])
+    return Pulse(a=p["a"], x0=p["x0"], wl=p["wl"], wr=p["wr"])
+
+
+def _steps(s):
+    """MB Solver widget value -> number or Steps (index 0 of x0/w unused)."""
+    if not isinstance(s, dict):
+        return s
+    if s["symmetric"]:
+        return Steps(y=s["y"], x0=s["x0"][1:], w=s["w"][1:])
+    return Steps(y=s["y"], x0=s["x0"][1:], wl=s["wl"][1:], wr=s["wr"][1:])
+
+
+def test_matches_mb_solver_8_13():
+    """Same results as MB Solver 8.13's own solver for a reference case."""
+    p = json.loads((DATA / "reference_params.json").read_text())
+    ref = np.load(DATA / "reference_two_level.npz")
+    res = solve_1d(
+        t_max=p["solve.grid.t_max"], nt=p["solve.grid.nt"], nz=p["solve.grid.nz"],
+        eta=p["solve.sample"]["eta"], theta0=p["solve.sample"]["theta0"],
+        pump=[_pulse(p[f"solve.pump.pulse{i}"]) for i in (1, 2, 3)],
+        field_in=_pulse(p["solve.bcs"]),
+        t1=_steps(p["solve.t1"]), t2=_steps(p["solve.t2"]),
+        n_planes=min(p["slice.z"]["arr_length"], p["solve.grid.nz"]),
+    )
+    for ours, theirs in (("time", "time"), ("intensity", "intensity"), ("w", "w"),
+                         ("pump", "lambda_n"), ("field_in", "A0"), ("t1", "t1"), ("t2", "t2")):
+        np.testing.assert_allclose(getattr(res, ours), ref[theirs], rtol=1e-12, atol=1e-14,
+                                   err_msg=ours)
+
+def test_entrance_is_a_bloch_rotation():
+    """At z = 0 without relaxation or pump, the field rotates the Bloch angle by minus its area."""
+    theta0, a, x0, width = 0.2, 0.05, 40.0, 8.0
+    res = solve_1d(t_max=100, nt=4001, nz=3, eta=1.0, theta0=theta0, t1=math.inf, t2=math.inf,
+                   field_in=Pulse(a=a, x0=x0, w=width))
+    dt = res.time[1] - res.time[0]
+    area = np.concatenate(([0.0], np.cumsum(res.field_in[:-1]) * dt))
+    np.testing.assert_allclose(res.w[0], np.cos(theta0 - area), atol=1e-9)
+
+
+def test_no_coupling_leaves_field_unchanged():
+    """With eta = 0 the field crosses the medium unchanged."""
+    res = solve_1d(t_max=50, nt=501, nz=11, eta=0.0, theta0=0.1, t1=10, t2=5,
+                   field_in=Pulse(a=0.1, x0=20, w=5), n_planes=4)
+    for plane in res.intensity:
+        np.testing.assert_allclose(plane, res.field_in ** 2, rtol=0, atol=1e-15)
+
+
+def test_relaxation_and_pump_balance():
+    """Without a field, w relaxes to w0 + T1 * pump for a constant pump."""
+    res = solve_1d(t_max=200, nt=2001, nz=2, eta=1.0, w0=0.0, R0=0.0, t1=10.0, t2=5.0,
+                   pump=0.01)
+    assert res.w[-1, -1] == pytest.approx(0.1, rel=1e-6)
+
+
+def test_result_shapes_and_planes():
+    res = solve_1d(t_max=10, nt=101, nz=21, eta=1.0, theta0=0.0, t1=1, t2=1, n_planes=5)
+    assert res.intensity.shape == res.w.shape == (5, 101)
+    np.testing.assert_allclose(res.z, [0, 0.25, 0.5, 0.75, 1.0])
+
+
+@pytest.mark.parametrize("kwargs, message", [
+    (dict(nt=1), "nt and nz"),
+    (dict(n_planes=50), "n_planes"),
+    (dict(t1=0.0), "t1 must be positive"),
+    (dict(theta0=0.1, w0=1.0, R0=0.0), "not both"),
+    (dict(theta0=None), "initial state"),
+    (dict(pump="x"), "expected None"),
+])
+def test_invalid_input(kwargs, message):
+    args = dict(t_max=10, nt=11, nz=11, eta=1.0, theta0=0.0, t1=1.0, t2=1.0)
+    args.update(kwargs)
+    with pytest.raises((ValueError, TypeError), match=message):
+        solve_1d(**args)