Add type variables to parameters in several drivers

docs/changes/newsfragments/8694.breaking

@@ -0,0 +1,7 @@
+The ``auto_zero_once`` parameter of ``Keithley7510Sense`` and the ``trigger_in_ext_clear``
+parameter of ``Keithley7510`` have been replaced by methods of the same name. Both were
+command-only parameters, so calling them without an argument, e.g.
+``dmm.sense.auto_zero_once()``, only returned the cached value and did not send anything to the
+instrument. Calling them like this now sends the command. Code that passed a value to them, e.g.
+``dmm.trigger_in_ext_clear(None)``, must drop the argument, and they are no longer part of the
+instrument's parameters or snapshot.

docs/changes/newsfragments/8694.breaking.1

@@ -0,0 +1,7 @@
+The ``trigger_count`` parameter of ``Keithley6500``, which sets the number of times a scan is
+repeated (``ROUT:SCAN:COUN:SCAN``), now accepts the full range documented in the DMM6500
+Reference Manual: 0 to 100,000,000, where 0 repeats the scan until it is aborted. It previously
+only accepted 1 to 9999 or the strings ``"inf"``, ``"default"``, ``"minimum"`` and ``"maximum"``,
+which were copied from the Keithley 2000 and are not documented for this command. These strings
+are now rejected; use 0 instead of ``"inf"``. Whole-number floats are accepted and sent as
+integers, and the parameter is annotated as ``Parameter[int, Self]``.

docs/changes/newsfragments/8694.improved

@@ -0,0 +1,5 @@
+The "Creating Instrument Drivers" example notebook now explains how to annotate a parameter with
+the type of its value, e.g. ``Parameter[float, Self]``, and all of its example drivers are
+annotated this way. This also fixed bugs in the example code: the Ithaco example passed ``units``
+instead of ``unit``, the Keithley 2600 example lacked its ``model`` attribute and
+``_display_settext`` method, and the Alazar example used outdated ``TraceParameter`` arguments.

docs/changes/newsfragments/8694.improved_driver

@@ -0,0 +1,4 @@
+The parameters of the Basel SP983, SP983a and SP983c, Ithaco 1211, Keithley 2450, DMM7510, S46
+and 2600 drivers that were not yet typed are now annotated with the type of their value, e.g.
+``Parameter[float, Self]``, so static type checkers can infer the type returned by ``get`` and
+accepted by ``set``.

src/qcodes/instrument/sims/Basel_SP983a.yaml

@@ -0,0 +1,35 @@
+spec: "1.0"
+devices:
+  device 1:
+    eom:
+      GPIB INSTR:
+        q: "\r\n"
+        r: "\r\n"
+    error: ERROR
+    dialogues:
+      - q: "GET O"
+        r: "Overload: OFF"
+
+    # replies follow the format that the driver parses
+    properties:
+      gain:
+        default: "1E8"
+        getter:
+          q: "GET G"
+          r: "Gain: {}"
+        setter:
+          q: "SET G {}"
+          r: "OK"
+
+      filter:
+        default: "1k"
+        getter:
+          q: "GET F"
+          r: "Filter: {}Hz"
+        setter:
+          q: "SET F {}"
+          r: "OK"
+
+resources:
+  GPIB::1::INSTR:
+    device: device 1

src/qcodes/instrument/sims/Keithley_6500.yaml

@@ -33,6 +33,18 @@ devices:
           min: 4
           max: 7
 
+      scan_count:
+        default: 1
+        getter:
+          q: "ROUT:SCAN:COUN:SCAN?"
+          r: "{}"
+        setter:
+          q: "ROUT:SCAN:COUN:SCAN {}"
+        specs:
+          type: int
+          min: 0
+          max: 100000000
+
 resources:
   GPIB::1::INSTR:
     device: device 1

src/qcodes/instrument/sims/keithley_7510.yaml

@@ -80,6 +80,15 @@ devices:
         specs:
           type: int
 
+      # command-only, no reply
+      auto_zero_once:
+        setter:
+          q: ":SENSe:AZERo:ONCE"
+
+      trigger_in_ext_clear:
+        setter:
+          q: ":TRIGger:EXTernal:IN:CLEar"
+
 resources:
   "GPIB::1::INSTR":
     device: device 1

src/qcodes/instrument_drivers/Keithley/Keithley_2450.py

@@ -113,7 +113,7 @@ def __init__(
         )
         """To get the number of readings in the reading buffer."""
 
-        self.elements: Parameter = self.add_parameter(
+        self.elements: Parameter[list[str], Self] = self.add_parameter(
             "elements",
             get_cmd=None,
             get_parser=self.from_scpi_to_name,
@@ -455,7 +455,7 @@ def __init__(self, parent: "Keithley2450", name: str, proper_function: str) -> N
             snapshot_value=False,
         )
 
-        self.sweep_axis: Parameter = self.add_parameter(
+        self.sweep_axis: Parameter[npt.NDArray, Self] = self.add_parameter(
             "sweep_axis",
             label=self._proper_function,
             get_cmd=self.get_sweep_axis,
@@ -663,7 +663,7 @@ def __init__(
         )
         """returns the power line frequency setting that is used for NPLC calculations"""
 
-        self.buffer_name: Parameter = self.add_parameter(
+        self.buffer_name: Parameter[str, Self] = self.add_parameter(
             "buffer_name",
             get_cmd=None,
             set_cmd=None,

src/qcodes/instrument_drivers/Keithley/Keithley_6500.py

@@ -2,7 +2,7 @@
 from typing import TYPE_CHECKING, Self
 
 from qcodes.instrument import VisaInstrument, VisaInstrumentKWArgs
-from qcodes.validators import Bool, Enum, Ints, MultiType, Numbers
+from qcodes.validators import Bool, Enum, Ints, Numbers, PermissiveInts
 
 if TYPE_CHECKING:
     from collections.abc import Callable
@@ -184,17 +184,18 @@ def __init__(
         )
         """Control the brightness of the display backligt. Off turns the display off andBlackout also turns off indicators and key lights on the device."""
 
-        self.trigger_count: Parameter = self.add_parameter(
+        self.trigger_count: Parameter[int, Self] = self.add_parameter(
             "trigger_count",
             get_parser=int,
             get_cmd="ROUT:SCAN:COUN:SCAN?",
             set_cmd="ROUT:SCAN:COUN:SCAN {}",
-            vals=MultiType(
-                Ints(min_value=1, max_value=9999),
-                Enum("inf", "default", "minimum", "maximum"),
-            ),
+            # accept whole-number floats such as 10.0 but send them as int
+            vals=PermissiveInts(0, 100_000_000),
+            set_parser=round,
+            docstring="Number of times the scan is repeated. "
+            "Set to 0 to repeat the scan until it is aborted.",
         )
-        """Parameter trigger_count"""
+        """Number of times the scan is repeated. Set to 0 to repeat the scan until it is aborted."""
 
         for trigger in range(1, 5):
             self.add_parameter(

src/qcodes/instrument_drivers/Keithley/Keithley_7510.py

@@ -163,7 +163,7 @@ def __init__(
         )
         """Get the starting index of readings in the reading buffer."""
 
-        self.data_start: Parameter = self.add_parameter(
+        self.data_start: Parameter[int, Self] = self.add_parameter(
             "data_start",
             initial_value=1,
             get_cmd=None,
@@ -172,7 +172,7 @@ def __init__(
         )
         """First index of the data to be returned."""
 
-        self.data_end: Parameter = self.add_parameter(
+        self.data_end: Parameter[int, Self] = self.add_parameter(
             "data_end",
             initial_value=1,
             get_cmd=None,
@@ -181,7 +181,7 @@ def __init__(
         )
         """Last index of the data to be returned."""
 
-        self.elements: Parameter = self.add_parameter(
+        self.elements: Parameter[list[str], Self] = self.add_parameter(
             "elements",
             get_cmd=None,
             get_parser=self._from_scpi_to_name,
@@ -223,7 +223,7 @@ def __init__(
         )
         """Parameter setpoints"""
 
-        self.t_start: Parameter = self.add_parameter(
+        self.t_start: Parameter[float, Self] = self.add_parameter(
             "t_start",
             label="start time",
             unit="s",
@@ -234,7 +234,7 @@ def __init__(
         )
         """Parameter t_start"""
 
-        self.t_stop: Parameter = self.add_parameter(
+        self.t_stop: Parameter[float, Self] = self.add_parameter(
             "t_stop",
             label="stop time",
             unit="s",
@@ -566,14 +566,6 @@ def __init__(
         )
         """Enable or disable automatic updates to the internal reference measurements (autozero) of the instrument."""
 
-        self.auto_zero_once: Parameter = self.add_parameter(
-            "auto_zero_once",
-            set_cmd=":SENSe:AZERo:ONCE",
-            docstring="Cause the instrument to refresh the reference and "
-            "zero measurements once",
-        )
-        """Cause the instrument to refresh the reference and zero measurements once"""
-
         self.average: Parameter[bool, Self] = self.add_parameter(
             "average",
             get_cmd=f":SENSe:{self._proper_function}:AVERage?",
@@ -628,6 +620,13 @@ def clear_trace(self, buffer_name: str = "defbuffer1") -> None:
         """
         self.write(f":TRACe:CLEar '{buffer_name}'")
 
+    def auto_zero_once(self) -> None:
+        """
+        Cause the instrument to refresh the reference and zero measurements
+        once.
+        """
+        self.write(":SENSe:AZERo:ONCE")
+
 
 class Keithley7510DigitizeSense(InstrumentChannel["Keithley7510"]):
     """
@@ -772,7 +771,7 @@ def __init__(
         )
         """Make readings using the active digitize function."""
 
-        self.buffer_name: Parameter = self.add_parameter(
+        self.buffer_name: Parameter[str, Self] = self.add_parameter(
             "buffer_name",
             get_cmd=None,
             set_cmd=None,
@@ -787,13 +786,6 @@ def __init__(
         )
         """Return the settings for all trigger model blocks."""
 
-        self.trigger_in_ext_clear: Parameter = self.add_parameter(
-            "trigger_in_ext_clear",
-            set_cmd=":TRIGger:EXTernal:IN:CLEar",
-            docstring="Clear the trigger event on the external in line.",
-        )
-        """Clear the trigger event on the external in line."""
-
         self.trigger_in_ext_edge: Parameter[str, Self] = self.add_parameter(
             "trigger_in_ext_edge",
             get_cmd=":TRIGger:EXTernal:IN:EDGE?",
@@ -896,6 +888,13 @@ def wait(self) -> None:
         """
         self.write("*WAI")
 
+    def trigger_in_ext_clear(self) -> None:
+        """
+        Clear the trigger event on the external in line. This also discards
+        the event history and clears the overrun status.
+        """
+        self.write(":TRIGger:EXTernal:IN:CLEar")
+
     def clear_status(self) -> None:
         """
         This command clears the event registers of the Questionable Event and

src/qcodes/instrument_drivers/Keithley/Keithley_s46.py

@@ -4,7 +4,7 @@
 
 import re
 from itertools import product
-from typing import TYPE_CHECKING, Any, ClassVar
+from typing import TYPE_CHECKING, Any, ClassVar, Self
 
 from qcodes.instrument import (
     VisaInstrument,
@@ -151,7 +151,7 @@ def __init__(
     ):
         super().__init__(name, address, **kwargs)
         try:
-            self.closed_channels: Parameter = self.add_parameter(
+            self.closed_channels: Parameter[list[str], Self] = self.add_parameter(
                 "closed_channels",
                 get_cmd=":CLOS?",
                 get_parser=self._get_closed_channels_parser,

src/qcodes/instrument_drivers/Keithley/_Keithley_2600.py

@@ -959,7 +959,7 @@ def __init__(self, parent: Keithley2600, name: str, channel: str) -> None:
             ... )
         """
 
-        self.timetrace_npts: Parameter = self.add_parameter(
+        self.timetrace_npts: Parameter[int, Self] = self.add_parameter(
             "timetrace_npts",
             initial_value=500,
             label="Number of points",
@@ -968,7 +968,7 @@ def __init__(self, parent: Keithley2600, name: str, channel: str) -> None:
         )
         """Parameter timetrace_npts"""
 
-        self.timetrace_dt: Parameter = self.add_parameter(
+        self.timetrace_dt: Parameter[float, Self] = self.add_parameter(
             "timetrace_dt",
             initial_value=1e-3,
             label="Time resolution",

src/qcodes/instrument_drivers/basel/BaselSP983.py

@@ -1,4 +1,4 @@
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Self
 
 from qcodes.instrument import Instrument, InstrumentBaseKWArgs
 from qcodes.parameters import DelegateParameter, Parameter
@@ -44,7 +44,7 @@ def __init__(
     ):
         super().__init__(name, **kwargs)
 
-        self.gain: Parameter = self.add_parameter(
+        self.gain: Parameter[float, Self] = self.add_parameter(
             "gain",
             initial_value=1e8,
             label="Gain",
@@ -55,7 +55,7 @@ def __init__(
         )
         """Parameter gain"""
 
-        self.fcut: Parameter = self.add_parameter(
+        self.fcut: Parameter[float, Self] = self.add_parameter(
             "fcut",
             initial_value=1e3,
             label="Cutoff frequency",

src/qcodes/instrument_drivers/basel/BaselSP983a.py

@@ -40,7 +40,7 @@ def __init__(
 
         self.connect_message()
 
-        self.gain: Parameter = self.add_parameter(
+        self.gain: Parameter[float, Self] = self.add_parameter(
             "gain",
             label="Gain",
             unit="V/A",
@@ -49,7 +49,7 @@ def __init__(
             vals=vals.Enum(1e5, 1e6, 1e7, 1e8, 1e9),
         )
         """Parameter gain"""
-        self.fcut: Parameter = self.add_parameter(
+        self.fcut: Parameter[float, Self] = self.add_parameter(
             "fcut",
             unit="Hz",
             label="Filter Cut-Off Frequency",

src/qcodes/instrument_drivers/ithaco/Ithaco_1211.py

@@ -82,7 +82,7 @@ class Ithaco1211(Instrument):
     def __init__(self, name: str, **kwargs: "Unpack[InstrumentBaseKWArgs]"):
         super().__init__(name, **kwargs)
 
-        self.sens: Parameter = self.add_parameter(
+        self.sens: Parameter[float, Self] = self.add_parameter(
             "sens",
             initial_value=1e-8,
             label="Sensitivity",
@@ -103,7 +103,7 @@ def __init__(self, name: str, **kwargs: "Unpack[InstrumentBaseKWArgs]"):
         )
         """Parameter invert"""
 
-        self.sens_factor: Parameter = self.add_parameter(
+        self.sens_factor: Parameter[float, Self] = self.add_parameter(
             "sens_factor",
             initial_value=1,
             label="Sensitivity factor",
@@ -114,7 +114,7 @@ def __init__(self, name: str, **kwargs: "Unpack[InstrumentBaseKWArgs]"):
         )
         """Parameter sens_factor"""
 
-        self.suppression: Parameter = self.add_parameter(
+        self.suppression: Parameter[float, Self] = self.add_parameter(
             "suppression",
             initial_value=1e-7,
             label="Suppression",
@@ -125,7 +125,7 @@ def __init__(self, name: str, **kwargs: "Unpack[InstrumentBaseKWArgs]"):
         )
         """Parameter suppression"""
 
-        self.risetime: Parameter = self.add_parameter(
+        self.risetime: Parameter[float, Self] = self.add_parameter(
             "risetime",
             initial_value=0.3,
             label="Rise Time",