Running measurements with QDrive
================================

.. note::
    The measurements will be stored in the default selected scope, for more information on how to set up a scope, see :ref:`here <setting-up-a-scope>`

Performing sweeps using the ``do0D``, ``do1D`` and ``do2D`` functions.
-----------------------------------------------------------------------

For most experiments simple sweeps can be used, i.e., they are usually gridded sweeps in 0, 1 or 2 dimensions.

Below you can find some examples of measurement that can be made using these functions:

.. code-block:: python

    from qdrive.measurement.sweeps import do0D, do1D, do2D
    from qdrive.demo.station import get_station

    station = get_station()
    t_exp = 10 # seconds

    def run_0D_experiment():
        graph_instr = station.zero_D_graph_instr

        # add_qcodes_snapshot --> if True, the qcodes snapshot will be added (can be used in all doXD functions)
        return do0D("0D_sweep_example", graph_instr.m_param, add_qcodes_snapshot=True)

    def run_1D_experiment():
        n_x_vals = 1000
        graph_instr = station.one_D_graph_instr
        graph_instr.set_shape(n_x_vals) # for demo purposes, not needed with real instruments

        dac = station.QH_dac
        # sweep the dac - ch1 from -200 to 250
        # wait after setting the dac value t_exp/n_x_vals to let the output settle.
        return do1D("1D_sweep_example", dac.ch1, -200, 250, n_x_vals, t_exp/n_x_vals, graph_instr.m_param)

    def run_2D_experiment():
        n_x_vals = 100
        n_y_vals = 150
        graph_instr = station.two_D_graph_instr
        graph_instr.set_shape(n_x_vals, n_y_vals) # for demo purposes, not needed with real instruments
        
        dac = station.QH_dac

        # sweep the dac - ch1 from 0   to -400
        # sweep the dac - ch2 from 200 to  350
        # when the first dac, ch1 is set, wait t_exp/n_x_vals.
        # when the second dac, ch2 is set, do not wait.
        return do2D("2D_sweep_example", dac.ch1, 0, -400, n_y_vals, t_exp/n_y_vals,
                                        dac.ch2, 200, 350, n_x_vals, 0, graph_instr.m_param)

These examples demonstrate the basic usage. It is also possible to add multiple measured parameters to the function, e.g.:

.. code-block:: python

    do1D("1D_sweep_example", dac.ch1, -200, 250, n_x_vals, t_exp/n_x_vals, m_param1, m_param2) # and so on.

Writing your own loops using the measurement class
--------------------------------------------------

The example below shows a lower-level interface that can be used to define your own loops (based on the qcodes measurement object):

.. code-block:: python

    import time 
    import numpy as np

    from qdrive.measurement.measurement import Measurement
    from qdrive.demo.station import get_station

    n_x_vals = 100
    n_y_vals = 150

    station = get_station()

    # Combine the previous 1D and 2D experiments in a single experiment

    # 1 load relevant instruments
    graph_instr_1D = station.one_D_graph_instr
    graph_instr_1D.set_shape(n_x_vals)
    graph_instr_2D = station.two_D_graph_instr
    graph_instr_2D.set_shape(n_x_vals, n_y_vals)

    dac = station.QH_dac

    # 2 create a measurement object
    meas = Measurement("combined_1D_and_2D_measurement")
    meas.register_m_param(graph_instr_1D.m_param, dac.ch1)
    meas.register_m_param(graph_instr_2D.m_param, dac.ch1, dac.ch2)

    # 3 run the measurement
    with meas.measure() as data_collector:
        for ch1_voltage in np.arange(0,n_y_vals,1):
            dac.ch1.set(ch1_voltage)
            # provide collection of m_params and their setpoints here
            data_collector.add_data({dac.ch1 : ch1_voltage, graph_instr_1D.m_param : graph_instr_1D.m_param()})

            for ch2_voltage in np.arange(0,n_x_vals,1):
                dac.ch2.set(ch2_voltage)
                data_collector.add_data({dac.ch1 : ch1_voltage,
                                            dac.ch2 : ch2_voltage,
                                            graph_instr_2D.m_param : graph_instr_2D.m_param()})

                time.sleep(0.001)

    ds = meas.dataset