Repository navigation
solprop 0.1.0
The first public release of solprop and of its compiled backend, solprop-native,
which is released at the same version. Releases are 0.x for now: a minor release may
break the API, the output schema or the resume key, and lists every such break under
"Changed (breaking)" (ADR-058).
Added
- Propagation equations. The unidirectional pulse propagation equation (UPPE) and
the generalised nonlinear Schrödinger equation (GNLSE), for the real electric field or
a complex envelope, in waveguides and in free space. - Waveguides.
- Gas-filled hollow capillaries, with resolved modes (the default) or mode-averaged
(mode_average=Trueonprop_capillaryandprop_waveguide). Tapers,
pressure gradients and gas flow are supported, as is a coherent wall that couples
the modes. - Antiresonant hollow-core fibres (the Vincetti model).
- Step-index, graded-index, rectangular and planar guides.
- Modes tabulated from arrays or from external mode solvers.
- A general modal route for any guide that supplies its own electric and magnetic
mode fields, including guides that change along their length.
- Gas-filled hollow capillaries, with resolved modes (the default) or mode-averaged
- Free space. Radial, Cartesian and line grids with the exact (non-paraxial)
diffraction operator; planar guides can be resolved across their width. Launches,
shot noise, energies, fluences and intensities measure the medium's axial Poynting
flux at the plane, so a requested energy is the physical energy there
(SEP 34).
Far-field and aperture statistics. - Media and responses.
- Gases, gas mixtures, glasses and metals from the optmat
material library. - Kerr and third-harmonic nonlinearity, including a dispersive electronic response.
- Photoionisation with atomic and molecular rate models, and plasma on field and
envelope grids. - Rotational and vibrational Raman responses, scalar and vector.
- Quantum shot noise, on by default
(SEP 37):
one photon per mode with a random phase, added to the input field (noise="input")
and recorded with its seed. A resumed run draws the same realisation again, and a
scan draws each point's from a seed of its own.
noise=Noneswitches it off andnoise="modified"keeps the realisation apart
from the field. The Cartesian, line and hybrid planar grids, slab mode sets, the
TDSE response and single precision carry none by default and record why. Spectral
densities can subtract the one-photon floor (noise_floor="subtract"). - An optional helium TDSE atomic response for research. Its native backend is not
yet publicly available.
- Gases, gas mixtures, glasses and metals from the optmat
- Integrators and their defaults.
- Two adaptive integrators: a low-call exponential Adams method (
Multistep()) and
an embedded interaction-picture Runge–Kutta pair (RungeKutta()), with a
low-storage Runge–Kutta variant and fixed schedules. The linear propagation is
integrated exactly. - Each interface has its own default integrator and tolerances, chosen by
measurement:RungeKutta()forprop_gnlse(rtol1e-7),prop_waveguide(1e-5)
andprop_free(1e-4);Multistep()forprop_capillary(1e-6),prop_radial
andprop_planar(1e-5). The
choosing-a-stepper page
tabulates them and says when to choose another. Multistep(carrier_frame="scalar"), an opt-in carrier frame for the Adams history
that is the fastest method measured on dense, multimode, Raman-active runs such as
a comb-to-continuum capillary
(SEP 35).- Backends agree with each other to bounded, rounding-level differences.
- Two adaptive integrators: a low-call exponential Adams method (
- Time-window boundaries
(SEP 21).
Every interface absorbs at the edges of the time window and of the spectrum. The
temporal collar lies outside the requested window: the grid widens to
trange / (1 - 2 collar_fraction)(collar_fraction0.1), so the whole request is
flat, and transform sizes default tofft_size="auto", the cheapest 2-3-5-smooth
size up to the next power of two.absorber=Falseswitches the soft collars off and
keeps the same grid. A boundary monitor, on by default (boundary_check=on every
prop_*function andSimulation.from_*constructor), warns (BoundaryWarning) and
then stops the run (BoundaryError) when light above the shot-noise floor reaches
the window's edge, and records the energy the collar removed. - Coupling simulations
(SEP 31).
solprop.couplinghands a field from one simulation to the next. AFieldPlane
holds a coherent field at one plane with its reference and provenance;couplemaps
it into another simulation'sInputPortunder a declaredCouplingModeland returns
an energy report;transportcarries a free-space plane through lenses, apertures,
masks, mirrors, interfaces and spectral filters;Outcouplesynthesises a guide's
exit field. An incident beam launches into a general modal guide with the share of
its energy that the guide captures. Each step is admitted against an error budget and
refuses what it cannot certify. - Backends.
numpy_ref, the NumPy reference, against which every other backend is tested
within derived error bounds, andnumba_cpu, compiled with Numba. The backends come
in tiers: new features land onnumpy_refandnative;numba_cpuis mature and
takes a new feature only where its design says so;mlxis experimental.- The optional native backend,
the solprop-native distribution: C++20 kernels on Kokkos for multi-core CPUs
(OpenMP) and for NVIDIA and AMD GPUs (CUDA, HIP).pip install "solprop[native]"
installs a precompiled CPU wheel on macOS on Apple silicon, Linux on x86-64 and
aarch64, and Windows on x86-64.backend="auto"selects it when installed, except
on a processor below the wheel's CPU baseline, where it usesnumba_cpuand warns
once (SEP 29).
On the native backend the exponential Adams march runs in compiled code, many steps
per call
(SEP 39). - One thread budget per process, which every pool of both CPU backends stays within:
the smallest of the CPU affinity mask, the physical cores that hold it, the
control group's CPU quota andSOLPROP_THREADS(ADR-052). - Single precision
(SEP 33):
precision="single"holds the state, the transforms and the responses in binary32,
with the controller in binary64.numpy_refruns it as the reference, and themlx
backend (pip install "solprop[mlx]") on the Apple GPU. A
survival record
states which problems keep their accuracy.
- Running and recording.
- HDF5 output with periodic snapshots and provenance, and resuming an interrupted
run, which continues the Adams history. - A summary at the start of every run of what it is about to compute (the code, the
machine, the backend, the grid, the medium, the responses, the noise, the
integrator, the absorber and the output), and at its end the wall time, CPU time
and peak memory. Each execution records its machine and what it spent in the file. - Statistics along the propagation.
- Parameter scans on process pools and Slurm clusters.
- HDF5 output with periodic snapshots and provenance, and resuming an interrupted
- Analysis and tools.
- Processing and plotting. Spectral ranges and band-pass windows are given in the
units of any spectral axis (spec_range,Passband). - Ensemble coherence by spectral band, and replay of a run's accepted steps
(FixedSchedule.from_history), to compare two precisions or backends on one
discretisation. - Soliton and dispersive-wave design tools.
- Pulse compressors: Taylor phase, chirped mirrors, materials, gratings and prisms.
- An interactive session through
import solprop.sol as sol.
- Processing and plotting. Spectral ranges and band-pass windows are given in the
- Performance tracking for developers
(SEP 38):
python -m benchmarks tracktimes about a dozen representative workloads, with each
interface's defaults, at one thread and at the production width, and records them by
hardware;python -m benchmarks abcompares two builds. - Documentation. An introduction with executable lessons, a user guide, a
long-form primer on the physics and numerics, focused tutorials and worked examples,
the API reference, and a developer's guide with the design records (SEPs and ADRs).
Changed (breaking)
Nothing was released before 0.1.0. For scripts and files from a development checkout:
- Output files of development versions are not read. The output schema restarts at
1 (solprop.output.SCHEMA_VERSION); keep the development install that wrote such a
file to read it. The kernel contract's version isKERNEL_SCHEMA_VERSION, separate
from it. - Defaults changed late in development, so a development script's results change:
shot noise is on; each interface takes its own integrator and tolerances; the
temporal collar lies outside the requested window, which widens the grid
(collar_placement="inside"rebuilds the former geometry); transform sizes are
fft_size="auto"; and the boundary monitor is on. - Renamed or removed.
prop_gnlse,prop_capillary,prop_waveguideand their
Simulation.from_*constructors takewavelengthandshape, notlambda0and
pulseshape, andresponses_fortakeswavelength, as the pulses and the design
tools already did. The plots'wavelength_rangeisspec_range, in the units of
their axis, andsolprop.plotting.style.spectral_limitsis gone
(wavelength_to_axisconverts a wavelength range);bandpasstakeslimits, not
wavelength_limits;poynting_spectrumis gone (beam_spectrumis the axial-flux
spectrum); thesame_basisfunction is gone (usecouple); andsolprop.driverno
longer exportspropagate_fixed_rk4, the tests' fixed-step oracle.Multistep()
refuses thePIControllersettings it does not read.
Known limitations
- The
mlxbackend is experimental. Its Metal kernels are tested by hand on a
Metal device, not in continuous integration, and its coverage is not measured there.
The single-precision survival record is the reference implementation's (onmlxfor
two cases). On the defaultfft_size="auto"grids MLX's GPU transform runs four to
eight times slower than on powers of two, so a run can be slower than binary64
native: build single-precision grids withfft_size="pow2". The guide's speed table
predates the current grids and is marked so. - Free space has no accurate transverse absorber. By default a radial grid's edge is
a hard wall and a Cartesian or line grid wraps around; the optional real-space collar
(an absorber given to a spatial run,Absorber.spatial) removes only part of the light that reaches it, at a large cost
in steps, and the boundary monitor watches the time window only. Size the transverse
window so that the light stays clear of its edge.
SEP 40
(a draft) rebuilds these boundaries. - A run is resumed by the release that wrote it. A run's configuration hash covers
every recorded field, so a release that adds one changes every hash, and within 0.x
the output schema may change too: finish a run with the release that started it. - GPU builds are made from source. The wheels are for CPUs; CUDA and HIP builds of
solprop-native are built from the repository
(building the native backend). - CPython 3.14 only. solprop-native, pyFFTW and h5py have no wheels for 3.15 yet.
- macOS: import solprop before pyFFTW. pyFFTW's macOS wheel starts its own OpenMP
runtime, so the native backend refuses to load in a process that imported pyFFTW
first; solprop itself imports them in the working order.