Add generic annotations to Keysight drivers

docs/changes/newsfragments/8695.breaking

@@ -0,0 +1,6 @@
+The ``open`` and ``short`` parameters of ``KeysightE4980ACorrection`` have been replaced by
+methods of the same name. Both were command-only parameters, so calling them without an
+argument, e.g. ``meter.correction.open()`` as in the example notebook, only returned the cached
+value and did not execute the OPEN or SHORT correction. Calling them like this now sends the
+command. Code that passed a value to them, e.g. ``meter.correction.open(None)``, must drop the
+argument, and they are no longer part of the instrument's parameters or snapshot.

docs/changes/newsfragments/8695.improved_driver

@@ -0,0 +1,15 @@
+The enum parameters of the ``KeysightB1517A`` and ``KeysightB1520A`` modules of the Keysight
+B1500, such as ``sweep_mode``, ``measurement_mode`` and ``impedance_model``, are now annotated
+with their enum type, e.g. ``Parameter[constants.SweepMode, Self]``, and
+``KeysightB1517A.time_axis`` as a numpy array. The parameters of the Keysight B220x and the
+``phase`` of the ``AgilentE8257D`` and ``AgilentE8267C`` (``float``, in degrees) are annotated
+as well. The ``post_sweep_voltage_val`` argument of ``KeysightB1517A.setup_staircase_sweep`` is
+now typed as ``constants.WM.Post``, the enum used by the B1517A sweep, instead of
+``constants.WMDCV.Post``, which belongs to the B1520A CV sweep. Both have the same values, so
+existing calls keep working.
+
+Parameters of the Keysight 344xxA DMMs and 33XXX waveform generators that can also be set to
+SCPI keywords such as ``"MIN"``, ``"MAX"``, ``"DEF"`` or ``"INF"``, e.g.
+``Keysight344xxASample.timer``, are annotated as ``Parameter[float | str, Self]`` (or
+``int | str`` for counts). Getting them always returns a number, but the cached value is the
+string that was set until the parameter is read again, as now explained in their docstrings.

docs/changes/newsfragments/8695.improved_driver.1

@@ -0,0 +1,2 @@
+Setting ``resolution`` of the Keysight 344xxA DMMs to ``"MIN"``, ``"MAX"`` or ``"DEF"`` raised a
+``ValueError`` instead of sending the setting to the instrument.

src/qcodes/instrument/sims/Agilent_E8257D.yaml

@@ -25,6 +25,16 @@ devices:
         setter:
           q: "OUTP {}"
 
+      phase:
+        # *RST value according to the E8257D/67D SCPI command reference;
+        # the query returns radians
+        default: "+0.00000000E+000"
+        getter:
+          q: "PHASE?"
+          r: "{}"
+        setter:
+          q: "PHASE {}"
+
 resources:
   GPIB::1::INSTR:
     device: device 1

src/qcodes/instrument/sims/Agilent_E8267C.yaml

@@ -36,6 +36,16 @@ devices:
         setter:
           q: "PULM:INT:PWID {}"
 
+      phase:
+        # *RST value according to the E8257D/67D SCPI command reference;
+        # the query returns radians
+        default: "+0.00000000E+000"
+        getter:
+          q: "PHAS?"
+          r: "{}"
+        setter:
+          q: "PHAS {}"
+
 resources:
   GPIB::1::INSTR:
     device: device 1

src/qcodes/instrument/sims/Keysight_34465A.yaml

@@ -127,7 +127,8 @@ devices:
           q: "SENSe:VOLTage:DC:RESolution?"
           r: "{}"
         setter:
-          q: "SENSe:VOLTage:DC:RESolution {}"
+          # the driver sets the resolution with the short form
+          q: "VOLT:DC:RES {}"
       current_ac_autorange:
         default: 0
         getter:

src/qcodes/instrument/sims/Keysight_E4980A.yaml

@@ -49,6 +49,15 @@ devices:
         setter:
           q: ":FUNCtion:IMPedance:RANGe:AUTO {}"
 
+      # command-only, no reply
+      correction_open:
+        setter:
+          q: ":CORRection:OPEN"
+
+      correction_short:
+        setter:
+          q: ":CORRection:SHORt"
+
 resources:
   GPIB::1::INSTR:
     device: device 1

src/qcodes/instrument_drivers/Keysight/KeysightAgilent_33XXX.py

@@ -180,16 +180,30 @@ def val_parser(parser: type, inputstring: str) -> float | int:
         )
         """Parameter pulse_width"""
 
-        self.edges: Parameter = self.add_parameter(
+        self.edges: Parameter[float | str, Self] = self.add_parameter(
             "edges",
             label=f"Channel {channum} edges width",
             set_cmd=f"SOURce{channum}:FUNCtion:PULSe:TRANsition {{}}",
             get_cmd=f"SOURce{channum}:FUNCtion:PULSe:TRANsition?",
             get_parser=float,
             unit="s",
             vals=vals.MultiType(vals.Numbers(), vals.Enum("MIN", "MAX")),
+            docstring=(
+                "Sets the transition times for the leading and trailing edges of "
+                "the pulse. Besides a number, this can be set to 'MIN' or 'MAX', "
+                "which the instrument converts to the corresponding number. "
+                "Getting the parameter always returns a number, but until it is "
+                "read again, the cached value is the string that was set. The "
+                "value is therefore annotated as ``float | str``."
+            ),
         )
-        """Sets the transition times for the leading and trailing edges of the pulse."""
+        """
+        Sets the transition times for the leading and trailing edges of the pulse.
+        Besides a number, this can be set to "MIN" or "MAX", which the instrument
+        converts to the corresponding number. Getting the parameter always returns
+        a number, but until it is read again, the cached value is the string that
+        was set. The value is therefore annotated as ``float | str``.
+        """
 
         # TRIGGER MENU
         self.trigger_source: Parameter[str, Self] = self.add_parameter(
@@ -214,15 +228,24 @@ def val_parser(parser: type, inputstring: str) -> float | int:
 
         # Older models do not have all the fancy trigger options
         if self._parent.model[2] in ["5", "6"]:
-            self.trigger_count: Parameter = self.add_parameter(
+            self.trigger_count: Parameter[float, Self] = self.add_parameter(
                 "trigger_count",
                 label=f"Channel {channum} trigger count",
                 set_cmd=f"TRIGger{channum}:COUNt {{}}",
                 get_cmd=f"TRIGger{channum}:COUNt?",
                 vals=vals.Ints(1, 1000000),
                 get_parser=partial(val_parser, int),
+                docstring=(
+                    "Number of triggers. Reads back as ``float('inf')`` if the "
+                    "instrument reports an infinite count (9.9e37), so the value "
+                    "is annotated as ``float``."
+                ),
             )
-            """Parameter trigger_count"""
+            """
+            Number of triggers. Reads back as ``float("inf")`` if the instrument
+            reports an infinite count (9.9e37), so the value is annotated as
+            ``float``.
+            """
 
             self.trigger_delay: Parameter[float, Self] = self.add_parameter(
                 "trigger_delay",
@@ -279,15 +302,29 @@ def val_parser(parser: type, inputstring: str) -> float | int:
         )
         """Parameter burst_mode"""
 
-        self.burst_ncycles: Parameter = self.add_parameter(
+        self.burst_ncycles: Parameter[float | str, Self] = self.add_parameter(
             "burst_ncycles",
             label=f"Channel {channum} burst no. of cycles",
             set_cmd=f"SOURce{channum}:BURSt:NCYCles {{}}",
             get_cmd=f"SOURce{channum}:BURSt:NCYCLes?",
             get_parser=partial(val_parser, int),
             vals=vals.MultiType(vals.Ints(1), vals.Enum("MIN", "MAX", "INF")),
+            docstring=(
+                "Number of cycles in a burst. Besides a number, this can be set "
+                "to 'MIN', 'MAX' or 'INF', which the instrument converts to the "
+                "corresponding number. Getting the parameter always returns a "
+                "number, ``float('inf')`` for an infinite count, but until it is "
+                "read again, the cached value is the string that was set. The "
+                "value is therefore annotated as ``float | str``."
+            ),
         )
-        """Parameter burst_ncycles"""
+        """
+        Number of cycles in a burst. Besides a number, this can be set to "MIN",
+        "MAX" or "INF", which the instrument converts to the corresponding number.
+        Getting the parameter always returns a number, ``float("inf")`` for an
+        infinite count, but until it is read again, the cached value is the string
+        that was set. The value is therefore annotated as ``float | str``.
+        """
 
         self.burst_phase: Parameter[float, Self] = self.add_parameter(
             "burst_phase",
@@ -325,16 +362,34 @@ def val_parser(parser: type, inputstring: str) -> float | int:
         )
         """The burst period is the time between the starts of consecutive bursts when trigger is immediate."""
 
-        self.output_load: Parameter = self.add_parameter(
+        self.output_load: Parameter[float | str, Self] = self.add_parameter(
             "output_load",
             label=f"Channel {channum} output load",
             set_cmd=f"OUTPut{channum}:LOAD {{}}",
             get_cmd=f"OUTPut{channum}:LOAD?",
             get_parser=partial(val_parser, float),
             unit="ohms",
             vals=vals.MultiType(vals.Numbers(1, 10000), vals.Enum("INF", "MIN", "MAX")),
+            docstring=(
+                "Sets expected output termination. Should equal the load "
+                "impedance attached to the output. Besides a number, this can be "
+                "set to 'INF' (high impedance), 'MIN' or 'MAX', which the "
+                "instrument converts to the corresponding number. Getting the "
+                "parameter always returns a number, ``float('inf')`` for high "
+                "impedance, but until it is read again, the cached value is the "
+                "string that was set. The value is therefore annotated as "
+                "``float | str``."
+            ),
         )
-        """Sets expected output termination. Should equal the load impedance attached to the output."""
+        """
+        Sets expected output termination. Should equal the load impedance attached
+        to the output. Besides a number, this can be set to "INF" (high
+        impedance), "MIN" or "MAX", which the instrument converts to the
+        corresponding number. Getting the parameter always returns a number,
+        ``float("inf")`` for high impedance, but until it is read again, the
+        cached value is the string that was set. The value is therefore annotated
+        as ``float | str``.
+        """
 
         self.auto_range: Parameter[str, Self] = self.add_parameter(
             "auto_range",
@@ -352,7 +407,7 @@ def val_parser(parser: type, inputstring: str) -> float | int:
             "6",
         ]:  # Older models do not support all arbitrary options
             max_srate = self._parent._max_srate[self.model]
-            self.srate: Parameter = self.add_parameter(
+            self.srate: Parameter[float | str, Self] = self.add_parameter(
                 "srate",
                 label=f"Channel {channum} sample rate",
                 set_cmd=f"SOURce{channum}:FUNCtion:ARBitrary:SRATe {{}}",
@@ -362,8 +417,22 @@ def val_parser(parser: type, inputstring: str) -> float | int:
                 vals=vals.MultiType(
                     vals.Numbers(1e-6, max_srate), vals.Enum("MIN", "MAX", "DEF")
                 ),
+                docstring=(
+                    "Sets the sample rate for the arbitrary waveform. Besides a "
+                    "number, this can be set to 'MIN', 'MAX' or 'DEF', which the "
+                    "instrument converts to the corresponding number. Getting the "
+                    "parameter always returns a number, but until it is read "
+                    "again, the cached value is the string that was set. The "
+                    "value is therefore annotated as ``float | str``."
+                ),
             )
-            """Sets the sample rate for the arbitrary waveform."""
+            """
+            Sets the sample rate for the arbitrary waveform. Besides a number, this
+            can be set to "MIN", "MAX" or "DEF", which the instrument converts to
+            the corresponding number. Getting the parameter always returns a
+            number, but until it is read again, the cached value is the string
+            that was set. The value is therefore annotated as ``float | str``.
+            """
 
             self.add_function(
                 "load_arb",

src/qcodes/instrument_drivers/Keysight/keysight_b220x.py

@@ -147,7 +147,7 @@ def __init__(
         'mbb' (make before break)
         """
 
-        self.bias_input_port: Parameter = self.add_parameter(
+        self.bias_input_port: Parameter[int, Self] = self.add_parameter(
             name="bias_input_port",
             get_cmd=f":BIAS:PORT? {self._card}",
             set_cmd=f":BIAS:PORT {self._card},{{}}",
@@ -175,7 +175,7 @@ def __init__(
         )
         """Param: True for ON, False for OFF"""
 
-        self.gnd_input_port: Parameter = self.add_parameter(
+        self.gnd_input_port: Parameter[int, Self] = self.add_parameter(
             name="gnd_input_port",
             get_cmd=f":AGND:PORT? {self._card}",
             set_cmd=f":AGND:PORT {self._card},{{}}",
@@ -201,7 +201,7 @@ def __init__(
         )
         """Parameter gnd_mode"""
 
-        self.unused_inputs: Parameter = self.add_parameter(
+        self.unused_inputs: Parameter[list[int], Self] = self.add_parameter(
             name="unused_inputs",
             get_cmd=f":AGND:UNUSED? {self._card}",
             set_cmd=f":AGND:UNUSED {self._card},'{{}}'",
@@ -213,7 +213,7 @@ def __init__(
         )
         """Parameter unused_inputs"""
 
-        self.couple_ports: Parameter = self.add_parameter(
+        self.couple_ports: Parameter[list[int], Self] = self.add_parameter(
             name="couple_ports",
             get_cmd=f":COUP:PORT? {self._card}",
             set_cmd=f":COUP:PORT {self._card},'{{}}'",

src/qcodes/instrument_drivers/Keysight/keysight_e4980a.py

@@ -153,13 +153,6 @@ def __init__(
     ) -> None:
         super().__init__(parent, name, **kwargs)
 
-        self.open: Parameter = self.add_parameter(
-            "open",
-            set_cmd=":CORRection:OPEN",
-            docstring="Executes OPEN correction based on all frequency points.",
-        )
-        """Executes OPEN correction based on all frequency points."""
-
         self.open_state: Parameter[bool, Self] = self.add_parameter(
             "open_state",
             get_cmd=":CORRection:OPEN:STATe?",
@@ -169,13 +162,6 @@ def __init__(
         )
         """Enables or disable OPEN correction"""
 
-        self.short: Parameter = self.add_parameter(
-            "short",
-            set_cmd=":CORRection:SHORt",
-            docstring="Executes SHORT correction based on all frequency points.",
-        )
-        """Executes SHORT correction based on all frequency points."""
-
         self.short_state: Parameter[bool, Self] = self.add_parameter(
             "short_state",
             get_cmd=":CORRection:SHORt:STATe?",
@@ -185,6 +171,18 @@ def __init__(
         )
         """Enables or disable SHORT correction."""
 
+    def open(self) -> None:
+        """
+        Executes OPEN correction based on all frequency points.
+        """
+        self.write(":CORRection:OPEN")
+
+    def short(self) -> None:
+        """
+        Executes SHORT correction based on all frequency points.
+        """
+        self.write(":CORRection:SHORt")
+
 
 class KeysightE4980A(VisaInstrument):
     """