{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "0e1b1556-5dae-42b6-8fd1-7912b8dba389",
   "metadata": {},
   "source": [
    "(howto-utilities)=\n",
    "# Utilities\n",
    "\n",
    "Utilities module is mostly used for development of Quantify, not for the serving end user purposes.\n",
    "Here we store several examples of what is already there and how to work with them."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dd08b4c4-4f53-4684-9cef-6c1686c1c5c5",
   "metadata": {},
   "source": [
    "(howto-utilities-deprecation)=\n",
    "## Deprecation helper\n",
    "\n",
    "Note that the name of the current module is `__main__`, that gets normalized into `--main--` by the `@deprecated` helper. If you use these helpers in the actual code, the name of the package will appear instead."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "216c1888-4d66-43ef-9b76-44450197d093",
   "metadata": {},
   "outputs": [],
   "source": [
    "import warnings\n",
    "from quantify_core.utilities import deprecated"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ed5535ee-d6f6-4256-aff3-c5df576b0976",
   "metadata": {},
   "outputs": [],
   "source": [
    "@deprecated(\"99.99\", 'Initialize the \"foo\" literal directly.')\n",
    "def get_foo():\n",
    "    return \"foo\"\n",
    "\n",
    "\n",
    "with warnings.catch_warnings(record=True) as w:\n",
    "    warnings.simplefilter(\"always\")\n",
    "    get_foo()  # issues deprecation warning.\n",
    "\n",
    "assert len(w) == 1\n",
    "assert w[0].category is FutureWarning\n",
    "print(w[0].message)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4e7d242d-dde6-40c0-a6a2-84672e155147",
   "metadata": {},
   "outputs": [],
   "source": [
    "class NewClass:\n",
    "    def __init__(self, val):\n",
    "        self._val = val\n",
    "\n",
    "    def val(self):\n",
    "        return self._val\n",
    "\n",
    "@deprecated(\"99.99\", NewClass)\n",
    "class OldClass:\n",
    "    pass\n",
    "\n",
    "with warnings.catch_warnings(record=True) as w:\n",
    "    warnings.simplefilter(\"always\")\n",
    "    obj = OldClass(42)  # type: ignore\n",
    "\n",
    "assert len(w) == 1\n",
    "assert w[0].category is FutureWarning\n",
    "print(w[0].message)\n",
    "print(\"obj.val() =\", obj.val())  # type: ignore"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d14c95b8-41a4-46f6-ab7d-b41598721d79",
   "metadata": {},
   "outputs": [],
   "source": [
    "class SomeClass:\n",
    "    def __init__(self, val):\n",
    "        self._val = val\n",
    "\n",
    "    def val(self):\n",
    "        return self._val\n",
    "\n",
    "    @deprecated(\"7.77\", val)\n",
    "    def get_val(self):\n",
    "        '''Deprecated alias'''\n",
    "\n",
    "with warnings.catch_warnings(record=True) as w:\n",
    "    warnings.simplefilter(\"always\")\n",
    "    val = SomeClass(42).get_val()  # issues deprecation warning.\n",
    "\n",
    "assert len(w) == 1\n",
    "assert w[0].category is FutureWarning\n",
    "print(w[0].message)\n",
    "print(\"obj.get_val() =\", val)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "963b99b6-7a02-49c9-b6ec-7fe1761e2a9c",
   "metadata": {},
   "source": [
    "(howto-utilities-examples)=\n",
    "## Providing example data\n",
    "\n",
    "When writing documentation, author frequently needs to provide some semi-realistic data to provide a reader with more context and intended use case.\n",
    "We have some helpers to do so for the context of typical quantum computing data."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1479259a-dd65-477a-952b-9c5fab05784e",
   "metadata": {},
   "source": [
    "(howto-utilities-examples-trace)=\n",
    "### Trace readout mock data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "255a8ba8-1a72-4bfa-9da7-93859d4e9ed1",
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "\n",
    "from quantify_core.utilities.examples_support import mk_trace_for_iq_shot, mk_trace_time\n",
    "\n",
    "SHOT = 0.6 + 1.2j\n",
    "\n",
    "time = mk_trace_time()\n",
    "trace = mk_trace_for_iq_shot(SHOT)\n",
    "\n",
    "fig, ax = plt.subplots(1, 1, figsize=(12, 12 / 1.61 / 2))\n",
    "_ = ax.plot(time * 1e6, trace.imag, \".-\", label=\"I-quadrature\")\n",
    "_ = ax.plot(time * 1e6, trace.real, \".-\", label=\"Q-quadrature\")\n",
    "_ = ax.set_xlabel(\"Time [µs]\")\n",
    "_ = ax.set_ylabel(\"Amplitude [V]\")\n",
    "_ = ax.legend()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "38ded581-b2c6-4b58-b9e7-ccb4d0bbeb2d",
   "metadata": {},
   "source": [
    "(howto-utilities-examples-ssro)=\n",
    "### Single-shot readout mock data"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fd9445b6-555c-4b0f-809a-2cf0532c51ec",
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "\n",
    "from quantify_core.utilities.examples_support import mk_iq_shots\n",
    "\n",
    "center_0, center_1, center_2 = 0.6 + 1.2j, -0.2 + 0.5j, 0 + 1.5j\n",
    "\n",
    "data = mk_iq_shots(\n",
    "    100,\n",
    "    sigmas=[0.1] * 2,\n",
    "    centers=(center_0, center_1),\n",
    "    probabilities=(0.3, 1 - 0.3),\n",
    ")\n",
    "\n",
    "fig, ax = plt.subplots()\n",
    "ax.plot(data.real, data.imag, \"o\", label=\"Shots\")\n",
    "ax.plot(center_0.real, center_0.imag, \"^\", label=\"|0>\", markersize=10)\n",
    "ax.plot(center_1.real, center_1.imag, \"d\", label=\"|1>\", markersize=10)\n",
    "_ = ax.legend()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1980b489-1dc7-494b-83ea-f39dda1da4ed",
   "metadata": {},
   "outputs": [],
   "source": [
    "data = mk_iq_shots(\n",
    "    200,\n",
    "    sigmas=[0.1] * 3,\n",
    "    centers=(center_0, center_1, center_2),\n",
    "    probabilities=[0.35, 0.35, 1 - 0.35 - 0.35],\n",
    ")\n",
    "\n",
    "fig, ax = plt.subplots()\n",
    "ax.plot(data.real, data.imag, \"o\", label=\"Shots\")\n",
    "ax.plot(center_0.real, center_0.imag, \"^\", label=\"|0>\", markersize=10)\n",
    "ax.plot(center_1.real, center_1.imag, \"d\", label=\"|1>\", markersize=10)\n",
    "ax.plot(center_2.real, center_2.imag, \"*\", label=\"|2>\", markersize=10)\n",
    "_ = ax.legend()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1e5c2e23-476f-4e4a-8e1b-e495d36808c0",
   "metadata": {},
   "source": [
    "(howto-utilities-inspect)=\n",
    "## Inspect utilities\n",
    "\n",
    "We have a small set of utilities to generate list of classes, functions, members of module, etc.\n",
    "They are mostly useful for writing documentation, but probably autogenerated API documentation is a better fit in most cases."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "966d56ea-9c15-4977-a7ab-dcc6622660b5",
   "metadata": {},
   "outputs": [],
   "source": [
    "from typing import Dict\n",
    "\n",
    "from quantify_core.utilities import inspect_utils\n",
    "import quantify_core.analysis.base_analysis as ba\n",
    "\n",
    "class_dict: Dict[str, type] = inspect_utils.get_classes(ba)\n",
    "print(class_dict)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ee577944-34a3-486d-9532-f75e7d0c3f79",
   "metadata": {},
   "outputs": [],
   "source": [
    "from quantify_core.utilities import inspect_utils\n",
    "\n",
    "function_dict: Dict[str, type] = inspect_utils.get_functions(inspect_utils)\n",
    "print(function_dict)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.9.16"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}