Developer guide

CPMpy is an open source project and we are happy for you to read and change the code as you see fit.

This page introduces how to get started on developing on CPMpy itself, with a focus on sharing these changes back with us for inclusion.

Setting up your development environment

The easiest is to use the pip to do an ‘editable install’ of your local CPMpy folder.

pip install --editable .

With that, any change you do there (including checking out different branches) is automatically used wherever you use CPMpy on your system.

Running the test suite

We only accept pull requests that pass all the tests. In general, you want to know if your changes screwed up another part. From your local CPMpy folder, execute:

python -m pytest tests/

This will run all tests in our tests/ folder.

You can also run an individual test, as such (e.g. when wanting to test a new solver):

python -m pytest tests/test_solvers.py

Code structure

  • tests/ contains the tests

  • docs/ contains the docs. Any change there is automatically updated, with some delay, on https://cpmpy.readthedocs.io/

  • examples/ our examples, always happy to include more

  • cpmpy/ the python module that you install when doing pip install cpmpy

The module is structured as such:

  • model.py contains the omnipresent Model() container

  • expressions/ Classes and functions that represent and create expressions (constraints and objectives)

  • solvers/ CPMpy interfaces to (the Python API interface of) solvers

  • transformations/ Methods to transform CPMpy expressions in other CPMpy expressions

  • tools/ Set of independent tools that users might appreciate.

The typical flow in which these submodules are used when using CPMpy is: the user creates expressions which they put into a model object. This is then given to a solver object to solve, which will first transform the expressions into expressions that it supports, which it then posts to the Python API interface of that particular solver.

Tools are not part of the core of CPMpy. They are additional tools that use CPMpy, e.g. for debugging, parameter tuning etc.

Github practices

When filing a bug, please add a small case that allows us to reproduce it. If the testcase is confidential, mail Tias directly.

Only documentation changes can be directly applied on the master branch. All other changes should be submitted as a pull request.

When submitting a pull request, make sure it passes all tests.

When fixing a bug, you should also add a test that checks we don’t break it again in the future (typically, the case from the bugreport).

We are happy to do code reviews and discuss good ways to fix something or add a new feature. So do not hesitate to create a pull request for work-in-progress code. In fact, almost all pull requests go through at least 1 revision iteration.