Source code for qcodes.parameters.array_parameter

from __future__ import annotations

import os
from import Mapping, Sequence
from typing import TYPE_CHECKING, Any

import numpy as np

    from import DataArray

    has_loop = True
except ImportError:
    has_loop = False

from .parameter_base import ParameterBase
from .sequence_helpers import is_sequence_of

    from qcodes.instrument import InstrumentBase

[docs]class ArrayParameter(ParameterBase): """ A gettable parameter that returns an array of values. Not necessarily part of an instrument. For new driver we strongly recommend using :class:`.ParameterWithSetpoints` which is both more flexible and significantly easier to use Subclasses should define a ``.get_raw`` method, which returns an array. This method is automatically wrapped to provide a ``.get`` method. :class:`.ArrayParameter` can be used in both a :class:`qcodes.dataset.Measurement` as well as in the legacy :class:`qcodes.loops.Loop` and :class:`qcodes.measure.Measure` measurements When used in a ``Loop`` or ``Measure`` operation, this will be entered into a single ``DataArray``, with extra dimensions added by the ``Loop``. The constructor args describe the array we expect from each ``.get`` call and how it should be handled. For now you must specify upfront the array shape, and this cannot change from one call to the next. Later we intend to require only that you specify the dimension, and the size of each dimension can vary from call to call. Args: name: The local name of the parameter. Should be a valid identifier, i.e. no spaces or special characters. If this parameter is part of an ``Instrument`` or ``Station``, this is how it will be referenced from that parent, i.e. ```` or ``instrument.parameters[name]`` shape: The shape (as used in numpy arrays) of the array to expect. Scalars should be denoted by (), 1D arrays as (n,), 2D arrays as (n, m), etc. instrument: The instrument this parameter belongs to, if any. label: Normally used as the axis label when this parameter is graphed, along with ``unit``. unit: The unit of measure. Use ``''`` for unitless. setpoints: ``array`` can be a DataArray, numpy.ndarray, or sequence. The setpoints for each dimension of the returned array. An N-dimension item should have N setpoint arrays, where the first is 1D, the second 2D, etc. If omitted for any or all items, defaults to integers from zero in each respective direction. **Note**: if the setpoints will be different each measurement, leave this out and return the setpoints (with extra names) in ``.get``. setpoint_names: One identifier (like ``name``) per setpoint array. Ignored if a setpoint is a DataArray, which already has a name. setpoint_labels: One label (like ``labels``) per setpoint array. Ignored if a setpoint is a DataArray, which already has a label. setpoint_units: One unit (like ``v``) per setpoint array. Ignored if a setpoint is a DataArray, which already has a unit. docstring: documentation string for the ``__doc__`` field of the object. The ``__doc__`` field of the instance is used by some help systems, but not all. snapshot_get: Prevent any update to the parameter, for example if it takes too long to update. Default ``True``. snapshot_value: Should the value of the parameter be stored in the snapshot. Unlike Parameter this defaults to False as ArrayParameters are potentially huge. snapshot_exclude: ``True`` prevents parameter to be included in the snapshot. Useful if there are many of the same parameter which are clogging up the snapshot. Default ``False``. metadata: Extra information to include with the JSON snapshot of the parameter. """ def __init__( self, name: str, shape: Sequence[int], instrument: InstrumentBase | None = None, label: str | None = None, unit: str | None = None, setpoints: Sequence[Any] | None = None, setpoint_names: Sequence[str] | None = None, setpoint_labels: Sequence[str] | None = None, setpoint_units: Sequence[str] | None = None, docstring: str | None = None, snapshot_get: bool = True, snapshot_value: bool = False, snapshot_exclude: bool = False, metadata: Mapping[Any, Any] | None = None, **kwargs: Any, ) -> None: super().__init__( name, instrument, snapshot_get, metadata, snapshot_value=snapshot_value, snapshot_exclude=snapshot_exclude, **kwargs, ) if self.settable: # TODO (alexcjohnson): can we support, ala Combine? raise AttributeError("ArrayParameters do not support set " "at this time.") self._meta_attrs.extend( ["setpoint_names", "setpoint_labels", "setpoint_units", "label", "unit"] ) self.label = name if label is None else label self.unit = unit if unit is not None else "" nt: type[None] = type(None) if not is_sequence_of(shape, int): raise ValueError("shapes must be a tuple of ints, not " + repr(shape)) self.shape = shape # require one setpoint per dimension of shape sp_shape = (len(shape),) if has_loop: sp_types: tuple[type, ...] = ( nt, DataArray,,, np.ndarray, ) else: sp_types = ( nt,,, np.ndarray, ) if setpoints is not None and not is_sequence_of( setpoints, sp_types, shape=sp_shape ): raise ValueError("setpoints must be a tuple of arrays") if setpoint_names is not None and not is_sequence_of( setpoint_names, (nt, str), shape=sp_shape ): raise ValueError("setpoint_names must be a tuple of strings") if setpoint_labels is not None and not is_sequence_of( setpoint_labels, (nt, str), shape=sp_shape ): raise ValueError("setpoint_labels must be a tuple of strings") if setpoint_units is not None and not is_sequence_of( setpoint_units, (nt, str), shape=sp_shape ): raise ValueError("setpoint_units must be a tuple of strings") self.setpoints = setpoints self.setpoint_names = setpoint_names self.setpoint_labels = setpoint_labels self.setpoint_units = setpoint_units self.__doc__ = os.linesep.join( ( "Parameter class:", "", "* `name` %s" %, "* `label` %s" % self.label, "* `unit` %s" % self.unit, "* `shape` %s" % repr(self.shape), ) ) if docstring is not None: self.__doc__ = os.linesep.join((docstring, "", self.__doc__)) if not self.gettable and not self.settable: raise AttributeError("ArrayParameter must have a get, set or both") @property def setpoint_full_names(self) -> Sequence[str] | None: """ Full names of setpoints including instrument names if available """ if self.setpoint_names is None: return None # omit the last part of name_parts which is the parameter name # and not part of the setpoint names inst_name = "_".join(self.name_parts[:-1]) if inst_name != "": spnames = [] for spname in self.setpoint_names: if spname is not None: spnames.append(inst_name + "_" + spname) else: spnames.append(None) return tuple(spnames) else: return self.setpoint_names