{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "82e8096b",
   "metadata": {},
   "source": [
    "# Abstract Instruments and parameters\n",
    "\n",
    "Abstract parameters allow us to create abstract instrument types which are guaranteed to have certain parameters present. For instance, this will allow us to create a unified interface for all voltage sources.\n",
    "\n",
    "Note: An instrument which contains abstract parameters shall be called an 'Abstract Instrument'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "32244de2",
   "metadata": {},
   "outputs": [],
   "source": [
    "from qcodes.instrument import Instrument"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "7ccb1db4",
   "metadata": {},
   "outputs": [],
   "source": [
    "class BaseVoltageSource(Instrument):\n",
    "    \"\"\"\n",
    "    All abstract parameters *must* be implemented\n",
    "    before this class can be initialized. This\n",
    "    allows us to enforce an interface.\n",
    "    \"\"\"\n",
    "\n",
    "    def __init__(self, name: str):\n",
    "        super().__init__(name)\n",
    "\n",
    "        self.add_parameter(\"voltage\", unit=\"V\", abstract=True)\n",
    "\n",
    "        self.add_parameter(\"current\", unit=\"A\", get_cmd=None, set_cmd=None)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a3d0714c",
   "metadata": {},
   "source": [
    "### We cannot instantiate a Instrument with abstract parameters."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "74035d25",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Error: Class 'BaseVoltageSource' has un-implemented Abstract Parameter(s): 'voltage'\n"
     ]
    }
   ],
   "source": [
    "try:\n",
    "    bv = BaseVoltageSource(\"name\")\n",
    "except NotImplementedError as error:\n",
    "    print(f\"Error: {error}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c322bd66",
   "metadata": {},
   "source": [
    "Instruments which fail to initialize are not registered:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "0576d8e6-f335-4344-9e2f-f74dfa63a86d",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[]"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "BaseVoltageSource.instances()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "067f0cd8",
   "metadata": {},
   "source": [
    "### Units of parameters defined in sub classes *must* match units defined in the base class "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "90720c97",
   "metadata": {},
   "outputs": [],
   "source": [
    "class WrongSource2(BaseVoltageSource):\n",
    "    \"\"\"\n",
    "    We implement the voltage paramter with the wrong unit\n",
    "    \"\"\"\n",
    "\n",
    "    def __init__(self, name: str, *args, **kwargs):\n",
    "        super().__init__(name, *args, **kwargs)\n",
    "\n",
    "        self.add_parameter(\"voltage\", unit=\"mV\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "890aec75",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Error: The unit of the parameter 'voltage' is 'mV'. This is inconsistent with the unit defined in the base class\n"
     ]
    }
   ],
   "source": [
    "try:\n",
    "    WrongSource2(\"name4\")\n",
    "except ValueError as error:\n",
    "    print(f\"Error: {error}\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4e23bed0-2d60-4e26-9e52-5fc9c61256f2",
   "metadata": {},
   "source": [
    "Instruments which fail to initialize due to the wrong unit are also not registered:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "8bd10672-e6fa-4efb-a5f2-f5459ff26c6f",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[]"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "BaseVoltageSource.instances()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a43888a9-65f2-410b-ba20-46920c63408a",
   "metadata": {},
   "source": [
    "# Working subclass"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "1a954275-aed8-4e4d-a961-d6cf28070308",
   "metadata": {},
   "outputs": [],
   "source": [
    "class VoltageSource(BaseVoltageSource):\n",
    "    \"\"\"\n",
    "    We implement the voltage paramter with the correct unit.\n",
    "    Here we just implement it as a manual parameter but in a\n",
    "    real instrument we would probably not do that.\n",
    "    \"\"\"\n",
    "\n",
    "    def __init__(self, name: str, *args, **kwargs):\n",
    "        super().__init__(name, *args, **kwargs)\n",
    "\n",
    "        self.add_parameter(\"voltage\", unit=\"V\", set_cmd=None, get_cmd=None)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "ae7ed4a7-4d58-471d-8775-5581a4874757",
   "metadata": {},
   "outputs": [],
   "source": [
    "vs = VoltageSource(\"name\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "cdb66d15-066c-427a-b6f0-51d159f0b2ea",
   "metadata": {},
   "outputs": [],
   "source": [
    "vs.voltage(1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "fad3fda4-cb6b-46ec-b17c-490bacb99cdc",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "vs.voltage()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5175c314-2ea7-4139-bb41-12b88f2fdcff",
   "metadata": {},
   "source": [
    "This instrument is registered as expected."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "f40bfff7-8329-41bd-8632-5f22c69d8eeb",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[<VoltageSource: name>]"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "VoltageSource.instances()"
   ]
  }
 ],
 "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.10.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}