Environment Variable Catalog

This is the catalog of the available environment variables that can be used in Sardana.

General Environment Variables

ActiveMntGrp

Mandatory, set by user

Environment variable to define the measurement group that will be used when running a scan.

See also

For further information regarding measurement groups, please read the following document: Measurement Group Overview

PreserveMacroData

Boolean environment variable used to keep in memory the data generated by a macro.

DefaultPool

Mandatory when more than one Pool is defined in MacroServer, set by user

Environment variable used to define which Pool will be used in case there is an ambiguity when defining an element (e.g. defctrl in a MacroServer with more than one Pool containing the controller class).

Diffractometer Environment Variables

DiffracDevice

Mandatory, set by user

This environment variable is used to define the name of the diffractometer device. At this moment, this name is supporting only Tango device names and it should be pointing to the Sardana controller of the class HklPseudoMotorCtrl that will be used by the hkl macros.

Psi

Not mandatory, set by user

Environment variable to specify the psi device. This device must be the Tango device server corresponding Sardana PseudoMotor steering the movement of the azimuthal angle.

Q

Mandatory, set by macro wh

This environment variable is set by the macro wh and it correspond to the Q vector.

See also

For a better understanding of the wh macro, please refer to wh

Macro Logging Environment Variables

LogMacro

Not mandatory, set by user

Enable and disable the macro logging via this boolean environment variable.

LogMacroDir

Not mandatory, set by user or to default value: tmp, by macro

Directory where the macro logging file will be save.

LogMacroMode

Not mandatory, set by user or to default value: 0, by macro

With this environment variable it’s possible to specify the number of backup files to be saved.

Todo

Add and example here.

LogMacroFormat

Not mandatory, set by user or to default value by macro

Definition of the format to be used to save the file.

Motion Environment Variables

MotionDecoupled

Not mandatory, set by user

Enable/disable the decoupled motion for continuous scans.

See also

For a deeper understanding of the continuous scans, please refer to the continuous scans documentation

Scan Environment Variables

ApplyExtrapolation

Not mandatory, set by user

Enable/disable the extrapolation method to fill the missing parts of the very first scan records in case the software synchronized acquisition could not follow the pace. Can be used only with the continuous acquisition macros e.g. ct type of continuous scans or timescan. Its value is of boolean type.

Note

The ApplyExtrapolation environment variable has been included in Sardana on a provisional basis. Backwards incompatible changes (up to and including removal of this variable) may occur if deemed necessary by the core developers.

ApplyInterpolation

Not mandatory, set by user

Enable/disable the zero order hold a.k.a. “constant interpolation” method to fill the missing parts of the scan records in case the software synchronized acquisition could not follow the pace. Can be used only with the continuous acquisition macros ct type of continuous scans or timescan. Its value is of boolean type.

Note

The ApplyInterpolation environment variable has been included in Sardana on a provisional basis with SEP6. Backwards incompatible changes (up to and including removal of this variable) may occur if deemed necessary by the core developers.

DataCompressionRank

Not mandatory, set by user

Environment variable used to select the data compression rank that will be used to save the data into a file.

The data compression rank is the minimum number of dimensions above which the dataset will be compressed, e.g. 0 for scalars, 1 for spectrums, 2 for images.

The possible values are:

  • -1: No where

  • 0: for all datasets

  • 1: for datasets of rank 1 or more

  • 2: for datasets of rank 2 or more

  • 3: for datasets of rank 3 or more

DataRecorder

Not mandatory, set by user

Environment variable used to enable data recorders, it can be a string or or a list of strings.

DirectoryMap

Not mandatory, set by user

In case that the server and the client do not run on the same host, the scan data may be easily shared between them using the NFS. Since some of the tools e.g. showscan rely on the scan data file the DirectoryMap may help in overcoming the shared directory naming issues between the hosts.

Its value is a dictionary with keys pointing to the server side directory and values to the client side directory/ies (string or list of strings).

Todo

Add an example here.

GeneralCondition

Not mandatory, set by user

Macro to be evaluated after each step scan point. It must have a return value, if True the current point of the scan will be repeated. All the points are shown in the output and stored (in case the scan data are stored).

JsonRecorder

Not mandatory, set by user

Enable/disable the JsonRecorder. This recorder is used to retrieve the data generated by a macro during its run time in a json format. An example of usage of this recorder is plotting live scans.

Todo

Add reference to the jsonrecorder documentation when available.

MeshM2CorrectDrift

Not mandatory, set by user

Its value must be of type boolean and it indicates whether, in a mesh scan, the position of the second motor (a.k.a. slow motor) is sent at each point (True, default behaviour), even when only the position of the first motor (a.k.a. fast motor) changes. Set it to False to not send the postion for the second motor. This variable is ignored if the optional macro parameter with the same purpose is specified when launching it.

OutputCols

Not mandatory, set by user

Select a subset of the scan output columns to be printed. Two different ways of specifying the selected columns exists. First, by specifying an integer number e.g. 2 means print just the very first two columns. Second, by specifying a list of string identifiers e.g. scan elements URIs or the scan record metadata identifiers: “point_nb”, “timestamp”.

The original order of colums is not changed. This feature is similar to the expconf enable/disable output.

Example:

senv OutputCols "['tango_host:port/expchan/zerodctrl01/1','motor1','timestamp']"

PreScanSnapshot

Not mandatory, set by user

Variable listing the elements that will be collected and saved before a Scan is executed.

The format for the value is the following:

[(taurus model URI, label)]

If the first element in the tuple is a Sardana element, it’s enough to set up the URI up to the Tango device server name. If the element is outside Sardana, i.e. A Tango attribute, you need to add the full URI, up to the attribute name.

Example:

[('tango://sardana/motor/01', 'mot01')]

or

[('tango://device/server/01/attribute','label')]

SampleInfo

Not mandatory, set by user

Extra information about the sample that could be added as a string. This environment variable exist for metadata purposes.

ScanDir

Mandatory if you want scan file to be saved, set by user

Its value is of string type and indicates an absolute path to the directory where scan data will be stored.

In order to store every new started scan in a new directory use {ScanID} placeholder in the directory name e.g. /foo/bar_{ScanID} will produce scan files in /foo/bar_1, /foo/bar_2, etc. directories.

ScanFile

Mandatory if you want scan file to be saved, set by user

Its value may be either of type string or of list of strings. In the second case data will be duplicated in multiple files (different file formats may be used). Recorder class is implicitly selected based on the file extension. For example “myexperiment.spec” will by default store data in SPEC compatible format.

In order to store every new started scan in a new file use {ScanID} placeholder in the file name(s) e.g. foo_{ScanID}.dat will produce scan files in foo_1.dat, foo_2.dat, etc. files.

ScanID

Set automatically by sardana

Its value is an integer. Starts from 0 (on using a new scan file) and increments by 1 on every started scan.

ScanH5SWMR

Not mandatory, set by user

Enable/disable HDF5 SWMR mode when using HDF5 write sessions with NXscanH5_FileRecorder.

ScanMntGrpFinishTimeout

Not mandatory, set by user

Its value must be of numeric type and it indicates how much extra time a continuous scan will wait for measurement group to finish acquisition. After exceeding this time and not finishing acquisition scan ends with an exception. This may happen due to missed hardware triggers or positioning problems.

ScanOvershootCorrection

Not mandatory, set by user

Its value must be of type boolean and it indicates whether the continuous scan overshoot correction is performed at the end of the scan. If not defined the overshoot correction will be applied.

ScanRecorder

Not mandatory, set by user

Its value may be either of type string or of list of strings. If ScanRecorder variable is defined, it explicitly indicates which recorder class should be used and for which file defined by ScanFile (based on the order).

Example 1:

ScanFile = myexperiment.spec
ScanRecorder = FIO_FileRecorder

FIO_FileRecorder will write myexperiment.spec file.

Example 2:

ScanFile = myexperiment.spec, myexperiment.h5
ScanRecorder = FIO_FileRecorder

FIO_FileRecorder will write myexperiment.spec file and
NXscan_FileRecorder will write the myexpriment.h5. The selection of the
second recorder is based on the extension.

See also

More about the extension to recorder map in Writing recorders.

ScanStats

Not mandatory, set by scanstats macro

Stores the last calculated scan statistics. Its value is a dictionary with the following key - value:

  • Motors - motor(s) name on which the statistics were calculated

  • ScanID - scan ID

  • Stats - dictionary with motor(s) names as key and dictionary as value being a dictionary with channel(s) name as key and value being a dictionary with the channel’s scan statistics:

    • cen - center of FWHM

    • com - center of mass of channel data

    • fwhm - full-width at half-max of channel data

    • int - sum/integral of channel data

    • max - maximum of channel data

    • maxpos - motor position where the channel reached the maximum

    • mean - average of channel data

    • min - minimum of channel data

    • minpos - motor position where the channel reached the minimum

For example:

{'Motors': ['mot01'],
 'ScanID': 1,
 'Stats': {
  'mot01': {
   'ct01': {
    'cen': 5.0,
    'com': 5.0,
    'fwhm': 10.0,
    'int': 1.1,
    'max': 0.1,
    'maxpos': 0.0,
    'mean': 0.1,
    'min': 0.1,
    'minpos': 0.0},
   'gct01': {
    'cen': 5.0,
    'com': 5.0,
    'fwhm': 1.9999999568277493,
    'int': 2.1289340331309955,
    'max': 1.0,
    'maxpos': 5.0,
    'mean': 0.21078554783475204,
    'min': 2.9802322387695312e-08,
    'minpos': 0.0}}}}

ScanUser

Not mandatory, set by user

Its value is of type string. Its value is delivered to the recorders which may use it, for example, as a user contact information. If not set, the OS user executing the Sardana server (which executes the scan) will be passed to the recorders instead.

SharedMemory

Not mandatory, set by user

Its value is of string type and it indicates which shared memory recorder should be used during the scan e.g. “sps” will use SPSRecorder (sps Python module must be installed on the PC where the MacroServer runs).

See also

For more information about the implementation details of the scan macros in Sardana, see scan framework

SourceInfo

Not mandatory, set by user

Extra information about the source that could be added as a string. This environment variable exist for metadata purposes.