.. _sardana-tutorial-first-scan: ==================== Run your first scan ==================== Scans are the bread and butter of an experiment: macros that move one or more motors and acquire data along the way. In this final lesson of the series you will count, run absolute and relative step scans, and store the resulting data in a file. You need the simulated beamline from :ref:`sardana-tutorial-demo-beamline` (the demo counters ``ct01`` ... ``ct04`` and motors ``mot01`` ... ``mot04``). The measurement group --------------------- Which data is acquired is not decided by the scan macro itself -- it is defined by the active *measurement group*, a Sardana element that groups experimental channels (counters, 0D/1D/2D channels, ...) so they can be acquired together. The ``sar_demo`` macro already created one, ``mntgrp01``, containing the four demo counters, and set it as the *active* one via the ``ActiveMntGrp`` environment variable: .. sourcecode:: spock Door_demo1_1 [1]: lsmeas Active Name State Experim. channels -------- ---------- ------- ----------------------------- * mntgrp01 ON ct01, ct02, ct03, ct04 You can read more in :ref:`measurement group acquisition `. Counting -------- The simplest acquisition is the ``ct`` (*count*) macro: acquire the active measurement group for a given integration time, without moving anything: .. sourcecode:: spock Door_demo1_1 [2]: ct 1 Wed Jun 10 17:34:12 2026 ct01 = 1.0 ct02 = 2.0 ct03 = 3.0 ct04 = 4.0 (The dummy counters simply return the integration time multiplied by their axis number -- handy for checking that everything works.) Your first step scan -------------------- ``ascan`` (*absolute scan*) moves one motor from a start to a stop position in a number of equally spaced intervals, stopping at each point to acquire the measurement group. Its arguments are: motor, start, stop, number of intervals, integration time: .. sourcecode:: spock Door_demo1_1 [3]: ascan mot01 0 10 10 0.2 Scan #1 started at Wed Jun 10 17:36:30 2026. It will take at least 0:00:05 #Pt No mot01 ct01 ct02 ct03 ct04 dt 0 0 0.2 0.4 0.6 0.8 0.1547 1 1 0.2 0.4 0.6 0.8 0.5894 2 2 0.2 0.4 0.6 0.8 1.0244 ... 10 10 0.2 0.4 0.6 0.8 5.4621 Scan #1 ended at Wed Jun 10 17:36:36 2026, taking 0:00:05.97. Dead time 60.5% (setup time 2.1%, motion dead time 56.3%) Because this is a *step* scan, the position associated with each data row is well defined: the motor is standing still while the counters acquire. A scan can be interrupted at any moment with :kbd:`Ctrl+C` -- Sardana stops the motion and the acquisition gracefully. The relative variant, ``dscan``, scans around the *current* position and returns the motor to it afterwards. This scans from -2 to +2 around wherever ``mot01`` currently is, in 8 intervals of 0.5 s: .. sourcecode:: spock Door_demo1_1 [4]: dscan mot01 -2 2 8 0.5 There are many siblings: ``a2scan`` moves two motors, ``mesh`` scans a 2D grid, etc. Use ``lsdef`` or the macro catalog in the reference section to explore them. Where does the data go? ----------------------- Until you configure storage, scan data only goes to the Spock screen (you will see a warning starting with ``This operation will not be stored persistently.``). Data storage is controlled by two environment variables, ``ScanDir`` and ``ScanFile``, which you set with the ``senv`` macro: .. sourcecode:: spock Door_demo1_1 [5]: senv ScanDir /tmp/scans ScanDir = /tmp/scans Door_demo1_1 [6]: senv ScanFile demo1.h5 ScanFile = demo1.h5 The file extension selects the *recorder*: ``.h5`` stores NeXus/HDF5 files, ``.spec`` or ``.dat`` stores SPEC-style ASCII files. You may even set ``ScanFile`` to a list to write both at once. From now on every scan announces and saves its data: .. sourcecode:: spock Door_demo1_1 [7]: ascan mot01 0 10 10 0.2 Operation will be saved in /tmp/scans/demo1.h5 (HDF5::NXscan from NXscanH5_FileRecorder) ... Use ``lsenv`` to inspect all environment variables, and the ``newfile`` macro as a convenient shortcut to change the scan file. To have a quick look at the acquired data, you can plot it from the file with any HDF5/SPEC-aware tool, or use Sardana's scan viewer GUI (run ``sardanactl showscan``, requires the Qt dependencies). Inside Spock, the ``scanhist`` macro shows the history of past scans. A teaser: continuous scans -------------------------- In a step scan most of the time is spent accelerating, decelerating and waiting -- the *dead time*. Sardana also offers *continuous* scans, where data is acquired while the motors keep moving. Most step scan macros have a continuous counterpart with a ``ct`` suffix and the same parameters, e.g.: .. sourcecode:: spock Door_demo1_1 [8]: ascanct mot01 0 10 10 0.2 Continuous scans come with constraints (synchronization, no backlash correction, ...) that you can read about in the :ref:`scans user documentation `. Next steps ---------- Congratulations -- you have completed the tutorial series! You can now set up a Sardana system, extend it with macros and controllers, and run scans. Where to go from here: - :ref:`Scans ` -- step vs. continuous scans, recorders and data storage in depth. - :ref:`Measurement group acquisition ` -- advanced acquisition and synchronization. - :ref:`Writing macros ` -- including how to write your own scan macros with the scan framework. - :ref:`Spock ` -- the full command line interface guide.