qudi.util.units

Functions

`create_formatted_output`(param_dict[, ...])	Display a parameter set nicely in SI units.
`get_relevant_digit`(entry)	By using log10, abs and int operations, the proper relevant digit is obtained.
`get_si_norm`(entry)	A rather different way to display the value in SI notation.
`get_unit_prefix_dict`()	Return the dictionary, which assigns the prefix of a unit to its proper order of magnitude.
`round_value_to_error`(value, error)	The scientifically correct way of rounding a value according to an error.

Classes

ScaledFloat([x])

Format code 'r' for scaled output.

class qudi.util.units.ScaledFloat(x=0, /)[source]

Bases: builtins.float

Format code ‘r’ for scaled output.

__format__(fmt)[source]

Fromats the string using format fmt.

r for scaled output.

Parameters:

fmtstr: format string

property scale: Returns the scale. (No prefix if 0)

property scale_val: Returns the scale value which can be used to devide the actual value

qudi.util.units.create_formatted_output(param_dict, num_sig_digits=5)[source]

Display a parameter set nicely in SI units.

Parameters:

param_dictdict: Dictionary with entries being dictionaries with two needed keywords ‘value’ and ‘unit’ and one optional keyword ‘error’. Add the proper items to the specified keywords. Note that if no error is specified, no proper rounding (and therefore displaying) can be guaranteed.
num_sig_digitsint, optional: The number of significant digits will be taken if the rounding procedure was not successful at all. Default is 5.

Returns:

str: A nicely formatted string.

Notes

The absolute tolerance to a zero is set to 1e-18.

Examples

Example of a param dict:

param_dict = {‘Rabi frequency’: {‘value’: 123.43, ‘error’: 0.321, ‘unit’: ‘Hz’},: ‘ODMR contrast’: {‘value’: 2.563423, ‘error’: 0.523, ‘unit’: ‘%’}, ‘Fidelity’: {‘value’: 0.783, ‘error’: 0.2222, ‘unit’: ‘’}}

If you want to access the value of the Fidelity, then you can do that via:

>>> param_dict['Fidelity']['value']

or on the error of the ODMR contrast:

>>> param_dict['ODMR contrast']['error']

qudi.util.units.get_relevant_digit(entry)[source]

By using log10, abs and int operations, the proper relevant digit is obtained.

Parameters:

entryfloat

Returns:

int: the leading relevant exponent

qudi.util.units.get_si_norm(entry)[source]

A rather different way to display the value in SI notation.

Parameters:

entryfloat: the float number from which normalization factor should be obtained.

Returns:

tuple

A tuple containing:

norm_valfloat: The value in a normalized representation.
normalizationfloat: The factor by which to divide the number.

qudi.util.units.get_unit_prefix_dict()[source]

Return the dictionary, which assigns the prefix of a unit to its proper order of magnitude.

Parameters:

None

Returns:

dict: keys are string prefix and values are magnitude values.

qudi.util.units.round_value_to_error(value, error)[source]

The scientifically correct way of rounding a value according to an error.

Parameters:

valuefloat or int: the measurement value
errorfloat or int: the error for that measurement value

Returns:

tuple

A tuple containing the following elements:

float: The rounded value according to the error.
float: The rounded error.
int: The digit to which the rounding procedure was performed. A positive number indicates the position of the digit right from the comma, zero means the first digit left from the comma, and negative numbers are the digits left from the comma. This follows the convention used in the native round method and numpy.round.

Notes

The input type of value or error will not be changed. If float is the input, float will be the output; the same applies to integer.
This method does not return strings, as each display method might want to display the rounded values in a different way (in exponential representation, in a different magnitude, etc.).
This function can handle an invalid error, i.e., if the error is zero, NaN, or infinite. The absolute tolerance to detect a number as zero is set to 1e-18.

Procedure explanation: The scientific way of displaying a measurement result in the presence of an error is applied here. It follows this procedure: Take the first leading non-zero number in the error value and check whether the number is a digit within 3 to 9. If so, the rounding value is the specified digit. Otherwise, if the first leading digit is 1 or 2, then the next right digit is the rounding value. The error is rounded according to that digit, and the same applies to the value.

Examples

Example 1:

>>> x_meas = 2.05650234
>>> delta_x = 0.0634
>>> result = some_function(x_meas, delta_x)
>>> print(result)
(2.06, 0.06, 2)

Example 2:

>>> x_meas = 0.34545
>>> delta_x = 0.19145
>>> result = some_function(x_meas, delta_x)
>>> print(result)
(0.35, 0.19, 2)

Example 3:

>>> x_meas = 239579.23
>>> delta_x = 1289.234
>>> result = some_function(x_meas, delta_x)
>>> print(result)
(239600.0, 1300.0, -2)

Example 4:

>>> x_meas = 961453
>>> delta_x = 3789
>>> result = some_function(x_meas, delta_x)
>>> print(result)
(961000, 4000, -3)