Source code for solprop.calibration.problems

# SPDX-FileCopyrightText: 2026 John C. Travers and contributors
#
# SPDX-License-Identifier: GPL-3.0-or-later

"""The calibration's synthetic problems (SEP 46 section 6.3).

:data:`PROBLEMS` maps each problem's name to a builder of its
:class:`~solprop.driver.simulation.Simulation`, and :func:`build` builds one at a
*scale* that sizes its grid. Five problems that solprop ships, so that a calibration
never needs a user's simulation: a GNLSE with Raman response and self-steepening, a
four-mode helium capillary with plasma, a mode-averaged hydrogen capillary with Raman
response, a radial argon filament with plasma and a one-dimensional free-space line;
four of them also come at production size (``*_large``). Each is adapted from the
benchmark tracking set's case of the same physics (``benchmarks/builders.py``), without
noise. Why they are chosen so is in ``docs/dev/backends.md`` (section 3.4a).
"""

from __future__ import annotations

import dataclasses
import math
from collections.abc import Callable
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from solprop.driver import Simulation

__all__ = ["PROBLEMS", "build"]


def _gnlse(scale: float) -> Simulation:
    """Build Dudley, Genty and Coen's soliton fission on a `scale` x 3 ps window.

    The dispersion coefficients follow J. M. Dudley, G. Genty and S. Coen, Rev. Mod.
    Phys. 78, 1135 (2006), doi:10.1103/RevModPhys.78.1135, section III, as the
    benchmark case does.
    """
    from solprop.driver import Simulation  # noqa: PLC0415 - imports the physics

    return Simulation.from_gnlse(
        0.11,
        0.15,
        [
            0.0,
            0.0,
            -11.830e-27,
            8.1038e-41,
            -9.5205e-56,
            2.0737e-70,
            -5.3943e-85,
            1.3486e-99,
            -2.5495e-114,
            3.0524e-129,
            -1.7140e-144,
        ],
        wavelength=835e-9,
        fwhm=50e-15,
        shape="sech",
        peak_power=10e3,
        raman=True,
        shock=True,
        noise=None,
        backend="native",
        wavelength_limits=(400e-9, 2e-6),
        trange=3e-12 * scale,
    )


def _capillary(scale: float) -> Simulation:
    """Build four modes of a helium capillary with plasma, on `scale` x 200 fs."""
    from solprop.driver import Simulation  # noqa: PLC0415 - imports the physics

    return Simulation.from_capillary(
        125e-6,
        1.5,
        "He",
        (0.8, 0.0),
        wavelength=800e-9,
        fwhm=7.5e-15,
        energy=275e-6,
        modes=4,
        noise=None,
        backend="native",
        wavelength_limits=(90e-9, 4e-6),
        trange=200e-15 * scale,
    )


def _averaged(scale: float) -> Simulation:
    """Build a mode-averaged hydrogen capillary with Raman, on `scale` x 800 fs."""
    from solprop.driver import Simulation  # noqa: PLC0415 - imports the physics

    return Simulation.from_capillary(
        20e-6,
        0.4,
        "H2",
        10.0,
        wavelength=1030e-9,
        fwhm=40e-15,
        energy=3e-6,
        loss_scale=0.0,
        plasma=False,
        modes=1,
        mode_average=True,
        noise=None,
        backend="native",
        wavelength_limits=(200e-9, 4e-6),
        trange=800e-15 * scale,
    )


def _spatial(kind: str, scale: float) -> Simulation:
    """Build an argon filament on a radial grid, or Kerr focusing on a line.

    - ``kind``: ``"radial"`` or ``"line"``.
    """
    import numpy as np  # noqa: PLC0415

    from solprop.constants import C  # noqa: PLC0415
    from solprop.driver import Simulation, SimulationSettings  # noqa: PLC0415
    from solprop.grid import FieldGrid, LineGrid, RadialGrid  # noqa: PLC0415
    from solprop.nonlinear.optmat_rates import OptmatRate  # noqa: PLC0415
    from solprop.nonlinear.responses import (  # noqa: PLC0415
        KerrResponse,
        PlasmaResponse,
    )
    from solprop.physdata import gamma3  # noqa: PLC0415
    from solprop.pulses import GaussianPulse, SpatialPulse  # noqa: PLC0415
    from solprop.spatial import SpatialMedium, critical_power  # noqa: PLC0415

    radial = kind == "radial"
    length = 0.01
    grid = FieldGrid.from_limits(
        length,
        800e-9,
        (350e-9, 2e-6) if radial else (500e-9, 1.6e-6),
        150e-15,
    )
    medium = SpatialMedium("Ar", 1.0)
    chi3 = gamma3("Ar", wavelength=800e-9)
    density = float(medium.density(np.array([0.0]))[0])
    carrier = 2 * math.pi * C / 800e-9
    index = float(np.real(medium.index(np.array([carrier]))[0]))
    power = (3.0 if radial else 3000.0) * critical_power(
        800e-9, chi3 * density, index=index
    )
    energy = power * 30e-15 * math.sqrt(math.pi / (4 * math.log(2)))
    pulse = SpatialPulse(
        GaussianPulse(wavelength=800e-9, fwhm=30e-15, energy=energy), 100e-6
    )
    responses: list[KerrResponse | PlasmaResponse] = [KerrResponse(chi3, thg=False)]
    settings = SimulationSettings(
        save_planes=[length],
        dz_max=length,
        dz_init=length * 1e-4,
        auto_init=True,
        backend="native",
    )
    if radial:
        responses.append(PlasmaResponse("Ar", OptmatRate("Ar", 800e-9)))
        settings = dataclasses.replace(settings, ionisation_field_range=(1e7, 1e11))
        return Simulation.from_free(
            grid,
            RadialGrid(1.5e-3, max(16, 2 * round(32 * scale))),
            medium,
            responses,
            pulse,
            settings=settings,
            noise=None,
        )
    return Simulation.from_free(
        grid,
        LineGrid(1e-3, max(32, round(128 * scale))),
        medium,
        responses,
        pulse,
        settings=settings,
    )


PROBLEMS: dict[str, Callable[[float], Simulation]] = {
    "gnlse": _gnlse,
    "capillary": _capillary,
    "averaged": _averaged,
    "radial": lambda scale: _spatial("radial", scale),
    "line": lambda scale: _spatial("line", scale),
    # Production sizes: 16384 samples (the Raman GNLSE case), four modes on 5120
    # samples (the resonant dispersive wave case), 384 radial nodes (the filament
    # case), and 4096 columns standing in for the Kerr beams' many columns.
    "gnlse_large": lambda scale: _gnlse(4.0 * scale),
    "capillary_large": lambda scale: _capillary(2.0 * scale),
    "radial_large": lambda scale: _spatial("radial", 6.0 * scale),
    "line_large": lambda scale: _spatial("line", 32.0 * scale),
}
"""The calibration problems, each built at a scale (1 is the standard size)."""


[docs] def build(name: str, scale: float = 1.0) -> Simulation: """Build one calibration problem at a scale of its standard size. Parameters ---------- name : str One of :data:`PROBLEMS`. scale : float, optional Its grid's size relative to the standard one: the time window of the one-dimensional problems, the transverse count of the spatial ones. Returns ------- solprop.driver.Simulation The simulation, on the native backend, without noise. Raises ------ KeyError For an unknown name. """ return PROBLEMS[name](scale)