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