Skip to content

# Design of `langevin` package

The DP/APT Langevin-equation integrator package is fundamentally a `C++` code base with Python support modules, all bundled into a `pip`-installable package,

## Core C++

This `C++` is split into three groups, with files in each group denoted by one of the following prefixes: (1) `langevin_`; (2) `dplangevin_`; (3) `sim_dplangevin_`. The code itself can be found here and its Python wrapping is located here; detailed documentation, auto-generated by Doxygen, is available here.

### `langevin`

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.

### `dplangevin`

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.

### `sim_dplangevin`

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.

## Wrapping

To make the core `C++` code accessible to Python, there is a wrapper file called `cplusplus/dp/wrapper_dplvn.cpp`. It uses `pybind11` to link the `C++` code to a Python runtime via a class instance.

## Python support modules

The `langevin` package includes several Python modules to support use of the core `C++`-based integrator. They are grouped into a set of base modules, located in the `base` folder, and a set of DP-application modules, which can be found in the companion `dp` folder.

In addition, Python scripts and related Jupyter notebooks are provided to help run DP-type Langevin simulations (documented here).

The base modules are:

- base/file.py
- base/serialize.py
- base/utils.py
- base/viz.py

The DP-specific modules are:

- dp/ensemble.py
- dp/simulation.py
- dp/vizdp.py