docs: more example notebooks

CQCL · Oct 29, 2024 · d332267 · d332267
1 parent 47a00af
commit d332267
Show file tree

Hide file tree

Showing 18 changed files with 737 additions and 4 deletions.
diff --git a/examples/auth_quotas.ipynb → examples/basics/auth_quotas.ipynb b/examples/auth_quotas.ipynb → examples/basics/auth_quotas.ipynb
diff --git a/examples/backend_configuration.ipynb → examples/basics/backend_configuration.ipynb b/examples/backend_configuration.ipynb → examples/basics/backend_configuration.ipynb
diff --git a/examples/basics/braket_examples.ipynb b/examples/basics/braket_examples.ipynb
@@ -0,0 +1,179 @@
+{
+ "cells": [
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "5ad2486b",
+   "metadata": {
+    "nbsphinx": {
+     "execute": "never"
+    }
+   },
+   "source": [
+    "# Braket via Nexus\n",
+    "\n",
+    "Here you can find some examples and explanations on running quantum circuits on [AWS Braket](https://aws.amazon.com/braket/) via Nexus. \n",
+    "\n",
+    "These will require that you have set Braket credentials via Settings->Linked Accounts on the Nexus website."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7234def9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from datetime import datetime\n",
+    "from pytket import Circuit\n",
+    "\n",
+    "import qnexus as qnx"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "71767db3",
+   "metadata": {},
+   "source": [
+    "List available Braket devices, optionally specifying a specific AWS region (by default devices for ALL regions will be returned)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "4b7f0579",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "qnx.devices.get_all(\n",
+    "    issuers=[qnx.devices.IssuerEnum.BRAKET]\n",
+    ").df()"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "63794f17",
+   "metadata": {},
+   "source": [
+    "To configure Nexus to target Braket, you'll need to provide the following arguments to the BraketConfig.\n",
+    "\n",
+    "- `local`: `bool`\n",
+    "    - if true then the circuit will run as a simulation in the Nexus cloud.\n",
+    "- `device_type`: `str`\n",
+    "    - device type from device ARN (e.g. `\"qpu\"`, `\"quantum-simulator\"`)\n",
+    "- `provider`: `str`\n",
+    "    - provider name from device ARN (e.g. `\"ionq\"`, `\"rigetti\"`, `\"oqc\"`, `\"amazon\"`, ...)\n",
+    "- `device`: `str`\n",
+    "    - device name from device ARN (e.g. `\"ionQdevice\"`, `\"Aspen-8\"`, `\"sv1\"`, ...)\n",
+    "- `s3_bucket`: `str`\n",
+    "    - name of S3 bucket to store results\n",
+    "- `s3_folder`: `str`\n",
+    "    - name of folder (`\"key\"`) in S3 bucket to store results in"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "aaef7952",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "braket_config = qnx.BraketConfig(\n",
+    "    local=True,\n",
+    "    device_type=\"quantum-simulator\",\n",
+    "    provider=\"amazon\",\n",
+    "    device=\"sv1\",\n",
+    "    s3_bucket=\"\",\n",
+    "    s3_folder=\"\",\n",
+    ")"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "068ec022",
+   "metadata": {},
+   "source": [
+    "## Example of compiling and executing a circuit on AWS Braket"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9c6f87a8",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "my_project_ref = qnx.projects.get_or_create(name=\"My AWS Braket Project\")\n",
+    "\n",
+    "circuit = Circuit(2).H(0).CX(0,1).measure_all()\n",
+    "\n",
+    "my_circuit_ref = qnx.circuits.upload(\n",
+    "    name=f\"My AWS Braket Circuit from {datetime.now()}\",\n",
+    "    circuit = circuit,\n",
+    "    project = my_project_ref,\n",
+    ")\n",
+    "\n",
+    "compiled_circuits = qnx.compile(\n",
+    "    circuits=[my_circuit_ref],\n",
+    "    name=f\"My Compile Job from {datetime.now()}\",\n",
+    "    optimisation_level=1,\n",
+    "    backend_config=braket_config,\n",
+    "    project=my_project_ref,\n",
+    ")\n",
+    "\n",
+    "compiled_circuits.df()\n",
+    "\n",
+    "execute_job_ref = qnx.start_execute_job(\n",
+    "    circuits=compiled_circuits,\n",
+    "    name=f\"My Execute Job from {datetime.now()}\",\n",
+    "    n_shots=[100],\n",
+    "    backend_config=braket_config,\n",
+    "    project=my_project_ref,\n",
+    ")\n",
+    "\n",
+    "qnx.jobs.wait_for(execute_job_ref)\n",
+    "\n",
+    "\n",
+    "# Retrieve a ExecutionResultRef for every Circuit that was executed\n",
+    "execute_job_result_refs = qnx.jobs.results(execute_job_ref)\n",
+    "\n",
+    "# Get a pytket BackendResult for the execution\n",
+    "result = execute_job_result_refs[0].download_result()\n",
+    "\n",
+    "result.get_counts()"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "pytket-myqos-f6eBn_pg-py3.10",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.10"
+  },
+  "nbsphinx": {
+   "execute": "never"
+  },
+  "vscode": {
+   "interpreter": {
+    "hash": "f43baf218a87c34b36d0e78bf5bbda01518be954b242b9492c4c47b42fef4ee3"
+   }
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/examples/data/add_one.wasm → examples/basics/data/add_one.wasm b/examples/data/add_one.wasm → examples/basics/data/add_one.wasm
diff --git a/examples/devices_credentials.ipynb → examples/basics/devices_credentials.ipynb b/examples/devices_credentials.ipynb → examples/basics/devices_credentials.ipynb
diff --git a/examples/getting_started.ipynb → examples/basics/getting_started.ipynb b/examples/getting_started.ipynb → examples/basics/getting_started.ipynb
diff --git a/examples/basics/ibmq_examples.ipynb b/examples/basics/ibmq_examples.ipynb
@@ -0,0 +1,196 @@
+{
+ "cells": [
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "d60a276e",
+   "metadata": {
+    "collapsed": false
+   },
+   "source": [
+    "# IBMQ via Nexus\n",
+    "\n",
+    "Here you can find some examples and explanations on using IBMQ via Nexus. These will require that you have set IBMQ credentials via Settings->Linked Accounts on the Nexus website.\n",
+    "\n",
+    "There are two available configurations:\n",
+    "\n",
+    "- `IBMQConfig` - for submitting projects to the IBMQ system\n",
+    "- `IBMQEmulatorConfig` - for submitting to an emulation of an IBMQ device (running on an `AerBackend` based off sampled device characteristics), but running in a Nexus server."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "id": "e85549e3",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from datetime import datetime\n",
+    "from pytket import Circuit\n",
+    "\n",
+    "import qnexus as qnx"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "750f8bfe",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# See the names of the IBMQ devices available to you by default\n",
+    "qnx.devices.get_all(\n",
+    "    issuers=[qnx.devices.IssuerEnum.IBMQ]\n",
+    ").df()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "57fbc895",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Alternatively if you would like to list devices available to you through a particular IBMQ plan, you can specify the hub, group and project\n",
+    "qnx.devices.get_all(\n",
+    "    issuers=[qnx.devices.IssuerEnum.IBMQ],\n",
+    "    ibmq_hub=\"my-hub\", \n",
+    "    ibmq_group=\"my-group\", \n",
+    "    ibmq_project=\"my-project\"\n",
+    ").df()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ece09f03",
+   "metadata": {},
+   "source": [
+    "## IBMQConfig\n",
+    "\n",
+    "To use Nexus to run projects on IBMQ, you'll need to specify some configuration in a `IBMQConfig`.\n",
+    "\n",
+    "The arguments you can provide to this are:\n",
+    "\n",
+    "- `backend_name` (see Available Devices below)\n",
+    "- `hub` - The IBMQ hub you are running under\n",
+    "- `group` - The IBMQ group\n",
+    "- `project` - The IBMQ project\n",
+    "- `monitor` - Boolean specifying if you want to use the IBM job monitor. Defaults to True."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "50a48df2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# An example configuration specifying the 127 qubit ibm_kyiv machine under the open plan\n",
+    "ibm_kyiv_configuration = qnx.IBMQConfig(\n",
+    "    backend_name=\"ibm_kyiv\", hub=\"ibm-q\", group=\"open\", project=\"main\"\n",
+    ")\n",
+    "\n",
+    "# Use this configuration when submitting compile or execute jobs"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "id": "ac538cc4",
+   "metadata": {},
+   "source": [
+    "## The IBMQ Emulator\n",
+    "\n",
+    "To use Nexus to run projects on the IBMQ emulator, you'll need to specify some configuration in a `IBMQEmulatorConfig`.\n",
+    "\n",
+    "The arguments you can provide to this are:\n",
+    "\n",
+    "- `backend_name` - You can specify any available IBMQ backend\n",
+    "- `hub` - The IBMQ hub you are running under\n",
+    "- `group` - The IBMQ group\n",
+    "- `project` - The IBMQ project"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "id": "19750eac",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# An example configuration specifying the 5 qubit ibm_nairobi machine (no longer available)\n",
+    "ibm_nairobi_emulator_configuration = qnx.IBMQEmulatorConfig(\n",
+    "    backend_name=\"ibm_nairobi\", hub=\"ibm-q\", group=\"open\", project=\"main\"\n",
+    ")\n",
+    "\n",
+    "# Use this configuration when submitting compile or execute jobs"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "ddec4c84",
+   "metadata": {},
+   "source": [
+    "## Example of executing a circuit on ibm_kyiv"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c7228f69",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "my_project_ref = qnx.projects.get_or_create(name=\"My IBM Kyiv Project\")\n",
+    "\n",
+    "circuit = Circuit(2).H(0).CX(0,1).measure_all()\n",
+    "\n",
+    "my_circuit_ref = qnx.circuits.upload(\n",
+    "    name=f\"My IBM Kyiv Circuit from {datetime.now()}\",\n",
+    "    circuit = circuit,\n",
+    "    project = my_project_ref,\n",
+    ")\n",
+    "\n",
+    "execute_job_ref = qnx.start_execute_job(\n",
+    "    circuits=[my_circuit_ref],\n",
+    "    name=f\"My Execute Job from {datetime.now()}\",\n",
+    "    n_shots=[100],\n",
+    "    backend_config=ibm_kyiv_configuration,\n",
+    "    project=my_project_ref,\n",
+    ")\n",
+    "\n",
+    "qnx.jobs.wait_for(execute_job_ref)\n",
+    "\n",
+    "\n",
+    "# Retrieve a ExecutionResultRef for every Circuit that was executed\n",
+    "execute_job_result_refs = qnx.jobs.results(execute_job_ref)\n",
+    "\n",
+    "# Get a pytket BackendResult for the execution\n",
+    "result = execute_job_result_refs[0].download_result()\n",
+    "\n",
+    "result.get_counts()"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "qnexus-Rou6F43i-py3.12",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/examples/jobs_results.ipynb → examples/basics/jobs_results.ipynb b/examples/jobs_results.ipynb → examples/basics/jobs_results.ipynb
diff --git a/examples/projects_properties_context.ipynb → .../basics/projects_properties_context.ipynb b/examples/projects_properties_context.ipynb → .../basics/projects_properties_context.ipynb
diff --git a/examples/quantinuum_examples.ipynb → examples/basics/quantinuum_examples.ipynb b/examples/quantinuum_examples.ipynb → examples/basics/quantinuum_examples.ipynb
@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Quantinuum Simulators, Emulators and Quantum Hardware\n",
+    "# Quantinuum Simulators, Emulators and Quantum Hardware, via Nexus\n",
     "\n",
     "\n",
     "This notebook outlines how to target and configure specific simulators, emulators and quantum hardware offered by Quantinuum.\n",

diff --git a/examples/refs_nexus_iterator.ipynb → examples/basics/refs_nexus_iterator.ipynb b/examples/refs_nexus_iterator.ipynb → examples/basics/refs_nexus_iterator.ipynb
diff --git a/examples/saving_refs.ipynb → examples/basics/saving_refs.ipynb b/examples/saving_refs.ipynb → examples/basics/saving_refs.ipynb
diff --git a/examples/teams_roles.ipynb → examples/basics/teams_roles.ipynb b/examples/teams_roles.ipynb → examples/basics/teams_roles.ipynb
diff --git a/examples/wasm_examples.ipynb → examples/basics/wasm_examples.ipynb b/examples/wasm_examples.ipynb → examples/basics/wasm_examples.ipynb
diff --git a/examples/data/rus.wasm b/examples/data/rus.wasm