Get and install solprop#

You need Python 3.14 or newer and an environment in which you can install Python packages. On the four platforms with prebuilt wheels, install solprop together with its compiled native backend, the fastest way to run it; elsewhere, solprop’s included CPU backends run every model, and the native backend can be built from source and added later without changing the physical model. The installation commands bring in the dependencies: NumPy, SciPy, Matplotlib, h5py, Numba, pyFFTW (FFTW transforms for the Numba backend), optmat with its gas extra (the curated material library every built-in gas, solid, Raman response and ionisation rate comes from, with its equations of state through CoolProp), threadpoolctl (BLAS thread control), jaxtyping (array annotations) and tqdm (progress bars). solprop keeps no material data of its own: see materials for how model data are selected.

Installing solprop#

Install solprop from the Python Package Index, with its native backend. With uv (recommended):

uv venv --python 3.14
uv pip install "solprop[native]"
source .venv/bin/activate   # on Windows: .venv\Scripts\activate

or with pip into an existing Python 3.14 environment:

python -m pip install "solprop[native]"

The native extra adds solprop-native, the compiled native backend, at solprop’s own version. It is a precompiled wheel on four platforms:

platform	system
osx-arm64	macOS on Apple silicon
linux-64	Linux on x86-64
linux-aarch64	Linux on aarch64
win-64	Windows on x86-64

With it installed, backend="auto" uses the native backend (The native backend describes what it runs).

Processor requirements. The wheels are compiled for a minimum processor:

platform	minimum processor
osx-arm64	any Apple silicon Mac (M1 or newer)
linux-64, win-64	x86-64-v3: AVX2, FMA and BMI2, that is Intel Haswell (2013) or AMD Excavator (2015) and newer
linux-aarch64	Arm Neoverse N1 (Armv8.2-A with dot product and half precision): AWS Graviton2, Ampere Altra and newer

Low-power Intel Atom, Celeron and Pentium chips without AVX are below x86-64-v3 even when recent, as are older cluster nodes. On such a processor the native package refuses to load, naming the features it lacks, before any of its compiled code runs. backend="auto" then uses the numba_cpu backend instead and warns once, saying so; every model still runs, at the included backend’s speed. An explicit backend="native" raises the refusal. To use the native backend on such a machine, build it from source for it (Building the native backend), and please open an issue so that the maintainers know such processors are in use.

Other platforms. Install solprop alone, uv pip install solprop or python -m pip install solprop. This gives two backends, the NumPy reference backend and the compiled Numba CPU backend (see Choosing a backend), which run every model; consult backend support when choosing a representation or response, since some combinations require a particular backend. The native backend can then be built from source.

GPUs and source builds. For an NVIDIA GPU (CUDA) or an AMD GPU (HIP), and on any platform without a wheel, build the native backend from source: Building the native backend gives the requirements and the commands. A source build can also be compiled for the machine that runs it, which is a few per cent faster than the wheel.

For the development version, install from the repository instead (python -m pip install "git+https://github.com/LupoLab/solprop.git"); to work on solprop itself, use the contributor setup.

Checking the installation#

Use Python in the activated environment, or a notebook kernel using that same interpreter. Run the following code; it prints the package versions and the backends available to this interpreter.

import optmat

import solprop
from solprop.backends.registry import available, resolve_name

print("solprop", solprop.__version__, "with optmat", optmat.__version__)
print("backends:", available(), "- auto means", resolve_name("auto"))

available() lists the backends that are installed and resolve_name("auto") names the one a run uses by default: native when the native backend is installed. The first run of the numba_cpu backend compiles its kernels. This can make the first calculation slower than subsequent runs; many compiled kernels are cached on disk. Measure performance after that initial setup.

Make a first short run#

This small linear-envelope calculation checks that propagation and output work. The nonlinear coefficient is zero and the dispersion coefficients are zero, so the pulse should keep its energy. The propagation is only 1 mm; it is an installation check, not a demonstration of nonlinear dynamics.

import numpy as np

from solprop.driver import prop_gnlse
from solprop.processing import energy

run = prop_gnlse(
    0.0,
    1e-3,
    [0.0, 0.0, 0.0],
    lambda0=800e-9,
    fwhm=50e-15,
    energy=1e-9,
    trange=400e-15,
    wavelength_limits=(600e-9, 1.2e-6),
    shock=False,
    n_save=3,
    progress="none",
)
energies = energy(run, modes="sum")
print("saved positions (m):", run["z"])
print("input and exit energy (nJ):", energies[[0, -1]] * 1e9)
assert np.isclose(energies[-1], energies[0], rtol=1e-8, atol=0.0)

An approximately 1 nJ input and exit confirm this check. Continue with what solprop can do and choosing a spatial description, then run the dispersive-wave lesson for a complete physical example. For package import or backend errors, check that the interpreter is the one in which you installed solprop and inspect backend selection.

Platforms#

solprop is developed and tested on macOS (Apple silicon), Linux (x86-64) and Windows (x86-64). Single runs and scans work on all three with the included backends. The native backend has wheels for the four platforms above, builds from source on Linux and macOS, and builds for GPUs on Linux. The Queue and Slurm scan executors need a POSIX system and refuse to start on Windows; Local and Pool run there. On Windows a scan’s readers take its lock one at a time, where POSIX lets them read together, so concurrent reads of one scan file wait for each other.

The precompiled native wheels and the solprop[native] extra were proposed and qualified by SEP 29.