significantdigits package - v0.3.0

Compute the number of significant digits based on the paper Confidence Intervals for Stochastic Arithmetic. This package is also inspired by the Jupyter Notebook included with the publication.

Getting started

This synthetic example illustrates how to compute significant digits of a results sample with a given known reference:

>>> import significantdigits as sd
>>> import numpy as np
>>> from numpy.random import uniform as U
>>> np.random.seed(0)
>>> eps = 2**-52
>>> # simulates results with epsilon differences
>>> X = [1+U(-1,1)*eps for _ in range(10)]
>>> sd.significant_digits(X, reference=1)
>>> 51.02329058847853

or with the CLI interface assuming X is in test.txt:

> significantdigits --metric significant -i "$(cat test.txt)" --input-format stdin --reference 1
> (51.02329058847853,)

If the reference is unknown, one can use the sample average:

...
>>> sd.significant_digits(X, reference=np.mean(X))
>>> 51.02329058847853

Installation

python3 -m pip install -U significantdigits

or if you want the latest version of the code, you can install it from the repository directly

python3 -m pip install -U git+https://github.com/verificarlo/significantdigits.git
# or if you don't have 'git' installed
python3 -m pip install -U https://github.com/verificarlo/significantdigits/zipball/master

Advanced Usage

Inputs types

Functions accept the following types of inputs:

    InputType: ArrayLike

Those types are accessible with the numpy.typing.ArrayLike type.

Z computation

Metrics are computed using Z, the distance between the samples and the reference. There are four possible cases depending on the distance and the nature of the reference that are summarized in this table:

	constant reference (x)	random variable reference (Y)
Absolute precision	Z = X - x	Z = X - Y
Relative precision	Z = X/x - 1	Z = X/Y - 1

_compute_z(array: InternalArrayType, 
           reference: InternalArrayType | None, 
           error: Error | str, 
           axis: int, 
           shuffle_samples: bool = False) -> InternalArrayType
    Compute Z, the distance between the random variable and the reference

    Compute Z, the distance between the random variable and the reference
    with three cases depending on the dimensions of array and reference:

    X = array
    Y = reference
    Three cases:
        - Y is none
            The case when X = Y
            We split X in two and set one group to X and the other to Y
        - X.ndim == Y.ndim
            X and Y have the same dimension
            It it the case when Y is a random variable
        - X.ndim - 1 == Y.ndim or Y.ndim == 0
            Y is a scalar value

    Parameters
    ----------
    array : InternalArrayType
        The random variable
    reference : Optional[InternalArrayType]
        The reference to compare against
    error : Error | str
        The error function to compute Z
    axis : int, default=0
        The axis or axes along which compute Z
    shuflle_samples : bool, default=False
        If True, shuffles the groups when the reference is None

    Returns
    -------
    array : InternalArrayType
        The result of Z following the error method choose

Methods

Two methods exist for computing both significant and contributing digits depending on whether the sample follows a Centered Normal distribution or not. You can pass the method to the function by using the Method enum provided by the package. The functions also accept the name as a string "cnh" for Method.CNH and "general" for Method.General.

class Method(AutoName):
    """
    CNH: Centered Normality Hypothesis
         X follows a Gaussian law centered around the reference or
         Z follows a Gaussian law centered around 0
    General: No assumption about the distribution of X or Z
    """
    CNH = auto()
    General = auto()