Merge pull request #4412 from jenshnielsen/add_parameter_return

Return created parameter from add_parameter

docs/changes/newsfragments/4412.improved

@@ -0,0 +1,14 @@
+`InstrumentBase.add_parameter` now returns the created parameter.
+This allows explicitly assigning the parameter as an attribute on
+the instrument class. This in turn enables type checkers and
+documentation tools to detect the existence and type of the
+parameter statically.
+
+QCoDeS ships with a tool to automatically refactor instruments in this way. To use
+this tool qcodes should be installed with the refactor option e.g. ``pip install qcodes[refactor]``
+
+See `Creating-Instrument-Drivers <../examples/writing_drivers/Creating-Instrument-Drivers.ipynb>`__
+for more details.
+
+It is the plan to transform all drivers shipping with QCoDeS in this way
+as soon as possible.

docs/examples/writing_drivers/A-ParameterWithSetpoints-Example-with-Dual-Setpoints.ipynb

@@ -63,7 +63,6 @@
    "outputs": [],
    "source": [
     "class TimeTrace(ParameterWithSetpoints):\n",
-    "\n",
     "    def get_raw(self):\n",
     "        npts = self.root_instrument.npts()\n",
     "        dt = self.root_instrument.dt()\n",
@@ -72,75 +71,81 @@
     "\n",
     "\n",
     "class Periodogram(ParameterWithSetpoints):\n",
-    "\n",
     "    def get_raw(self):\n",
-    "\n",
     "        tt = self.root_instrument.trace()\n",
     "\n",
-    "        return np.abs(np.fft.fft(tt))**2\n",
+    "        return np.abs(np.fft.fft(tt)) ** 2\n",
     "\n",
     "\n",
     "class TimeAxis(Parameter):\n",
-    "\n",
     "    def get_raw(self):\n",
     "        npts = self.root_instrument.npts()\n",
     "        dt = self.root_instrument.dt()\n",
-    "        return np.linspace(0, dt*npts, npts, endpoint=False)\n",
+    "        return np.linspace(0, dt * npts, npts, endpoint=False)\n",
     "\n",
     "\n",
     "class FrequencyAxis(Parameter):\n",
-    "\n",
     "    def get_raw(self):\n",
     "        npts = self.root_instrument.npts()\n",
     "        dt = self.root_instrument.dt()\n",
     "\n",
-    "        return np.linspace(0, 1/dt, npts)\n",
+    "        return np.linspace(0, 1 / dt, npts)\n",
     "\n",
     "\n",
     "class OzzyLowScope(Instrument):\n",
-    "\n",
     "    def __init__(self, name: str, **kwargs: \"Unpack[InstrumentBaseKWArgs]\"):\n",
-    "\n",
     "        super().__init__(name, **kwargs)\n",
     "\n",
-    "        self.add_parameter(name='npts',\n",
-    "                           initial_value=500,\n",
-    "                           label='Number of points',\n",
-    "                           get_cmd=None,\n",
-    "                           set_cmd=None)\n",
-    "\n",
-    "        self.add_parameter(name='dt',\n",
-    "                           initial_value=1e-3,\n",
-    "                           label='Time resolution',\n",
-    "                           unit='s',\n",
-    "                           get_cmd=None,\n",
-    "                           set_cmd=None)\n",
-    "\n",
-    "        self.add_parameter(name='time_axis',\n",
-    "                           label='Time',\n",
-    "                           unit='s',\n",
-    "                           vals=vals.Arrays(shape=(self.npts,)),\n",
-    "                           parameter_class=TimeAxis)\n",
-    "\n",
-    "        self.add_parameter(name='freq_axis',\n",
-    "                           label='Frequency',\n",
-    "                           unit='Hz',\n",
-    "                           vals=vals.Arrays(shape=(self.npts,)),\n",
-    "                           parameter_class=FrequencyAxis)\n",
-    "\n",
-    "        self.add_parameter(name='trace',\n",
-    "                           label='Signal',\n",
-    "                           unit='V',\n",
-    "                           vals=vals.Arrays(shape=(self.npts,)),\n",
-    "                           setpoints=(self.time_axis,),\n",
-    "                           parameter_class=TimeTrace)\n",
-    "\n",
-    "        self.add_parameter(name='periodogram',\n",
-    "                           label='Periodogram',\n",
-    "                           unit='V^2/Hz',\n",
-    "                           vals=vals.Arrays(shape=(self.npts,)),\n",
-    "                           setpoints=(self.freq_axis,),\n",
-    "                           parameter_class=Periodogram)"
+    "        self.npts = self.add_parameter(\n",
+    "            name=\"npts\",\n",
+    "            initial_value=500,\n",
+    "            label=\"Number of points\",\n",
+    "            get_cmd=None,\n",
+    "            set_cmd=None,\n",
+    "        )\n",
+    "\n",
+    "        self.dt = self.add_parameter(\n",
+    "            name=\"dt\",\n",
+    "            initial_value=1e-3,\n",
+    "            label=\"Time resolution\",\n",
+    "            unit=\"s\",\n",
+    "            get_cmd=None,\n",
+    "            set_cmd=None,\n",
+    "        )\n",
+    "\n",
+    "        self.time_axis = self.add_parameter(\n",
+    "            name=\"time_axis\",\n",
+    "            label=\"Time\",\n",
+    "            unit=\"s\",\n",
+    "            vals=vals.Arrays(shape=(self.npts,)),\n",
+    "            parameter_class=TimeAxis,\n",
+    "        )\n",
+    "\n",
+    "        self.freq_axis = self.add_parameter(\n",
+    "            name=\"freq_axis\",\n",
+    "            label=\"Frequency\",\n",
+    "            unit=\"Hz\",\n",
+    "            vals=vals.Arrays(shape=(self.npts,)),\n",
+    "            parameter_class=FrequencyAxis,\n",
+    "        )\n",
+    "\n",
+    "        self.trace = self.add_parameter(\n",
+    "            name=\"trace\",\n",
+    "            label=\"Signal\",\n",
+    "            unit=\"V\",\n",
+    "            vals=vals.Arrays(shape=(self.npts,)),\n",
+    "            setpoints=(self.time_axis,),\n",
+    "            parameter_class=TimeTrace,\n",
+    "        )\n",
+    "\n",
+    "        self.periodogram = self.add_parameter(\n",
+    "            name=\"periodogram\",\n",
+    "            label=\"Periodogram\",\n",
+    "            unit=\"V^2/Hz\",\n",
+    "            vals=vals.Arrays(shape=(self.npts,)),\n",
+    "            setpoints=(self.freq_axis,),\n",
+    "            parameter_class=Periodogram,\n",
+    "        )"
    ]
   },
   {
@@ -482,7 +487,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.1"
+   "version": "3.12.3"
   },
   "toc": {
    "base_numbering": 1,