Skip to main content
uncertaintylib logo

PyPI version Python versions Tests Documentation License: MIT

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

To get a specific release, name its version, for example pip install uncertaintylib==1.1.2. The installed version is reported by uncertaintylib.__version__. Versions follow semantic versioning and are taken from the git release tags; see Releases and versions.

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

Running Tests

Tests are located in the tests/ folder and are run with pytest. The test extra installs the additional packages they need (pytest and pvtlib):

pip install -e .[test]
pytest

License

MIT License. See LICENSE for details.

Metadata

Release files for uncertaintylib 1.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for uncertaintylib 1.2.0
File Size Uploaded Provenance Actions
uncertaintylib-1.2.0.tar.gz 1.2 MB With provenance Details for uncertaintylib-1.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for uncertaintylib 1.2.0
File Interpreter ABI Platform Actions
uncertaintylib-1.2.0-py3-none-any.whl Python 3 none any Details for uncertaintylib-1.2.0-py3-none-any.whl

Total release size: 1.3 MB

Release files / uncertaintylib-1.2.0.tar.gz

Download URL uncertaintylib-1.2.0.tar.gz
Size 1.2 MB
Tags Source
SHA-256 checksum
How to use checksums
75cd23199f893179a91c4fd0bdc5cc9abe6018bc8000eca8ed7e86253d05c923
BLAKE2b-256 checksum
How to use checksums
7304568b42628b782a02c0b3767211128a2d88c9ced589d4c14e6637350d0dcc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / uncertaintylib-1.2.0-py3-none-any.whl

Download URL uncertaintylib-1.2.0-py3-none-any.whl
Size 27.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9762fdcba6774b35beef56d3fdb49ba8f6c65f11235bdf3017d6025aa794dae2
BLAKE2b-256 checksum
How to use checksums
fb269d96f2b0e7c2653df784846010706e4a183498c7f151cada9ace4ae80299
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Security for uncertaintylib 1.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for uncertaintylib-1.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page