Developer Introduction

Contributions to ProbNum are very welcome. Before getting started make sure to read the following guidelines.

All contributions to ProbNum should be made via pull requests (PR) to the master branch on GitHub. Some suggestions for a good PR are:

  • implements or fixes one functionality;

  • includes tests and appropriate documentation; and

  • makes minimal changes to the interface and core codebase.

If you would like to contribute but are unsure how, then writing examples, documentation or working on open issues are a good way to start. See the developer guides for detailed instructions.

Getting Started

Begin by forking the repository on GitHub and cloning your fork to a local machine. Next, create a new branch in your forked repository describing the feature you would like to implement. You can now get started writing code in your new branch. Make sure to keep the following best practices regarding code quality in mind.

Code Quality

Code quality is an essential component in a collaborative open-source project.

For all of the above the existing ProbNum code is a good initial reference point.

Using Tox

Probnum uses tox in its continuous integration (CI) pipeline to run tests, build documentation, check code formatting and code quality. Under the hood, tox builds virtual environments following the specifications in ./tox.ini in order to run tests across multiple python versions, while making sure that all the necessary dependencies are installed. Using tox unifies the local development process with continuous integration builds (via Github Actions), such that local test results should match the outcomes of the CI builds more closely. This ensures that your pull request can be merged seamlessly into ProbNum’s codebase.

Install tox from the Python Package Index (PyPI) via

pip install -U tox

Once tox and the required external tools below are installed, you can run tests and build the documentation locally by simply calling


Note, to reduce runtime tox caches and reuses the virtual environment it creates the first time you run the command. If you are frequently switching between branches or adjusting the build configuration make sure to force recreation of the virtual environment via tox -r, if you experience unexpected tox failures.

Word of caution: Running tox runs all environments as specified in tox.ini, thus potentially running tests across many different Python versions. To run the full test suite make sure that you have all specified Python versions installed. Alternatively, you can run a single specific environment through tox -e <env>, e.g. tox -e py36 to run tests with Python 3.6 or tox -e docs to just build the documentation.

External Tools

Building the documentation locally requires additional packages (e.g. for inheritance diagrams), which can be found in .github/workflows/CI-build.yml. These packages are currently:

  • pandoc: In Ubuntu, install via sudo apt install pandoc

  • graphviz: In Ubuntu, install via sudo apt install graphviz

Advanced Developer Setup

For regular contributors to ProbNum we provide a configuration file .pre-commit-config.yaml with useful pre-commit hooks. These allow the automatic identification of simple issues in a commit, e.g. inconsistent code formatting. They are executed automatically whenever git commit is executed. This way one can avoid common problems in a pull request which prevent an automatic merge into the master branch on GitHub. To set up ProbNum’s pre-commit hooks simply install pre-commit by executing

pip install pre-commit

and install the configuration script via

pre-commit install

in the probnum folder.


test coverage: latest

We use unittest for testing and aim to cover as much code with tests as possible. Make sure to always add tests for newly implemented code. To run the test suite on your machine you have multiple options:

  • Full test suite with tox: Run the full suite across different Python versions with

  • Single environment with tox: Run tests for a single Python environment, e.g. for Python 3.6

    tox -e py36
  • pytest: Run tests directly in your local environment by calling


Code coverage of the tests is reported via codecov.


docs: stable docs: latest

ProbNum’s documentation is created with Sphinx and automatically built and hosted by ReadTheDocs for stable releases and the latest (master branch) version.

You can build the documentation locally via

tox -e docs

This creates a static web page under ./docs/_build/html/ which you can view in your browser by opening ./docs/_build/html/intro.html.

Alternatively, if you want to build the docs in your current environment you can manually execute

cd docs
make clean
make html

Continuous Integration

CI build

ProbNum uses Github Actions for continuous integration. For every pull request and every commit the project is built, the test suite is run, the documentation is built, the benchmarks are dry-run, the code is linted and checked for consistency with the *Black* code style. This ensures that no breaking changes are introduced by mistake. Changes to Github Actions can be made in the .github/workflows/ folder, as well as in tox.ini since Github Actions rely on tox for all the above checks.