Metadata-Version: 2.4
Name: uncertainties
Version: 3.2.3
Summary: calculations with values with uncertainties, error propagation
Author-email: "Eric O. LEBIGOT (EOL)" <eric.lebigot@normalesup.org>
License: Revised BSD License
Project-URL: Documentation, https://uncertainties.readthedocs.io/
Project-URL: Repository, https://github.com/lmfit/uncertainties
Project-URL: Issues, https://github.com/lmfit/uncertainties/issues
Project-URL: Changelog, https://github.com/lmfit/uncertainties/blob/master/CHANGES.rst
Keywords: error propagation,uncertainties,uncertainty calculations,standard deviation,derivatives,partial derivatives,differentiation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Other Audience
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: Jython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Education
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/x-rst
License-File: LICENSE.txt
Provides-Extra: arrays
Requires-Dist: numpy; extra == "arrays"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest_codspeed; extra == "test"
Requires-Dist: pytest_cov; extra == "test"
Requires-Dist: scipy; extra == "test"
Provides-Extra: doc
Requires-Dist: sphinx; extra == "doc"
Requires-Dist: sphinx-copybutton; extra == "doc"
Requires-Dist: python-docs-theme; extra == "doc"
Provides-Extra: all
Requires-Dist: uncertainties[arrays,doc,test]; extra == "all"
Dynamic: license-file

uncertainties
=============

.. image:: https://readthedocs.org/projects/uncertainties/badge/?version=latest
   :target: https://uncertainties.readthedocs.io/en/latest/?badge=latest
.. image:: https://img.shields.io/pypi/v/uncertainties.svg
   :target: https://pypi.org/project/uncertainties/
.. image:: https://pepy.tech/badge/uncertainties/week
   :target: https://pepy.tech/project/uncertainties
.. image:: https://codecov.io/gh/lmfit/uncertainties/branch/master/graph/badge.svg
   :target: https://codecov.io/gh/lmfit/uncertainties/
.. image:: https://img.shields.io/github/actions/workflow/status/lmfit/uncertainties/python-package.yml?logo=github%20actions
   :target: https://github.com/lmfit/uncertainties/actions/workflows/python-package.yml

The ``uncertainties`` package allows calculations with values that have
uncertaintes, such as (2 +/- 0.1)*2 = 4 +/- 0.2.  ``uncertainties`` takes the
pain and complexity out of error propagation and calculations of values with
uncertainties.  For more information, see https://uncertainties.readthedocs.io/

Basic examples
--------------

.. code-block:: python

    >>> from uncertainties import ufloat
    >>> x = ufloat(2, 0.25)
    >>> x
    2.0+/-0.25

    >>> square = x**2
    >>> square
    4.0+/-1.0
    >>> square.nominal_value
    4.0
    >>> square.std_dev  # Standard deviation
    1.0

    >>> square - x*x
    0.0  # Exactly 0: correlations taken into account

    >>> from uncertainties.umath import sin, cos  # and many more.
    >>> sin(1+x**2)
    -0.95892427466313845+/-0.2836621854632263

    >>> print (2*x+1000).derivatives[x]  # Automatic calculation of derivatives
    2.0

    >>> from uncertainties import unumpy  # Array manipulation
    >>> varr = unumpy.uarray([1, 2], [0.1, 0.2])
    >>> print(varr)
    [1.0+/-0.1 2.0+/-0.2]
    >>> print(varr.mean())
    1.50+/-0.11
    >>> print(unumpy.cos(varr))
    [0.540302305868+/-0.0841470984808 -0.416146836547+/-0.181859485365]

Main features
-------------

- **Transparent calculations with uncertainties**: Little or
  no modification of existing code is needed to convert calculations of floats
  to calculations of values with uncertainties.

- **Correlations** between expressions are correctly taken into
  account.  Thus, ``x-x`` is exactly zero.

- **Most  mathematical operations** are supported, including most
  functions from the standard math_ module (sin,...).  Comparison
  operators (``>``, ``==``, etc.) are supported too.

- Many **fast operations on arrays and matrices** of numbers with
  uncertainties are supported.

- **Extensive support for printing** numbers with uncertainties
  (including LaTeX support and pretty-printing).

- Most uncertainty calculations are performed **analytically**.

- This module also gives access to the **derivatives** of any
  mathematical expression (they are used by `error
  propagation theory`_, and are thus automatically calculated by this
  module).


Installation or upgrade
-----------------------

To install `uncertainties`, use::

     pip install uncertainties

To upgrade from an older version, use::

     pip install --upgrade uncertainties

Further details are in the `on-line documentation
<https://uncertainties.readthedocs.io/en/latest/install.html>`_.


Git branches
------------

The GitHub ``master`` branch is the latest development version, and is intended
to be a stable pre-release version. It will be experimental, but should pass
all tests..  Tagged releases will be available on GitHub, and correspond to the
releases to PyPI.  The GitHub ``gh-pages`` branch will contain a stable test version
of the documentation that can be viewed at
`<https://lmfit.github.io/uncertainties/>`_.  Other Github branches should be
treated as unstable and in-progress development branches.


License
-------

This package and its documentation are released under the `Revised BSD
License <LICENSE.txt>`_.


History
-------

..
   Note from Eric Lebigot: I would like the origin of the package to
   remain documented for its whole life. Thanks!

This package was created back around 2009 by `Eric O. LEBIGOT <https://github.com/lebigot>`_.

Ownership of the package was taken over by the `lmfit GitHub organization <https://github.com/lmfit>`_ in 2024.

.. _IPython: https://ipython.readthedocs.io/en/stable/
.. _math: https://docs.python.org/library/math.html
.. _error propagation theory: https://en.wikipedia.org/wiki/Propagation_of_uncertainty
.. _main website: https://uncertainties.readthedocs.io/
