Operator-splitting method for integrating Langevin equations of directed percolation (DP) type
dplvn: A Python/C++ package for integrating the directed-percolation (DP) Langevin equation — and more generally, for integrating Langevin equations that represent absorbing phase transitions.
The 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,1]:
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.
Program 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 wrapper_pybind.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_:
- The 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.
The 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.
- The 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.
Installation
At minimum, you will need Python≥3.12 and the package pybind11 to allow installation of dplvn. To run the demos, you will also need numpy, matplotlib, jupyter, and ipython.
If you use conda or miniconda, take a look at the environment.yml file and use it to set up a suitable Python environment. If you prefer to use pip, you can either install the requisite packages by hand, or use the requirements.txt file (it's very strict, so it may not be helpful, but you can use it as a guide).
Then, use pip to install the dplvn package from TestPyPI into whatever Python environment you have set up (even if you use conda):
pip install -i https://test.pypi.org/simple/ dplvn
This only works if we have pre-built a binary wheel for your platform: we currently support macOS 14, macOS 15, and all(?) flavors of Linux.
Once project development has matured, the dplvn package will be made available on the full PyPI site with broader platform support. Its package dependencies will then be made automatic; apparently it's not currently possible to set such dependencies with TestPyPI without incurring problems. Eventually, dplvn may also be made available via conda.
Build from source
If your platform is not explicitly supported with a pre-built binary, the following will force a build from source:
pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ -v --no-binary :all: dplvn
Be aware that this takes a long time, because it recompiles pretty much everything needed.
The package can also be built "by hand." Some build info is provided in src/ directory. The build system is meson-python, using pybind11 as the C++ wrapper.
Usage
Simple demos are provided in the test/ directory. The easiest route is to git clone the repo to get these files, or you can download one-by-one.
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"
