Eliminate the Variable class

.github/workflows/test.yml

@@ -5,9 +5,9 @@ name: Run Tests
 
 on:
   push:
-    branches: [ "master" ]
+    branches: [ "main", "master" ]
   pull_request:
-    branches: [ "master" ]
+    branches: [ "main", "master" ]
 
 jobs:
   build:

CHANGES.rst

@@ -1,6 +1,40 @@
 Change Log
 ===================
 
+Unreleased 4.x
+--------------
+
+Changes:
+
+- Includes the `main` branch in continuous integration automation.
+- [**BREAKING**] Previously when tallying the uncertainty for a `UFloat` object, the
+   contribution from other `UFloat` objects with `std_dev == 0` were excluded. Now this
+   special casing for `std_dev == 0` has been removed so that the contribution from all
+   contributing `UFloat` objects is included. This changes the behavior in certain
+   corner cases where `UFloat` `f` is derived from `UFloat` `x`, `x` has `x.s == 0`, but
+   the derivative of `f` with respect to `x` is `NaN`. For example, previously
+   `(-1)**ufloat(1, 0)` gave `-1.0+/-0`. The justification for this was that the second
+   `UFloat` with `std_dev` of `0` should be treated like a regular float. Now the same
+   calculation returns `-1.0+/-nan`. In this case the `UFloat` in the second argument
+   of the power operator is treated as a degenerate `UFloat`.
+
+Removes:
+
+- [**BREAKING**] Removes certain deprecated `umath` functions and
+   `AffineScalarFunc`/`UFloat` methods. The following `umath` functions are removed:
+   `ceil`, `copysign`, `fabs`, `factorial`, `floor`, `fmod`, `frexp`, `ldexp`, `modf`,
+   `trunc`. The following `AffineScalarFunc`/`UFloat` methods are removed:
+   `__floordiv__`, `__mod__`, `__abs__`, `__trunc__`, `__lt__`, `__le__`, `__gt__`,
+   `__ge__`, `__bool__`.
+- [**BREAKING**] Previously it was possible for a `UFloat` object to compare equal to a
+   `float` object if the `UFloat` `standard_deviation` was zero and the `UFloat`
+   `nominal_value` was equal to the `float`. Now, when an equality comparison is made
+   between a `UFloat` object and another object, if the object is not a `UFloat` then
+   the equality comparison is deferred to this other object. For the specific case of
+   `float` this means that the equality comparison always returns `False`.
+- [**BREAKING**] The `uncertainties` package is generally dropping formal support for
+   edge cases involving `UFloat` objects with `std_dev == 0`.
+
 Unreleased
 ----------
 

doc/index.rst

@@ -27,10 +27,8 @@ quick taste of how to use :mod:`uncertainties`:
 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).
+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`_.

doc/tech_guide.rst

@@ -27,7 +27,7 @@ user-supplied function.
 
 .. autofunction:: ufloat_fromstr
 
-.. autoclass:: Variable
+.. autoclass:: UFloat
 
 .. autofunction:: wrap
 
@@ -93,102 +93,47 @@ are completely uncorrelated.
 .. _comparison_operators:
 
 
-Comparison operators
---------------------
+Equality Comparison
+-------------------
 
-Comparison operations (>, ==, etc.) on numbers with uncertainties have
-a **pragmatic semantics**, in this package: numbers with uncertainties
-can be used wherever Python numbers are used, most of the time with a
-result identical to the one that would be obtained with their nominal
-value only.  This allows code that runs with pure numbers to also work
-with numbers with uncertainties.
+Numbers with uncertainty, :class:`UFloat` objects, model random variables.
+There are a number of senses of equality for two random variables.
+The stronger senses of equality define two random variables to be equal if the two
+random variables always produce the same result given a random sample from the sample
+space.
+For :class:`UFloat`, this is the case if two :class:`UFloat` objects have equal
+nominal values and standard deviations and are perfectly correlated.
+We can test for these conditions by taking the difference of two :class:`UFloat` objects
+and looking at the nominal value and standard deviation of the result.
+If both the nominal value and standard deviation of the difference are zero, then the
+two :class:`UFloat` objects have the same nominal value, standard deviation, and are
+perfectly correlated.
+In this case we say the two :class:`UFloat` are equal.
 
-.. index:: boolean value
-
-The **boolean value** (``bool(x)``, ``if x …``) of a number with
-uncertainty :data:`x` is defined as the result of ``x != 0``, as usual.
-
-However, since the objects defined in this module represent
-probability distributions and not pure numbers, comparison operators
-are interpreted in a specific way.
-
-The result of a comparison operation is defined so as to be
-essentially consistent with the requirement that uncertainties be
-small: the **value of a comparison operation** is True only if the
-operation yields True for all *infinitesimal* variations of its random
-variables around their nominal values, *except*, possibly, for an
-*infinitely small number* of cases.
-
-Example:
-
->>> x = ufloat(3.14, 0.01)
->>> x == x
+>>> x = ufloat(1, 0.1)
+>>> a = 2 * x
+>>> b = x + x
+>>> print(a - b)
+0.0+/-0
+>>> print(a == b)
 True
 
-because a sample from the probability distribution of :data:`x` is always
-equal to itself.  However:
+It might be the case that two random variables have the same marginal probability
+distribution but are uncorrelated.
+A weaker sense of equality between random variables may consider two such random
+variables to be equal.
+This is equivalent to two :class:`UFloat` objects have equal nominal values and
+standard deviations, but, are uncorrelated.
+The :mod:`uncertainties` package, however, keeps to the stronger sense of random
+variable equality such that two such :class:`UFloat` objects do not compare as equal.
 
->>> y = ufloat(3.14, 0.01)
->>> x == y
+>>> x = ufloat(1, 0.1)
+>>> y = ufloat(1, 0.1)
+>>> print(x - y)
+0.00+/-0.14
+>>> print(x == y)
 False
 
-since :data:`x` and :data:`y` are independent random variables that
-*almost* always give a different value (put differently,
-:data:`x`-:data:`y` is not equal to 0, as it can take many different
-values). Note that this is different
-from the result of ``z = 3.14; t = 3.14; print(z == t)``, because
-:data:`x` and :data:`y` are *random variables*, not pure numbers.
-
-Similarly,
-
->>> x = ufloat(3.14, 0.01)
->>> y = ufloat(3.00, 0.01)
->>> x > y
-True
-
-because :data:`x` is supposed to have a probability distribution largely
-contained in the 3.14±~0.01 interval, while :data:`y` is supposed to be
-well in the 3.00±~0.01 one: random samples of :data:`x` and :data:`y` will
-most of the time be such that the sample from :data:`x` is larger than the
-sample from :data:`y`.  Therefore, it is natural to consider that for all
-practical purposes, ``x > y``.
-
-Since comparison operations are subject to the same constraints as
-other operations, as required by the :ref:`linear approximation
-<linear_method>` method, their result should be essentially *constant*
-over the regions of highest probability of their variables (this is
-the equivalent of the linearity of a real function, for boolean
-values).  Thus, it is not meaningful to compare the following two
-independent variables, whose probability distributions overlap:
-
->>> x = ufloat(3, 0.01)
->>> y = ufloat(3.0001, 0.01)
-
-In fact the function (x, y) → (x > y) is not even continuous over the
-region where x and y are concentrated, which violates the assumption
-of approximate linearity made in this package on operations involving
-numbers with uncertainties.  Comparing such numbers therefore returns
-a boolean result whose meaning is undefined.
-
-However, values with largely overlapping probability distributions can
-sometimes be compared unambiguously:
-
->>> x = ufloat(3, 1)
->>> x
-3.0+/-1.0
->>> y = x + 0.0002
->>> y
-3.0002+/-1.0
->>> y > x
-True
-
-In fact, correlations guarantee that :data:`y` is always larger than
-:data:`x`: ``y-x`` correctly satisfies the assumption of linearity,
-since it is a constant "random" function (with value 0.0002, even
-though :data:`y` and :data:`x` are random). Thus, it is indeed true
-that :data:`y` > :data:`x`.
-
-
 .. index:: linear propagation of uncertainties
 .. _linear_method:
 
@@ -252,16 +197,6 @@ This indicates that **the derivative required by linear error
 propagation theory is not defined** (a Monte-Carlo calculation of the
 resulting random variable is more adapted to this specific case).
 
-However, even in this case where the derivative at the nominal value
-is infinite, the :mod:`uncertainties` package **correctly handles
-perfectly precise numbers**:
-
->>> umath.sqrt(ufloat(0, 0))
-0.0+/-0
-
-is thus the correct result, despite the fact that the derivative of
-the square root is not defined in zero.
-
 .. _math_def_num_uncert:
 
 Mathematical definition of numbers with uncertainties