.. include:: <isonum.txt>

Use cases
=========

This section provides a few ideas of how basic operation of the eprcontrol toolbox for MATLAB\ |reg| may look like.


Measurements
------------

One particular strength of the eprcontrol toolbox for MATLAB\ |reg| are the :doc:`recipe-driven measurements <recipes>`. Thus, a user does not need any programming experience and can define the complete measurement in a simple text file.


A real example
~~~~~~~~~~~~~~

A measurement that has a few more parameters than those shown in the :doc:`introduction to recipe-driven measurements <recipes>` is given below. Here, additional blocks for info and sample have been added, aiming at a full set of metadata necessary for reproducibility.

.. code:: yaml

    info:
        operator: John Doe
        purpose: Waste time
    sample:
        name: stuff
        id: 42
    experiment:
        name: TreprExperiment
        setup: UdSEmXM4i
        parameters:
            filename: trepr-testrun
            magnetic_field:
                start: 3410
                end: 3510
                step: 1
        settings:
            digitizer:
                accumulations: 20
                channels:
                - number: 0
                  input_range: 200
                  termination: 1M
                  coupling: DC
                - number: 2
                  input_range: 5000
                  termination: '50'
                  coupling: DC
    display:
        name: Display


Suppose you have saved this file to ``Sa42-01.yaml``. In this case, performing the actual measurement is as simple as typing the following line in the MATLAB\ |reg| command line and hit return:

.. code:: matlab

    eprcontrol.measurements.perform('Sa42-01.yaml');


Note that it is good practice to save the measurement descriptions along with the data they produced. Thus, it is much easier to find out what and how you actually recorded those data.


Experiments
-----------

The dummy experiment
~~~~~~~~~~~~~~~~~~~~

Originally written to test the interplay of the different components, the demo experiment available through the :class:`+eprcontrol.+experiments.DummyExperiment` class, is a good starting point. According to the documentation of this experiment, you could simply use two lines of MATLAB\ |reg| code to run the experiment:

.. code:: matlab

	experiment = eprcontrol.experiments.DummyExperiment()
	experiment.run()
	

However, this will not give you more than a series of dots on the MATLAB\ |reg| command line, nothing spectacular. More fun comes with connecting a display to see the data being "recorded" during the experiment. How about this:

.. code:: matlab

	experiment = eprcontrol.experiments.DummyExperiment;
	display = eprcontrol.displays.Display;
	display.add_listener(experiment);
	experiment.run();


This will run the exact same experiment as before, but this time, with a display attached that lets you watch the progress of the experiment.

So, why a dummy experiment? Well, because it lets you play with the eprcontrol toolbox for MATLAB\ |reg| without needing a setup available or drivers for your particular setup implemented. And it gives you an idea how the eprcontrol toolbox generally works.


Setups
------

Setups consist of individual components that each have a connection to talk to the underlying hardware. However, due to their modular nature, setups can be fully described using text files (usually YAML files) and created "on the fly".

Two concrete setups with their complete configuration as YAML file are provided as examples below. Use them as starting points for your own needs and change settings accordingly.


Basic TREPR setup
~~~~~~~~~~~~~~~~~

This setup for time-resolved EPR spectroscopy consists of a Bruker EMX spectrometer controlled via Bruker Xenon software. As a digitizer, a Spectrum Instrumentation A/D card (M4i.4421-x8) gets used. Communication to Xenon running on the local computer is done using the XML-RPC protocol.

.. code:: yaml

    connections:
        xenon: 
            type: BrukerXenonXmlrpcConnection
            configuration:
                protocol: http
                ip: 192.168.1.1
                port: 7998
        spcm: 
            type: SpcmConnection
            configuration:
                device_string: /dev/spcm0
    components:
        microwavebridge: 
            type: BrukerXenonMicrowaveBridge
            connection: xenon
        fieldcontroller: 
            type: BrukerXenonFieldController
            connection: xenon
        digitizer: 
            type: SpcmM4i4421x8
            connection: spcm



TREPR setup with software-controlled OPO
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

This setup for time-resolved EPR spectroscopy is rather similar to the one described above. It consists of a Bruker EMX spectrometer controlled via Bruker Xenon software. As a digitizer, a Spectrum Instrumentation A/D card (M4i.4421-x8) gets used. Furthermore, the OPO (GWU) is software-controlled via a Windows computer. Communication to Xenon running on the local computer is done using the XML-RPC protocol. Communication to the GWU OPO software is done using telnets via the TCP/IP protocol.

.. code:: yaml

    connections:
        xenon: 
            type: BrukerXenonXmlrpcConnection
            configuration:
                protocol: http
                ip: 192.168.1.1
                port: 7998
        spcm: 
            type: SpcmConnection
            configuration:
                device_string: /dev/spcm0
        gwu: 
            type: GwuTcpipConnection
            configuration:
                protocol: tcpip
                ip: 192.168.1.120
                port: 992
    components:
        microwavebridge: 
            type: BrukerXenonMicrowaveBridge
            connection: xenon
        fieldcontroller: 
            type: BrukerXenonFieldController
            connection: xenon
        digitizer: 
            type: SpcmM4i4421x8
            connection: spcm
        opo:
            type: GwuOpo
            connection: gwu