Doc

.dockerignore

@@ -0,0 +1,9 @@
+qlpdb/data/
+qlpdb/media/
+.git
+.github
+docs
+notebooks
+Notes
+paper
+*.egg-info

.gitattributes

@@ -0,0 +1 @@
+qlpdb/data.tar.gz filter=lfs diff=lfs merge=lfs -text

.github/workflows/compile-tex.yaml

@@ -16,10 +16,3 @@ jobs:
               with:
                   name: main.pdf
                   path: paper/main.pdf
-            - name: Send slack notification
-              uses: rtCamp/action-slack-notify@v2.0.2
-              env:
-                SLACK_WEBHOOK: https://hooks.slack.com/services/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
-                SLACK_USERNAME: "CompileBot"
-                SLACK_TITLE: "PDF compiled!"
-                SLACK_MESSAGE: "I was able to compile the most recent pdf. You can check it out here: https://github.com/cchang5/quantum_linear_programming/actions."

.github/workflows/docker-build.yaml

@@ -0,0 +1,12 @@
+name: Build qlp & qlpdb and load data
+on: [push]
+jobs:
+    docker_compose:
+        runs-on: ubuntu-latest
+        steps:
+            - name: Set up Git repository
+              uses: actions/checkout@v1
+            - name: Git LFS Pull
+              run: git lfs pull
+            - name: Build the stack
+              run: docker-compose build

Dockerfile

@@ -0,0 +1,45 @@
+# Load in python image
+FROM python:3.7-buster
+
+# Who to contact
+MAINTAINER Christopher Körber
+
+# Environment variables and dirs used
+ENV APP_DIR=/opt/app
+
+# Create dirs
+RUN mkdir -p $APP_DIR
+RUN mkdir -p $APP_DIR/qlp
+RUN mkdir -p $APP_DIR/qlpdb
+RUN mkdir -p $APP_DIR/.pip_cache
+
+# Install requirements
+RUN pip install --upgrade pip --cache-dir $APP_DIR/.pip_cache
+
+## Install qlp
+WORKDIR $APP_DIR/qlp
+COPY requirements.txt .
+COPY README.md .
+COPY setup.py .
+COPY qlp qlp
+RUN pip install -r requirements.txt --cache-dir $APP_DIR/.pip_cache
+RUN pip install .
+
+# Install qlpdb
+# DO NOT COPY FILES LIKE db-config.yaml or settings.yaml if they contain secrete passwords
+WORKDIR $APP_DIR/qlpdb
+COPY qlpdb/requirements.txt .
+COPY qlpdb/setup.py .
+COPY qlpdb/settings.yaml .
+COPY qlpdb/db-config.example.yaml db-config.yaml
+COPY qlpdb/README.md .
+COPY qlpdb/manage.py .
+COPY qlpdb/qlpdb qlpdb
+RUN pip install -r requirements.txt --cache-dir $APP_DIR/.pip_cache
+RUN pip install .
+
+# Port to expose
+EXPOSE 8000
+
+# Run entrypoint script
+CMD ["python", "manage.py", "runserver"]

README.md

@@ -1,26 +1,130 @@
-# qlp
+# Integer Programming from Quantum Annealing and Open Quantum Systems
 
-Module for converting set of inequalities to matrix which can be implemented on a quantum annealer.
+This repository contains software and data associated with the publication [Integer Programming from Quantum Annealing and Open Quantum Systems [2009.11970]](https://arxiv.org/abs/2009.11970).
 
-## Description
+It contains Python code for mapping [Integer Linear Programming problems](https://en.wikipedia.org/wiki/Integer_programming), notably the [Minimum Dominating Set](https://mathworld.wolfram.com/MinimumDominatingSet.html) Problem, to [QUBOs or Ising Hamiltonians utilized as input for Quantum Annealers](https://docs.dwavesys.com/docs/latest/c_gs_3.html#qubo).
+It furthermore contains code that simulates the quantum hardware.
 
-The module `qlp` converts a set of `sympy` equations to a `numpy` matrix which corresponds to a constrained minimization problem.
 
-## Install
-Install via pip
+## How to install it?
+
+This repository contains two modules:
+
+1. `qlp` used for computations and
+2. `qlpdb` for accessing and storing computation data
+
+
+### Install the computation module
+The `qlp` module can be installed via pip:
 ```bash
-pip install [-e] [--user] .
+pip install [--user] .
 ```
 
-## Compile the doc
-Run once to get dependencies
+### Install the data module
+
+To interface with the publication data, you also have to install the data module `qlpdb`
 ```bash
-pip install [-e] [--user] .
-pip install -r requirements-dev.txt
+cd qlpdb
+pip install [--user] .
 ```
-Compile the docs
+
+### Access publication data
+
+This repository contains all the data presented in [[2009.11970]](https://arxiv.org/abs/2009.11970).
+To access this data, you must host a [PostgreSQL database](https://www.postgresql.org/about/) (other database formats are not sufficient because we have implemented `JSON` and `ArrayFields`).
+We provide more information on the [`qlpdb/README.md`](qlpdb/README.md).
+
+## Usage
+
+### `qlp`
+
+The module `qlp` contains two major components:
+
+* The first submodule, `mds`, was used to map the Minimum Dominating Set Problem to annealing Hardware:
+    ```python
+    from qlp.mds.graph_tools as generate_nn_graph
+    from qlp.mds.qubo import get_mds_qubo
+
+    # generate line graph of length 4: o-o-o-o
+    graph, tag = gt.generate_nn_graph(4)
+    # Generate mds qubo
+    qubo = get_mds_qubo(
+        graph,          # The graph as a set of edges
+        directed=False, # no directed edges
+        penalty=2       # strength of penalty term
+    )
+    ```
+    The solution to the MDS problem is given by the bit vector `psi`, which minimizes
+    ```python
+    E = psi.T@qubo@psi
+    ```
+    The QUBO serves as input for the annealing hardware.
+* the second submodule, `tdse`, simulates the time-dependent Schrödinger equation for given input (Ising) Hamiltonians:
+    ```python
+    from qlp.mds.mds_qlpdb import QUBO_to_Ising, graph_summary
+    from qlp.tdse import TDSE
+
+    Jij, hi, c = QUBO_to_Ising(qubo.todense().tolist())
+    ising_params = {
+        "Jij": [list(row) for row in Jij],
+        "hi": list(hi),
+        "c": c,
+        "energyscale": annealing_time * 1000.0,
+        "qubo_constant": penalty * nvertices,
+        "penalty": penalty,
+    }
+    graph_params = graph_summary(tag, graph, qubo)
+    ...
+    # Initialize the solver
+    tdse = TDSE(
+        graph_params,  # Graph parameters
+        ising_params,  # Ising Hamiltonian parameters
+        offset_params, # how is the annealing curve implemented
+        solver_params, # numerical parameters for solving the time-dependent equation
+    )
+    # Compute the starting wave density
+    rho = tdse.init_densitymatrix(
+        temp,        # full counting decoherence parameters
+        temp_local,  # local decoherence parameters
+        initial_wavefunction="transverse",
+    )
+    tdse.gamma = gamma              # set FC decoherence rate
+    tdse.gamma_local = gamma_local  # set local decoherence rate
+    # Solve time-dependent Schrödinger equation
+    sol_densitymatrix = tdse.solve_mixed(rho)
+    ```
+
+See also the [`notebooks`](notebooks) folder, especially the [`notebooks/runs`](notebooks/runs), for reproducing computations.
+
+### `qlpdb`
+
+`qlpdb` is an [(ORM)](https://en.wikipedia.org/wiki/Object–relational_mapping) framework for mapping database structures to Python objects using [EspressoDB](https://espressodb.readthedocs.io/en/latest/) / [Django](https://www.djangoproject.com).
+
+Once the database [is appropriately set up](qlpdb/README.md), you can launch a local web server for inspecting data and browsing the documentation (viewable in any browser)
 ```bash
-cd docs
-make html
-open build/html/index.html
+cd qlpdb
+python manage.py runserver
 ```
+and query data in Python code
+```python
+from qlpdb.tdse.models import Tdse
+...
+solutions = Tdse.objects.filter(
+    graph__tag=graph_params["tag"],
+    offset__contains=convert_params(offset_params),
+    ising__contains=convert_params(ising_params),
+    solver__contains=solver_params,
+    wave__contains=wave_params,
+)
+```
+
+## Who is responsible for it?
+* [@cchang5](https://github.com/cchang5)
+* [@ckoerber](https://www.ckoerber.com)
+* [@lastyoru](https://github.com/lastyoru)
+
+Feel free to reach out for questions.
+
+## License
+
+BSD 3-Clause License. See also the [LICENSE](LICENSE.md) file.

docker-compose.yml

@@ -0,0 +1,22 @@
+version: '3'
+
+services:
+    db:
+        build:
+            context: qlpdb
+            dockerfile: Dockerfile.postgres
+        environment:
+            - POSTGRES_DB=qlpdb
+            - POSTGRES_USER=admin
+            - POSTGRES_PASSWORD=postgres
+        ports:
+            - "5432:5432"
+        expose:
+            - "5432"
+    qlpdb:
+        build: .
+        ports:
+            - "8000:8000"
+        depends_on:
+            - db
+        command: "python manage.py runserver 0.0.0.0:8000"