🐍 Added Python bindings

.clang-format

@@ -55,7 +55,7 @@ IncludeCategories:
     Priority: 2
   - Regex: '<fiction\/[a-zA-Z0-9_]+.+>$'
     Priority: 3
-  - Regex: '<(alice|lorina|mockturtle|kitty|bill|nlohmann|fmt|z3|phmap|btree|tinyxml2|units)(\/[a-zA-Z0-9_])*.+>$'
+  - Regex: '<(alice|lorina|mockturtle|kitty|bill|nlohmann|fmt|z3|phmap|btree|tinyxml2|pybind11)(\/[a-zA-Z0-9_])*.+>$'
     Priority: 4
   - Regex: '<z3[a-zA-Z0-9_\+]+.+>$'
     Priority: 5

.github/pull_request_template.md

@@ -13,5 +13,6 @@ This checklist serves as a reminder of a couple of things that ensure your pull
 
 - [ ] The pull request only contains commits that are related to it.
 - [ ] I have added appropriate tests and documentation.
+- [ ] I have created/adjusted the Python bindings for any new or updated functionality.
 - [ ] I have made sure that all CI jobs on GitHub pass.
 - [ ] The pull request introduces no new warnings and follows the project's style guidelines.

.github/workflows/clang-tidy-review.yml

@@ -36,7 +36,7 @@ jobs:
             -DMOCKTURTLE_EXAMPLES=OFF
           build_dir: build
           config_file: '.clang-tidy'
-          exclude: 'libs/*, docs/*, benchmarks/*, bib/*'
+          exclude: 'libs/*, docs/*, benchmarks/*, bib/*, */pyfiction/pybind11_mkdoc_docstrings.hpp, */pyfiction/documentation.hpp'
           split_workflow: true
 
       - name: Make sure that the review file exists

.github/workflows/codeql-analysis.yml

@@ -63,11 +63,6 @@ jobs:
       - name: Install libraries and the respective compiler
         run: sudo apt-get update && sudo apt-get install -yq libtbb-dev ${{matrix.compiler}}
 
-      - name: Setup Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.9.x'
-
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
@@ -82,6 +77,12 @@ jobs:
           save: true
           max-size: 10G
 
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.9.x'
+          cache: 'pip'
+
       - name: Setup mold
         uses: rui314/setup-mold@v1
 

.github/workflows/coverage.yml

@@ -47,11 +47,6 @@ jobs:
       - name: Install the Compiler
         run: sudo apt-get update && sudo apt-get install -yq ${{matrix.compiler}}
 
-      - name: Setup Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.9.x'
-
       - name: Clone Repository
         uses: actions/checkout@v4
         with:
@@ -65,6 +60,12 @@ jobs:
           save: true
           max-size: 10G
 
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.9.x'
+          cache: 'pip'
+
       - name: Setup mold
         uses: rui314/setup-mold@v1
 

.github/workflows/pyfiction-docstring-generator.yml

@@ -0,0 +1,43 @@
+name: pyfiction Docstring Generator
+
+on:
+  push:
+  workflow_dispatch:
+
+jobs:
+  get_docstrings:
+    name: Auto-generate docstrings for pyfiction from C++ code
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone Repository
+        uses: actions/checkout@v3
+        with:
+          submodules: recursive
+
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.11.x"
+          cache: 'pip'
+
+      - name: Install pybind11_mkdoc and clang
+        working-directory: ${{ github.workspace }}
+        run: pip install pybind11_mkdoc clang==15.0.7
+
+      - name: Create docstrings file
+        working-directory: ${{ github.workspace }}
+        run: touch ${{ github.workspace }}/pybind11_mkdoc_docstrings.hpp
+
+      - name: Run pybind11_mkdoc
+        working-directory: ${{ github.workspace }}
+        run: >
+          python3
+          -m pybind11_mkdoc
+          -o ${{ github.workspace }}/pybind11_mkdoc_docstrings.hpp
+          -D FICTION_Z3_SOLVER
+          `find ${{ github.workspace }}/include/fiction -name "*.hpp" -print`
+
+      - name: Upload docstrings as an artifact
+        uses: actions/upload-artifact@v3
+        with:
+          path: ${{ github.workspace }}/pybind11_mkdoc_docstrings.hpp

.github/workflows/pyfiction-pypi-deployment.yml

@@ -0,0 +1,138 @@
+# this file is heavily based on https://github.com/cda-tum/qmap/blob/main/.github/workflows/deploy.yml
+
+name: pyfiction PyPI Deployment
+
+on:
+  release:
+    types: [ published ]
+  pull_request:
+  merge_group:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+env:
+  Z3_VERSION: 4.10.0
+  ENABLE_Z3: 'ON'
+
+jobs:
+  build_wheels:
+    name: Wheels for ${{ matrix.config.os }} (${{ matrix.config.arch }})
+    runs-on: ${{ matrix.config.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        config:
+          - { os: ubuntu-latest, arch: x64 }
+          - { os: macos-latest, arch: x64 }
+          - { os: macos-latest, arch: arm64 }
+          - { os: windows-latest, arch: x64 }
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          submodules: recursive
+          fetch-depth: 0
+
+      - name: Setup ccache
+        uses: hendrikmuhs/[email protected]
+        with:
+          key: '${{matrix.config.os}}-pyfiction'
+          variant: ccache
+          save: true
+          max-size: 10G
+
+      # on Linux, the action does not work because it can't install to the manylinux container
+      - if: runner.os != 'Linux'
+        name: Install Z3
+        uses: cda-tum/setup-z3@v1
+        with:
+          version: ${{ env.Z3_VERSION }}
+          architecture: ${{ matrix.config.arch }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - if: runner.os == 'Linux'
+        name: Setup mold
+        uses: rui314/setup-mold@v1
+
+      - if: ${{ matrix.config.arch == 'arm64' }}
+        name: Set Architecture to arm64 if necessary
+        run: echo "CIBW_ARCHS_MACOS=arm64" >> $GITHUB_ENV
+
+      - name: Build wheel
+        uses: pypa/[email protected]
+        env:
+          CIBW_BEFORE_ALL_LINUX: /opt/python/cp39-cp39/bin/pip install z3-solver==${{ env.Z3_VERSION }}
+          CIBW_TEST_EXTRAS: test
+          CIBW_TEST_COMMAND: 'python -m unittest discover --start-directory {project} --verbose'
+
+      - name: Upload wheel as an artifact
+        uses: actions/upload-artifact@v3
+        with:
+          path: ./wheelhouse/*.whl
+
+  build_sdist:
+    name: Build Source Distribution
+    runs-on: ubuntu-latest
+    steps:
+      - name: Clone respository
+        uses: actions/checkout@v3
+        with:
+          submodules: recursive
+          fetch-depth: 0
+
+      - name: Setup ccache
+        uses: hendrikmuhs/[email protected]
+        with:
+          key: 'ubuntu-latest-pyfiction'
+          variant: ccache
+          save: true
+          max-size: 10G
+
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+          cache: 'pip'
+
+      - name: Setup Z3 Solver
+        uses: cda-tum/setup-z3@v1
+        with:
+          version: ${{ env.Z3_VERSION }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build sdist
+        run: pipx run build --sdist
+
+      - name: Test sdist
+        run: z3=${{env.ENABLE_Z3}} pip install dist/*.tar.gz --verbose
+
+      - name: Upload sdist as an artifact
+        uses: actions/upload-artifact@v3
+        with:
+          path: dist/*.tar.gz
+
+  publish_to_pypi:
+    needs: [ build_wheels, build_sdist ]
+    runs-on: ubuntu-latest
+    name: Publish to PyPI
+    if: github.event_name == 'release' && github.event.action == 'published'
+    steps:
+      - name: Download the previously stored artifacts
+        uses: actions/download-artifact@v3
+        with:
+          name: artifact
+          path: dist
+
+      - name: Deploy to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_DEPLOY_TOKEN }}
+          skip-existing: true
+          verbose: true

.github/workflows/python-bindings.yml

@@ -0,0 +1,85 @@
+name: pyfiction CI
+
+on:
+  push:
+    paths:
+      - 'bindings/pyfiction/**'
+      - '**/*.py'
+      - '**/*.hpp'
+      - '**/*.cpp'
+      - '**/*.cmake'
+      - '**/CMakeLists.txt'
+      - 'libs/**'
+      - '.github/workflows/python-bindings.yml'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+defaults:
+  run:
+    shell: bash
+
+env:
+  Z3_VERSION: 4.10.0
+  ENABLE_Z3: 'ON'
+
+jobs:
+  build_and_test:
+    strategy:
+      matrix:
+        os: [ ubuntu-latest, macos-latest, windows-latest ]
+        python_version: [ '3.7.x', '3.8.x', '3.9.x', '3.10.x', '3.11.x' ]
+        include:
+          - os: ubuntu-latest
+            z3_platform: linux
+          - os: macos-latest
+            z3_platform: macOS
+          - os: windows-latest
+            z3_platform: windows
+      fail-fast: false  # allow other jobs to finish even if one fails
+
+    name: pyfiction on ${{matrix.os}} with Python ${{matrix.python_version}}
+    runs-on: ${{matrix.os}}
+
+    steps:
+      - name: Clone Repository
+        uses: actions/checkout@v3
+        with:
+          submodules: recursive
+
+      - name: Setup ccache
+        uses: hendrikmuhs/[email protected]
+        with:
+          key: '${{matrix.os}}-pyfiction'
+          variant: ccache
+          save: true
+          max-size: 10G
+
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{matrix.python_version}}
+          cache: 'pip'
+
+      - if: runner.os == 'Linux'
+        name: Setup mold
+        uses: rui314/setup-mold@v1
+
+      - name: Setup Z3 Solver
+        id: z3
+        uses: cda-tum/setup-z3@v1
+        with:
+          version: ${{env.Z3_VERSION}}
+          platform: ${{matrix.z3_platform}}
+          architecture: x64
+        env:
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+
+      - name: Build pyfiction
+        working-directory: ${{github.workspace}}
+        run: z3=${{env.ENABLE_Z3}} pip install '.[test]'
+
+      - name: Test
+        working-directory: ${{github.workspace}}
+        run: python -m unittest discover --verbose

.github/workflows/ubuntu.yml

@@ -76,11 +76,6 @@ jobs:
       - name: Install libraries and the respective compiler
         run: sudo apt-get update && sudo apt-get install -yq libtbb-dev ${{matrix.compiler}}
 
-      - name: Setup Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.9.x'
-
       - name: Clone Repository
         uses: actions/checkout@v4
         with:
@@ -94,14 +89,20 @@ jobs:
           save: true
           max-size: 10G
 
-      - name: Setup mold
-        uses: rui314/setup-mold@v1
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.9.x'
+          cache: 'pip'
 
       - name: Install pip packages
         uses: BSFishy/pip-action@v1
         with:
           requirements: ${{github.workspace}}/libs/mugen/requirements.txt
 
+      - name: Setup mold
+        uses: rui314/setup-mold@v1
+
       - name: Setup Z3 Solver
         id: z3
         uses: cda-tum/setup-z3@v1