Installing the NIST scan framework
===================================

The NIST scan framework runs under ARTIQ version 3.7 and requires Python version 3.5.

First, create a conda environment with Python version 3.5 and ARTIQ version 3.7 installed and activate the
environment.  See `installing ARTIQ version 3.7 <https://m-labs.hk/artiq/manual-release-3/installing.html>`_ for
further details on installing ARTIQ.

.. code-block:: console

    conda create -n artiq-3.7 artiq=3.7
    conda activate artiq-3.7

Next, clone the scan_framework repository into a folder that is in your :code:`PYTHONPATH` and make sure the top level
folder containing the scan_framework source is named :code:`scan_framework`.

TODO: update github url below

.. code-block:: console

    git clone https://github.com/nist/scan_framework.git /folder/on/pythonpath

Finally, create ARTIQ applets to plot data generated by the scan framework.

.. note::
    All scan framework applets are listed in the source code at scan_framework/applet_commands.txt

In the ARTIQ dashboard, create the current scan applet using the command below.  Scan's automatically write
all data to the :code:`current_scan` namespace.  The current scan applet plots this data as a scan is being executed.

.. code-block:: console

    $python -m scan_framework.applets.plot_xy current_scan.plots.y
        --x current_scan.plots.x
        --fit current_scan.plots.fitline
        --title current_scan.plots.plot_title
        --x_scale current_scan.plots.x_scale
        --x_units current_scan.plots.x_units
        --y_scale current_scan.plots.y_scale
        --x_label current_scan.plots.x_label
        --y_units current_scan.plots.y_units
        --y_label current_scan.plots.y_label
        --rid current_scan.rid
        --error current_scan.plots.error

In the ARTIQ dashboard, create the current sub-scan applet using the command below.
The current sub-scan applet plots data from 2D scans as they execute.

.. code-block:: console

    $python -m scan_framework.applets.plot_xy current_scan.plots.dim1.y
        --x current_scan.plots.dim1.x
        --fit current_scan.plots.dim1.fitline
        --title current_scan.plots.dim1.plot_title
        --x_scale current_scan.plots.dim1.x_scale
        --x_units current_scan.plots.dim1.x_units
        --x_label current_scan.plots.dim1.x_label
        --y_units current_scan.plots.dim1.y_units
        --y_label current_scan.plots.dim1.y_label
        --trigger current_scan.plots.trigger
        --rid current_scan.rid
        --i_plot current_scan.plots.subplot.i_plot

In the ARTIQ dashboard, create the count monitor applet using the command below (optional).
The count monitor applet displays the average measured value at each scan point.

.. code-block:: console

    ${artiq_applet}big_number counts

In the ARTIQ dashboard, create the current histogram applet (optional).
The current histogram applet plots a histogram of collected data at each scan point as the scan executes.

.. code-block:: console

    $python -m scan_framework.applets.plot_hist current_hist.bins
        --x current_hist.bin_boundaries
        --x_units current_hist.x_units
        --x_label current_hist.x_label
        --plot_title current_hist.plot_title