.. _sardana-howto-scan-configuration: =================================== 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 :ref:`sardana-users-scan`. Configuration ------------- Scans are highly configurable using the environment variables (on how to use environment variables see environment related macros in :ref:`sardana-standard-macro-catalog`). .. seealso:: For further information about the available Sardana Environment Variables, check the :ref:`Environment Variable Catalog ` .. _sardana-users-scan-shutter: Shutter ------- A shutter is a Pool element that can be synchronized with the active :ref:`measurement group ` acquisition. Create one with :class:`~sardana.macroserver.macros.expert.defsh`:: defsh fast_shutter and remove it with :class:`~sardana.macroserver.macros.expert.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 :ref:`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 :class:`~sardana.macroserver.macros.standard.ct`, step scans and *ct* continuous scans such as :class:`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 :class:`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 `_. .. _sardana-users-scan-data-storage: 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 :ref:`Storage tab in Experiment Configuration UI `, `~sardana.macroserver.macros.standard.newfile` macro, or :ref:`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 :class:`~sardana.macroserver.macros.lists.lsrec` and :class:`~sardana.macroserver.macros.lists.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 :ref:`scanid` environment variable (see :ref:`scandir` and :ref:`scanfile` environment variables on how to configure it). .. _sardana-users-scan-data-storage-nxscanh5_filerecorder: 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 `~sardana.macroserver.macros.h5storage.h5_start_session` / `~sardana.macroserver.macros.h5storage.h5_start_session_path` and `~sardana.macroserver.macros.h5storage.h5_end_session` / `~sardana.macroserver.macros.h5storage.h5_end_session_path` macros. You can list the active sessions with `~sardana.macroserver.macros.h5storage.h5_ls_session` macro. * Programmatic session control with context manager (for macro developers) You can use the `~sardana.macroserver.macros.h5storage.h5_write_session` context manager to ensure that the write session is only active over a specific part of your macro code. .. _sardana-users-scan-snapshot: 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 :ref:`Experiment Configuration widget ` and :ref:`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 :ref:`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 :class:`~sardana.macroserver.macros.scan.scanstats` macro to the ``post-scan`` hook place (see :ref:`hook documentation ` for more info). You can also do it on demand by directly executing :class:`~sardana.macroserver.macros.scan.scanstats` after executing the scan macro. Apart from printing the statistics by the scanstats macro these are stored in the door's :ref:`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 (:class:`~sardana.macroserver.macros.standard.pic`) * move the scanned motor to center position of FWHM (:class:`~sardana.macroserver.macros.standard.cen`)