First release of the framework (#1)

Author: DeborahVolpe

.flake8

@@ -11,6 +11,3 @@ coverage:
     patch:
       default:
         threshold: 1%
-codecov:
-  notify:
-    after_n_builds: 8

.github/codecov.yml

@@ -0,0 +1,25 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    groups:
+      github-actions:
+        patterns:
+          - "*"
+    schedule:
+      interval: "weekly"
+      day: "wednesday"
+      time: "06:00"
+      timezone: "Europe/Vienna"
+
+  - package-ecosystem: "pip"
+    directory: "/"
+    groups:
+      python-dependencies:
+        patterns:
+          - "*"
+    schedule:
+      interval: "weekly"
+      day: "friday"
+      time: "06:00"
+      timezone: "Europe/Vienna"

.github/dependabot.yml

@@ -7,7 +7,7 @@ on:
 jobs:
   python-packaging:
     name: 🐍 Packaging
-    uses: cda-tum/mqt-workflows/.github/workflows/[email protected].0
+    uses: cda-tum/mqt-workflows/.github/workflows/[email protected].1
     with:
       pure-python: true
 

.github/workflows/cd.yml

@@ -14,21 +14,19 @@ concurrency:
 jobs:
   change-detection:
     name: 🔍 Change
-    uses: cda-tum/mqt-workflows/.github/workflows/[email protected].0
+    uses: cda-tum/mqt-workflows/.github/workflows/[email protected].1
 
   python-tests:
     name: 🐍 Test
     needs: change-detection
     if: fromJSON(needs.change-detection.outputs.run-python-tests)
-    uses: cda-tum/mqt-workflows/.github/workflows/[email protected]
-    secrets:
-      token: ${{ secrets.CODECOV_TOKEN }}
+    uses: cda-tum/mqt-workflows/.github/workflows/[email protected]
 
   code-ql:
     name: 📝 CodeQL
     needs: change-detection
     if: fromJSON(needs.change-detection.outputs.run-code-ql)
-    uses: cda-tum/mqt-workflows/.github/workflows/[email protected].0
+    uses: cda-tum/mqt-workflows/.github/workflows/[email protected].1
 
   required-checks-pass: # This job does nothing and is only used for branch protection
     name: 🚦 Check

.github/workflows/ci.yml

@@ -15,22 +15,35 @@ ci:
 repos:
   # Standard hooks
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: "v4.5.0"
+    rev: v4.6.0
     hooks:
       - id: check-added-large-files
       - id: check-case-conflict
       - id: check-docstring-first
       - id: check-merge-conflict
+      - id: check-symlinks
       - id: check-toml
       - id: check-yaml
       - id: debug-statements
       - id: end-of-file-fixer
       - id: mixed-line-ending
+      - id: requirements-txt-fixer
       - id: trailing-whitespace
 
+  # Clean jupyter notebooks
+  - repo: https://github.com/srstevenson/nb-clean
+    rev: 3.2.0
+    hooks:
+      - id: nb-clean
+        args:
+          - --remove-empty-cells
+          - --preserve-cell-metadata
+          - raw_mimetype
+          - --
+
   # Handling unwanted unicode characters
   - repo: https://github.com/sirosen/texthooks
-    rev: "0.6.2"
+    rev: 0.6.6
     hooks:
       - id: fix-ligatures
       - id: fix-smartquotes
@@ -43,67 +56,47 @@ repos:
       - id: rst-directive-colons
       - id: rst-inline-touching-normal
 
-  # Clean jupyter notebooks
-  - repo: https://github.com/srstevenson/nb-clean
-    rev: "3.1.0"
-    hooks:
-      - id: nb-clean
-  # Check for spelling
-  - repo: https://github.com/codespell-project/codespell
-    rev: "v2.2.6"
-    hooks:
-      - id: codespell
-        args: ["-L", "wille,linz,fro"]
-        exclude: "mqt/benchviewer/templates/legal.html"
-
-  # Format configuration files with prettier
-  - repo: https://github.com/pre-commit/mirrors-prettier
-    rev: "v3.0.3"
-    hooks:
-      - id: prettier
-        types_or: [yaml, markdown, html, css, javascript, json]
-
+  # Python linting using ruff
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.1.4
+    rev: v0.4.7
     hooks:
       - id: ruff
         args: ["--fix", "--show-fixes"]
         types_or: [python, pyi, jupyter]
       - id: ruff-format
         types_or: [python, pyi, jupyter]
 
+  # Static type checking using mypy
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.10.0
+    hooks:
+      - id: mypy
+        files: ^(src/mqt|tests)
+        args: []
+        additional_dependencies:
+          - pytest
+          - numpy
+
   # Also run Black on examples in the documentation
   - repo: https://github.com/adamchainz/blacken-docs
     rev: 1.16.0
     hooks:
       - id: blacken-docs
-        additional_dependencies: [black==23.*]
+        additional_dependencies: [black==24.*]
 
-  - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.6.1
+  # Format configuration files with prettier
+  - repo: https://github.com/pre-commit/mirrors-prettier
+    rev: v4.0.0-alpha.8
     hooks:
-      - id: mypy
-        files: ^(src|tests)
-        args: []
-        additional_dependencies:
-          - importlib_resources
-          - qubovert
-          - pytest==7.4.0
-          - types-setuptools
-          - setuptools<=65.6.3
-          - sympy==1.12
-          - numpy==1.23.5
-          - dwave-samplers
-          - dwave.system
-          - docplex==2.25.236
-          - qiskit==0.45.3
-          - qiskit_optimization==0.4.0
-          - qiskit-algorithms==0.2.1
-          - qiskit_ibm_runtime==0.14.0
-          - matplotlib
-          - pandas
-          - PyPortfolioOpt
-          - scikit-learn
+      - id: prettier
+        types_or: [yaml, markdown, html, css, scss, javascript, json]
+
+  # Check for spelling
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.3.0
+    hooks:
+      - id: codespell
+        args: ["-L", "wille,linz", "--skip", "*.ipynb"]
 
   # Catch common capitalization mistakes
   - repo: local
@@ -112,7 +105,7 @@ repos:
         name: Disallow improper capitalization
         language: pygrep
         entry: PyBind|Numpy|Cmake|CCache|Github|PyTest|Mqt|Tum
-        exclude: (.joblib|.pre-commit-config.yaml)
+        exclude: .pre-commit-config.yaml
 
   # Check best practices for scientific Python code
   - repo: https://github.com/scientific-python/cookie

.github/workflows/mypy.yml

@@ -0,0 +1,30 @@
+version: 2
+
+submodules:
+  include: all
+  recursive: true
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+  jobs:
+    post_checkout:
+      # Skip docs build if the commit message contains "skip ci"
+      - (git --no-pager log --pretty="tformat:%s -- %b" -1 | grep -viq "skip ci") || exit 183
+      # Skip docs build if there are no changes related to docs
+      - |
+        if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/ .readthedocs.yaml src/mqt/ .github/contributing* .github/support*;
+        then
+          exit 183;
+        fi
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

.pre-commit-config.yaml

@@ -1,7 +1,6 @@
-@MISC{volpe2024towards,
+@INPROCEEDINGS{volpe2024towards,
 	AUTHOR      = {D.Volpe and N. Quetschlich and M. Graziano and G. Turvani and R. Wille},
 	TITLE       = {{Towards an Automatic Framework for Solving Optimization Problems with Quantum Computers}},
 	YEAR        = {2024},
-	EPRINT      = {},
-	EPRINTTYPE  = {},
+	BOOKTITLE   = {IEEE International Conference on Quantum Software (QSW)},
 }

.readthedocs.yaml

@@ -17,7 +17,7 @@
 
 # MQT Quantum Auto Optimizer: Automatic Framework for Solving Optimization Problems with Quantum Computers
 
-MQT Quantum Auto Optimizer is a framework that allows one to automatically translate an optimization problem into a quantum-compliant formulation and to solve it with one of the main quantum solvers (Quantum Annelar, QAOA, VQE and GAS)
+MQT Quantum Auto Optimizer is a framework that allows one to automatically translate an optimization problem into a quantum-compliant formulation and to solve it with one of the main quantum solvers (Quantum Annealer, Quantum Approximate Optimization Algorithm, Variational Quantum Eigensolver and Grover Adaptive Search)
 
 MQT Quantum Auto Optimizer is part of the [Munich Quantum Toolkit (MQT)](https://mqt.readthedocs.io/) developed by the [Chair for Design Automation](https://www.cda.cit.tum.de/) at the [Technical University of Munich](https://www.tum.de/). This framework has been developed in collaboration with the [VLSI Lab](https://www.vlsilab.polito.it/) of [Politecnico di Torino](https://www.polito.it).
 

CITATION.bib

@@ -0,0 +1,45 @@
+Constraints Class
+=================
+
+It manages the constraints of the problem. It is used to store the constraints and to check if a solution satisfies them.
+
+Constraints types supported
+---------------------------
+
+Types of constraints supported:
+
+- *Equality*, writing the equality as a quadratic penalty function, i.e. sum = b imposed with g = (sum-b)^2
+- *Inequality*, moving to equality with the continuous auxiliary variables a to be expanded with the encoding technique of the Variables class
+- *Not constraint* among binary variables, i.e. Not(a) = b imposed with g = 2ab - a - b + 1
+- *And constraint* among binary variables, i.e.  a and b = c imposed with  ab -2(a+b)c + 3c
+- *Or constraint* among binary variables, i.e. a or b = c imposed with ab + (a+b)(1-2c) + c
+- *Xor constraint* among binary variables, i.e. a xor b = c imposed with 2ab - 2(a+b)c - 4(a+b)\_aux+4_aux c +a+b+c+4+\_aux
+
+Constraints declarations
+------------------------
+
+The class provides methods to declare variables:
+
+- *add_constraint(expression: str, hard: bool = True, variable_precision: bool = True)*: adds a constraint to the list of constraints.
+    - *expression* is a string that represents the constraint
+    - *hard* parameter is a boolean that indicates if the constraint is hard or soft.
+    - *variable_precision* parameter is a boolean that indicates if the constraint is to be considered in the precision of the variables.
+
+Example:
+--------
+
+.. code-block:: python
+
+    from mqt.qao.constraints import Constraints
+    from mqt.qao.variables import Variables
+
+    constraint = Constraints()
+    variables = Variables()
+    variables.add_binary_variable("a")
+    variables.add_binary_variable("b")
+    variables.add_binary_variable("c")
+    variables.add_discrete_variable("d", [-1, 1, 3])
+    variables.add_continuous_variable("e", -2, 2, 0.25, "", "")
+    constraint.add_constraint("~a = b", True, True, False)
+    constraint.add_constraint("a | b = c", True, True, False)
+    constraint.add_constraint("d + e <= 1", True, True, False)

README.md

@@ -0,0 +1 @@
+.. include:: ../.github/contributing.rst