7.2 EPR Modulation Functions

The following functions are for a pseudo-device that can be used to store informations about EPR modulation calibrations, the modulation field amplitude to modulation voltage ratios and modulation phase settings for different moduation frequencies. The module for this pseudo-device can be loaded by specifying

epr_mod

in the DEVICES section. The information about properties of calibrations get stored in a file (unless set differently in `/usr/local/lib/fsc2/epr_mod.state'). Each calibration in this file is characterised by its name, a (non-empty) string and applies to a certain hardware configuration (EPR resonator with modulation coils, lock-in amplifier and and, possibly, modulation frequency generator and amplifier).

For the modulation field to voltage ratio inter- or even extrapolation can be done if the requested frequency doesn't match one of the ones known for a calibration (interpolation for frequencies within the range of known frequencies, extrapolation for frequencies that are outside of this range). This requires that inter- or extrapolation is allowed for a calibration, that there are at least three known values for the field/voltage ratio and that a linear-square fit (assuming that the modulation field is proportional to the inverse of the frequency, with an voltage offset being taken into consideration) has a correlation coefficient (r^2) that's at least as large as set in the configuration file for the module.

List of EPR modulation functions:

`epr_modulation_name()'

`epr_modulation_name()'

`epr_modulation_ratio()'

`epr_modulation_phase()'

`epr_modulation_has_phase()'

`epr_modulation_calibration_interpolate()'

`epr_modulation_calibration_can_interpolate()'

`epr_modulation_calibration_extrapolate()'

`epr_modulation_calibration_can_extrapolate()'

`epr_modulation_add_calibration()'

`epr_modulation_delete_calibration()'

`epr_modulation_calibration_count()'

`epr_modulation_calibration_name()'

`epr_modulation_calibration_frequencies()'

`epr_modulation_calibration_amplitude_limit()'

`epr_modulation_calibration_check_amplitude()'

`epr_modulation_store()'

Descriptions of EPR modulation functions:

`epr_modulation_name()'

Returns a "device name" for the module that can be used in messages.

`epr_modulation_ratio()'

This function is for quering or setting the modulation field to voltage (or whatever the unit in the case under consideration is) ratio for a certain frequency and calibration. The function requires at least two arguments, first the calibration name (a string) and a positive, non-zero frequency. If the there is no further argument the function returns the ratio of the modulation field to the modulation frequency (in G/V or the ratio of the modulation field in Gauss to the unit used by the device for specifying modulation amplitudes) if possible.

The following algorithm is used to determine the field/voltage ratio: If the frequency is identical to one known for the calibration the corresponding ratio is returned. If the frequency does not match a known frequency exactly but is within a confidence interval around a known frequency (the interval is set via the configuration file) and interpolation is not allowed or possible the ratio for the known frequency is returned. If the requested frequency isn't within the confidence interval but is within the range of known values and interpolation is allowed and possible, an interpolated value gets returned. If the frequency is outside the range of known frequencies and extrapolation is allowed and possible the extrapolated for the ratio is returned. Otherwise the script is stopped.

If there's another argument this is taken to be a new ratio to be set. If the frequency given as the second argument is within the confidence interval of an already known frequency the argument replaces the ratio value for this frequency, otherwise a new entry for the frequency is created. Please note that setting the ratio for a new frequency only is in effect until the EDL script ends unless the function epr_modulation_store() is called afterwards to make this setting permanent.

`epr_modulation_phase()'

This function is for quering or setting the modulation phase for a certain calibration and frequency. The function must be called with at least two arguments, the name of the calibration (as a string) and a frequency that has already been assigned a field/voltage ratio.

If no further argument is given the function returns the modulation phase for the calibration and frequency if possible. This requires that the frequency matches one of the known frequencies within the confidence interval (as set in the configuration file for the module) and that a modulattion phase is known for this calibration and frequency. Otherwise the script is aborted.

If there's no other argument this is taken to be a modulation phase. This requires that a ration already has been set for the frequency given as the second argument (or for a frequency within the confidence interval). Please note that setting the phase for a new frequency only is in effect until the EDL script ends unless the function epr_modulation_store() is called afterwards to make this setting permanent.

`epr_modulation_has_phase()'

The function allows to query if a modulation phase for a certain calibration and (known) frequency is known. It takes two arguments, the name of the calibration (as a string) and a frequency. If the frequency is within the confidence interval of one of the known modulation frequencies and a phase is known for this frequency the function returns 1, otherwise 0.

`epr_modulation_calibration_interpolate()'

The function allows to either query or set if interpolation (for modulation field to voltage ratios) is allowed for a certain calibration. The function expects at least one argument, the name of the calibration (as a string). If there's no further argument the function returns 1 if interpolation is allowed for the calibration, otherwise 0.

If there's another argument it must be of boolean type, i.e. either "ON" or 1 to permit interpolation or "OFF" or 0 to disable interpolation. Please note that allowing interpolation does not guaqrantee that interpolation can be done since this also requires that there are at least 3 known frequencies and that the correlation coefficient of a least square fit is at least as large as set in the configuration file. Whether interpolation is possible for a certain calibration can be determined by calling the function epr_modulation_calibration_can_interpolate(). Please note also that allowing or disabling intrepolation for a calibration only is in effect until the EDL script ends unless the function epr_modulation_store() is called afterwards to make this setting permanent.

`epr_modulation_calibration_can_interpolate()'

This function allows to determine if interpolation is possible for a calibration. The function requires a single rgument, the name of the calibration (as a string). Itt returns 1 if interpolation can be done, otherwise 0. Interpolation is possible if it's allowed for the calibration, ratios for at least 3 frequencies are known and the correlation coefficient for a least square fit is at least as large as set in the configuration file for the device.

`epr_modulation_calibration_extrapolate()'

The function allows to query or set if extrapolation (for modulation field to voltage ratios) is allowed for a certain calibration. The function expects at least one argument, the name of the calibration (as a string). If there's no further argument the function returns 1 if extrapolation is allowed for the calibration, otherwise 0.

If there's another argument it must be of boolean type, i.e. either "ON" or 1 to permit extrapolation or "OFF" or 0 to disable extrapolation. Please note that allowing extrapolation does not gurantee that extrapolation can be done since this also requires that there are at least 3 known frequencies and that the correlation coefficient of the least square fit is at least as large as set in the configuration file. Whether extrapolation is possible for a certain calibration can be determined by calling the function epr_modulation_calibration_can_extrapolate(). Please note also that allowing or disabling intrepolation for a calibration only is in effect until the EDL script ends unless the function epr_modulation_store() is called afterwards to make this setting permanent.

`epr_modulation_calibration_can_extrapolate()'

This function allows to determine if extrapolation is possible for a calibration. The function requires a single rgument, the name of the calibration (as a string). Itt returns 1 if extrapolation can be done, otherwise 0. Extrapolation is possible if it's allowed for the calibration, ratios for at least 3 frequencies are known and the correlation coefficient for the least square fit is at least as large as set in the configuration file for the device.

`epr_modulation_add_calibration()'

This function allows to create an new calibration (i.e. a data structure that represents informations about a calibration). IIt expects a single arguemnt, the name of the new calibration (as a string). Informations for this calibration can be set by the functions listed above. Please note that creating a new calibration and setting properties only is in effect until the EDL script ends unless the function epr_modulation_store() is called afterwards to make this setting permanent.

`epr_modulation_delete_calibration()'

This function allows to delete a calibration and all its properties. The function tales a single argument, the name of the calibration to delete (as a string). Please note that deleting a calibration only is in effect until the EDL script ends unless the function epr_modulation_store() is called afterwards to make this setting permanent.

`epr_modulation_calibration_count()'

This function takes no arguments and returns the number of known calibrations.

`epr_modulation_calibration_name()'

This function allows to find the name of a calibration by its index in the list of calibrations (a number between 1 and the number of known calibrations). The function takes a single argument, the calibration's index (an invalid index will result in the experiment being aborted). The function can be used in conjunction with the epr_modulation_calibration_count() to obtain the names of all known calibrations.

`epr_modulation_calibration_frequencies()'

This function returns an array of all frequencies known for a certain calibration (in ascending order). It takes a single argument, the name of a calibration (as a string).

`epr_modulation_calibration_amplitude_limit()'

This function allows to store and retrieve a upper limit for the modulation amplitude to be used with a certain calibration (resonator). It takes at least one argument, the name of a calibration. If no further argument is given it returns the modulation amplitude limit in Gauss for that calibration (0.0 if none is set). If there's a second argument it is taken to be a new limit to be set.

`epr_modulation_calibration_check_amplitude()'

This function allows to check if a modulation amplitude is allowed (i.e. not to high) for a certain calibration (resonator). It expects two arguments, first the name of the calibration and then the modulation amplitude (in Gauss) to be checked. The function returns 1 if the modulation amplitude is within the limit set via epr_modulation_calibration_amplitude_limit(). If there isn't a limit set for the calibration it returns 0 and prints out a warning. If the modulation amplitude is above the limit set for the calibration an error message is printed out and the experiment is aborted.

`epr_modulation_store()'

This function takes no arguments and must be called to make changes to the settings for all calibrations permanent - without calling this function changes are discarded once the running EDL script ends.

This document was generated by Jens Thoms Toerring on September 6, 2017 using texi2html 1.82.