.. _configuration:

Configuration
*************

This section explains how to create the configuration files required by TeraPy.

.. contents::

.. _config_folders:

Main configuration settings
===========================

By default, TeraPy expects to find the following folders in the execution folder ::
 
 execution folder/
	backup
 	config
	data
	filters
	modules

This structure can be altered by specifying alternative folders in a file called ``terapy.ini``, placed in the execution folder.

This file must have the following structure :

.. code-block:: xml
   
	<?xml version="1.0" ?>
		<config scope="terapy">
	  		<default_path value="backup">
	  		<config_path value="config">
	  		<user_path value="data">
	  		<filter_path value="filters">
	  		<module_path value="modules">
	  		<refresh_delay value="0.2">
	 	</config>

Missing entries will be replaced by default values. TeraPy checks that the given folders exist, and if not reverts back to execution folder. The function of these directories is:

- **default_path**: path where files are saved by default, for instance for backup files or automatic save feature
- **config_path**: folder with default configuration files (see :ref:`config_files` below)
- **user_path**: path where TeraPy will open file dialogs
- **filter_path**: folder containing custom filter bank files
- **module_path**: folder containing custom modules (see :ref:`programmer` for details)

In addition to directories, ``terapy.ini`` contains

- **refresh_delay**: delay, in seconds, to wait before refreshing the interface. Useful on slow systems or for fast measurements, where updating the interface may slow down the measurement process.

Alternatively, ``terapy.ini`` can be placed inside the ``config_path`` (this requires that ``config`` be present in the execution folder).


.. _config_files:

Configuration files
===================

The configuration folder (the one given by ``config_path``) can contain files, which will define the default state of several interface modules. Namely:

- **devices.ini**: hardware devices, which will be loaded on startup
- **events.ini**: default scan event sequences
- **filters.ini**: default filter banks

All of them are XML files. Their structure is described below.

devices.ini
___________

This file contains a list of devices, which TeraPy will attempt to load on startup. Place here the default hardware configuration of your experiment.
The structure of this file should be :

.. code-block:: xml

 <?xml version="1.0" ?>
	<config scope="devices">
  
		<input driver="driver name" handle="instrument address" name="display name">
			<property some_property="some value"/>
		</input>
		
		<axis driver="driver name" handle="instrument address" name="display name" axis="axis number (integer)">
			<property some_property="some value"/>
		</axis>
  
	</config>

Input devices are specified by ``<input>`` tags and axis devices by ``<axis>`` tags. Properties depend on the specific driver and should be set according to the :ref:`add_drivers` section.


See the :doc:`example_devices_ini` for an example.

events.ini
__________

This file contains measurements sequences, which will appear in the scan event list on startup. It has the following structure :

.. code-block:: xml

 <?xml version="1.0" ?>
	<config scope="events">
		<events>
			<item name="sequence name" class="Sequence">
				<item class="scan event class 1" name="display name 1" some_property="some value"/>
				<item class="scan event class 2" name="display name 2" some_property="some value">
					<item class="scan event class 3" name="display name 3" some_property="some value"/>
			  	</item>
				...
			</item>
		</events>
	</config>

The file can describe one or several scan sequences. Each item in the sequence is represented by an ``<item>`` tag. Properties depend on the scan event class and should be set according to the :ref:`add_events` section.

To ease the creation procedure, you can save sequences that you created within TeraPy graphical user interface and copy them within your own ``events.ini``. See :ref:`user_events` to learn how to do that.

See the :doc:`example_events_ini` for an example.


filters.ini
___________

This file contains the default filter banks for post-processing canvases. Its structure is:

.. code-block:: xml

 <?xml version="1.0" ?>
	<config scope="filters">
		<filters name="Filter bank name" dimension="data dimension to apply to (int)">
			<item class="filter class 1" name="filter display name 1" some_property="some value"/>
			<item class="filter class 2" name="filter display name 2" some_property="some value"/>
			...
		</filters>
	</config>

Several filter banks can be placed in the same file, each corresponding to a separate ``<filters>`` entry. The *dimension* property sets the data dimension, to which the filter bank applies (e.g. 1D data -> ``dimension="1"``). If, for a given dimension, more than one bank is present, TeraPy takes the last one in the file.

Each filter in a filter bank corresponds to one ``<item>`` tag. Properties depend on the filter class and should be set according to the :ref:`add_filters` section.

See the :doc:`example_filters_ini` for an example.

Sample files
____________

Sample configuration files are available in the ``sample`` folder in the TeraPy source package. You can also download them separately here:

- :doc:`example_devices_ini`
- :doc:`example_events_ini`
- :doc:`example_filters_ini`