langevin

Tools to integrate Langevin equations of absorbing phase transition (APT) type — with a focus on solution of the directed percolation (DP) Langevin equation.

The langevin package implements the operator-splitting method originally developed by Dornic et al (2005), Pechenik & Levine (1999) and others, and improved upon by Weissmann et al (2018). It provides a Python wrapper around core C++ heavily adapted from a code base written by Paula Villa Martín, extended by Victor Buendía ("VMB"), and arising from earlier efforts by Ivan Dornic and Juan Bonachela. The wrapper provides easy access to the Langevin integrator, and broad opportunity to experiment, adapt, and extend it further.

The current C++ implementation extends the VMB code to allow run-time specification of grid dimension and size, boundary topology (bounded or periodic), boundary conditions, and initial conditions. It further provides tools for running model integration in batches, time-slicing the Langevin field grid, and recording of time-series of grid properties.

The equation solved in the demo here is the DP Langevin for a 2D grid with initial values sampled from U[0, 0.3]:

where ρ(x,t) is the order parameter field, a and b are rate constants, D is the diffusion rate over x, ξ(x,t) is Gaussian white noise (uncorrelated, zero mean, unit variance), and η is the "demographic" noise amplitude.

See Victor Buendía's fork of Paula Villa Martín's repo for details on more general applications and on how the integration scheme is implemented.

Installation

In most circumstances, pip install langevin should suffice to get things up and running. See below more comprehensive installation notes, or here in the main documentation.

Optional: Python environment

First, set up a suitable Python environment. This is optional, but recommended. The simplest tool is uv, but there are several other options. If you use conda or miniconda, take a look at the environment.yml file provided.

Using uv, all that's needed is to create an appropriately named folder (within which you want to use the environment), navigate to it, and execute:

uv venv --python=3.14
source .venv/bin/activate

where the --python option forces uv to choose version 3.14 of the Python interpreter (recommended).

Package from PyPI

Then, install the langevin package from PyPI:

[uv] pip install langevin

where uv is needed only if you are using that tool. This step should automatically install all the dependencies as well. If it does not, see below.

Usage

Simple demonstration scripts are provided in demos/. More complete examples are provided in the simulation/ directory. The easiest route is to git clone the repo to get these files, or you can download one-by-one.

Platform support

All major platforms (Linux, macOS, Windows) are supported: binary wheels are provided for all the recent releases. If you have a different vintage OS, you can build from source (using pip — see below), and the code should work fine.

Software design

The structure of the DP/APT Langevin-equation integrator package is broadly as follows (detailed documentation is available here).

First, there is a wrapper file called cplusplus/dp/wrapper_dplvn.cpp that uses pybind11 to link the C++ code to a Python runtime.

Next, the code is split into a hierarchy of three groups, with each corresponding file denoted by one of following prefixes: (1) sim_dplangevin_, (2) dplangevin_ and (3) langevin_:

1. The cplusplus/dp/sim_dplangevin_* files provide a SimDP class, made available through the wrapper at the Python level, required to manage and execute DP Langevin model integration. This SimDP class instantiates a DPLangevin class integrator to do the hard work of numerical integration of the stochastic differential equation. Langevin field density grids are returned to Python (via the wrapper) as numpy arrays as are time series of the mean density field and its corresponding epochs.

2. The cplusplus/dp/dplangevin_* files define this DPLangevin integrator class. They inherit the general BaseLangevin integrator class and implement several methods left undefined by that parent; most important, they define methods implementing the particular functional form of the directed-percolation Langevin equation and its corresponding nonlinear, deterministic integration step in the split operator scheme.

   Other types of absorbing-phase transition-type Langevin equation could be implemented with alternate subclasses of BaseLangevin and alternate versions of the SimDP class.

3. The cplusplus/langevin_* source files provide the base BaseLangevin class that implements the operator-splitting integration method in a fairly general fashion. Grid geometry and topology, boundary conditions, initial conditions, the integration scheme, and a general form of the Langevin equation are all coded here. The core Dornic-style integrator is a heavily altered version of the Villa-Martín and Buendía code.

Build from source

Dependencies

At minimum, langevin needs Python≥3.12 and the package pybind11. To run the demos, you will also need numpy, matplotlib, jupyter, ipython, along with pandas, tqdm, and ffmpeg-python. If you are using conda or miniconda, it would be best to install them using the environment.yml file, instead of relying on pip to do the job (mixing pip and conda is not a great idea anyway, but langevin is not yet available on conda).

If you want to build locally, you will also need meson-python, wheel, pybind11, and ninja.

To turn density field image sequences into animations, langevin uses ffmpeg-python, which assumes that ffmpeg is itself installed on your system.

On Linux platforms, matplotlib has a tendency to complain about missing fonts, e.g., Arial, generating large numbers of warnings in some of the notebooks. This can be fixed by installing the missing fonts and ensuring that matplotlib's cache is refreshed.

Build using pip install

If your platform is not explicitly supported with a pre-built binary, the following will force a build from source:

[uv] pip install -v langevin --no-binary langevin

Alternative: build by hand

The package can also be built "by hand." Some build info is provided in the cplusplus/ directory. The build system is meson-python, using pybind11 as the C++ wrapper.

References

• Buendía, 2019: "Dornic integration method for multipicative [sic] noise" (fork of GitHub repo by Villa Martín)

• Buendía et al, 2020: "Feedback mechanisms for self-organization to the edge of a phase transition"

• Dornic et al, 2005: "Integration of Langevin equations with multiplicative noise and the viability of field theories for absorbing phase transitions"

• Pechenik & Levine, 1999: "Interfacial velocity corrections due to multiplicative noise"

• Villa Martín et al, 2014: "Eluding catastrophic shifts"

• Villa Martín, 2019 (GitHub repo): "Dornic integration method for multipicative [sic] noise" [shared PDF]

• Weissmann et al, 2018: "Simulation of spatial systems with demographic noise"