feat: q3as in default use case template (#105)

* feat: q3as in default use case template

* chore: add caution message for user cred

* fix: make q3as as demo and not solution

* fix: use env var for q3as secrets

* chore: add .env file for loading q3as secrets

* chore: add .env to submission template

---------

Co-authored-by: Julian Popescu <[email protected]>

template/.gitignore

@@ -0,0 +1 @@
+!assets/**/*

template/assets/use_case/template/.env

@@ -0,0 +1,13 @@
+# Keep your secrets safe here and load with python-dotenv
+
+# Q3AS API Key
+# ---
+# Start by visiting https://q3as.aqora.io and signing in with your GitHub or Google account.
+# Click on your profile in the top right and go to API Keys.
+# Tap Add API Key and enter a description for your API key.
+# Copy your id and secret and paste them here
+
+Q3AS_ID="<your_q3as_id>"
+Q3AS_SECRET="<your_q3as_secret>"
+
+# ---

template/assets/use_case/template/.gitignore → template/assets/use_case/template/.gitignore.hbs

@@ -53,3 +53,6 @@ docs/_build/
 .aqora
 .venv
 __aqora__/
+
+# environment
+.env

template/assets/use_case/template/README.md.hbs

@@ -13,3 +13,6 @@ And when you are ready to submit run
 ```bash
 aqora upload
 ```
+
+## Extra Notebook 
+- **[q3as_demo.ipynb](./template/submission/q3as_demo.ipynb)** : This is an additional notebook provided as an q3as usage example.

template/assets/use_case/template/pyproject.toml.hbs

@@ -4,7 +4,10 @@ version = "0.1.0"
 requires-python = ">={{ python_version }}"
 
 # You can add dependencies with `aqora add`
-dependencies = []
+dependencies = [
+  "q3as>=0.1.3",
+  "python-dotenv>=1.0.1",
+]
 
 [build-system]
 requires = [
@@ -24,4 +27,4 @@ type = "submission"
 competition = "{{ competition }}"
 
 [tool.aqora.refs]
-solution = { path = "submission.solution", notebook = true }
+solution = { path = "submission.solution", notebook = true }

template/assets/use_case/template/submission/q3as_demo.ipynb

@@ -0,0 +1,123 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Getting an API Key\n",
+    "\n",
+    "To run your algorithms in the cloud, you have to create an API key and load it into your Credentials\n",
+    "\n",
+    "Start by visiting https://q3as.aqora.io and signing in with your GitHub or Google account. Click on your profile in the top right and go to API Keys. Tap Add API Key and enter a description for your API key. Tap Copy id and secret and paste them into the [`env`](../.env) file. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from q3as import Client, Credentials\n",
+    "from dotenv import load_dotenv\n",
+    "import os\n",
+    "\n",
+    "load_dotenv()\n",
+    "\n",
+    "id = os.getenv(\"Q3AS_ID\")\n",
+    "secret = os.getenv(\"Q3AS_SECRET\")\n",
+    "\n",
+    "client = Client(Credentials(id=id, secret=secret))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "From here we can start building out the definition of the problem that we would like to solve. We'll start with an NP Hard problem called Maximum Weighted Cut. We can define a graph we would like to cut by supplying a list of edges and their weights."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "graph = [\n",
+    "    (0, 1, 1.0),\n",
+    "    (0, 2, 1.0),\n",
+    "    (0, 4, 1.0),\n",
+    "    (1, 2, 1.0),\n",
+    "    (2, 3, 1.0),\n",
+    "    (3, 4, 1.0),\n",
+    "]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We can then give this graph to our \"Application\" which will define what we want to do with it and how to translate it into the quantum world and back. Q3AS defines multiple such problem domains that you can use"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from q3as.app import Maxcut\n",
+    "\n",
+    "app = Maxcut(graph)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We now need to define a solver for our problem. We will use a Variational Quantum Eigensolver or VQE for short"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from q3as import VQE\n",
+    "\n",
+    "vqe = VQE.builder().app(app)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now we can send the job to the Q3AS, and let the server handle the computation and the visualization of the intermediate results"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "job = vqe.send(client)\n",
+    "# get the name of the job\n",
+    "print(job.name)\n",
+    "# wait for and retrieve the results of the job\n",
+    "print(job.result())\n",
+    "# get the problem cost\n",
+    "print(job.result().cost)\n",
+    "# see job in the dashbaord\n",
+    "print(\"https://q3as.aqora.io/jobs/\" + job.name)"
+   ]
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}