Guide for Developers


FlamingPy requires the following Python version to be installed:

as well as the following Python packages for development purposes:

If you currently do not have Python 3 installed, we recommend Anaconda for Python 3, a distributed version of Python packaged for scientific computation.

Setting up a development environment

If you are a developer and wish to manipulate and test FlamingPy source code, you need to set up a development environment. First, clone the FlamingPy repository. Then, create and activate a new virtual environment (if you prefer using an existing environment, you may need to uninstall existing FlamingPy builds). If you use Conda, for example, you may run the following:

conda create -n flamingpy python=3.8
conda activate flamingpy

FlamingPy uses a pytest suite for testing and pytest-cov for code coverage. These dependencies among compilation and other requirements as stated in the above section can be installed via pip:

python -m pip install -r dev_requirements.txt

Using MPI

FamingPy’s frontend simulator script,, now supports simple and highly-scalable MPI jobs through mpi4py libraries in a non-intrusive manner. The users who do not have or want MPI, can run single-threaded as per usual without facing any errors. MPI users can speed up Monte Carlo samplings in EC steps virtually up to as many processors they can throw at it. The script support jobs both on local machines and large-scale clusters.

To setup FlamingPy’s MPI dependencies on a linux system run

sudo apt install libopenmpi-dev
python -m pip install mpi4py>=3.1.3

and continue with the steps described in the following section.

Then, MPI users on their local machines can simply run the following for a 4-processor job:

mpirun -np 4 python flamingpy/

Installation from Source

To install FlamingPy from Source, next change to the directory where FlamingPy was cloned and run:

python develop # only installs Python libraries
python build_cmake --inplace # [OPTIONAL] compiles CMake-based backends

The purpose of the commands is as follows:

  • The first command installs dependencies for building the project and testing purposes, and can be skipped if already satisfied.

  • The second command (develop) installs FlamingPy Python libraries without compiling the optional backends.

  • The next optional commands compile various FlamingPy backends as required (given you have appropriate compilers pre-installed).

If you encountered a CMake error, you may need to (re-)install it through conda install cmake or other means before re-attempting the above. Furthermore, you may wish to try conda install git.

Software tests

The FlamingPy test suite includes pytest and pytest-cov for coverage reports.

To ensure that FlamingPy is working correctly after installation, the test suite can be run by navigating to the source code folder and running

python -m pytest tests

Test coverage

Test coverage can be checked by running

python -m pytest tests --cov=ft_stack --cov-report=xml --cov-report=term-missing -p no:warnings

The output of the above command will show the coverage percentage of each file, as well as the line numbers of any lines missing test coverage.

To obtain coverage, the pytest-cov plugin is needed.


See Build Documentation for the details on how to build the HTML documentation.