qudi.util.units.round_value_to_error

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)