Tools to integrate Langevin equations of absorbing phase transition (APT) type — with a focus on simulation of directed percolation (DP).
The lvn 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.
Design of lvn package
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 src/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_:
- The src/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 Langevin 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 src/dp/dplangevin_* files define this Langevin 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 src/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 lvn. 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 lvn package from TestPyPI into whatever Python environment you have set up (even if you use conda):
pip install -i https://test.pypi.org/simple/ lvn
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 lvn 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, lvn 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: lvn
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"
