Ready to contribute to the project? Here is how to set up a local development environment.
Fork the cda-tum/mqt-qmap repository on GitHub (see https://docs.github.com/en/get-started/quickstart/fork-a-repo).
Clone your fork locally
$ git clone email@example.com:your_name_here/mqt-qmap --recursive
--recursiveflag is required to also clone all the required submodules. If you happen to forget passing the flag on your initial clone, you can initialize all the submodules by executing
git submodule update --init --recursivein the main project directory.
Change into the project directory
$ cd mqt-qmap
Create a branch for local development
$ git checkout -b name-of-your-bugfix-or-feature
Now you can make your changes locally.
(Optional, highly recommended) Set up a virtual environment
$ python3 -m venv venv $ source venv/bin/activate
If you are using Windows, you can use the following command instead:
$ python3 -m venv venv $ venv\Scripts\activate.bat
Ensure that pip, setuptools, and wheel are up to date:
(venv) $ pip install --upgrade pip setuptools wheel
(Optional, highly recommended) Setup nox to conveniently run many development tasks.
(venv) $ pipx install nox
If you use macOS, then nox is in brew, use
brew install nox.
If you do not have pipx (pip for applications) installed, you can install it with:
(venv) $ pip install pipx (venv) $ pipx ensurepath
If you use macOS, then pipx is in brew, use
brew install pipx.
(Optional) Install pre-commit to automatically run a set of checks before each commit.
(venv) $ pipx install pre-commit (venv) $ pre-commit install
If you use macOS, then pre-commit is in brew, use
brew install pre-commit.
Make sure to have the SMT Solver Z3 >= 4.8.15 installed. This can be accomplished in a multitude of ways:
Under Ubuntu 20.04 and newer:
sudo apt-get install libz3-dev
brew install z3
pip install z3-solverin the virtual environment
Download pre-built binaries from https://github.com/Z3Prover/z3/releases and copy the files to the respective system directories
Build Z3 from source and install it to the system
Working on the core C++ library#
Building the project requires a C++ compiler supporting C++17 and CMake with a minimum version of 3.19.
We noticed some issues when compiling with Microsoft’s MSCV compiler toolchain. If you want to start development on this project under Windows, consider using the clang compiler toolchain. A detailed description of how to set this up can be found here.
Configure and Build#
Our projects use CMake as the main build configuration tool. Building a project using CMake is a two-stage process. First, CMake needs to be configured by calling
$ cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_QMAP_TESTS=ON -DBINDINGS=ON
This tells CMake to
search the current directory
-S) for a
process it into a directory
-DCMAKE_BUILD_TYPE=Releasetells CMake to configure a Release build (as opposed to, e.g., a Debug build).
-DBUILD_QMAP_TESTS=ONtells CMake to also build the C++ tests.
-DBINDINGS=ONtells CMake to also build the Python bindings.
After configuring with CMake, the project can be built by calling
$ cmake --build build --config Release
This tries to build the project in the
build directory (passed via
Some operating systems and development environments explicitly require a configuration to be set, which is why the
--config flag is also passed to the build command. The flag
--parallel <NUMBER_OF_THREADS> may be added to trigger a parallel build.
Building the project this way generates
the main libraries
qmap_*_lib.lib(Windows) in the
qmap_test_*containing unit tests in the
the Python bindings library
Running C++ Tests#
We use the GoogleTest framework for unit testing of the C++ library.
All tests are contained in the
After building the project (as described above), the C++ unit tests can be run by executing the test executables in the
[.../build/test] $ ./qmap_heuristic_test [.../build/test] $ ./qmap_exact_test
C++ Code Formatting and Linting#
This project mostly follows the LLVM Coding Standard, which is a set of guidelines for writing C++ code. To ensure the quality of the code and that it conforms to these guidelines, we use
clang-tidy – a static analysis tool that checks for common mistakes in C++ code, and
clang-format – a tool that automatically formats C++ code according to a given style guide.
If you are using Visual Studio Code, you can install the clangd extension.
If you are using CLion, you can configure the project to use the
.clang-formatfiles in the project root directory.
They will automatically execute clang-tidy on your code and highlight any issues. In many cases, they also provide quick-fixes for these issues. Furthermore, they provide a command to automatically format your code according to the given style.
If you want to use clang-tidy from the command line, you first have to configure CMake with
-DCMAKE_EXPORT_COMPILE_COMMANDS=ON to generate a compilation database.
It needs this information to correctly analyze the code.
After configuring CMake, you can run clang-tidy on a file by calling
$ clang-tidy <FILE> -- -I <PATH_TO_INCLUDE_DIRECTORY>
<FILE> is the file you want to analyze and
<PATH_TO_INCLUDE_DIRECTORY> is the path to the
include directory of the project.
Working on the Python module#
Pybind11 is used for providing bindings of the C++ core library to Python.
This allows to keep the performance critical parts of the code in C++ while providing a convenient interface for Python users.
All of the bindings code as well as the Python module itself is contained in the
Building the Python module#
The recommended way of building the Python module is to perform an editable install using pip.
(venv) $ pip install --editable .[dev]
--editable flag ensures that changes in the Python code are instantly available without re-running the command.
[dev] extra makes sure that all dependencies for running the Python tests and building the documentation are available.
When using the
zsh shell it might be necessary to add double quotes around the
.[dev] part of the command.
Do not forget to run the above command again after any changes to the C++ core library or bindings to make the changes available in the Python module.
Running Python Tests#
The Python part of the code base is tested by unit tests using the pytest framework.
The corresponding test files can be found in the
nox session is provided to conveniently run the Python tests.
(venv) $ nox -rs tests
This installs all dependencies for running the tests in an isolated environment, builds the Python package, and then runs the tests.
-r flag ensures that the environment is reused for subsequent runs.
To speed up subsequent runs, the installation step can be skipped by adding the
(venv) $ nox -rs tests -- skip-install
If you don’t want to use
nox, you can also run the tests directly using
(venv) $ pytest test/python
Python Code Formatting and Linting#
The Python code is formatted and linted using a collection of pre-commit hooks. This collection includes:
flake8 – a linter that checks for common mistakes in Python code
mypy – a static type checker for Python code
pyupgrade – a tool that automatically upgrades Python syntax to a newer version
There are two ways of using these hooks:
You can install the hooks manually by running
pre-commit installin the project root directory. This will install the hooks in the
.git/hooksdirectory of the repository. The hooks will then be executed automatically when committing changes.
You can use the
lintto run the hooks manually.
(venv) $ nox -rs lint
If you don’t want to use
nox, you can also run the hooks directly using
(venv) $ pre-commit run --all-files
In addition to the pre-commit hooks, the Python code is also type checked by mypy.
This is done by the
(venv) $ nox -rs mypy
Working on the Documentation#
The documentation is written in reStructuredText and built using Sphinx.
The documentation source files can be found in the
You can build the documentation using the
(venv) $ nox -rs docs
In order to properly build the jupyter notebooks in the documentation, you need to have
pandoc installed. See the pandoc documentation for installation instructions.
This will install all dependencies for building the documentation in an isolated environment, build the Python package, and then build the documentation. The session also provides a convenient option to automatically serve the docs on a local web server. Running
(venv) $ nox -rs docs -- serve
will start a local web server on port 8000 and provide a link to open the documentation in your browser.
To build the documentation without (re-)installing the Python package, you can use the
(venv) $ nox -rs docs -- skip-install
If you don’t want to use
nox, you can also build the documentation directly using
sphinx-build.(venv) $ sphinx-build -b html docs/source docs/build
The docs can then be found in the