{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Refs & Nexus Database\n",
    "\n",
    "\n",
    "One of the core features of Quantinuum Nexus is a database for usefully structuring your scientific data.\n",
    "\n",
    "`qnexus` aims to provide a useful way of interacting with this database through:\n",
    "\n",
    "- `Ref` objects that can be used as a proxy object to 'reference' data like Circuits or Projects.\n",
    "\n",
    "- `get` functions that take filters and try to return a single matching `Ref` \n",
    "\n",
    "- `get_all` functions that take filters and return `NexusIterator` objects for more than one matching`Ref`.  "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from datetime import datetime, timedelta\n",
    "\n",
    "import qnexus as qnx\n",
    "\n",
    "from pytket import Circuit"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get a 'ProjectRef' to a Project in Nexus, creating it if it doesn't exist\n",
    "my_project_ref = qnx.projects.get_or_create(name=\"My Project\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Refs have a pandas DataFrame representation\n",
    "my_project_ref.df()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Upload a circuit to Nexus, getting a CircuitRef in return\n",
    "my_circuit_ref = qnx.circuits.upload(\n",
    "    name=f\"My Circuit from {datetime.now()}\",\n",
    "    circuit = Circuit(2).H(0).CX(0,1).measure_all(),\n",
    "    project = my_project_ref,\n",
    ")\n",
    "\n",
    "my_circuit_ref.df()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Refs point to underlying scientific data, in this case a pytket Circuit. We need to call a function to 'dereference' the CircuitRef and obtain the underlying circuit."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_circuit_ref.download_circuit()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can perform queries to Nexus to retrieve all matching references."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "last_months_projects = qnx.projects.get_all(created_after=datetime.now() - timedelta(days=30))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This will return a NexusIterator, a Python object that represents our query. It behaves like a Python Iterator but with some additional functionality."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# See how many projects match my query\n",
    "last_months_projects.count()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Get the first ProjectRef\n",
    "next(last_months_projects)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "You can use other methods on the NexusIterator to get the ProjectRefs.\n",
    "\n",
    "```python\n",
    "# Get all the projects as a list\n",
    "last_months_projects.list()\n",
    "\n",
    "# Get all the projects as a DataFrame\n",
    "last_months_projects.df()\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If we think we can identify a single matching Ref to our query, we can use `get`. Bear in mind this will error if there is not exactly one matching Ref."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "qnx.projects.get(name_like=\"My Project\").df()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "qnexus-Rou6F43i-py3.11",
   "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.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}