Adding a potential

In this tutorial we will teach you how to use your own potential function with Lumol. This tutorial consists of two parts. In the first part, we will implement the logic in a separate project using Lumol as an external library. The second part describes the neccessary steps to implement the logic into the core package of Lumol called lumol-core.

A potential is a function that describes the energy and force between interaction sites. In Lumol we differentiate between two types of potentials: First, there are potential functions that need the global state of the system, i.e. all positions, as input. The Ewald summation which is used to compute electrostatic interactions is an example for this kind of potential. We call them GlobalPotentials. And second, we have potentials that take a single geometric parameter as input. This geometric parameter can be for example a distance or an angle. Typical examples are Van-der-Waals potentials (e.g. Lennard-Jones) and potential functions describing covalent bonds (e.g. harmonic potential, cosine potential, torsion, etc.). There are plenty of potentials falling into this category, hence in Lumol we simply call them Potentials.


There are two kind of potentials. A GlobalPotential takes the global systems’ state as input and a Potential takes a single scalar value (distance, angle, …) as input.

In this tutorial we will focus on the implementation of the latter. More specific, we will implement a potential to compute van-der-Waals interactions between pairs of particles. We will make liberal use of the API documentation of both the Rust standard library as well as the Lumol API. Please note that we will point to other references, such as the Rust book, concerning general Rust concepts to keep this tutorial brief. If you have questions concerning Rust or Lumol, please don’t hesitate to file an issue on github or join the discussion on our gitter.

The tutorial is structured as follows: First we will have a look at how Potentials are represented (what data structures are used) and what functionalities we have to implement. Then, we describe how we add those functionalities. We will write a small simulation program that makes use of our newly created potential. In the second part we talk about implementing the potential into Lumol’s core. Rust offers beautiful utilities to add documentation inside the code. We will have a look at the documentation of currently implemented potentials to guide us. We will then add some tests to make sure that our implementation is correct. This concludes the bulk the work, but to make our new potential function accessible to all Lumol users we will also add a parsing function. Doing so, our potential can be conveniently specified from an input file. We conclude the tutorial by adding a short documentation to the user manual.

In this tutorial, we will implement a potential to describe non-bonded pair interactions, namely the Mie potential.

We have a lot to do. Ready? Let’s go.


We recommend you read the chapters concerning structs and traits in the rust book.