Adding a new solver

Solvers must adhere to the libmobility::Mobility interface (see include/MobilityInterface). This C++ base class unifies all solvers under a common interface. Once the C++ interface is prepared, Python bindings can be added automatically using pythonify.h (a tool under MobilityInterface).

Solvers are exposed to Python and C++ via a single class that inherits from libmobility::Mobility.

Directory Structure

A new solver must add a directory under the “solvers” folder, which must be the name of both the Python and C++ classes. Inside the solver directory, the following files (and only these files) must exist:

mobility.h

This file must include MobilityInterface.h and define a single class, named the same as the directory for the solver, that inherits the libmobility::Mobility base class. For example, in solvers/NBody/mobility.h:
```
class NBody: public libmobility::Mobility {
    // ...
};
```
Functions that are not purely virtual offer default behavior that can be overridden. For example, \(\sqrt{\boldsymbol{\mathcal{M}}}d\boldsymbol{W}\) defaults to using the iterative Lancozs algorithm and the thermal drift defaults to returning zero. Confined solvers that have a non-zero thermal drift, such as NBody with a bottom wall and DPStokes, override the function to provide a thermal drift.
python_wrapper.cu

This file must provide the Python bindings for the class in mobility.h. If the class follows the libmobility::Mobility interface correctly, this file can generally be quite simple, using the MOBILITY_PYTHONIFY or MOBILITY_PYTHONIFY_WITH_EXTRA_CODE utility in include/MobilityInterface/pythonify.h. For example:
```
MOBILITY_PYTHONIFY(MODULENAME, documentation)
```
or
```
MOBILITY_PYTHONIFY_WITH_EXTRA_CODE(MODULENAME, EXTRA, documentation)
```
See solvers/NBody/python_wrapper.cpp for an example.
CMakeLists.txt

This must contain rules to create the shared library for the particular solver and its Python wrapper. The solver library should be called “lib[Solver].so”, while the Python library should be called “[Solver].[Python_SOABI].so” with the correct extension suffix.
README.md

The documentation for the specific module (anything relevant about the particular solver that does not fit the class docstring).
tests

Add any relevant tests to the test folder using pytest.
extra

Any additional source files required for the compilation of the solver.

Additional Considerations

A new line should be added to solvers/CMakeLists.txt to include the new module in the compilation process.
Some interface functions provide default behavior if not defined. For example, stochastic displacements will be computed using a Lanczos solver if the module does not override the corresponding function.
The LangevinVelocities function defaults to calling Mdot followed by sqrtMdotW and finally divM.
The clean function defaults to doing nothing.
The initialize function of a new solver must call the libmobility::Mobility::initialize function at some point.

Python-only Modules

In the case of a module being Python-only (or not providing a correct child of libmobility::Mobility), python_wrapper.cu may be omitted. Instead, a file called [solver].py must exist, providing a Python class that is compatible with libmobility::Mobility. This allows users to write from solver import * and get a class called “solver” that adheres to the libmobility requirements.

Additional Parameters

When a module needs additional parameters beyond those provided to initialize, an additional function called setParameters[SolverName] must be defined and exposed to Python. See solvers/PSE/mobility.h and solver/PSE/python_wrapper.cu for an example. Users of the library are responsible for calling setParameters before calling initialize with the required arguments.

Examples

See solvers/SelfMobility for a basic example.
The NBody solver only provides an initialization, Mdot and divM functions, demonstrating the use of default implementations for other methods.

Using the default fluctuation computation

If the sqrtMdotW function is not implemented, libMobility will automatically provide the functionality using the Lanczos algorithm. No extra step is needed to adhere to it.

Using Random Finite Diferences for thermal drift computation

By default it is assumed that the divergence of the mobility is null. If the new solver has a non-zero divergence and offers no way to compute this term you can use the available functions for computing using only Mdot via RFD. See the NBody solver for an example