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 Set up a simulated 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:

Door_demo1_1 [1]: lsmeas
  Active   Name       State   Experim. channels
 -------- ---------- ------- -----------------------------
    *      mntgrp01   ON      ct01, ct02, ct03, ct04

You can read more in 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:

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:

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 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:

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:

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:

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.:

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 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:

  • Scans – step vs. continuous scans, recorders and data storage in depth.

  • Measurement group acquisition – advanced acquisition and synchronization.

  • Writing macros – including how to write your own scan macros with the scan framework.

  • Spock – the full command line interface guide.