Skip to content

Commit 449a5b1

Browse files
authored
📝 Rework existing project documentation (#789)
## Description This PR reworks most of the existing project documentation. Some of this was triggered by the ongoing JOSS submission, some was long overdue. While extending the documentation, a small bug in the OpenQASM dump of classic controlled operations has been found and subsequently fixed. While this PR mostly touches existing documentation, a follow-up PR will add documentation for the DD and the ZX package. ## Checklist: <!--- This checklist serves as a reminder of a couple of things that ensure your pull request will be merged swiftly. --> - [x] The pull request only contains commits that are related to it. - [x] I have added appropriate tests and documentation. - [x] I have made sure that all CI jobs on GitHub pass. - [x] The pull request introduces no new warnings and follows the project's style guidelines.
2 parents 653c606 + 5ca5391 commit 449a5b1

File tree

10 files changed

+559
-313
lines changed

10 files changed

+559
-313
lines changed

.github/contributing.md

Lines changed: 24 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -39,28 +39,34 @@ Nevertheless, please try to follow the guidelines below as well as you can to he
3939
## Core Guidelines
4040

4141
- ["Commit early and push often"](https://www.worklytics.co/blog/commit-early-push-often).
42-
- Write meaningful commit messages (preferably using [gitmoji](https://gitmoji.dev) to give additional context to your commits).
43-
- Focus on a single feature/bug at a time and only touch relevant files. Split multiple features into multiple contributions.
44-
- If you added a new feature, you should add tests that ensure it works as intended. Furthermore, the new feature should be documented appropriately.
45-
- If you fixed a bug, you should add tests that demonstrate that the bug has been fixed.
46-
- Document your code thoroughly and write readable code.
47-
- Keep your code clean. Remove any debug statements, left-over comments, or code unrelated to your contribution.
48-
- Run `pre-commit run -a` to check your code for style and linting errors before committing.
42+
- Write meaningful commit messages, preferably using [gitmoji](https://gitmoji.dev) for additional context.
43+
- Focus on a single feature or bug at a time and only touch relevant files. Split multiple features into separate contributions.
44+
- Add tests for new features to ensure they work as intended. Document new features appropriately.
45+
- Add tests for bug fixes to demonstrate that the bug has been resolved.
46+
- Document your code thoroughly and ensure it is readable.
47+
- Keep your code clean by removing debug statements, leftover comments, and unrelated code.
48+
- Check your code for style and linting errors before committing.
49+
- Follow the project's coding standards and conventions.
50+
- Be open to feedback and willing to make necessary changes based on code reviews.
4951

5052
## Pull Request Workflow
5153

5254
- Create PRs early. It is ok to create work-in-progress PRs. You may mark these as draft PRs on GitHub.
53-
- Describe your PR. Start with a descriptive title, reference any related issues by including the issue number in the PR description, and add a comprehensive description of the changes. We provide a PR template that you can (and should) follow to create a PR. Do not delete any sections from the template.
54-
- Whenever a PR is created or updated, several workflows on all supported platforms and versions of Python are executed. These workflows ensure that the project still builds, that all tests pass, and that the code is properly formatted and introduces no new linting errors. Your PR is expected to pass all these continuous integration (CI) checks before it can be merged. Here are some tips for finding the cause of certain failures:
55-
- If any of the `CI / 🇨‌ Test` checks fail, this most likely indicates build errors or test failures in the C++ part of the code base. Look through the respective logs on GitHub for any error or failure messages.
56-
- If any of the `CI / 🐍 Test` checks fail, this most likely indicates build errors or test failures in the Python part of the code base. Look through the respective logs on GitHub for any error or failure messages.
57-
- If any of the `codecov/\*` checks fail, this means that your changes are not appropriately covered by tests or that the overall project coverage decreased too much. Ensure that you include tests for all your changes in the PR.
58-
- If `cpp-linter` comments on your PR with a list of warnings, these have been raised by `clang-tidy` when checking the C++ part of your changes for warnings or style guideline violations. The individual messages frequently provide helpful suggestions on how to fix the warnings. If you don't see any messages, but the `🇨‌ Lint / 🚨 Lint` check is red, click on the `Details` link to see the full log of the check and a step summary.
59-
- If the `pre-commit.ci` check fails, some of the `pre-commit` checks failed and could not be fixed automatically by the _pre-commit.ci_ bot. Such failures are most likely related to the Python part of the code base. The individual log messages frequently provide helpful suggestions on how to fix the warnings.
60-
- If the `docs/readthedocs.org:mqt-core` check fails, the documentation could not be built properly. Inspect the corresponding log file for any errors.
61-
- Once your PR is ready, change it from a draft PR to a regular PR and request a review from one of the project maintainers. Please make sure to only request a review once you are done with your changes and the PR is ready to be merged. If you are unsure whether your PR is ready for review, please ask in the PR comments.
62-
- If your PR gets a "Changes requested" review, you will need to address the feedback and update your PR by pushing to the same branch. You don't need to close the PR and open a new one. Respond to review comments on the PR (e.g., with "done 👍" or "done in @\<commit\>") to let the reviewer know that you have addressed the feedback. Note that reviewers do not get a notification if you just react to the review comment with an emoji. You need to write a comment to notify the reviewer.
63-
- Be sure to re-request review once you have made changes after a code review so that maintainers know that the requests have been addressed.
55+
- Describe your PR with a descriptive title, reference any related issues by including the issue number in the PR description, and add a comprehensive description of the changes. Follow the provided PR template and do not delete any sections, except for the issue reference if your PR is not related to an issue.
56+
- Whenever a PR is created or updated, several workflows on all supported platforms and versions of Python are executed. These workflows ensure that the project still builds, all tests pass, the code is properly formatted, and no new linting errors are introduced. Your PR must pass all these continuous integration (CI) checks before it can be merged.
57+
- Once your PR is ready, change it from a draft PR to a regular PR and request a review from one of the project maintainers. Only request a review once you are done with your changes and the PR is ready to be reviewed. If you are unsure whether your PR is ready, ask in the PR comments. If you are a first-time contributor, request a review from one of the maintainers by mentioning them in a comment on the PR.
58+
- If your PR gets a "Changes requested" review, address the feedback and update your PR by pushing to the same branch. Do not close the PR and open a new one. Respond to review comments on the PR (e.g., with "done 👍" or "done in @<commit>") to let the reviewer know that you have addressed the feedback. Note that reviewers do not get a notification if you just react to the review comment with an emoji. Write a comment to notify the reviewer. Do not resolve the review comments yourself. The reviewer will mark the comments as resolved once they are satisfied with the changes.
59+
- Be sure to re-request a review once you have made changes after a code review so that maintainers know that the requests have been addressed.
60+
- No need to squash commits before merging; we usually squash them to keep the history clean. We only merge without squashing if the commit history is clean and meaningful. Avoid rebasing or force-pushing your PR branch before merging, as it complicates reviews. You can rebase or clean up commits after addressing all review comments if desired.
61+
62+
Here are some tips for finding the cause of certain failures:
63+
64+
- If any of the `CI / 🇨‌ Test` checks fail, this indicates build errors or test failures in the C++ part of the code base. Look through the respective logs on GitHub for any error or failure messages.
65+
- If any of the `CI / 🐍 Test` checks fail, this indicates build errors or test failures in the Python part of the code base. Look through the respective logs on GitHub for any error or failure messages.
66+
- If any of the `codecov/\*` checks fail, this means that your changes are not appropriately covered by tests or that the overall project coverage decreased too much. Ensure that you include tests for all your changes in the PR.
67+
- If `cpp-linter` comments on your PR with a list of warnings, these have been raised by `clang-tidy` when checking the C++ part of your changes for warnings or style guideline violations. The individual messages frequently provide helpful suggestions on how to fix the warnings. If you don't see any messages, but the `🇨‌ Lint / 🚨 Lint` check is red, click on the `Details` link to see the full log of the check and a step summary.
68+
- If the `pre-commit.ci` check fails, some of the `pre-commit` checks failed and could not be fixed automatically by the _pre-commit.ci_ bot. Such failures are most likely related to the Python part of the code base. The individual log messages frequently provide helpful suggestions on how to fix the warnings.
69+
- If the `docs/readthedocs.org:\*` check fails, the documentation could not be built properly. Inspect the corresponding log file for any errors.
6470

6571
---
6672

docs/index.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66

77
MQT Core is an open-source C++17 and Python library for quantum computing that forms the backbone of the quantum software tools developed as part of the _{doc}`Munich Quantum Toolkit (MQT) <mqt:index>`_ by the [Chair for Design Automation](https://www.cda.cit.tum.de/) at the [Technical University of Munich](https://www.tum.de/).
88
To this end, it consists of multiple components that are used throughout the MQT, including a fully fledged intermediate representation (IR) for quantum computations, a state-of-the-art decision diagram (DD) package for quantum computing, and a state-of-the-art ZX-diagram package for working with the ZX-calculus.
9-
This documentation provides a comprehensive guide to the MQT Core library, including {doc}`installation instructions <installation>`, a {doc}`quickstart guide <quickstart>`, and detailed {doc}`API documentation <api/mqt/core/index>`.
9+
This documentation provides a comprehensive guide to the MQT Core library, including {doc}`installation instructions <installation>`, a {doc}`quickstart guide for the MQT Core IR <mqt_core_ir>`, and detailed {doc}`API documentation <api/mqt/core/index>`.
1010
The source code of MQT Core is publicly available on GitHub at [cda-tum/mqt-core](https://github.com/cda-tum/mqt-core), while pre-built binaries are available via [PyPI](https://pypi.org/project/mqt.core/) for all major operating systems and all modern Python versions.
1111
MQT Core is fully compatible with Qiskit 1.0 and above.
1212

@@ -33,7 +33,7 @@ self
3333
:caption: User Guide
3434
3535
installation
36-
quickstart
36+
mqt_core_ir
3737
```
3838

3939
````{only} not latex

docs/installation.md

Lines changed: 139 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,69 @@
11
# Installation
22

33
MQT Core is mainly developed as a C++17 library with Python bindings.
4-
The resulting Python package is available on [PyPI](https://pypi.org/project/mqt.core/) and can be installed via `pip` for all major operating systems and all modern Python versions.
4+
The resulting Python package is available on [PyPI](https://pypi.org/project/mqt.core/) and can be installed on all major operating systems using all modern Python versions.
5+
6+
:::::{tip}
7+
We highly recommend using [`uv`](https://docs.astral.sh/uv/) for working with Python projects.
8+
It is an extremely fast Python package and project manager, written in Rust and developed by [Astral](https://astral.sh/) (the same team behind [`ruff`](https://docs.astral.sh/ruff/)).
9+
It can act as a drop-in replacement for `pip` and `virtualenv`, and provides a more modern and faster alternative to the traditional Python package management tools.
10+
It automatically handles the creation of virtual environments and the installation of packages, and is much faster than `pip`.
11+
Additionally, it can even set up Python for you if it is not installed yet.
12+
13+
If you do not have `uv` installed yet, you can install it via:
14+
15+
::::{tab-set}
16+
:::{tab-item} macOS and Linux
17+
18+
```console
19+
$ curl -LsSf https://astral.sh/uv/install.sh | sh
20+
```
21+
22+
:::
23+
:::{tab-item} Windows
24+
25+
```console
26+
$ powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
27+
```
28+
29+
::::
30+
31+
Check out their excellent [documentation](https://docs.astral.sh/uv/) for more information.
32+
33+
:::::
34+
35+
::::{tab-set}
36+
:sync-group: installer
37+
38+
:::{tab-item} uv _(recommended)_
39+
:sync: uv
40+
41+
```console
42+
$ uv pip install mqt.core
43+
```
44+
45+
:::
46+
47+
:::{tab-item} pip
48+
:sync: pip
549

650
```console
7-
(.venv) $ pip install mqt.core
51+
(.venv) $ python -m pip install mqt.core
852
```
953

54+
:::
55+
::::
56+
1057
In most practical cases (under 64-bit Linux, MacOS incl. Apple Silicon, and Windows), this requires no compilation and merely downloads and installs a platform-specific pre-built wheel.
1158

59+
Once installed, you can check if the installation was successful by running:
60+
61+
```console
62+
(.venv) $ python -c "import mqt.core; print(mqt.core.__version__)"
63+
```
64+
65+
which should print the installed version of the library.
66+
1267
:::{attention}
1368
As of version 2.7.0, support for Python 3.8 has been officially dropped.
1469
We strongly recommend that users upgrade to a more recent version of Python to ensure compatibility and continue receiving updates and support.
@@ -19,10 +74,28 @@ Thank you for your understanding.
1974

2075
In order to get the best performance and enable platform-specific optimizations that cannot be enabled on portable wheels, it is recommended to build the library from source via:
2176

77+
::::{tab-set}
78+
:sync-group: installer
79+
80+
:::{tab-item} uv _(recommended)_
81+
:sync: uv
82+
83+
```console
84+
$ uv pip install mqt.core --no-binary mqt.core
85+
```
86+
87+
:::
88+
89+
:::{tab-item} pip
90+
:sync: pip
91+
2292
```console
2393
(.venv) $ pip install mqt.core --no-binary mqt.core
2494
```
2595

96+
:::
97+
::::
98+
2699
This requires a [C++ compiler supporting C++17](https://en.wikipedia.org/wiki/List_of_compilers#C++_compilers) and a minimum [CMake](https://cmake.org/) version of 3.19.
27100
The library is continuously tested under Linux, MacOS, and Windows using the [latest available system versions for GitHub Actions](https://github.com/actions/virtual-environments).
28101
In order to access the latest build logs, visit the [GitHub Actions page](https://github.com/cda-tum/mqt-core/actions/workflows/ci.yml).
@@ -33,12 +106,21 @@ If you want to use the MQT Core Python package in your own project, you can simp
33106
This will automatically install the MQT Core package when your project is installed.
34107

35108
::::{tab-set}
109+
110+
:::{tab-item} uv _(recommended)_
111+
112+
```console
113+
$ uv add mqt.core
114+
```
115+
116+
:::
117+
36118
:::{tab-item} pyproject.toml
37119

38120
```toml
39121
[project]
40122
# ...
41-
dependencies = ["mqt.core>=2.4.0"]
123+
dependencies = ["mqt.core>=2.7.0"]
42124
# ...
43125
```
44126

@@ -51,7 +133,7 @@ from setuptools import setup
51133

52134
setup(
53135
# ...
54-
install_requires=["mqt.core>=2.4.0"],
136+
install_requires=["mqt.core>=2.7.0"],
55137
# ...
56138
)
57139
```
@@ -75,21 +157,28 @@ Furthermore, CMake's [FetchContent](https://cmake.org/cmake/help/latest/module/F
75157
include(FetchContent)
76158
set(FETCH_PACKAGES "")
77159
78-
set(MQT_CORE_VERSION 2.4.0 CACHE STRING "MQT Core version")
160+
# cmake-format: off
161+
set(MQT_CORE_VERSION 2.7.0
162+
CACHE STRING "MQT Core version")
163+
set(MQT_CORE_REV "2ccf532b66998af376c256ae94a39eed802b990c"
164+
CACHE STRING "MQT Core identifier (tag, branch or commit hash)")
165+
set(MQT_CORE_REPO_OWNER "cda-tum"
166+
CACHE STRING "MQT Core repository owner (change when using a fork)")
167+
# cmake-format: on
79168
if(CMAKE_VERSION VERSION_GREATER_EQUAL 3.24)
80169
FetchContent_Declare(
81170
mqt-core
82-
GIT_REPOSITORY https://github.com/cda-tum/mqt-core.git
83-
GIT_TAG v${MQT_CORE_VERSION}
171+
GIT_REPOSITORY https://github.com/${MQT_CORE_REPO_OWNER}/mqt-core.git
172+
GIT_TAG ${MQT_CORE_REV}
84173
FIND_PACKAGE_ARGS ${MQT_CORE_VERSION})
85174
list(APPEND FETCH_PACKAGES mqt-core)
86175
else()
87176
find_package(mqt-core ${MQT_CORE_VERSION} QUIET)
88177
if(NOT mqt-core_FOUND)
89178
FetchContent_Declare(
90179
mqt-core
91-
GIT_REPOSITORY https://github.com/cda-tum/mqt-core.git
92-
GIT_TAG v${MQT_CORE_VERSION})
180+
GIT_REPOSITORY https://github.com/${MQT_CORE_REPO_OWNER}/mqt-core.git
181+
GIT_TAG ${MQT_CORE_REV})
93182
list(APPEND FETCH_PACKAGES mqt-core)
94183
endif()
95184
endif()
@@ -98,6 +187,38 @@ endif()
98187
FetchContent_MakeAvailable(${FETCH_PACKAGES})
99188
```
100189

190+
We even offer a Dependabot-like GitHub workflow that automatically updates the `MQT_CORE_VERSION` and `MQT_CORE_REV` variables in your `CMakeLists.txt` file.
191+
Simply add the following workflow to your project's `.github/workflows` directory:
192+
193+
```yaml
194+
name: Update MQT Core
195+
on:
196+
schedule:
197+
# run once a month on the first day of the month at 00:00 UTC
198+
- cron: "0 0 1 * *"
199+
workflow_dispatch:
200+
inputs:
201+
update-to-head:
202+
description: "Update to the latest commit on the default branch"
203+
type: boolean
204+
required: false
205+
default: false
206+
pull_request:
207+
paths:
208+
- .github/workflows/update-mqt-core.yml
209+
210+
concurrency:
211+
group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
212+
cancel-in-progress: true
213+
214+
jobs:
215+
update-mqt-core:
216+
name: Update MQT Core
217+
uses: cda-tum/mqt-workflows/.github/workflows/[email protected]
218+
with:
219+
update-to-head: ${{ github.event.inputs.update-to-head == 'true' }}
220+
```
221+
101222
:::
102223
103224
:::{tab-item} git submodule
@@ -106,8 +227,8 @@ Integrating the library as a git submodule is the simplest approach.
106227
However, handling git submodules can be cumbersome, especially when working with multiple branches or versions of the library.
107228
First, add the submodule to your project (e.g., in the `external` directory) via:
108229

109-
```bash
110-
git submodule add https://github.com/cda-tum/mqt-core.git external/mqt-core
230+
```console
231+
$ git submodule add https://github.com/cda-tum/mqt-core.git external/mqt-core
111232
```
112233

113234
Then, add the following lines to your `CMakeLists.txt` to make the library's targets available in your project:
@@ -122,18 +243,18 @@ add_subdirectory(external/mqt-core)
122243

123244
MQT Core can be installed on your system after building it from source.
124245

125-
```bash
126-
git clone https://github.com/cda-tum/mqt-core.git
127-
cd mqt-core
128-
cmake -S . -B build
129-
cmake --build build
130-
cmake --install build
246+
```console
247+
$ git clone https://github.com/cda-tum/mqt-core.git
248+
$ cd mqt-core
249+
$ cmake -S . -B build
250+
$ cmake --build build
251+
$ cmake --install build
131252
```
132253

133254
Then, in your project's `CMakeLists.txt`, you can use the `find_package` command to locate the installed library:
134255

135256
```cmake
136-
find_package(mqt-core 2.4.0 REQUIRED)
257+
find_package(mqt-core 2.7.0 REQUIRED)
137258
```
138259

139260
::::

0 commit comments

Comments
 (0)