Components subpackage

Each setup consists of different components that each have their connection. The base class for components is eprcontrol.components.Component. Every component should inherit from this class.

There are currently a number of derived classes serving as starting point for the different types of components, with a strict focus on (time-resolved) EPR experiments:

The other classes are derived from these base classes and are designed to control a particular component, such as a Bruker microwave bridge via the Xenon software, hence using a particular type of connection. The concrete component classes currently implemented are:

A rather special case is the eprcontrol.components.DigitizerChannel class dealing with the settings for digitizer channels, such as input range, termination, and coupling mode.

Classes

class eprcontrol.components.BrukerXenonFieldController

Bases: eprcontrol.components.FieldController

Driver for the Bruker field controller via Xenon software

All components of a Bruker EPR spectrometer connected to Xenon and controlled via the Xenon software can generally be controlled as well using the XML RPC interface to Xenon.

get_field()

Obtain current magnetic field value

Returns

field – current magnetic field value in Gauss

Return type

scalar

Note

Bruker still uses the non-SI unit “Gauss” for magnetic field values. However, conversion is rather simple, as 10 G = 1 mT.

set_field(field)

Set magnetic field to given value

Parameters

field (scalar) – value (in Gauss) the actual magnetic field shall be set to

Note

Bruker still uses the non-SI unit “Gauss” for magnetic field values. However, conversion is rather simple, as 10 G = 1 mT.

Note

“FieldPosition” can only be set within the current sweep width, but setting “CenterField” does not necessarily set the current field position to this value. Hence, both, “CenterField” and F”ieldPosition” are set in exactly this order to set the actual field to the position requested.

class eprcontrol.components.BrukerXenonMicrowaveBridge

Bases: eprcontrol.components.MicrowaveBridge

Driver for a Bruker microwave bridge via Xenon software

All components of a Bruker EPR spectrometer connected to Xenon and controlled via the Xenon software can generally be controlled as well using the XML RPC interface to Xenon.

Note

The methods currently implemented in this class are only a rather small subset of the functionality Xenon provides. Therefore, in the future, this might be extended, allowing better (remote) control of the microwave bridge.

get_frequency()

Obtain current microwave frequency value

Returns

frequency – current microwave frequency value

Return type

scalar

get_attenuation()

Obtain current attenuation value

Returns

attenuation – current attenuation value in dB

Return type

scalar

Note

Attenuation values are per se useless if one does not know the maximum power output of a microwave bridge. Therefore, use with caution.

set_attenuation(attenuation)

Set attenuation to given value

Parameters

attenuation (scalar) – value in dB the attenuation should be set to

Note

Attenuation values are per se useless if one does not know the maximum power output of a microwave bridge. Therefore, use with caution.

get_power()

Obtain current microwave power value

Returns

power – current microwave power value in mW

Return type

scalar

get_qvalue()

Obtain current Q value

Returns

qvalue – current Q value

Return type

scalar

class eprcontrol.components.Component

Bases: handle

Base class for a component.

Each setup, i.e. object of class eprcontrol.setups.Setup, consists of a list of components. A component, in turn, has a connection, i.e. an object of class eprcontrol.connections.Connection.

type

Type of component, such as “digitizer”

Shall be set in each of the general classes derived from eprcontrol.components.Component.

Type

string

model

details of the model of the actual component

Type

string

manufacturer

name of the manufacturer of the actual component

Type

string

connection

setup used to perform the experiment

Type

eprcontrol.connections.Connection

connected

Indicates whether the component is connected, i.e., the connection is active

Type

boolean

apply_settings()

Set parameters to hardware

The settings stored in the properties of the eprcontrol.components.Component object need eventually be transferred to the hardware, at least in some cases. This is what this method is used for.

set_properties(parameters)

Assign values to properties

If the “parameters” structure contains a field that corresponds to a property of the class, set this property to the corresponding value of the struct.

In case of the property being an object, this object will be tested for having a “set_properties” method itself and in this case, this method will be called with the respective value of the struct (that may in those cases be a struct itself). Thus, cascaded setting of properties is possible.

Parameters

parameters (struct) – Structure with fields (keys) corresponding to the properties of the class. Only those properties will be set.

Note

This functionality will eventually perhaps allow to create derived classes for concrete types of components by simply defining their properties in a configuration file.

connect()

Connect the component

Check whether the connection is active, and if not, call a protected method connect_component() that does the connection, usually calling the connect() method on the connection.

Note

All connection details need to go into the protected method connect_component(), as the connect() method is sealed.

disconnect()

Disconnect the component

Check whether the connection is active, and if so, call a protected method disconnect_component() that does the disconnection, usually calling the disconnect() method on the connection.

Note

All disconnection details need to go into the protected method disconnect_component(), as the disconnect() method is sealed.

class eprcontrol.components.Digitizer

Bases: eprcontrol.components.Component

Base class for digitizers

Digitizers are used to convert analog signals to digital representations. Typical representatives are oscilloscopes or dedicated A/D cards.

accumulations

Number of accumulations the signal is averaged for

Type

scalar

short_repetition_rate

Number of repetitions of the signal per second

Usually, this is fixed by the hardware triggering the data recording, such as a laser in a TREPR experiment.

Type

scalar

channels

list of objects of class eprcontrol.components.DigitizerChannel each containing information on one of the channels of the digitizer.

Usually, at least two channels are required, one for signal recording and one for triggering.

Type

cell array

apply_settings()

Send settings stored in object properties to hardware

As a digitizer is a piece of hardware, storing the settings in the object properties is not sufficient, as they need to be communicated to the hardware itself.

Hence, after each changing of settings, this method needs to be called to ensure the hardware to be in a consistent and known state.

get_data()

Obtain data from the digitizer

Returns

data – Actual digitized data, usually a vector containing floats

Return type

vector

This is usually the one method used within a loop controlling a multi-dimensional experiment such as a TREPR experiment.

class eprcontrol.components.DigitizerChannel(number)

Bases: handle

General information on digitizer channels

Objects of this class are used to provide and store information on the different hardware channels of digitizers represented by objects of class eprcontrol.components.Digitizer.

Optionally, you can instantiate an object of the class providing a channel number that gets saved in the number property. For details, see below.

number

number of the physical channel on the digitizer

Usually, channels are enumerated starting with 0.

Type

scalar

input_range

Maximum input voltage accepted by the input channel.

Usually, the value means that the full range is twice the value, but with opposite sign. E.g., a value of 200 means +/- 200 mV.

The input range can only be set to quite discrete values. Hence, setting will be rejected if the value is not within the list of valid values.

Type

scalar

termination

impedance of the channel

Usually, there are only two possible values: 50 Ohm and 1 MOhm

The actually possible values are stored as a map in the protected property termination_values.

Type

scalar

coupling

mode of coupling

Usually, there are only two modes: AC and DC coupling.

The actually possible values are stored as a map in the protected property coupling_values.

Type

scalar

show_settings()

Display current settings in a human-readable way

Many settings (e.g., coupling and termination) are encoded in scalar values that are not very readable. This method provides a human-readable overview of the current settings.

set_properties(parameters)

Assign values to properties

If the “parameters” structure contains a field that corresponds to a property of the class, set this property to the corresponding value of the struct.

Parameters

parameters (struct) – Structure with fields (keys) corresponding to the properties of the class. Only those properties will be set.

static get_key_from_map(value, map)

Reverse lookup a map

Usually, values are obtained from maps using the key. However, sometimes, one wants to get the key corresponding to a value.

Parameters

value (scalar) – Value the corresponding key should be found

Returns

key – key corresponding to the value given

Return type

string

class eprcontrol.components.FieldController

Bases: eprcontrol.components.Component

Base class for magnetic field controllers.

get_field()

Get the current value of the magnetic field

Returns

field – Value of the field as returned by the field controller, i.e., the actual hardware.

Beware that for historic reasons, some field controllers will return values in the non-SI unit Gauss, not in the SI unit tesla (or, for EPR reasons, the more familiar mT).

Return type

scalar

set_field(field)

Set the actual value of the magnetic field

Parameters

field (scalar) –

Value of the magnetic field that should be set by the field controller, i.e., the actual hardware.

Beware that for historic reasons, some field controllers will accept values only in the non-SI unit Gauss, not in the SI unit tesla (or, for EPR reasons, the more familiar mT).

class eprcontrol.components.GwuOpo

Bases: eprcontrol.components.Opo

Driver for a GWU OPO

Obtaining the current wavelength helps with automating metadata records and allows for consistency.

Setting the wavelength allows for more advanced experiments up to 3D TREPR experiments recording multiple 2D TREPR spectra consecutively for different wavelengths.

get_wavelength()

Obtain current wavelength value

Returns

wavelength – current wavelength value in nm

Return type

scalar

set_wavelength(wavelength)

Set wavelength to given value

Parameters

wavelength (scalar) – value in nm the wavelength should be set to

Note

Note that currently, there is no control whatsoever that the value for the wavelength is sensible or that it is set correctly. Use with caution.

class eprcontrol.components.LeCroyHDO9204

Bases: eprcontrol.components.Digitizer

Driver for the Teledyne LeCroy HDO9204 oscilloscope

This class currently relies on a not so usefil driver provided with the toolbox and on the MATLAB® Instrument Control Toolbox™. For details, see the eprcontrol.connections.LecroyTcpipConnection class.

get_data()

Obtain data from scope

Returns

data – data from the channel set in the channel property

Return type

numeric

get_xaxis()

Obtain time axis from A/D card

The time axis (x axis) depends on the setting on the scope.

Returns

xaxis – values of the time axis (x axis) in seconds

Return type

vector

class eprcontrol.components.MicrowaveBridge

Bases: eprcontrol.components.Component

Base class for microwave bridges.

get_frequency()

Obtain current frequency (usually in GHz)

Returns

frequency – Microwave frequency value (usually in GHz)

Depending on the kind of frequency counter, different accuracies are obtained. As frequencies can be detected with quite high accurracy, +/- 100 kHz for a base frequency of 10 GHz are rather common.

Return type

scalar

get_attenuation()

Obtain current attenuation (in dB)

Microwaves need usually to be attenuated. The attenuation is given in dB values.

Returns

attenuation – microwave attenuation in dB

Return type

scalar

Note

Without knowing the unattenuated nominal power output of the microwave bridge, attenuation values are not comparable and rather useless.

The long-term standard of 200 mW nominal maximum power output is no longer true for some modern Bruker microwave bridges.

set_attenuation(attenuation)

Set actual attenuation (in dB)

Parameters

attenuation (scalar) – microwave attenuation in dB

Note

Without knowing the unattenuated nominal power output of the microwave bridge, attenuation values are not comparable and rather useless.

The long-term standard of 200 mW nominal maximum power output is no longer true for some modern Bruker microwave bridges.

get_power()

Obtain current microave power (usually in mW)

Returns

power – microwave power (usually in mW)

Return type

scalar

Quite in contrast to the attenuation values (see above), this value is an absolute number and can be used for comparison between measurements and setups.

Note, however, that the nominal output of a microwave bridge is quite different from the actual microwave power at the sample position and depends on a number of parameters both connected to the setup used and the conditions of the experiment. Obtaining actual microwave power values at the sample position is rarely done and rather involved.

get_qvalue()

Obtain quality value (connected to bandwidth)

Returns

qvalue – current quality value as returned by the bridge

Return type

scalar

The quality value (short: Q value) is directly connected to the actual bandwidth of the setup in its current state and therefore quite important for both, microwave conversion efficiency (and hence signal-to-noise ratio) as well as time resolution.

Note

At least for Bruker setups, the Q value is only automatically determined when you change from tune to operate mode at 33 dB attenuation.

class eprcontrol.components.Opo

Bases: eprcontrol.components.Component

Base class for optical parametric oscillators (OPOs)

Often, though not always, OPOs are used within a TREPR setup to have great control over the excitation wavelength, as OPOs allow to tune the wavelength of a pulsed laser over a rather large range, usually within the whole of the visible spectrum.

get_wavelength()

Obtain current wavelength

Returns

wavelength – actual wavelength (usually in nm)

Return type

scalar

set_wavelength(wavelength)

Set actual wavelength

Parameters

wavelength (scalar) – wavelength the OPO should be set to (usually in nm)

class eprcontrol.components.SpcmM4i4421x8

Bases: eprcontrol.components.Digitizer

Driver for the Spectrum Instrumentation M4i.4421-x8 A/D card

This class relies on the MATLAB® drivers for Spectrum Instrumentation hardware to be installed. You should have received a copy of this driver with your hardware.

number_of_points

How many points per time trace should be recorded

Needs to be divisible by 16.

A typical value would be 2^14, amounting to a time trace length of roughly 65 us.

Type

scalar

pretrigger

How many points should be before the trigger

posttrigger = number_of_points - pretrigger

Needs to be divisible by 16.

A typical value would be 2^10 in case of 2^14 total points.

Type

scalar

timeout

time to wait before interrupting acquisition

Will usually be set automatically depending on the shot repetition rate and the number of accumulations

Type

scalar

trigger

settings for the triggering of the A/D card

A complete struct may look like the following:

trigger = struct(...
    'channel_number', 2, ...
    'level', 1500, ...
    'mode', 'pos' ...
    );

Channel numbering usually starts with 0, the level is usually given in mV, and the mode can be one of “pos”, “neg”, or “both”.

Type

struct

channels

list of eprcontrol.components.DigitizerChannel objects.

For each channel, the following properties can be set:

  • number: 0..3

  • input_range: 200, 500, 1000, 2000, 5000, 10000 (mV)

  • termination: “50”, “1M” (Ohm)

  • coupling: “AC”, “DC”

Type

cell array

debug

whether to write some debug output to the standard output

Default: false

Type

boolean

Note

Currently, only the data from the first channel (channel 0) are returned using the method get_data(). This may be changed in a future version, to make the data from all four channels available.

apply_settings()

Set parameters to hardware

The timeout and recording mode are set, as are channels and trigger.

get_data()

Obtain data from A/D card

Returns

data – currently only data from the first channel

Return type

numeric

get_xaxis()

Obtain time axis from A/D card

The time axis (x axis) depends on the number of points and sampling rate set. Currently, the A/D card is set to maximum sampling rate, meaning 4 ns steps between data points.

Returns

xaxis – values of the time axis (x axis) in seconds

Return type

vector