Merge pull request #118 from QUARK-framework/dev

Release 2.0.3

.github/workflows/lint.yml

@@ -21,10 +21,10 @@ jobs:
         shell: bash -el {0}
     steps:
       - name: Check out Git repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.9.16'
           token: ${{ secrets.QUARK_GH_GITHUB_COM_TOKEN }}

.github/workflows/test.yml

@@ -17,10 +17,10 @@ jobs:
         shell: bash -el {0}
     steps:
       - name: Check out Git repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: '3.9.16'
           cache: 'pip' # caching pip dependencies

.settings/module_db.json

@@ -1,7 +1,7 @@
 {
-  "build_number": 6,
-  "build_date": "22-11-2023 13:47:42",
-  "git_revision_number": "5ea1fcf56c438df4b32fcc318dcb6e2c8e58447b",
+  "build_number": 7,
+  "build_date": "20-03-2024 12:51:58",
+  "git_revision_number": "3be6f3847150d4bb8debee2451522b0b19fa205f",
   "modules": [
     {
       "name": "PVC",
@@ -1863,6 +1863,16 @@
                   "module": "modules.devices.HelperClass",
                   "requirements": [],
                   "submodules": []
+                },
+                {
+                  "name": "ibm_eagle",
+                  "class": "HelperClass",
+                  "args": {
+                    "device_name": "ibm_eagle"
+                  },
+                  "module": "modules.devices.HelperClass",
+                  "requirements": [],
+                  "submodules": []
                 }
               ]
             }

README.md

@@ -126,6 +126,23 @@ Example run (You need to check at least one option with an ``X`` for the checkbo
 
 All used config files, logs and results are stored in a folder in the ```benchmark_runs``` directory.
 
+#### interrupt/resume
+The processing of backlog items may get interrupted in which case you will see something like
+```
+2024-03-13 10:25:20,201 [INFO] ================================================================================
+2024-03-13 10:25:20,201 [INFO] ====== Run 3 backlog items with 10 iterations - FINISHED:15 INTERRUPTED:15
+2024-03-13 10:25:20,201 [INFO] ====== There are interrupted jobs. You may resume them by running QUARK with
+2024-03-13 10:25:20,201 [INFO] ====== --resume-dir=benchmark_runs\tsp-2024-03-13-10-25-19
+2024-03-13 10:25:20,201 [INFO] ================================================================================
+```
+This happens if you press CTRL-C or if some QUARK module does its work asynchronously, e.g. by submitting its job to some 
+batch system. Learn more about how to write asynchronous modules in the [developer guide](https://quark-framework.readthedocs.io/en/dev/).
+You can resume an interrupted QUARK run by calling: 
+```
+python src/main.py --resume-dir=<result-dir>
+```
+Note that you can copy/paste the --resume-dir option from the QUARK output as shown in the above example.
+
 #### Non-Interactive Mode
 It is also possible to start the script with a config file instead of using the interactive mode:
 ```

docs/conf.py

@@ -106,6 +106,9 @@
 #
 # html_sidebars = {}
 
+# If smartquotes is True, double dashes (--) are transformed to en-dashes (–)
+# which could be confused with single dashes (-).
+smartquotes = False
 
 # -- Options for HTMLHelp output ---------------------------------------------
 

docs/developer.rst

@@ -192,6 +192,35 @@ Example for an application, which should reside under ``src/modules/applications
             def save(self, path, iter_count):
                 save_your_application(self.application, f"{path}/application.txt")
 
+Writing an asynchronous Module
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+A typical example for an asynchronous module is a solver which submits its job into
+the queue of some server and retrieves the result some times later. In QUARK this is
+supported via the interrupt/resume mechanism.
+
+QUARK modules may return instructions to the BenchmarkManager as first entry in the return value of
+pre and post-process. Currently the following instructions are supported:
+    - PROCEED
+    - INTERRUPT
+
+PROCEED: If the BenchmarkManager gets the instruction "PROCEED" (or no instruction at all) it continues with the regular QUARK workflow.
+If the current job can be finished without getting an "INTERRUPT" instruction or an exception,
+the BenchmarkManager adds "quark_job_status"=FINISHED to the metrics.
+
+INTERRUPT: If the BenchmarkManager gets the instruction "INTERRUPT" it stops the current QUARK workflow,
+adds "quark_job_status"=INTERRUPTED to the metrics, saves all the metrics written so far to the BenchmarkRecord
+and continues with the configuration/repetition loop.
+
+QUARK Resume Mode:
+
+After running QUARK in its regular mode QUARK can be run again on the same results directory in resume mode by
+specifying the existing results directory with the --resume-dir option. This can be done repeatedly for the same
+results directory.
+
+If QUARK is called in resume mode the module which has returned an INTERRUPT previously will be called again
+with the same input supplemented by the key word argument "previous_job_info" which contains all the information
+the moduls has written to the metrics on the previous run.
+
 
 Updating the Module Database
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^

docs/tutorial.rst

@@ -133,6 +133,20 @@ Example run (You need to check at least one option with an ``X`` for the checkbo
 All used config files, logs and results are stored in a folder in the
 ``benchmark_runs`` directory.
 
+Access to IBM Eagle
+^^^^^^^^^^^^^^^^^^^
+
+In order to use the IBM Eagle device in QUARK you have to first save your API token. 
+This can be done similar to accessing AWS:
+
+.. code:: bash
+
+   export ibm_quantum_token='Your Token'
+   python src/main.py
+
+::
+
+
 Non-Interactive Mode
 ^^^^^^^^^^^^^^^^^^^^