The Measure class
=================

``qcodespp.Measure`` is used to measure a set of ``Parameter`` s at a single point in time. The typical use case is where the ``Parameter`` (s)'s get function(s) return(s) an array, e.g. an oscilloscope trace, or a spectrum analyser trace. At init, you can provide the ``Parameter`` s to measure and (optionally) ``setpoints``. If no ``Parameter`` s are provided, the default ``station.measure()`` is used. If no ``setpoints`` are provided, dummy setpoints are created for each dimension found in the parameters (recommended, see below). ``Measure.run()`` will execute the measurement, and return and save a ``DataSetPP``

Examples:

Measure two parameters:

.. code-block:: python

    station.set_measurement(array_param1, array_param2)
    data = qc.Measure(name='Name for dataset filename').run()

Measure two parameters twice, changing some value in between:

.. code-block:: python

    station.set_measurement(array_param1, array_param2)
    measure = qc.Measure()
    data=measure.run(name='instrument parameter value = 0')
    instrument.some_parameter(1.0)  # Set some parameter to a value
    data=measure.run(name='instrument parameter value = 1')

Iteratively:

.. code-block:: python

    station.set_measurement(array_param1, array_param2)
    measure = qc.Measure()
    for i in range(10):
        instrument.some_parameter(i)  # Set some parameter to a value
        data=measure.run(name=f'iteration {i}')

And of course if the parameters return 1D or 2D rectangular arrays, you can plot the results using

.. code-block:: python

    pp=qc.live_plot(data,[data.array_param1, data.array_param2])

Note that the above can also be done within a ``Loop``. The ``Loop`` class is smart enough to work out what the dimensions of the data will be, and create an array in the ``DataSetPP`` of the correct shape. The downside is that these higher dimensional data sets then don't play nice with default plotting, meaning you will always have to plot them manually.


Setpoints
---------

Elements in a ``DataSetPP`` can either be ``setpoints`` or ``measured``, and each ``measured`` element must have corresponding ``setpoints`` with the correct dimensions. In the case of ``Loop``, the setpoints are automatically generated based on the sweep parameters, and the measured data is automatically assigned to the correct setpoints. For ``Measure``, this has no obvious meaning. By default, each measured element gets associated with setpoints that are simply the indices of the measured data, i.e. for a measured element with shape (10,), the setpoints will be (0, 1, 2, ..., 9). Therefore, it's usually much more interesting to plot two measured elements against each other, rather than against the default setpoints.

For example, if you measure the x-axis and y-axis of an oscilloscope trace, you can do:

.. code-block:: python

    station.set_measurement(oscilloscope.x_axis,oscilloscope.y_axis)
    measure = qc.Measure(name='dummy_name')
    data = measure.run()
    pp=qc.live_plot()
    pp.add(data.oscilloscope_x_axis, data.oscilloscope_y_axis, 
            title='Oscilloscope trace', name='oscilloscope_trace', subplot=0)

Optionally, one can provide ``setpoints`` to the ``Measure`` class, which has the disadvantage of being tricky to set up, but the advantage that if you do set it up correctly, ``live_plot`` will detect the axes automatically. A measured element with shape (10,) must have a corresponding setpoint with shape (10,), and a measured element with shape (10, 5) must have two corresponding setpoints: one with shape (10, 5) and a second with shape (10,). If you are familiar with the ``DataSetPP`` objects generated by the ``Loop`` class, hopefully this system will also be familiar.

Examples of using setpoints:

For measuring a set of parameters with a shape of (101,):

.. code-block:: python

    setpoints=np.linspace(0,0.5,101)
    measure = qc.Measure(setpoints=[setpoints],name='dummy_name')
    data = measure.run()

The setpoints can also be a ``Parameter`` which returns an array of the correct shape. Taking the oscilloscope example from above, you can also do:

.. code-block:: python

    station.set_measurement(oscilloscope.y_axis)
    setpoints=oscilloscope.x_axis
    measure = qc.Measure(setpoints=[setpoints],name='dummy_name')
    data = measure.run()
    pp=qc.live_plot(data,[data.oscilloscope_y_axis])

and the two axes will be plotted against each other correctly.

However, **please note that you can just as easily simply measure both parameters as measured elements, let the automatic setpoints be created, and then plot the data manually**. This is the recommended way to do it, as it is much less error-prone.