UFloat doesn't need to be like float. Drop certain features.

[jagerber48]

It seems that when uncertainties was written there was some intent to make UFloat like a LSP safe subclass of float. That is, anything you can do with a float should be possible to be done with UFloat. This includes passing UFloat through the function in the math module, but, since that isn't directly possible, the umath module was written, trying to duplicate every function in the math. module.

I think this goal was too much and has created a maintenance burden for features which I doubt are used broadly. I reach for UFloat when I am representing a result of a physical measurement or the result of fitting to physical data. I am probably doing basic algebra to my UFloat objects or at least putting them through some continuous physical model. This means I'm typically dealing with UFloats with non-zero standard deviations and I am putting them through mathematical functions that a physicist would encounter, but I'm NOT putting them through mathematical functions that a computer scientist would encounter.

I propose we drop support, on the UFloat class, for certain float features.

• Equality comparison between UFloat and float should never be True, even if the UFloat has zero standard deviation.
• <, <=, >=, > should not be defined on UFloat.
• UFloat with zero standard deviation should never behave like a float in terms of uncertainty propagation. See Problem with special casing std_dev = 0 #283.
• Many functions from the math module should not be supported in umath. See below for an enumeration of which functions should be supported and which shouldn't.
• Some UFloat instance methods should likewise be dropped.

These changes are largely motivated by asking the question: if we think of UFloat as modeling a normally distributed random variable, then does this operation make sense? For example, consider UFloat(0, 10) > UFloat(0.1, 10). Thinking of these two objects as normally distributed random variables, then on a single sampling there is a basically a 50% change for True and 50% chance for False. It doesn't make sense to assign False to this expression just because of the comparison on nominal values. Hence, it just should be legal to take > on UFloat.

---

More details about umath versus math. Here is a script comparing (for Python 3.12) which functions are present in math and umath. After running the script I added Yes/No comments indicating which functions I think should be included in umath and which I think should not.

import math
import sys

from uncertainties import umath

print(f'{sys.version=}\n')

print('Shared items between math and umath')
for item in dir(math):
    if item in dir(umath):
        print(f'  {item}')

print('Items in math but not umath:')
for item in dir(math):
    if item not in dir(umath):
        print(f'  {item}')

print('Items in umath but not math:')
for item in dir(umath):
    if item not in dir(math):
        print(f'  {item}')

sys.version='3.12.6 (tags/v3.12.6:a4a2d2b, Sep  6 2024, 20:11:23) [MSC v.1940 64 bit (AMD64)]'

Shared items between math and umath
  __doc__
  __loader__
  __name__
  __package__
  __spec__
  acos       # Yes
  acosh      # Yes
  asin       # Yes
  asinh      # Yes
  atan       # Yes
  atan2      # Yes
  atanh      # Yes
  ceil       # No
  copysign   # No
  cos        # Yes
  cosh       # Yes
  degrees    # Yes
  erf        # Yes
  erfc       # Yes
  exp        # Yes
  expm1      # No
  fabs       # Probably No
  factorial  # No 
  floor      # No
  fmod       # Probably no
  frexp      # No
  fsum       # Yes
  gamma      # Yes
  hypot      # Yes
  isinf      # No
  isnan      # No
  ldexp      # No
  lgamma     # Yes
  log        # Yes
  log10      # Yes
  log1p      # Yes
  modf       # No
  pow        # Yes
  radians    # Yes
  sin        # Yes
  sinh       # Yes
  sqrt       # Yes
  tan        # Yes
  tanh       # Yes
  trunc      # No
Items in math but not umath:
  cbrt       # Yes when we drop support < 3.11
  comb       # No
  dist       # Yes
  e          # No
  exp2       # Yes when we drop support < 3.11
  gcd        # No
  inf        # No
  isclose    # No
  isfinite   # No
  isqrt      # No
  lcm        # No
  log2       # Yes
  nan        # No
  nextafter  # No
  perm       # No
  pi         # No
  prod       # Yes
  remainder  # No
  sumprod    # Yes
  tau        # No
  ulp        # No
Items in umath but not math:
  __builtins__
  __cached__
  __file__

Essentially if you could imagine using the function on real number representing physical measurements then the function is a yes. E.g. real inputs and real outputs. If the inputs or outputs involve rounding or integers then it is probably a no because it may be ambiguous what the function "should" do based on the range of std_dev. Does it makes sense to round 0.75 +/- 12 to 1 +/- 12 by just rounding the value? Should the std_dev be coerced to 0 in the case of rounding? What actual use cases are we covering? Here is a summary of the changes

Remove:

• ceil
• copysign
• expm1
• fabs I could be convinced to keep this
• factorial
• floor
• fmod I could be convinced to keep this
• frexp
• isinf
• isnan
• ldexp
• modf
• trunc

Add

• cbrt when uncertainties drops support < 3.11
• dist
• exp2 when uncertainties drops support < 3.11
• log2
• prod
• sumprod

---

Some of the corresponding instance methods on UFloat should also be dropped:

• __floordiv__
• __mod__ I could be convinced to keep this
• __div__ (This is a Python 2 relic, replaced by __truediv__)
• __abs__ I could be convinced to keep this
• __trunc__

---

More discussion. Let's think about X = UFloat(0.75, 12.2) as a normally distributed random variable with mean 0.75 and 12.2. If we take round(X) then there is a good chance the result is 1, but there is also a chance the result is 2, -1, -3 etc. The distribution is also no longer normally distributed because the sample space has change from the real numbers to the integers. If we think of X as a normally distributed random variable than the result of round(X) is not longer a normally distributed random variable so we should not allow it to be a UFloat.

---

What are others' thoughts on dropping support for these things?

[newville]

@jagerber48 I mostly agree with this. Well, except that UFloat (AffineScalarFunc and also Variable) does (do) not subclass Float. The functions from the math module are functions, not methods of Float objects -- they act on integers too. One could imagine such a world, or perhaps a Number class from with Integer, Float, Complex (and perhaps other) derive, with methods as in the math module, but that world is not Python. I think that means that any invocation of LSP or "inheritance should be transparent" is just plain irrelevant or incorrect here. There exists an uncertainties.umath module at all - that ain't subclassing. So, I mostly agree with your conclusions, but I don't agree that the intent or goal was ever (or could ever be) for UFloat to subclass Float. I think the intent was to make something "Float-like" for which uncertainties could be propagated. That's more of a "use-based" intention and not an "implementation-based" or "API-based" intention.

I propose we drop support, on the UFloat class, for certain float features.

• Equality comparison between UFloat and float should never be True, even if the UFloat has zero standard deviation.

OK. Can UFloat can equal a UFloat? I might suggest that also be False, so that x==y is False even if x is y is True. That is

class UFloat: 
    def __eq__(self, other): 
        return False

• <, <=, >=, > should not be defined on UFloat.

OK. Just to be clear, with those undefined, uval > 0 would raise a TypeError. Whereas uval == 0 is False.....
Hm, maybe uval == 0 and uval1 == uval2 should also be undefined and raise TypeError. That seems more consistent to me.

• UFloat with zero standard deviation should never behave like a float in terms of uncertainty propagation. See Problem with special casing std_dev = 0 #283.

Is "should never" correct there?

I believe that a UFloat with zero standard deviation, or even more strictly:

ufloat_is_invalid = x.std_dev is None or x.std_dev =< 0 or x.std_dev < 2.2e-16*abs(x.nominal_value)

should be considered invalid and non-sensical. It may be OK to have UFloats with std_dev = zero or None (such as x-x -- a toy example that is unlikely to exist in real, valid code), but calculations with them may fail, and those failures are not something the uncertainties code should promise to handle.

More specifically, I thin we do not need to test any calculations or make promises about results with std_dev of None or zero.

I would be OK if the function ufloat() raised ValueError or returned a plain float value if

def ufloat(nominal_value, std_dev): # note: no default values
    if std_dev is None or std_dev =< 0 or std_dev < 2.2e-16*abs(nominal_value) :  # note: abs(nominal_value) must work.
         return float(nominal_value) # or raise ValueError(f"bad ufloat() values: {nominal_value}, {std_dev}")
    return UFloat(nominal_value, std_dev)

• Many functions from the math module should not be supported in umath. See below for an enumeration of which functions should be supported and which shouldn't.

I agree. No disagreement with your list of methods.

• Some UFloat instance methods should likewise be dropped.

I am OK with dropping the methods that are there to convert float to integer (__floordiv__, __mod__, __trunc__). I might hesitate with __abs__, but I guess that replacing abs(uval) with abs(uval.nominal_value) is always better.

[jagerber48]

@newville thanks for the response! I think it sounds like we are in overall agreement.

---

Equality

Regarding comparison between UFloat and float: ok, yes. I agree <, <=, >=, > should be not defined on UFloat. Equality comparison between UFloat and float should behave as if it's not defined, so if that is raising a TypeError then agree that is the right thing to do (instead of returning False).

But I DO think equality between UFloat should be defined. Two UFloats are equal if their nominal values are equal and they are perfectly correlated. One way to detect correlation is by looking at (x - y).std_dev == 0. This makes sense interpreting UFloat as a random variable. If x and y, as random variables, are perfectly correlated, then whenever we take a sample the value of x will always equal the value of y. So the value realized by x realizes the value realized by y 100% of the time, so I think it makes sense to say x=y. But, that said, in practice, I can't imagine users actually needing to do equality comparison between UFloats. Basically I think two UFloat would be equal if they are identical and then only rarely would x == y with not x is y.

So I would prefer to keep equality comparison between UFloat but could be convinced to drop it if others feel strongly.

---

UFloat with std_dev == 0

I think we both agree that this is an odd case but differ in how it should be handled. Rather than get bogged down in the discussion my plan here is to handle it a certain way in the code, then show the code when I finish and we can discuss. On my first pass I will still have tests testing std_dev == 0 behavior, modified from the old tests testing this behavior, but if we want to just remove those tests, as you suggest, it will be easy to do so.

All of that said, if you prefer to continue the discussion here or at #283 let me know and I'm happy to do so and start addressing your points/suggestions.

---

umath math functions and UFloat math methods

I'm glad you agree with the list of methods. That will already make some work on #262 easier.

Regarding __abs__, yes I also hesitate on that one. Lean towards removing and letting users do abs(uval.nominal_value) on their own, but I only slightly lean that way. Maybe I'll take it out for now and wait to hear what others have to to say. __abs__ is easy to add into the code and maintain. It's not like ldexp or frexp which are handled as very special cases.

[newville]

@jagerber48

But I DO think equality between UFloat should be defined. Two UFloats are equal if their nominal values are equal and they are perfectly correlated. One way to detect correlation is by looking at (x - y).std_dev == 0. This makes sense interpreting UFloat as a random variable. If x and y, as random variables, are perfectly correlated, then whenever we take a sample the value of x will always equal the value of y. So the value realized by x realizes the value realized by y 100% of the time, so I think it makes sense to say x=y. But, that said, in practice, I can't imagine users actually needing to do equality comparison between UFloats. Basically I think two UFloat would be equal if they are identical and then only rarely would x == y with not x is y.

I think that using if x == y as a test for "perfectly correlated" is not that useful. Relying on float1 == 0 or float1 == float2 is hazardous enough. Testing "values are close" is fine, as is x is y - both be done by the user. Using (x - y).std_dev==0 (and nominal value, of course) as part of the meaning of == seems pretty weird to me, especially at extreme scales. If (x - y).std_dev happens to be very, very small, well, that might be interesting, but unless x is y, one should not act on that.

Also, correlations between UFloats are not well advertised and are difficult to discover without relying on identity. Is there even a simple function to display the correlation of two ufloats? What if the correlation between to UFloats is 1.0-2e-27 ? Are those equal? Identical?

Since x = ufloat(1, 1); y = yfloat(1, 1) ; x == y must be False. The case for x == y ever being True needs a lot of documentation and testing, include the edge cases of floating point (eg, ufloat(7.493e84, 2.208e-19)) And then, we would have careful documentation and tests for this, suggesting that it is an important and conscious decision to have x==y be separate from x is y. Do we want that?

OTOH, saying == is False or a TypeError and relying on is eliminates the problem and is a normal use of Python is.

For std_dev=0:

I think my view is similar: Having tests implies that there is a "right answer" and that we promise to give it. But std_dev=0 makes no sense, and there is no right answer for us to promise for any computation with such values unless we say that it is a Float, in which case, well, it should be a Float and sort of doesn't need testing.

[jagerber48]

@newville Ok. I'm seeing your points well enough to take them.

For removing equality comparison between UFloats the main thing convincing me is that I can't think of a use case where a user will naturally generate two UFloats that (1) have equal nominal value (2) are perfectly correlated and (3) the user will want to do an equality comparison between the two. I think we do currently test stuff like x+x == 2*x or similar, but we could remove tests like that. Are you ok with __eq__ being undefined on UFloat so that equality comparison delegates to is comparison? Or do you prefer/strongly prefer == always be False for UFloat?

For not testing std_dev==0 I do see your point that there isn't really a "right" answer so we don't want to go along saying that there is. There was an idea that treating such UFloat as float, at least during uncertainty propagation is the right answer, but that runs into issues on certain edge cases and is a strange/maybe surprising "special case" behavior. FWIW for many cases if we don't special case std_dev=0 we will still get the same answer as if the UFloat were a float, but yes, on a few edge cases things break down, and supporting those edge cases is a big headache, so I'm happy to just say we don't test std_dev=0.

---

@newville and others: Going forward I would appreciate your input on a few things. I desire these changes because they will make #262 easier, but I think I should make them in separate PRs. But these are starting to be, I think, more breaking changes than we've done previously. Will these changes go into 4.0? Are we happy with 4.0 being the next release so that we can merge these into master soon? Or should we do another release before then? The PRs I would want to make:

• Drop the indicated umath functions and UFloat methods
• Stop defining <, <=, >=, >, == on UFloat
• Stop special casing std_dev==0 and stop testing it. I think the behavior of pow will be what is most modified.

Also, while I appreciate Newville's input a lot, since these could be seen as moderate breaking changes I would appreciate hearing opinions from at least one other person/maintainer before merging each of these three changes.

So the plan of action would be

• Make and merge these 3 PRs
• Complete Eliminate the Variable class #262 which is getting there but still has some work
• Merge Eliminate the Variable class #262
• Release 4.0

Thoughts?

[jagerber48]

Ok, a note that's worth mentioning. After reading the comments in the modules and test I see that one of the intents of the umath module was to make it drop in replacement for the math module. I think the idea was to make it so that users could do from uncertainties import umath and get rid of import math. So it was necessary for the umath functions to operate on UFloat, but to also give their expected result on floats. I guess the point is you might have

from math import sin

but then if you want

from uncertainties.umath import sin

You would need to do something like

from math import sin
from uncertainties.umath import usin

or

import math
from uncertainties import umath

This touches on the conversation at https://discuss.python.org/t/math-exp-and-math-log-delegate-to-exp-and-log-methods/73495/1 that it would be nice if there were some sort of API that allowed delegation of math methods to avoid these namespace collisions for libraries that define versions of these math functions for special objects.

---

I think it's worth bringing up the above. However, the way I use uncertainties, I would be happy with the above importing workarounds rather than using umath functions for any regular math needs. Actually if I need math functions I'll probably access it as np.sin rather than math.sin.

[newville]

@jagerber48 I don't view "umath replaces math" as meaning "fully drop-in replacement". It can be used instead, and has a similar API. But that is like numpy ufuncs vs math functions: there are similarities, and there are differences. As important examples, they support different datatypes (complex, float, arrays, etc).

So umath is not very different from that idea, and it should be fine to say "These functions do work on ufloats, and they might work on floats". Indeed,

>>> from uncertainties import ufloat, umath
>>> umath.sin(ufloat(0.5, 0.1))
0.479425538604203+/-0.08775825618903728
>>> umath.sin(0.2)
0.19866933079506122    # a float!!

Which reminds me that maybe

>>> x = ufloat(0.3, std=0)

could legitimately return a float ;)

FWIW, I don't think the __log__ and __exp__ are that useful unless expanded to all math functions (__acosh__?).

[jagerber48]

I don't view "umath replaces math" as meaning "fully drop-in replacement".

Right, I was suggesting that based on the comments and efforts made in the module it looks like "drop-in replacement" may have been at least a partial goal for @lebigot. It looks like the direction this discussion is going is, in line with what you're saying, remove any explicit effort for umath to be a drop-in replacement and rather guarantee, again like you say, that umath works on UFloat and might work on float.

Which reminds me that maybe ... could legitimately return a float ;)

Want to avoid that conversation this second but it hasn't dropped off my radar.

FWIW, I don't think the __log__ and __exp__ are that useful unless expanded to all math functions (__acosh__?).

I think you're referring to the linked python discourse thread here. Yes, if you read that thread to the end it shifts to a discussion of a generic "scalar" API compatible with the so-called array API such that you can somehow define your own versions of these functions for your own special scalar, and it would play nice in a lot of ways with other math libraries (like math or numpy).

[wshanks]

@jagerber48 My main interest in maintaining Uncertainties was to keep it working for my use case. It came to my attention due to its dependency on the future package that had open CVEs. I don't have need for any new features at the moment, so I am wary about making breaking changes.

With all that said, the changes you propose regarding adding and removing functions all seem reasonable to me. It might be nice to make a release with warnings about the removals before removing them.

Regarding standard deviation of 0, it also seems fine not to support it. Perhaps a warning could be issued when 0 is passed to UFloat. I am not completely sure that x -x could never show up real code, though I can't think of how it could. Otherwise perhaps 0 standard deviation could be completely disallowed. I sometimes use functions written for Uncertainties where I don't care about the uncertainty but when I do I set standard deviation to nan rather than 0.

Regarding equality of UFloats, I don't think checking equality is something that comes up directly outside of testing. I think the reason it is of interest is for cases like putting UFloats into sets or using them as dictionary keys. One of our previous rounds of discussion on this involved sorting pandas arrays, where the pandas algorithm first deduplicated the values in a set. Of course, dropping support for comparison operators would make that case irrelevant. I am not sure if there is enough reason to make UFloat hashable but dropping support for comparisons also seems okay to me.

I think the net result of all these changes are it is less likely that a function written for floats will "just work" with UFloat if you change math to umath, but I think there are good reasons for why it would not (cases like comparison operators not making sense).

[andrewgsavage]

I like the idea of a warning for 0 std dev. Users can then treat the warning as an error if they desire.

Sorting is a valid use case for comparison operators so they should not be removed. UFloat(0, 10) > UFloat(0.1, 10) is an extreme example. Imagine a case where you have measurements of voltages like UFloat(0, 0.1), UFloat(3, 0.1), UFloat(0, 0.1) There's at least one issue related to sorting #186

[jagerber48]

@wshanks

umath function deprecation:

With all that said, the changes you propose regarding adding and removing functions all seem reasonable to me. It might be nice to make a release with warnings about the removals before removing them.

Open to this idea, but I wonder what the timeline would be like for this. Especially given we're planning to do the 4.0 change anyways. But that is a legitimate question I have: Should these changes come in with 4.0? If so then maybe we should do a release now before even #297 is merged in (because this PR drops some tests for these functions). That release could also contain the warnings? Then the next release could be 4.0 and it would include these changes.

If the changes don't come with 4.0 then I feel like we would have one release with the deprecation warnings but then another release that actually removes the functions. Would the deprecation be based on time? Do we have that much time before we want to release 4.0? The other alternative is to just make a 3.x release that has these functions removed with no deprecation warning. Maybe, until 4.0, we could instead have a descriptive exception if the user tries to use any of the old functions.

---

std_dev = 0:

I also like warning for ufloat or UFloat called with std_dev=0.

I sometimes use functions written for Uncertainties where I don't care about the uncertainty but when I do I set standard deviation to nan rather than 0.

This is a good usage datapoint.

---

UFloat equality:

I am not sure if there is enough reason to make UFloat hashable but dropping support for comparisons also seems okay to me.

I fully plan to make UFloat hashable with #262.

But yes, the conversation about sorting is a bit interesting. We should dig into that use case someone had for sorting a set of UFloat. If they really want to sort by nominal value they could provide a function to do so if the uncertainties library doesn't provide a native way for UFloat to be sorted. On the one hand. But on the other hand, like @andrewgsavage points out,, yes, while it is not mathematically reasonable/useful to sort [UFloat(0, 10), UFloat(0.1, 10)] it MIGHT be mathematically reasonable/useful to sort [UFloat(0, 0.01), UFloat(10, 0.01)]. My inclination, in the interest of reducing clutter in the package and slightly weird features is still to remove the comparison operators and let users do it on their own if they want. If we hear demand for native "sort-by-nominal-value" functionality we can add it back..

[andrewgsavage]

My inclination, in the interest of reducing clutter in the package and slightly weird features is still to remove the comparison operators and let users do it on their own if they want. If we hear demand for native "sort-by-nominal-value" functionality we can add it back..

That is not a good justification for removing features people may be relying upon in a mature package. The correct way to go removing features is as @wshanks said:

It might be nice to make a release with warnings about the removals before removing them.

This gives time for people to respond with their use cases. We should not expect to preempt all uses cases for existing functionality. In general, if someone has written code for a function, it should be assumed there is a use case for that function. That's not always the case, but is a good first assumption.

If you find the code is cluttered, declutter it by moving parts to other files.

[jagerber48]

@andrewgsavage this takes my comments a bit out of context.. in the quoted paragraph I was discussing a preference for removing the feature, not that it should be removed without warning. In one of my other posts I proposed 3 removal strategies. Let me spell them out clearly here for discussion.

Right now uncertainties is at version 3.2.2. master differs from 3.2.2 by a few PRs. If we released master now I would say it should be 3.2.3. #262 is in the pipeline and will make some breaking changes. Most notably the derivatives method will no longer be available on UFloat and UFloats will no longer be taggable, rather, UAtoms (or whatever they're named) will be taggable. #262 would be released with 4.0.0.

So given that we have a major release planned, and probably not many changes to introduce prior to 4.0.0, IF we agree to remove any of these features, then what would be a good release strategy? Here are 4 options (not in any preferred order)

1. Remove the features in 4.0.0 with no deprecation warning. Let the major version bump be the warning so that users can check the changelog.
2. Remove the features in 4.00 with a deprecation warning timeline. This means e.g. 3.2.3 should probably have those deprecation warning included. It's not clear how long we'll be on 3.2.3 before releasing 4.0.0.
3. Remove the features in 3.3.0 with no deprecation warning. <<< It sounds like this option is rejected, I'm fine with rejecting this option.
4. Remove the features in 3.3.0 with a deprecation warning ahead of time. In this case we could set up deprecation warnings on 3.2.3, but it will probably be a very short time between 3.2.3 being released and the PRs for removing these features to be ready for review/merging.

In either option 2 or 4 would we intentionally hold off the release of 4.0.0 or 3.3.0 so that the deprecation warnings could be present on the latest release for e.g. 6 months or a year or something? It seems to me like we don't want to hold ourselves back that way. The PRs removing these features will go quick, so unless we introduce a delay, the warnings may only be present on the latest branch for e.g. a few weeks. #262 will take more time to complete, so that route naturally leaves more time for the message to be out there.

Here's a proposed strategy:

1. Agree upon which features to remove
2. Add a PR which introduces FutureWarnings for the features we are removing.
3. Merge that PR into master
4. Release 3.2.3.
5. Create 4.0.0 release branch
6. Create PRs for any features being removed, merge them into the 4.0.0 release branch
7. Eliminate the Variable class #262 targets 4.0.0 instead of master.
8. Complete Eliminate the Variable class #262 and merge it into master
9. Any minor PRs in the meantime continue to target master branch
10. re-merge master into 4.0.0 release branch
11. PR 4.0.0 release into master, complete the PR and
12. release 4.0.0

Note that many of these issues and discussions I'm generated are motivated by moving #262 forward. I.e. if we remove these features it will speed up the release of #262 because they are all, in some way, complicating that refactor. That's due to either some tricky code that I need to understand and reproduce under the refactor, some tests that I need to reproduce, or some documentation I need to do.

[jagerber48]

I just made a message to @andrewgsavage above discussing the release strategy in the event that we DO choose to remove any of the features under discussion. In this post I want to give an update on where everyone stands on the features in question.

---

Remove some umath functions and UFloat methods.

• I think they should all be removed.
• @newville seems ok with them being removed.
• @wshanks seems ok with them being removed.
• I don't think @andrewgsavage has really weighed in on this one

---

Remove <, > operators from UFloat

• I think they should be removed
• I think @newville is ok with them being removed
• @wshanks expressed some hesitation due to the sorting application
• @andrewgsavage expressed more hesitation due to the sorting application

---

No longer allow UFloat equality comparison with float, or remove equality comparison on UFloat entirely

• I think we should definitely remove UFloat comparison with float. I'm open to removing __eq__ entirely.
• @newville would be happy if we removed __eq__ entirely I think
• The use cases @wshanks shares are better handled by a __hash__ function which is coming in a future release.
• I don't think @andrewgsavage weighed in on __eq__ other than the hesitation related to sorting

---

No longer special case std_dev=0

I think everyone expressed support for uncertainties dropping support for std_dev=0 and at least myself, @wshanks and @andrewgsavage support warnings when users try to create UFloat with std_dev=0. @newville emphasizes that dropping support for std_dev=0 means removing those tests. @newville has also repeatedly suggest that maybe the ufloat constructor function with std_dev=0 could return a float. I think this is kind of a type-safety concern and would want to at least couple that strategy with a warning.

---

So I am (through biased eyes) seeing some agreement we can drop the umath functions and UFloat methods (maybe we can discuss about details of which exact functions to drop in the PR rather than here) and also that we can stop special casing std_dev=0.

But it seems more discussion is needed about the comparison operators. Let me address this again.

First off, I want to give a reminder that these comparison operators on UFloat have the strange behavior that they don't obey the trichotomy law. This is because UFloat(1, 0.2) is neither less than, greater than, nor equal to UFloat(1, 0.4). And then I will also re-emphasize the point that <, > comparison doesn't really make sense for random variables, rather, these operators give boolean valued random variables. Sometimes A < B and sometimes B < A. If A - B << max(dA, dB) then it might be the case that the boolean-valued random variable is almost always True or False, but there are cases when it may be almost 50-50 chances.

Regarding the sorting operation: There is already the ambiguity I just mentioned that, for random variables these comparison operators are statistical. But there is another ambiguity: Should ufloat(1, 0.1) < ufloat(1, 0.2) or not? Rather than bake an answer into uncertainties I would say we should just leave sorting to the user. If the user wants to resolve this ambiguity and sort by nominal value then they can do that themselves. We can provide a simple recipe for how to do this in the documentation rather than support some functionality for it in the code. I would say that UFloats should not be natively sortable. If a user wants to sort by nominal value then they should sort by nominal value, not by the UFloat itself.

[andrewgsavage]

I think isnan and isinf are worth keeping. I don't have a strong opinion on the other umath fuctions.

And then I will also re-emphasize the point that <, > comparison doesn't really make sense for random variables, rather, these operators give boolean valued random variables. Sometimes A < B and sometimes B < A. If A - B << max(dA, dB) then it might be the case that the boolean-valued random variable is almost always True or False, but there are cases when it may be almost 50-50 chances.

The module has always had this behaviour:

>>> uncertainties.ufloat(1,0.2) < uncertainties.ufloat(1,0.1)
False
>>> uncertainties.ufloat(1,0.1) < uncertainties.ufloat(1,0.2)
False

And nobody has complained; I found no issues about them being confusing. I did find one issue that relies on comparisons/equalities: #66 which uses <. For these reasons I think they should be kept and we can revisit it if users find this to be an issue.

When searching for how sort() operates, I found in PEP8:

When implementing ordering operations with rich comparisons, it is best to implement all six operations (eq, ne, lt, le, gt, ge) rather than relying on other code to only exercise a particular comparison.
To minimize the effort involved, the functools.total_ordering() decorator provides a tool to generate missing comparison methods.
PEP 207 indicates that reflexivity rules are assumed by Python. Thus, the interpreter may swap y > x with x < y, y >= x with x <= y, and may swap the arguments of x == y and x != y. The sort() and min() operations are guaranteed to use the < operator and the max() function uses the > operator. However, it is best to implement all six operations so that confusion doesn’t arise in other contexts.

[wshanks]

The difficulty with the comparison operators comes from Python's use of __eq__ in multiple contexts. I agree with @jagerber48's point that philosophically it doesn't make sense to sort numbers with finite uncertainty. On the other hand, I could imagine defining the comparison operators as just working with nominal value and that would be a slight convenience for the user in typing x < y rather than x.n < y.n (or more convenient if __lt__ also allows for y being a float). As long as that is the documented behavior, the user should only be using it with that knowledge and it would be fine. The problem is that __eq__ is grouped together with __lt__ and the other comparison operators but it currently accounts for both the nominal value and the uncertainty, being true only if the nominal value and standard deviation of x -y are both 0. Like @jagerber48 mentioned, this means that it can be the case that x < y, x > y, and x == y are all false which breaks the usual assumptions for the comparison operators.

__eq__ behaves this way because it is designed for testing uncertainty equivalence rather than comparing just nominal values. In the Python data model, it is documented that objects that compare equal must hash to the same value and the natural hash for a UFloat includes both the nominal value and the uncertainty content, so the hash will be different for UFloats with different uncertainties and so they must not compare equal.

I don't see a way to have all the comparison operators be based on the nominal value and have the equality/hash operators be based on both nominal value and uncertainty. On the other hand, I take @andrewgsavage's point that UFloat has had the current behavior for a long time without complaint, and sorted(list_of_ufloats) does do the right thing in practice any way (sorts by nominal value without raising an exception for items with the same nominal value that are not equal).

[jagerber48]

@wshanks thanks. you've captured my point of view perfectly. My main argument is that it philosophically/mathematically doesn't make sense to do < comparison on random variables. As soon as you start doing < comparisons on UFloats you lose what could be a very clean modeling of random variables by UFloat and it ends up complicating the codebase, API, documentation, and user mental model because of special cases that break with the model.

I understand that this package has been used in this way for a long time, but I also see the 4.0.0 transition is an opportunity (possibly the only opportunity) to clean up the API and UFloat data model. So if there are places where we can clean up the model, even if it comes at the cost of some backwards compatibility breaking, it can be worth it in my eyes. Yes uncertainties has a large user base, but (1) we think most users are through lmfit and lmfit will certainly quick to respond to uncertainties updates and (2) it's not like this is a python release. I think we can handle some breaking of backwards compatibility if we agree that some change is for the better, or at least provides a cleaner data model.

And then also emphasizing the point, in the spirit of "explicit is better than implicit" that if users want to sort by nominal value (or do anything by nominal value) then can easily and should explicitly do so. While, in the meantime, the UFloat class will do exactly the things it should be able to do consistent with it's random variable data model.

[newville]

@wshanks @jagerber48 I agree with all of this. And so, my opinion is that dropping support '>', '<', '!=', and '==' in version 4 makes the most sense. It's not a small change or decision and it would need documentation and deprecation. But, I think it is the right thing to do.

I doubt that many users will be relying on sorting UFloats. For those comparing them, converting ufloat1 < ufloat2 to ufloat1.n < ufloat2.n does not seem like too much of a burden, and helps clarify -- make explicit -- whether they actually meant nominal value, or were expecting that to mean "outside of a 1-sigma uncertainty" (or something else).

[newville]

@jagerber48 has stated my opinions correctly.

I agree that the discussion here is mostly about what "4.0" should look like, and that deprecations for removed features will be needed (once we agree on what to change.)

Needing to sort or compare ufloats seems odd to me - so dropping comparison operators seems OK. I can believe somebody somewhere might use those operators, but we don't need to encourage the notion that there is an obvious, correct way to compare ufloats.

[lebigot]

While I haven't read every message or everything in detail, I can share a few points:

1. I don't foresee many problems with removing support for < and >. Indeed, they don't make perfect sense.
2. I haven't read the discussion on making UFloats hashable, but the semantics of UFloats is that they represent random variables; also, I considered that x == y is equivalent to x-y == 0, i.e. that the distribution of x-y is 0 with probability 1. Without thinking much about it, I'm not yet sure how easy it is to make sure that x and y have the same hash, when x == y!

Historical note: my reasoning, for handling < and >, was that (1) users with existing float code could use UFloats as a drop-in replacement, and comparison operators would behave similarly similarly to what they did before; (2) comparing 1±0.1 and 42±0.1 is relatively meaningful, based on an idea similar to linear error propagation theory requiring uncertainties to be "small", so my reasoning was that users were similarly responsible for keeping comparison meaningful.

[jagerber48]

Thanks for the response lebigot!

I'm not yet sure how easy it is to make sure that x and y have the same hash, when x == y!

There's a simple plan for this in the new framework. I can point you to discussions/code if you want more information.

comparing 1±0.1 and 42±0.1 is relatively meaningful, based on an idea similar to linear error propagation theory requiring uncertainties to be "small", so my reasoning was that users were similarly responsible for keeping comparison meaningful.

This is a fair point that there is already some onus on the users to make sure what they're doing makes sense mathematically. For example uncertainties will calculate pow(ufloat(0.1, 10), 3.2) and give a real nominal value with some standard deviation, but, thought of in terms of random variables, there would actually be a very large probability that the result is complex. This is an example I've been thinking about a bit lately. But nonetheless, I still prefer keeping the UFloat implementation as close to the random variable model in places where we can so I'm still in favor of removing < and >. Especially given that this change will end up nudging the user's code to be a little bit more explicit about what they're doing.