Information for developers

This provides some short overview on the code and the ideas and principles being used.

Everything was written in python3.6, see the file for the versions of numpy and scipy that the code was designed with.

The code uses classes and inheritance and generally follows more the OOP approach.

Also the code attempts to use the typing module for annotations wherever possible, although this is currently throwing some warnings and errors and not fully carried out.

For installation and distribution this uses a simple Makefile and the setup module. The documentation is done in rst format and created with Sphinx.

Short explanation of the program flow

The central unit is the file, it creates all the actions and runs the main loop over the time steps.

After reading the cli arguments (containing the input file) it then calls the file. This defines some custom methods on top of the configparser module (e.g. to allow lists) and then defines all possible input options and does the input parsing.

The resulting options are then processed in the files to set up all actions, sadly some of the code is duplicated here currently (the options have to be passed as the arguments of the respective setup functions of the actions)

After setup, the main loop is called for the desired number of iterations. The run() method of all actions is called in a fixed order in the loop, and not in the order they appear in the file. After the loop has finished the final_run() method of all actions is called to allow for final clean up and saving operations.


Everything that happens after initialization is an action, e.g. the Langevin dynamics, the birth-death steps but also the data storage and analysis (e.g. calculating and storing the FES).

All actions are subclasses of the bdld.action.Action class, and have to implement at least the run() method to be useable in the main loop.

The core of this code is surely the BirthDeath action, see there for how the algorithm is implemented.

Currently under development / Upcoming

The bd-estimate-FES branch hosts first attempts of using the estimated FES for the birth-death term (instead of the exact one from the potential which is typically not available).

While the basic idea is implemented, this is still work-in-progress to allow for more sophisticated schemes.

Several problems have to be addressed:

  • The main branch only allows to have each action type once, so the same histogram/FES has to be used for the birth-death scheme as for the sampling analysis. The code therefore rewrites parts of the and to allow multiple actions of the same type.

  • We want to be able to have more options on how to determine/set the equilibrium density (similarly to a “target distribution”). As a first idea, I plan implemented a “uniform density” to test the behavior, as well as estimating it from a specific histogram.

  • More sophisticated histogram schemes could then be implemented (e.g. as simple idea: introduce decay)