lmfit · jagerber48 · Aug 9, 2024 · Aug 10, 2024 · Aug 11, 2024 · Aug 11, 2024
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -4,6 +4,11 @@ Change Log
 Unreleased 4.x
 --------------
 
+Adds:
+
+- Adds `UFloat.covariance()` and `UFloat.correlation()` methods to allow easy
+   calclation of the correlation and covariance between two `UFloat` objects.
+
 Changes:
 
 - Includes the `main` branch in continuous integration automation.
@@ -40,6 +45,13 @@ Removes:
 - [**BREAKING**] Previously if a negative `std_dev` was used to construct a `UFloat`
    object a custom `NegativeStdDev` exception was raised. Now a standard `ValueError`
    exception is raised.
+- Previously it was possible to generate and print `UFloat` objects with very large
+   values, e.g. `ufloat(3.14e200, 0.1e200)`. However, applying any mathematical
+   operation would result in an `OverflowError` rendering these objects of minimal use.
+   As a result of other changes, it is no longer possible to print such large `UFloat`
+   objects. It is still possible to generate large `UFloat` objects, but operations
+   still result in `OverflowError` and their use is generally not supported.
+
 
 Unreleased
 ----------

diff --git a/README.rst b/README.rst
@@ -22,27 +22,28 @@ Basic examples
 
 .. code-block:: python
 
-    >>> from uncertainties import ufloat
-    >>> x = ufloat(2, 0.25)
-    >>> x
+    >>> from uncertainties import UFloat
+    >>> x = UFloat(2, 0.25)
+    >>> print(x)
     2.0+/-0.25
 
+    >>> print(x**2)
     >>> square = x**2
-    >>> square
+    >>> print(square)
     4.0+/-1.0
-    >>> square.nominal_value
+    >>> print(square.nominal_value)
     4.0
-    >>> square.std_dev  # Standard deviation
+    >>> print(square.std_dev)  # Standard deviation
     1.0
 
-    >>> square - x*x
-    0.0  # Exactly 0: correlations taken into account
+    >>> print(square - x*x)
+    0.0  # Exactly 0: `uncertainties` is aware of correlations
 
     >>> from uncertainties.umath import sin, cos  # and many more.
-    >>> sin(1+x**2)
+    >>> print(sin(1+x**2))
     -0.95892427466313845+/-0.2836621854632263
 
-    >>> print (2*x+1000).derivatives[x]  # Automatic calculation of derivatives
+    >>> print(2*x+1000).derivatives[x]  # Automatic calculation of derivatives
     2.0
 
     >>> from uncertainties import unumpy  # Array manipulation
@@ -64,23 +65,19 @@ Main features
 - **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  mathematical operations** are supported, including many
+  functions from the standard math_ module (sin,...).
 
 - Many **fast operations on arrays and matrices** of numbers with
   uncertainties are supported.
 
-- **Extensive support for printing** numbers with uncertainties
+- **Extensive support for formatting** 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).
-
+- This module gives access to the error components and weights which contributed to the
+   total uncertainty on any :class:`UFloat` object.
 
 Installation or upgrade
 -----------------------
@@ -89,9 +86,6 @@ 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>`_.
@@ -100,13 +94,12 @@ Further details are in the `on-line documentation
 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.
+The GitHub ``main`` 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

diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html
@@ -6,7 +6,7 @@
 <li>|<a href="{{ pathto('user_guide') }}">User Guide</a></li>
 <li>|<a href="{{ pathto('formatting') }}">Formatting</a></li>
 <li>|<a href="{{ pathto('numpy_guide') }}"> Numpy Arrays</a></li>
-<li>|<a href="{{ pathto('tech_guide') }}">Advanced Topics</a>]</li> &nbsp;
+<li>|<a href="{{ pathto('api') }}">API</a>]</li> &nbsp;
 &nbsp;
 &nbsp; &nbsp;
 {% endblock %}

diff --git a/doc/api.rst b/doc/api.rst
@@ -0,0 +1,31 @@
+.. index:: technical details
+
+=========================
+Advanced Topics
+=========================
+
+
+This page gives more in-depth technical description of the
+:mod:`uncertainties` package.
+
+ .. index:: api
+
+.. _api_funcs:
+
+
+API: Application Programming Interface
+==============================================
+
+.. module:: uncertainties
+
+The most important object is the :class:`UFloat` object.
+The :class:`UFloat` object can also be constructed using the :class:`ufloat` alias.
+The :func:`ufloat_from_str` function is an alternate constructor.
+The :func:`wrap` function wraps user-provided functions to support :class:`UFloat`
+objects with uncertainty propagation.
+
+.. autoclass:: UFloat
+
+.. autofunction:: ufloat_fromstr
+
+.. autofunction:: wrap
diff --git a/doc/formatting.rst b/doc/formatting.rst
@@ -14,7 +14,8 @@ Printing
 
 .. Overview:
 
-Numbers with uncertainties can be printed conveniently:
+The :mod:`uncertainties` package provides functionality for convenient formatting of
+:class:`UFloat` objects:
 
 >>> from uncertainties import ufloat
 >>> x = ufloat(0.2, 0.01)
@@ -34,8 +35,7 @@ Standard formats
 
 .. Formatting method:
 
-More **control over the format** can be obtained (in Python 2.6+)
-through the usual :func:`format` method of strings:
+The formatting can be controlled using various means of formatting python strings:
 
 >>> print('Result = {:10.2f}'.format(x))
 Result =       0.20+/-      0.01
@@ -48,10 +48,9 @@ with the ``n`` format type. In particular, a fill character, an
 alignment option, a sign or zero option, a width, or the ``%`` format
 type are all supported.
 
-The usual **float formats with a precision** retain their original
-meaning (e.g. ``.2e`` uses two digits after the decimal point): code
-that works with floats produces similar results when running with
-numbers with uncertainties.
+The usual **float formats with a precision** retain their original meaning (e.g. ``.2e``
+uses two digits after the decimal point): code that works with floats produces similar
+results when running used with :class:`UFloat` objects.
 
 Precision control
 -----------------
@@ -203,7 +202,7 @@ It is sometimes useful to have a **consistent formatting** across
 multiple parts of a program. Python's `string.Formatter class
 <https://docs.python.org/3/library/string.html#custom-string-formatting>`_
 allows one to do just that. Here is how it can be used to consistently
-use the shorthand notation for numbers with uncertainties:
+use the shorthand notation for :class:`UFloat` objects:
 
 .. code-block:: python
 
@@ -230,10 +229,10 @@ Customizing the pretty-print and LaTeX outputs
 
 The pretty print and LaTeX outputs themselves can be customized.
 
-For example, the pretty-print representation of numbers with uncertainty can
-display multiplication with a centered dot (⋅) instead of the default symbol
-(×), like in ``(2.00±0.10)⋅10⁻¹``; this is easily done through the global
-setting ``uncertainties.core.MULT_SYMBOLS["pretty-print"] = "⋅"``.
+For example, the pretty-print representation of :class:`UFloat` objects can display
+multiplication with a centered dot (⋅) instead of the default symbol (×), like in
+``(2.00±0.10)⋅10⁻¹``; this is easily done through the global setting
+``uncertainties.core.MULT_SYMBOLS["pretty-print"] = "⋅"``.
 
 Beyond this multiplication symbol, the "±" symbol, the parentheses and the
 exponent representations can also be customized globally. The details can be

diff --git a/doc/index.rst b/doc/index.rst
@@ -14,9 +14,9 @@ The :mod:`uncertainties` package takes the pain and
 complexity out of uncertainty calculations and error propagation.  Here is a
 quick taste of how to use :mod:`uncertainties`:
 
->>> from uncertainties import ufloat
->>> x = ufloat(2, 0.1)   # x = 2+/-0.1
->>> y = ufloat(3, 0.2)   # y = 3+/-0.2
+>>> from uncertainties import UFloat
+>>> x = UFloat(2, 0.1)   # x = 2+/-0.1
+>>> y = UFloat(3, 0.2)   # y = 3+/-0.2
 >>> print(2*x)
 4.00+/-0.20
 >>> print(x+y)
@@ -25,12 +25,11 @@ quick taste of how to use :mod:`uncertainties`:
 6.0+/-0.5
 
 The :mod:`uncertainties` library calculates uncertainties using linear `error
-propagation theory`_ by automatically :ref:`calculating derivatives
-<derivatives>` and analytically propagating these to the results.  Correlations
-between variables are automatically handled.  This library can also yield the
-derivatives of any expression with respect to the variables that have uncertain
-values.  For other approaches, see soerp_ (using higher-order terms) and mcerp_
-(using a Monte-Carlo approach).
+propagation theory`_ by automatically calculating derivatives and analytically
+propagating these to the results.
+Correlations between variables are automatically handled.
+For other approaches, see soerp_ (using higher-order terms) and mcerp_ (using a
+Monte-Carlo approach).
 
 The `source code`_ for the uncertainties package is licensed under the `Revised
 BSD License`_.  This documentation is licensed under the `CC-SA-3 License`_.
@@ -58,4 +57,4 @@ Table of Contents
    user_guide
    numpy_guide
    formatting
-   tech_guide
+   api