Skip to content

numerics

Contains the tolerance checks that are required within numerics calculations with the FLOAT_TOLERANCE attribute alongside the ability to set your own global tolerance.

Tolerance Control

FLOAT_TOLERANCE Global attribute of tolerance for toolbox

equal_within_tolerance Function to check equality of two real numbers up to a tolerance

set_tolerance Function used to set global tolerance

FLOAT_TOLERANCE = 1e-09 module-attribute

The default tolerance to use when testing for equality of real numbers.

equal_within_tolerance(x, y, rel_tol=None, abs_tol=None)

Test equality of two real numbers or sequences of real numbers up to a tolerance.

This function compares either two real numbers or two sequences of real numbers element-wise, determining if they are close within specified tolerances.

Parameters:

  • x (Union[Real, Sequence[Real]]) –

    Real numbers or sequences of real numbers to test equality of.

  • y (Union[Real, Sequence[Real]]) –

    Real numbers or sequences of real numbers to test equality of.

  • rel_tol (Real, default: None ) –

    The maximum allowed relative difference. Dynamically passed at runtime to allow for updating of FLOAT_TOLERANCE. Defaults to FLOAT_TOLERANCE (1e-9) if no change.

  • abs_tol (Real, default: None ) –

    The minimum permitted absolute difference. Dynamically passed at runtime to allow for updating of FLOAT_TOLERANCE. Defaults to FLOAT_TOLERANCE (1e-9) if no change.

Returns:

  • bool –

    Whether the two numbers or sequences of numbers are equal up to the relative and absolute tolerances.

Source code in exauq/core/numerics.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def equal_within_tolerance(
    x: Union[Real, Sequence[Real]],
    y: Union[Real, Sequence[Real]],
    rel_tol: Real = None,
    abs_tol: Real = None,
) -> bool:
    """Test equality of two real numbers or sequences of real numbers up to a tolerance.

    This function compares either two real numbers or two sequences of real numbers
    element-wise, determining if they are close within specified tolerances.

    Parameters
    ----------
    x, y :
        Real numbers or sequences of real numbers to test equality of.
    rel_tol :
        The maximum allowed relative difference. Dynamically passed at runtime to allow
        for updating of FLOAT_TOLERANCE. Defaults to FLOAT_TOLERANCE (1e-9) if no change.
    abs_tol :
        The minimum permitted absolute difference. Dynamically passed at runtime to allow
        for updating of FLOAT_TOLERANCE. Defaults to FLOAT_TOLERANCE (1e-9) if no change.

    Returns
    -------
    bool
        Whether the two numbers or sequences of numbers are equal up to the relative and absolute tolerances.
    """
    # Use FLOAT_TOLERANCE if rel_tol and abs_tol aren't provided
    rel_tol = rel_tol or FLOAT_TOLERANCE
    abs_tol = abs_tol or FLOAT_TOLERANCE

    if _is_seq(x) and _is_seq(y):
        return len(x) == len(y) and all(
            equal_within_tolerance(a, b, rel_tol=rel_tol, abs_tol=abs_tol)
            for a, b in zip(x, y)
        )
    elif isinstance(x, Real) and isinstance(y, Real):
        return math.isclose(x, y, rel_tol=rel_tol, abs_tol=abs_tol)
    else:
        raise TypeError(
            f"Both 'arguments' must be of type {Real}, type sequences or type Numpy arrays, "
            "but one or more arguments were of an unexpected type."
        )

set_tolerance(tol)

Allows the updating of the global FLOAT_TOLERANCE from default (1e-9) to the tol value passed.

Parameters:

  • tol (float) –

    The new tolerance you wish to set the global FLOAT_TOLERANCE to.

Source code in exauq/core/numerics.py 
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
def set_tolerance(tol: float):
    """
    Allows the updating of the global FLOAT_TOLERANCE from default (1e-9) to the tol value
    passed.

    Parameters
    ----------
    tol :
        The new tolerance you wish to set the global FLOAT_TOLERANCE to.
    """

    if not isinstance(tol, float):
        raise TypeError(
            f"Expected 'tol' to be of type float, but received {type(tol)} instead."
        )

    if tol < 0:
        raise ValueError(f"Expected 'tol' to be non-negative but received {tol}.")

    global FLOAT_TOLERANCE
    FLOAT_TOLERANCE = tol