# 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](https://pypi.org/project/langevin/),


## Core C++ 

This `C++` is split into three groups, with files in each group denoted by one of the following prefixes: 
(1) [`langevin_`](https://cstarkjp.github.io/Langevin/doxygen/dir_413eba86a22d58dd6c01dd4edd69cedc.html);
 (2) [`dplangevin_`](https://cstarkjp.github.io/Langevin/doxygen/dir_29b47bf0c8dc04d64d9bcc2119390c05.html); 
 (3) [`sim_dplangevin_`](https://cstarkjp.github.io/Langevin/doxygen/dir_29b47bf0c8dc04d64d9bcc2119390c05.html).
 The code itself can be found [here](https://github.com/cstarkjp/Langevin/tree/main/cplusplus) and its Python wrapping is located [here](https://github.com/cstarkjp/Langevin/tree/main/python);
detailed documentation, auto-generated by Doxygen, is available 
[here](https://cstarkjp.github.io/Langevin/doxygen/annotated.html). 


### `langevin`

The [`cplusplus/langevin_*`](https://cstarkjp.github.io/Langevin/doxygen/dir_413eba86a22d58dd6c01dd4edd69cedc.html) source files provide the base [`BaseLangevin` class](https://cstarkjp.github.io/Langevin/doxygen/class_base_langevin.html) 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](references.md).


### `dplangevin`

The [`cplusplus/dp/dplangevin_*`](https://cstarkjp.github.io/Langevin/doxygen/dir_29b47bf0c8dc04d64d9bcc2119390c05.html) files define this [`DPLangevin` integrator class](https://cstarkjp.github.io/Langevin/doxygen/class_d_p_langevin.html). They inherit the general [`BaseLangevin` integrator class](https://cstarkjp.github.io/Langevin/doxygen/class_base_langevin.html)  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`](https://cstarkjp.github.io/Langevin/doxygen/class_base_langevin.html) and alternate 
versions of the [`SimDP` class](https://cstarkjp.github.io/Langevin/doxygen/class_sim_d_p.html).

### `sim_dplangevin`

 The [`cplusplus/dp/sim_dplangevin_*`](https://cstarkjp.github.io/Langevin/doxygen/dir_29b47bf0c8dc04d64d9bcc2119390c05.html) files provide a [`SimDP` class](https://cstarkjp.github.io/Langevin/doxygen/class_sim_d_p.html), made available through the wrapper at the Python level, required to manage and execute DP Langevin model integration.  This [`SimDP` class](https://cstarkjp.github.io/Langevin/doxygen/class_sim_d_p.html) instantiates a [`DPLangevin` class integrator](https://cstarkjp.github.io/Langevin/doxygen/class_d_p_langevin.html) to do the hard work of numerical integration of the stochastic differential equation. Langevin field density grids are returned to Python [(via the wrapper)](https://cstarkjp.github.io/Langevin/doxygen/wrapper__dplvn_8cpp.html) 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`](https://cstarkjp.github.io/Langevin/doxygen/wrapper__dplvn_8cpp.html). 
It uses [`pybind11`](https://pybind11.readthedocs.io/en/stable/) to link the [`C++` code](https://cstarkjp.github.io/Langevin/cplusplus/) 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](https://github.com/cstarkjp/Langevin/tree/main/python/base),
and a set of DP-application modules, which can be found in the companion
[`dp` folder](https://github.com/cstarkjp/Langevin/tree/main/python/dp).

In addition, [Python scripts and related Jupyter notebooks](https://github.com/cstarkjp/Langevin/tree/main/simulation/dp) are provided to help run DP-type Langevin simulations 
(documented [here](python-modules/simulation-reference.md)).

The base modules are:

- [base/file.py](python-modules/file-reference.md)
- [base/serialize.py](python-modules/serialize-reference.md)
- [base/utils.py](python-modules/utils-reference.md)
- [base/viz.py](python-modules/viz-reference.md)

The DP-specific modules are:

- [dp/ensemble.py](python-modules/ensemble-reference.md)
- [dp/simulation.py](python-modules/simulation-reference.md)
- [dp/vizdp.py](python-modules/vizdp-reference.md)

