is Parameter too complex ?

[giulioungaretti]

Maybe I am not clever enough 😭, but the class Parameter is maybe too complex?

The fact that writing docs (I mean valid python documentation) for the constructor is nearly impossible, made me think that we may want to make Parameter to behave differently.

This is a part of the api that the users will want to use if they have anything complex.

Example:

How can one tell what is required for a parameter that returns an array (the hardware parameter that was discussed in Delft) ?

• looking at the docstring does not give much help IMHO (see below)
• looking at the code kind of hints at what one needs
• trying until it works seems like the only solution if one does not really know the internals

The question is then, do we want to:

1. keep complex base classe and rely on long and detailed manually written documentation
   • 👎
     • documentation is boring to write and mostly to read
     • manuals/examples gets stale very fast
     • testing and refactoring is generally more painful
   • 👍
     • no need to write more code
     • no breaking changes
2. Reduce complexity, possibly making things slight less modular
   • 👎
     • breaking changes
     • requires major re write
   • 👍
     • things are easier to understand and maintain
     • sane auto documentation is possible

    A settable Parameter has a .set method, and supports only a single value
    at a time (see below)

    A gettable Parameter has a .get method, which may return:

    1.  a single value
    2.  a sequence of values with different names (for example,
        raw and interpreted, I and Q, several fit parameters...)
    3.  an array of values all with the same name, but at different
        setpoints (for example, a time trace or fourier transform that
        was acquired in the hardware and all sent to the computer at once)
    4.  2 & 3 together: a sequence of arrays. All arrays should be the same
        shape.
    5.  a sequence of differently shaped items

    Because .set only supports a single value, if a Parameter is both
    gettable AND settable, .get should return a single value too (case 1)
    Args:
        name: (1&3) the local name of this parameter, should be a valid
            identifier, ie no spaces or special characters

        names: (2,4,5) a tuple of names

        label: (1&3) string to use as an axis label for this parameter
            defaults to name

        labels: (2,4,5) a tuple of labels

        units: (1&3) string that indicates units of parameter for use in axis
            label and snapshot

        shape: (3&4) a tuple of integers for the shape of array returned by
            .get().

        shapes: (5) a tuple of tuples, each one as in `shape`.
            Single values should be denoted by None or ()

        setpoints: (3,4,5) the setpoints for the returned array of values.
            3&4 - a tuple of arrays. The first array is be 1D, the second 2D,
                etc.
            5 - a tuple of tuples of arrays
            Defaults to integers from zero in each respective direction
            Each may be either a DataArray, a numpy array, or a sequence
            (sequences will be converted to numpy arrays)
            NOTE: if the setpoints will be different each measurement, leave
            this out and return the setpoints (with extra names) in the get.

[MerlinSmiles]

I dont really get what you are asking ;) The parameter as is is not fully working, so it is strange to reduce complexity while there is still missing stuff. i.e. setting multiple values, it works kindof, but not with i.e. validators, but the same is true for get...

Often when I think about multi valued parameters, I think every value itself should be a parameter, that would reduce some of that 'name' 'names' 'label' 'labels' 'units' (only one version for both!?) stuff. And then have super simple combined parameters. param = [par1, par2, par3]

[giulioungaretti]

@MerlinSmiles yah, it's not clear what I am asking. I guess it boils down to: a) is parameter what people want? And I am too stupid to document what it does properly. (I seem to lose track quite quickly of the possible combinations of options that that constructor takes)

b) what parameter can do is possibly too much of too many things ?

[AdriaanRol]

@giulioungaretti In my mind a parameter is something very simple. It is something that is getable and/or setable and should support logging and use in data acquiring loops and measurements as it supplies the units and labels as well as standardisation. Additionally it should provide protection against stupid mistakes such as setting illegal (validator, hard coded) or dangerous values (soft-validator, #230 )

Now I do understand there is some confusion as to the different types of uses for a parameter. Let me go over them (I am sorting them by the shape of data they get/set) as that may be a cause of confusion.

Different "shapes" of parameters

• (single value) a simple parameter, sets a single value and reads back a single value.
  • (set example) any single value on an instrument
  • (get example) any single value on an instrument
• (tuple of n-single values) a multi-valued parameter, sets/gets a tuple of multiple values, each with it's own units and labels.
  • (set example) magnet position as a tuple? (not sure about this one but no reason to not support it)
  • (get example) data acquisition returns a tuple of complex values or magn and angle or a value and its uncertainty.
• (1D-array of values) a "hard" or array like parameter, used for devices that return arrays of values instead of single values. Absolutely essential as a lot of hardware returns data like this. note that 1D-array contains only 1 label and 1 units
  • (set example) specify integration weights as an array
  • (get example) array of measurement outcomes from a data acquisition card
• (nD-array of values) hard or array like parameter that returns an array of multiple values. contains a list of n-units and n-labels
  • (set example) can't think of one right now
  • (get example) same as above but now an array of IQ values (real and imag components).

"Special use cases" (which I do not consider special but other people do ;) )

• manual parameter, only difference is that the value is stored in the software, incredibly useful when running things that don't talk to hardware e.g. storing parameters used for sequence generation
• composite or nested parameters: parameters that contain a full measurement loop within them. Because the only criterium for a parameter is that it contains a get/or set it can be used to reduce complex experiments to a simple parameter that can be used in more complex experiments. This can be done by including a measurement loop in the parameter. (note currently impossible because of the dataserver blocking multiple writing processes). Example here is the T1 parameter, T1.get() performs a measurement (involving loading a sequence on a waveform generator, getting back an array of measured qubit states for different times, storing it in a dataset and handing that dataset to an analysis that performs a fit and returns a tuple of fitted values).

I hope this explains why we like the parameter, and why I think it is a good standard/paradigm to capture the essence of experiments. It can be that the implementation is a bit hard due to the multiprocessing constraints but I feel this captures everything the user should know (if this is in any way useful for the docs feel free to copy it).

[damazter]

The constructor of the base parameter class is not as simple as it could be. Would it be reasonable to split the Parameter class into several subclasses for each of the different usage types? (I know that this will break compatibility with a lot of drivers that are already written, but I do see some appeal to make the base of qcodes as simple as possible)

[AdriaanRol]

@damazter How about an abstract base class as some kind of template? It is not strictly speaking a python construct but in the end the only thing we are specifying is some standard that one needs to comply to in order to work with datasets and loops.

[damazter]

@AdriaanRol Yes. This would also create flexibility, because if you need something different, one can write a new class and inherit from the base class (something which is not possible atm)

[AdriaanRol]

@giulioungaretti

Hi Giulio, @damazter and me just went over the paramater and we would like to propose the following.

• Remove most of the docstring from Parameter, removing the different use cases
• Remove the different use-cases from the Parameter's code. This is the part following if names is not None: and if shape is not None or shapes is not None: .
• This turns Parameter into the base parameter class, the functionality for names and shape can then be implemented in whatever subclass one cares to implement.

This should be an easy solution, Parameter is as simple as the concept parameter, with minimal backwards breaking problems.

Damaz & Adriaan

[giulioungaretti]

@AdriaanRol @damazter unfortunately that will also break more things that we want. So for first release, parameter stays like this. And "handcrafted" documentation will help the lost hacker.