Cx

.github/workflows/docs.yml

@@ -1,13 +1,42 @@
 name: Documentation
 on:
-  push:
-    branches:
-      - main
+  pull_request:
+    branches: [ "main" ]
+  workflow_call:
+    inputs:
+      test-run-id:
+        required: true
+        type: string
 permissions:
   contents: write
 jobs:
+  build:
+    runs-on: ubuntu-latest
+    if: github.ref != 'refs/heads/main'
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install poetry
+        run: pipx install poetry
+      - name: Set up Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: 'poetry'
+      - name: Install dependencies
+        run: poetry install --with docs
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+      - name: Setting up Cache
+        uses: actions/cache@v4
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .ci-cache
+          restore-keys: |
+            mkdocs-material-
+      - name: Build Docs
+        run: poetry run mkdocs build
   deploy:
     runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
     steps:
       - uses: actions/checkout@v4
       - name: Configure Git Credentials
@@ -20,16 +49,22 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: "3.11"
-          cache: 'poetry' # caching pip dependencies
+          cache: 'poetry'
       - name: Install dependencies
         run: poetry install --with docs
-      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV # (3)!
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
       - name: Setting up Cache
         uses: actions/cache@v4
         with:
           key: mkdocs-material-${{ env.cache_id }}
           path: .ci-cache
           restore-keys: |
             mkdocs-material-
+      - name: Download a single artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: coverage-report
+          run-id: ${{ inputs.test-run-id }}
+          path: docs/coverage/
       - name: Deploy
         run: poetry run mkdocs gh-deploy --force

.github/workflows/publish.yml

@@ -0,0 +1,57 @@
+name: Publish
+on:
+  push:
+    branches: [ "main" ]
+permissions:
+  contents: write
+jobs:
+  test:
+    name: Trigger Tests
+    uses: ./.github/workflows/test.yml
+  quality:
+    name: Trigger Quality
+    uses: ./.github/workflows/quality.yml
+  documentation:
+    needs: test
+    name: Trigger Documentation
+    uses: ./.github/workflows/docs.yml
+    with:
+      test-run-id: ${{ github.run_id }}
+  release:
+    needs: [test, quality, documentation]
+    name: Release
+    if: github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Install poetry
+      run: pipx install poetry
+    - name: Set up Python 3.11
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
+        cache: 'poetry'
+    - name: Compare tag and version
+      run: |
+        if [ "$(git tag)" = "$(poetry version --short)" ]; then
+          echo "The tag and the version are the same, nothing to do."
+          echo "DORELEASE=false" >> $GITHUB_ENV
+        else
+          echo "DORELEASE=true" >> $GITHUB_ENV
+        fi
+    - name: Create Release & Tag
+      if: env.DORELEASE == 'true'
+      run: |
+        gh release create "$(poetry version --short)" \
+        --repo="$GITHUB_REPOSITORY" \
+        --title="${GITHUB_REPOSITORY#*/} $(poetry version --short)" \
+        --generate-notes
+      env:
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    - name: Publish to PyPI
+      if: env.DORELEASE == 'true'
+      run: |
+        poetry install --with dev
+        poetry config pypi-token.pypi ${{ secrets.PYPI_API_TOKEN }}
+        poetry build
+        poetry publish

.github/workflows/quality.yml

@@ -1,13 +1,12 @@
 name: Quality
 on:
-  push:
-    branches: [ "main" ]
   pull_request:
     branches: [ "main" ]
+  workflow_call:
 permissions:
   contents: read
 jobs:
-  build:
+  quality:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
@@ -17,10 +16,12 @@ jobs:
       uses: actions/setup-python@v5
       with:
         python-version: "3.11"
-        cache: 'poetry' # caching pip dependencies
+        cache: 'poetry'
     - name: Install dependencies
       run: poetry install --with dev
     - name: Lint with flake8
       run: |
         poetry run flake8 qml_essentials
         poetry run flake8 tests
+    - name: Running license check
+      run: poetry run licensecheck --zero --license mit

.github/workflows/test.yml

@@ -1,26 +1,38 @@
 name: Testing
 on:
-  push:
-    branches: [ "main" ]
   pull_request:
     branches: [ "main" ]
+  workflow_call:
 permissions:
-  contents: read
+  contents: write
 jobs:
-  build:
+  test:
     runs-on: ubuntu-latest
     steps:
+    # - name: Install Act dependencies
+    #   if: ${{ env.ACT }}
+    #   run: |
+    #     apt update -qq > /dev/null
+    #     apt install apt-utils -y -qq > /dev/null
+    #     apt remove python3
+    #     apt install python3.11 python3-venv pipx -y
     - uses: actions/checkout@v4
     - name: Install poetry
       run: pipx install poetry
     - name: Set up Python 3.11
       uses: actions/setup-python@v5
       with:
         python-version: "3.11"
-        cache: 'poetry' # caching pip dependencies
+        cache: 'poetry'
     - name: Install dependencies
       run: poetry install --with dev
     - name: Test with pytest
       run: |
         poetry run coverage run -m pytest
         poetry run coverage report -m
+        poetry run coverage html
+    - name: Share coverage report
+      uses: actions/upload-artifact@v4
+      with:
+        name: coverage-report
+        path: htmlcov/

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Contributing to QUAFEL
+# Contributing to QML-Essentials
 
 :tada: Welcome! :tada:
 
@@ -7,7 +7,7 @@ Start of by..
 1. Creating an issue using one of the templates (Bug Report, Feature Request)
    - let's discuss what's going wrong or what should be added
    - can you contribute with code? Great! Go ahead! :rocket:
-2. Forking the repository and working on your stuff
+2. Forking the repository and working on your stuff. See the sections below for details on how to set things up.
 3. Creating a pull request to the main repository
 
 ## Setup
@@ -24,23 +24,27 @@ poetry run pre-commit autoupdate
 poetry run pre-commit install
 ```
 
+Currently the only purpose of the hook is to run Black on commit which will do some code formatting for you.
+However be aware, that this might reject your commit and you have to re-do the commit.
+
 ## Testing
 
 We do our testing with Pytest. Corresponding tests can be triggered as follows:
 ```
 poetry run pytest
 ```
+There are Github action pipelines in place, that will do linting and testing once you open a pull request.
+However, it's a good idea to run tests and linting (either Black or Flake8) locally before pushing.
 
 ## Packaging
 
-Building and packaging requires some extra steps (assuming Poetry):
-- `poetry run devpi use https://ea3a0fbb-599f-4d83-86f1-0e71abe27513.ka.bw-cloud-instance.org`
-- `poetry run devpi login alice --password=456`
-- `poetry run devpi use alice/quantum`
-- `poetry config repositories.quantum https://ea3a0fbb-599f-4d83-86f1-0e71abe27513.ka.bw-cloud-instance.org/lc3267/quantum`
-- `poetry config http-basic.quantum alice 456` (or remove password for interactive prompt)
-- `poetry version (major|minor|patch|premajor|preminor|prepatch)` as explained [here](https://python-poetry.org/docs/cli/#version)
-- `poetry publish --build -r quantum`
+Packaging is done automagically using Github actions.
+This action is triggered when a new version is being detected in the `pyprojec.toml` file.
+This works by comparing the output of `poetry version --short` against `git tag` and triggering the publishing process if those differ.
+Publishing includes
+- setting the git tag equal to the version specified in `pyproject.toml`
+- creating a release with the current git tag and automatically generated release notes
+- publishing the package to PyPI using the stored credentials
 
 ## Re-Installing Package
 
@@ -59,13 +63,8 @@ We use MkDocs for our documentation. To run a server locally, run:
 ```
 poetry run mkdocs serve
 ```
+This will automatically trigger a rebuild each time you make changes.
+See the [MkDocs Documentation](https://cirkiters.github.io/qml-essentials/usage/) for more details.
 
-If you make changes to the documentation in the meantime, trigger a build by running
-```
-poetry run mkdocs build
-```
-
-For pushing to Github pages:
-```
-poetry run mkdocs gh-deploy
-```
+Publishing (and building) the documentation is done automagically using Github actions.
+This action is triggered when a new release is made.

README.md

@@ -1,16 +1,25 @@
 # QML Essentials
 
-[![version](https://img.shields.io/badge/version-0.1.12-green.svg)](https://ea3a0fbb-599f-4d83-86f1-0e71abe27513.ka.bw-cloud-instance.org/lc3267/quantum/) [![Pipx Status](https://servers.stroblme.de/api/badge/3/uptime/72?color=%2331c754&labelColor=%233f4850)](https://servers.stroblme.de/status/open) [![Quality](https://github.com/cirKITers/qml-essentials/actions/workflows/quality.yml/badge.svg)](https://github.com/cirKITers/qml-essentials/actions/workflows/quality.yml) [![Testing](https://github.com/cirKITers/qml-essentials/actions/workflows/test.yml/badge.svg)](https://github.com/cirKITers/qml-essentials/actions/workflows/test.yml) [![Documentation](https://github.com/cirKITers/qml-essentials/actions/workflows/docs.yml/badge.svg)](https://github.com/cirKITers/qml-essentials/actions/workflows/docs.yml)
+[![version](https://img.shields.io/badge/version-0.1.12-green.svg)](https://ea3a0fbb-599f-4d83-86f1-0e71abe27513.ka.bw-cloud-instance.org/lc3267/quantum/) [![Quality](https://github.com/cirKITers/qml-essentials/actions/workflows/quality.yml/badge.svg)](https://github.com/cirKITers/qml-essentials/actions/workflows/quality.yml) [![Testing](https://github.com/cirKITers/qml-essentials/actions/workflows/test.yml/badge.svg)](https://github.com/cirKITers/qml-essentials/actions/workflows/test.yml) [![Documentation](https://github.com/cirKITers/qml-essentials/actions/workflows/docs.yml/badge.svg)](https://github.com/cirKITers/qml-essentials/actions/workflows/docs.yml)
 
-## :scroll: About
+## 📜 About
 
 This repo contains some of the commonly used Ansaetze and coding stuff required for working with QML and Data-Reuploading models.
 There are also dedicated classes to calculate entanglement and expressiblity of a provided model as well as its Fourier coefficients.
 
-## :rocket: Getting Started
+## 🚀 Getting Started
 
-You can find installation instructions and documentation on the corresponding [Github Page](https://cirkiters.github.io/qml-essentials/).
+```
+pip install qml-essentials
+```
+or
+```
+poetry add qml-essentials
+```
 
-## :construction: Contributing
+To install our package from [PyPI](https://pypi.org/project/qml-essentials/).
+You can find details on how to use it and further documentation on the corresponding [Github Page](https://cirkiters.github.io/qml-essentials/).
+
+## 🚧 Contributing
 
 Contributions are very welcome! See [Contribution Guidelines](https://github.com/cirKITers/qml-essentials/blob/main/CONTRIBUTING.md).

docs/ansaetze.md

@@ -0,0 +1,13 @@
+# Ansaetze
+
+.. or Ansatzes as preferred by the english community.
+Anyway, we got various of the most-used Ansaetze implemented in this package.
+
+You can load them manually by
+```python
+from qml_essentials.ansaetze import Ansaetze
+print(Ansaetze.get_available())
+```
+
+However, usually you just want reference to them (by name) when instantiating a model.
+To get an overview of all the available Ansaetze, checkout the [references](https://cirkiters.github.io/qml-essentials/references/).

docs/coefficients.md

@@ -0,0 +1,18 @@
+# Coefficients
+
+A characteristic property of any Fourier model are its coefficients.
+Our package can, given a model, calculate the corresponding coefficients by utilizing the [Pennylane Fourier Coefficients](https://docs.pennylane.ai/en/stable/_modules/pennylane/fourier/coefficients.html) method.
+
+In the simplest case, this could look as follows:
+```python
+from qml_essentials.model import Model
+from qml_essentials.coefficients import Coefficients
+
+model = Model(
+            n_qubits=2
+            n_layers=1
+            circuit_type="HardwareEfficient",
+        )
+
+coeffs = Coefficients.sample_coefficients(model)
+```

docs/entanglement.md

@@ -0,0 +1,30 @@
+# Entanglement
+
+As one of the fundamental aspects of quantum computing, entanglement plays also an important role in quantum machine learning.
+Our package offers methods for calculating the entangling capability of a particular model.
+Currently, only the "Meyer-Wallach" measure is implemented, but other will be added soon!
+
+In the simplest case, this could look as follows:
+```python
+from qml_essentials.model import Model
+from qml_essentials.entanglement import Entanglement
+
+model = Model(
+            n_qubits=2,
+            n_layers=1,
+            circuit_type="HardwareEfficient",
+        )
+
+ent_cap = Entanglement.meyer_wallach(
+    model, n_samples=1000, seed=1000
+)
+```
+
+Note, that every function in this class accepts keyword-arguments which are being passed to the model call, so you could e.g. enable caching by
+```python
+ent_cap = Entanglement.meyer_wallach(
+    model, n_samples=1000, seed=1000, cache=True
+)
+```
+
+If you set `n_samples=None`, we will use the currently stored parameters of the model to estimate the degree of entanglement.