notebooks/an_intro_to_quantinuum_nexus.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "637c2589",
   "metadata": {
    "nbsphinx": {
     "execute": "never"
    }
   },
   "source": [
    "# Nexus Quick Start\n",
    "## iQuHACK 2025"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b33d0004",
   "metadata": {},
   "source": [
    "Welcome to the Quantinuum Nexus Lab! A hosted Jupyter environment with the pre-installed Python software packages you'll need, including:\n",
    "\n",
    "* [`pytket`](https://tket.quantinuum.com/api-docs/index.html): Quantinuum's Python SDK for TKET quantum programming tools.\n",
    "* [`qnexus`](https://docs.quantinuum.com/nexus/): the client software for submitting jobs to the Quantinuum Nexus platform\n",
    "\n",
    "You can also open a terminal in the Lab to commit and push your changes to your team's fork of this repository.\n",
    "\n",
    "### Step 1. Enable access to the Quantinuum simulator and emulator\n",
    "\n",
    "We provide two systems for you to target when executing quantum circuits as part of the challenge.\n",
    "\n",
    "\n",
    "\n",
    "* `H1-Emulator` (recommmended): A noisy of Quantinuum's 20 qubit `H1-1` quantum computer hosted within Quantinuum Nexus.\n",
    "* `H1-1LE`: a noiseless simulator of Quantinuum's 20 qubit `H1-1` quantum computer.\n",
    "* `H1-1E`: a noisy 'emulator' of `H1-1`. This system is much closer to the actual `H1-1` machine, and has longer queuing times. We recommend only using this system when you need to execute your circuit on something closer to the real hardware.\n",
    "* `H1-1SC`: a 'syntax checker' system for optionally testing things out (it won't run any code but can be used for validation of your usage of the API). \n",
    "\n",
    "In order to access these systems, you'll need to activate your access:\n",
    "\n",
    "* Visit https://nexus.quantinuum.com/backends/quantinuum and enter your username and password credentials by selecting 'Configure'.\n",
    "* You'll know if this succeeds as your available Quantinuum devices will be displayed below. The `H1-1LE` simulator is very new and might not be displayed, so don't worry if it doesn't show up.\n",
    "\n",
    "\n",
    "### Step 2: Try out the example code below to compile and simulate your first circuit.\n",
    "\n",
    "- Copy this file or its contents into the Quantinuum Nexus hub and run the code below to see some example usage.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8568469f",
   "metadata": {},
   "source": [
    "## Lets compose a quantum circuit using Pytket\n",
    "\n",
    "Nexus uses [pytket Circuits](https://cqcl.github.io/pytket/manual/manual_circuit.html). Here we'll create a simple one."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fa8e85be",
   "metadata": {},
   "outputs": [],
   "source": [
    "from pytket import Circuit\n",
    "from pytket.circuit.display import render_circuit_jupyter as draw\n",
    "\n",
    "circuit = Circuit(4, 4).H(0).CX(0, 1).CX(1, 2).CX(2, 3)\n",
    "circuit.measure_all()\n",
    "\n",
    "circuit.name = \"my-first-circuit\"\n",
    "\n",
    "draw(circuit)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "announced-viewer",
   "metadata": {},
   "source": [
    "### Create a Nexus Project\n",
    "\n",
    "A project is a way to compartmentalize your running jobs and data, allowing you to retrieve and share data easily."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "cdf45ead",
   "metadata": {},
   "outputs": [],
   "source": [
    "import qnexus as qnx\n",
    "\n",
    "# ADD YOUR OWN PROJECT NAME HERE\n",
    "project = qnx.projects.get_or_create(name=\"iQuHACK2025-demo\")\n",
    "qnx.context.set_active_project(project)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f8e81f3e",
   "metadata": {},
   "source": [
    "You should be able to see this project if you visit [https://nexus.quantinuum.com/projects/all](https://nexus.quantinuum.com/projects/all)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "17e15346-6d4d-428f-844d-51894b25a935",
   "metadata": {},
   "outputs": [],
   "source": [
    "import datetime\n",
    "\n",
    "jobname_suffix = datetime.datetime.now().strftime(\"%Y_%m_%d-%H-%M-%S\")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "15a83542",
   "metadata": {},
   "source": [
    "### Set up your Backend Configuration\n",
    "\n",
    "In Quantinuum Nexus, we use `BackendConfig`s to specify the details of the quantum system we want to target.\n",
    "\n",
    "\n",
    "For this example, we'll use ``QuantinuumConfig``, to configure Nexus to target a simulator for Quantinuum's `H1-1LE` device. \n",
    "\n",
    "We'll pass in the `device_name` and also `user_group=\"iQuHACK_2024\"` to identify jobs as part of iQuHack 2024."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "abc8440f",
   "metadata": {},
   "outputs": [],
   "source": [
    "h1_config = qnx.QuantinuumConfig(device_name=\"H1-Emulator\")\n",
    "\n",
    "aer_config = qnx.AerStateConfig()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8c187c8d-8ba6-4b02-beb4-bd8d23ddfe69",
   "metadata": {},
   "source": [
    "## Upload and download circuits"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "66e15905-a279-492d-bb76-7f7999d53a5e",
   "metadata": {},
   "outputs": [],
   "source": [
    "ref = qnx.circuits.upload(circuit=circuit, name=f\"GHZ-Circuit-{jobname_suffix}\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "09c1c834-02c7-4ae4-8b93-63a3ab67e8da",
   "metadata": {},
   "outputs": [],
   "source": [
    "draw(ref.download_circuit())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7d6705bb",
   "metadata": {},
   "source": [
    "### Compile the circuit\n",
    "\n",
    "Nexus offers compilation with the TKET quantum compiler, this is an easy way to:\n",
    "\n",
    "* Optimize the circuit\n",
    "* Convert it to run on a specific quantum device, which might not support all quantum gates.\n",
    "\n",
    "For the challenge you can use pytket directly to compile circuits, or you can get Nexus to do the compilation for you. If you'd like to disable any changes to your circuit other than making sure that the gateset is correct, you can always set `optimisation_level=0`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2e954153",
   "metadata": {},
   "outputs": [],
   "source": [
    "ref_compile_job = qnx.start_compile_job(\n",
    "    circuits=[ref],\n",
    "    backend_config=aer_config,\n",
    "    optimisation_level=2,\n",
    "    name=f\"compilation-job-{jobname_suffix}\"\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "eedb2e5f",
   "metadata": {},
   "source": [
    "You should now see the compile show up when you click on your project on [https://nexus.quantinuum.com/projects/all](https://nexus.quantinuum.com/projects/all).\n",
    "\n",
    "If you're curious to see what the compiler did, you can click on the job results and see all the passes the compiler performed on your circuit. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "d78c0ee0-4e6f-4f38-9043-8789a4253693",
   "metadata": {},
   "outputs": [],
   "source": [
    "qnx.jobs.wait_for(ref_compile_job)\n",
    "ref_compiled_circuit = qnx.jobs.results(ref_compile_job)[0].get_output()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "80b75c31-d0fa-46a9-83e8-f9b2bfb2462b",
   "metadata": {},
   "outputs": [],
   "source": [
    "compiled_circuit = ref_compiled_circuit.download_circuit()\n",
    "\n",
    "draw(compiled_circuit)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5216cf39",
   "metadata": {},
   "source": [
    "### Submit the circuit for execution\n",
    "\n",
    "Nexus will take care of submitting the circuit to your chosen device and storing the results when it has executed.\n",
    "\n",
    "In this case we are executing the circuit on a simulator running in the Nexus cluster so we should get the results back quickly, however many quantum devices have lengthy queues in which case Nexus will track the job and retrieve the results when they are ready."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "id": "opened-hobby",
   "metadata": {},
   "outputs": [],
   "source": [
    "ref_execute_job = qnx.start_execute_job(\n",
    "    circuits=[ref_compiled_circuit],\n",
    "    n_shots=[100],\n",
    "    backend_config=aer_config,\n",
    "    name=f\"execution-job-{jobname_suffix}\"\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "87b00dcb-b522-4874-af2a-2ac9aa6cc397",
   "metadata": {},
   "outputs": [],
   "source": [
    "qnx.jobs.status(ref_execute_job)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "id": "39e9ac93-6ca5-48d1-b30d-d2c8d11e1e7c",
   "metadata": {},
   "outputs": [],
   "source": [
    "qnx.jobs.wait_for(ref_execute_job)\n",
    "ref_result = qnx.jobs.results(ref_execute_job)[0]\n",
    "backend_result = ref_result.download_result()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f1f7f8ca-541b-428e-9664-b4bc2b415312",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(backend_result.get_state())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ce945166",
   "metadata": {},
   "source": [
    "You can also view the job from the project page on the Quantinuum Nexus website and check out the results there.\n",
    "\n",
    "\n",
    "### Next steps:\n",
    "\n",
    "Use the website to:\n",
    "- make a `Team` on the Nexus website and add your hackathon team members.\n",
    "- give this `Team` access to the Nexus `Project` you just created."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": ".venv",
   "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.11.1"
  },
  "widgets": {
   "application/vnd.jupyter.widget-state+json": {
    "state": {},
    "version_major": 2,
    "version_minor": 0
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}