.. _environment-variable-catalog:

============================
Environment Variable Catalog
============================

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

.. contents::

.. _general-env-vars:

General Environment Variables
-----------------------------

.. _activemntgrp:

ActiveMntGrp
~~~~~~~~~~~~
*Mandatory, set by user*

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

.. seealso:: For further information regarding measurement groups, please read
             the following document:
             :ref:`Measurement Group Overview <sardana-measurementgroup-overview>`

.. _preservemacrodata:

PreserveMacroData
~~~~~~~~~~~~~~~~~

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

.. _defaultpool:

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. :class:`~sardana.macroserver.macros.expert.defctrl`
in a MacroServer with more than one Pool containing the controller class).

.. _diffractometer-env-vars:

Diffractometer Environment Variables
------------------------------------

.. _diffracdevice:

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:

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:

Q
~
*Mandatory, set by macro wh*

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

.. seealso:: For a better understanding of the *wh* macro, please refer to
             :class:`~sardana.macroserver.macros.hkl.wh`

.. _macro-logging-env-vars:

Macro Logging Environment Variables
-----------------------------------

.. _logmacro:

LogMacro
~~~~~~~~
*Not mandatory, set by user*

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

.. _logmacrodir:

LogMacroDir
~~~~~~~~~~~
*Not mandatory, set by user or to default value: \tmp, by macro*

Directory where the macro logging file will be save.

.. _logmacromode:

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:

LogMacroFormat
~~~~~~~~~~~~~~
*Not mandatory, set by user or to default value by macro*

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

.. _motion-env-vars:

Motion Environment Variables
----------------------------

.. _motiondecoupled:

MotionDecoupled
~~~~~~~~~~~~~~~
*Not mandatory, set by user*

Enable/disable the decoupled motion for continuous scans.

.. seealso:: For a deeper understanding of the continuous scans, please refer
             to the :ref:`continuous scans documentation <sardana-users-scan-continuous>`

.. _scan-env-vars:

Scan Environment Variables
--------------------------

.. _applyextraploation:

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:

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:

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:

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:

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:

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:

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.

.. _outputcols:

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:

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:

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:

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:

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:

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:

ScanH5SWMR
~~~~~~~~~~

*Not mandatory, set by user*

Enable/disable HDF5 SWMR mode when using HDF5 *write sessions* with
:ref:`sardana-users-scan-data-storage-nxscanh5_filerecorder`.

.. _scanmntgrpfinishtimeout:

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:

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:

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.

.. seealso:: More about the extension to recorder map in
             :ref:`sardana-writing-recorders`.

.. _scanstats:

ScanStats
~~~~~~~~~
*Not mandatory, set by* :class:`~sardana.macroserver.macros.scan.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:

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:

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

.. seealso:: For more information about the implementation details of the scan
             macros in Sardana, see 
             :ref:`scan framework <sardana-macros-scanframework>`

.. _sourceinfo:

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.

.. _zero order hold: https://en.wikipedia.org/wiki/Zero-order_hold
.. _SEP6: http://www.sardana-controls.org/sep/?SEP6.md