Measurements subpackage¶

Measurements are currently the main user interface to the eprcontrol toolbox. A measurement is defined in a YAML file setting the experiment and display according to the user’s needs. Furthermore, parameters and settings for the experiment (and the display) can be put in there.

From the user’s perspective, the parameters of the measurement are defined in a YAML file somewhere convenient in a directory of the user. Thus, measurement parameters that need to change according to the specific needs are fully separated from the eprcontrol software and can be stored together with the data, providing a minimal documentation of the setup used and experiment performed.

Performing measurements based on recipes¶

Recipes are a way to define measurements in a user-friendly way, relieving the user from being able to program. All you need to do is to create/modify a simple text file according to the needs of your specific measurement. For the time being, those recipes are the primary user interface to the eprcontrol toolbox. All parameters and settings for an individual measurement are stored in a YAML file. An example for such a measurement YAML file is given below:

experiment:
    name: DummyExperiment
    parameters:
        filename: my_first_dummy_experiment_run
        number_of_rows: 200
    settings:
display:
    name: Display

As you can see, thanks to the YAML file format, this is a rather simple and straightforward way of defining measurements. You define an experiment and a display, whose names each need to correspond to classes of the respective subpackages. For the experiment you can provide parameters as well as settings. The main difference between the two: Parameters are the variables of the actual experiment, settings are applied to the setup used, i.e., the underlying hardware components. For further settings of both, experiment and display parameters, see the respective documentation.

To actually perform a measurement, you will need to do two simple steps:

Create an instance of the eprcontrol.measurements.Measurement class.
Perform the actual measurement.

In MATLAB® code, this could look like the following:

measurement = eprcontrol.measurements.Measurement('measurement.yaml');
measurement.perform();

If you don’t like working with objects, there is even a one-liner:

eprcontrol.measurements.perform('measurement.yaml');

This function will do nothing else than executing the two lines given above, i.e., instantiate an object of the eprcontrol.measurements.Measurement class and run its perform() method.

Why recipes?¶

Using recipes, i.e. simple human-readable and writable text files, to define measurements comes with a number of advantages:

Simple and straight-forward implementation
Strict separation of user interface and underlying code performing the real actions
One step further towards reproducibility: Recipes for measurements can be stored along with the data obtained.

For further discussion, see the in-depth discussion of recipe-driven measurements in the user documentation.

Classes and functions¶

class eprcontrol.measurements.Measurement(filename)¶

Bases: handle

Base class for measurements

The eprcontrol.measurements.Measurement class is for now the primary user interface to the eprcontrol toolbox. All parameters and settings for an individual measurement are stored in a YAML file and read by the eprcontrol.measurements.Measurement object either on instantiation or using the from_file() method.

An example for such a measurement YAML file is given below:

experiment:
    name: DummyExperiment
    parameters:
        number_of_rows: 200
    settings:
display:
    name: Display

As you can see, thanks to the YAML file format, this is a rather simple and straightforward way of defining measurements. You define an experiment and a display—whose names need to correspond to classes of the respective subpackages—, and for the experiment you can set parameters as well as settings. For further settings of both, experiment and display parameters, see the respective documentation.

To perform a measurement, you need to do two simple steps:

Create an instance of the eprcontrol.measurements.Measurement class.
Perform the actual measurement.

In MATLAB® code, this could look like the following:

measurement = eprcontrol.measurements.Measurement('measurement.yaml');
measurement.perform();

experiment¶

instance of the experiment class as defined in the YAML file

Type: eprcontrol.experiments.Experiment

display¶

instance of the display class as defined in the YAML file

Type: eprcontrol.displays.Display

Measurement(filename)¶

Create an instance of the Measurement class

Parameters

filename (string) –

optional filename to create the measurement from

If no filename is given upon instantiating the class, use the from_file() method later on.

If a filename is given, the method from_file() is called. See there for further details.

from_file(filename)¶

Load parameters for the measurement from a file

Parameters

filename (string) –

filename to create the measurement from

The file format may be everything understood by the eprcontrol.configurations.Configuration class.

After having loaded the parameters, the respective classes for experiment and display will be instantiated and the parameters and settings applied to those objects.

The display is hidden at first and only made visible when performing the measurement, using the perform() method.

perform()¶

Perform the actual measurement

This will make the display visible and run the experiment.

In case either the display or the experiment property of the eprcontrol.measurements.Measurement object are empty, a warning is issued and the operation aborted.

eprcontrol.measurements.perform(filename)¶

Carry out a measurement defined in a measurement recipe file.

Parameters

filename (string) –

filename to create the measurement from

The file format may be everything understood by the eprcontrol.configurations.Configuration class.