Scan configuration and data storage

This guide explains how to configure scans, where and how the scan data gets stored and how to use scan snapshots and scan statistics. For an introduction to scans in Sardana see Scans.

Configuration

Scans are highly configurable using the environment variables (on how to use environment variables see environment related macros in Standard macro catalog).

See also

For further information about the available Sardana Environment Variables, check the Environment Variable Catalog

Shutter

A shutter is a Pool element that can be synchronized with the active measurement group acquisition. Create one with defsh:

defsh fast_shutter

and remove it with udefsh:

udefsh fast_shutter

The shutter timing is configured with its Tango attributes:

• time_to_open: time needed by the shutter to fully open.

• time_to_close: time needed by the shutter to close.

• time_to_exposure: time between triggering the shutter and having full beam illuminating the sample. If set to -1 (default), Sardana uses time_to_open. Otherwise it must be non-negative and not greater than time_to_open.

• mode: single opens the shutter once for the whole experiment sequence; multiple opens and closes it for every acquisition in the sequence.

To use the shutter, add it to the measurement group and assign it a hardware Trigger/Gate as synchronizer. The software synchronizer is not allowed for shutters. Currently, scans support only one enabled shutter in the measurement group.

When an enabled shutter is present, Sardana includes it in the synchronization description used by ct, step scans and ct continuous scans such as ascanct. This has the following effects:

• Other experimental channels are delayed by time_to_exposure so their acquisition starts when the shutter exposure is expected to be valid.

• In multiple mode the measurement group latency time is at least time_to_exposure + time_to_close; scans using a smaller latency_time use this larger value.

• In ct continuous scans, the shutter timing is included in the scan motion synchronization. In ascanct, if time_to_exposure is longer than the motor acceleration time, Sardana moves the motor start position further back so that the first acquisition still happens at the initial position, in constant velocity and with the shutter open.

Note

A detailed explanation of the shutter effect on the synchronization description for each scan type can be found in this spreadsheet.

Data storage

Data being produced by scans can be optionally handled by recorders and sent to a variety of destinations. Typical use case is to store the scan data in a file. To enable scan storage please refer to Storage tab in Experiment Configuration UI, newfile macro, or environment variables.

Recorder types

Sardana defines some standard recorders e.g. the Spock output recorder or the SPEC file recorder. From the other hand users may define their custom recorders. Available recorders and recorder libraries can be displayed using the lsrec and lsreclib macros. Sardana defines the following recorder types and comes with some built-in recorders:

• file [*]

  • FIO_FileRecorder

  • NXscanH5_FileRecorder

  • SPEC_FileRecorder

• shared memory

  • SPSRecorder

  • ShmRecorder

• output

  • JsonRecorder

  • OutputRecorder

• generic

[*] file recorders may either append new scans into the same file or dynamically create a new file or directory per scan using the information from the ScanID environment variable (see ScanDir and ScanFile environment variables on how to configure it).

NXscanH5_FileRecorder

NXscanH5_FileRecorder is a scan recorder which writes the scan data according to the NXscan NeXus application definition in the HDF5 file format.

Sardana scan recorders are instantiated per scan execution and therefore this recorder opens and closes the HDF5 file for writing when the scan starts and ends respectively. This may cause file locking issues with reading applications opened in between the scans. To overcome this issue the write session concept, with optional support of SWMR mode, was introduced for this particular recorder.

The write sessions use case scenarios:

• Manual session control with macros

  To start and end the session you can use h5_start_session / h5_start_session_path and h5_end_session / h5_end_session_path macros. You can list the active sessions with h5_ls_session macro.

• Programmatic session control with context manager (for macro developers)

  You can use the h5_write_session context manager to ensure that the write session is only active over a specific part of your macro code.

Scan snapshots

Snapshots are used for saving data (or metadata) from elements and devices not necessarily related to the scan itself. A scan saves only the values of the involved elements, that is positions of motors being moved, and values read from experiment channels in the active measurement group. If you want your scans to include something more you can use the snapshot.

Snapshot group can be configured via Experiment Configuration widget and PreScanSnapshot environment variable. It can include both Sardana elements as well as external (Tango) data sources.

The snapshot is saved only once during a scan, on the very beginning. The exact way the snapshot data is saved depends on the recorder and scan file format being used.

Scan statistics

Sardana may automatically calculate some basic statistics over the scan results e.g., max, mean, FWHM, etc.

In order to enable the automatic statistics calculation you just need to attach the scanstats macro to the post-scan hook place (see hook documentation for more info). You can also do it on demand by directly executing scanstats after executing the scan macro.

Apart from printing the statistics by the scanstats macro these are stored in the door’s ScanStats environment variable. This way some other macro can use them e.g.,

• move the scanned motor to the position where a given channel reached the maximum value (pic)

• move the scanned motor to center position of FWHM (cen)