uncertaintylib 1.1.2

A library containing functions used for estimating uncertainties

uncertaintylib is a Python library for estimating and propagating uncertainties in engineering and scientific calculations. The library is developed by Equinor K-lab Technology Test Center. It is designed to work with any Python function whose inputs and outputs are flat dictionaries.

Key Principles

• Function-agnostic: You can pass any Python function to the library, as long as its inputs and outputs are flat dictionaries (no nested dicts or lists).
• Standard-inspired: Attempts to follow uncertainty propagation principles outlined in JCGM 100:2008 (Guide to the Expression of Uncertainty in Measurement).

Installation

Install from PyPI:

pip install uncertaintylib

Usage

The main interface is through functions in uncertaintylib.uncertainty_functions. You provide:

• A Python function (inputs: flat dict, outputs: flat dict)
• A dictionary containing 'mean' and 'standard_uncertainty' for each variable. These are provided as sub dictionaries.
• The standard uncertainty can also be given in relative terms (%), using the 'standard_uncertainty_percent' key
• If both 'standard_uncertainty' and 'standard_uncertainty_percent', the largest of the two will be used. This can be useful for variables where for example noise dominates the uncertainty in the lower region (such as zero stability of a coriolis massflow meter)
• 'min' and 'max' are only used in Monte Carlo calculations, to address the issue of non-physical distributions (for example distribution of mole-% of a component going below 0)
• 'distribution' is used mainly by Monte Carlo, but also in cases where some of the inputs are settings (for example 0 or 1), where you don't want to perturb or calculate sensitivity coefficients for that specific input variable. In this case 'distribution' can be set to 'none', which will ignore that parameter.

Example usage (standard uncertainty calculation):

from uncertaintylib import uncertainty_functions

inputs = {
    'mean': {'Q': 370, 'rho': 54},
    'standard_uncertainty': {'Q': 1, 'rho': 0.03},
    'standard_uncertainty_percent': {'Q': 0.25, 'rho': 0.1},
    'distribution': {'Q': 'normal', 'rho': 'normal'},
    'min': {'Q': 0, 'rho': 0},
    'max': {'Q': None, 'rho': None}
}

def calculate_massflow(inputs):
    outputs = {}
    
    outputs['MassFlow'] = inputs['Q']*inputs['rho']

    return outputs

results = uncertainty_functions.calculate_uncertainty(
    indata=inputs, 
    function=calculate_massflow
    )

print(results)

Another example, Example 06, demonstrates uncertainty calculations for a natural gas metering station, demonstrating usage of many of the functions available in this library.

Uncertainty Models

uncertaintylib.uncertainty_models provides specialized uncertainty estimation methods for specific measurement types:

• Gas Composition Uncertainty (gas_composition): Three methods for estimating GC analysis uncertainties:
  • ASTM D1945 (reproducibility method for pipeline quality gas)
  • NORSOK I-106 (molar mass ratio method)
  • Hagenvik 2024 (empirical power law from parallel gas samples)

See the uncertainty_models documentation for detailed guidance on method selection and Example 09 for practical comparison.

Plotting Functionalities

uncertaintylib includes plotting utilities based on matplotlib, available in uncertaintylib.plot_functions. These functions help visualize uncertainty propagation and contributions:

• Monte Carlo Distribution Plots: Visualize the distribution of output properties from Monte Carlo simulations, including summary tables of mean and uncertainty.
• Uncertainty Contribution Plots: Show the percentage contribution of each input variable to the total expanded uncertainty of an output property.

All plots are generated using matplotlib and can be customized or saved using standard matplotlib methods. See the API docstrings in plot_functions.py for details.

Documentation & Examples

• See the examples/ folder for practical scripts demonstrating usage.
• API documentation is available in the source code docstrings.

Running Tests

Tests are located in the tests/ folder and are run with pytest. Two additional packages are required:

pip install pytest pvtlib
pytest tests

License

MIT License. See LICENSE for details.