.. include:: <isonum.txt>

Setups subpackage
=================

Each :doc:`experiment <experiments>` uses a setup. Each setup in turn consists of different :doc:`components <components>` that each have their :doc:`connection <connections>`. The base class for setups is :class:`+eprcontrol.+setups.Setup`. Every setup should inherit from this class.

There are currently a number of derived classes designed to control a particular setup, for the time being dedicated to time-resolved EPR. However, in a long run, these classes are no longer needed, as the setups can be defined using description files. For details, carry on reading.


Defining setups using textual descriptions
------------------------------------------

One can think of a setup as a  simple list of components with each their individual connection. Hence, it is rather straight-forward to formalise the description of setups in simple config files and create the necessary classes a setup consists of on the fly.

An example of such a setup description using the YAML file format may look like the following:

.. code:: yaml

  connections:
      xenon:
          type: BrukerXenonXmlrpcConnection
          configuration:
              ip: 192.168.1.1
              port: 4711
      spcm:
          type: SpcmConnection
  components:
      microwavebridge:
          type: BrukerXenonMicrowaveBridge
          connection: xenon
      fieldcontroller:
          type: BrukerXenonFieldController
          connection: xenon
      digitizer:
          type: SpcmM4i4421x8
          connection: spcm


Here, you can see how to create a setup for time-resolved EPR spectroscopy, consisting of three components: a microwave bridge, a magnetic field controller, and a digitizer. Note that two of the components share the same connection. Therefore, there is only two connections defined, but three components. Besides that, the setup description should be self-explaining. The connections defined can be referred to by their names, thus reusing one connection object for several components. Note that currently, the descriptions are not parsed for errors, hence every typo in a class name will inevitably lead to immediate error messages on the MATLAB\ |reg| command line.

A note on the configuration for the connections: You can set any parameter that is understood by the respective connection class, *i.e.* where the ``configuration`` struct of the class has a corresponding field. That means that misspelling field names will prevent the settings to take effect. Furthermore, you need not to specify all configuration values here, but can rely on the defaults set in the respective connection class.


.. todo::

  For this functionality to reveal its full potential, one would need to create an infrastructure and define a strategy where to store setup descriptions (and possible other configuration files). The setup definition should be stored in the user space, whereas the eprcontrol toolbox will usually be located elsewhere.


Classes
-------

.. toctree::
   :maxdepth: 1


.. automodule:: +eprcontrol.+setups
    :members:
    :private-members: