Eliminate the Variable class

[jagerber48]

• Closes # (insert issue number)
• Executed pre-commit run --all-files with no errors
• The change is fully covered by automated unit tests
• Documented in docs/ as appropriate
• Added an entry to the CHANGES file

This PR:

• Eliminates the Variable class and eliminates the AffineScalarFunc.derivatives property.
• The AffineScalarFunc class is renamed to UFloat with AffineScalarFunc left as a legacy name.
• The LinearCombo class is refactored into the UCombo class but the architectural role is similar: track the uncertainties of UFloat objects as a lazily expanded combination of objects with uncertainty
• The UAtom object is introduced as the fundamental element which captures uncertainty. Each UAtom models a random variable with zero mean and unity standard deviation/variance. Each UAtom has a uuid and all UAtom are mutually statistically independent. The expanded version of the UCombo maps dict[UAtom, float].

For more detail/discussion see #251 (comment)

Note that as of the time opening this PR the PR is still a work in progress. Not all elements in the bullet list above are implemented and a good handful of tests are still failing.

[jagerber48]

These floats are too large to work with. Prior to this PR the large float value could be saved into the AffineScalarFunc object and displayed, but any arithmetic with such large values would result in an OverflowError. In the new framework even displaying a UFloat the first time requires a calculation, even if it's as simple as sqrt(x**2). So in the new framework the OverflowError appears immediately.

[jagerber48]

All the tests are passing except some having to do with the uarray inverse and pseudo inverse functions. The code for this is pretty complicated. It might make sense to just rewrite the code to convert array-compatible functions to ufloat array compatible functions.

[codecov]

Codecov Report

❌ Patch coverage is 85.40670% with 61 lines in your changes missing coverage. Please review.
✅ Project coverage is 85.42%. Comparing base (2c30134) to head (ac5ae02).

Files with missing lines	Patch %	Lines
uncertainties/unumpy/core.py	77.14%	32 Missing ⚠️
uncertainties/ucombo.py	80.61%	19 Missing ⚠️
tests/test_unumpy.py	0.00%	8 Missing ⚠️
tests/helpers.py	83.33%	1 Missing ⚠️
uncertainties/core.py	97.72%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #262      +/-   ##
==========================================
- Coverage   86.75%   85.42%   -1.33%     
==========================================
  Files          18       19       +1     
  Lines        1706     1832     +126     
==========================================
+ Hits         1480     1565      +85     
- Misses        226      267      +41     

Flag	Coverage Δ
macos-latest-3.10	89.93% <82.43%> (-4.12%)	⬇️
macos-latest-3.11	89.93% <82.43%> (-4.12%)	⬇️
macos-latest-3.12	89.93% <82.43%> (-4.12%)	⬇️
macos-latest-3.8	89.92% <82.43%> (-4.13%)	⬇️
macos-latest-3.9	89.92% <82.43%> (-4.13%)	⬇️
no-numpy	80.07% <62.91%> (-2.58%)	⬇️
ubuntu-latest-3.10	89.93% <82.43%> (-4.12%)	⬇️
ubuntu-latest-3.11	89.93% <82.43%> (-4.12%)	⬇️
ubuntu-latest-3.12	89.93% <82.43%> (-4.12%)	⬇️
ubuntu-latest-3.8	89.92% <82.43%> (-4.13%)	⬇️
ubuntu-latest-3.9	89.92% <82.43%> (-4.13%)	⬇️
windows-latest-3.10	89.93% <82.43%> (-4.12%)	⬇️
windows-latest-3.11	89.93% <82.43%> (-4.12%)	⬇️
windows-latest-3.12	89.93% <82.43%> (-4.12%)	⬇️
windows-latest-3.8	89.92% <82.43%> (-4.13%)	⬇️
windows-latest-3.9	89.92% <82.43%> (-4.13%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[jagerber48]

Wow all tests are passing now. That's a big milestone for this PR. If folks are interested I'd be curious to hear general feedback on the source code changes in this PR. I tried to do as little wholesale rewriting as possible but did chose to do some of that in unumpy/core.py.

Here's a summary of the changes so far. See #251 for a more thorough discussion of these changes and their motivations.

• Remove the Variable class.
• Remove the LinearCombination class.
• Add the UAtom class. A UAtom models a standard normally distributed random variable (zero mean, unity variance).
• Add the UCombo class. This class essentially maps UAtoms to float. This class models a linear combination of UAtoms. Exposes a method to extract its own standard deviation and its covariance with other UCombos. This class supports multiplication by floats/ints and additions with other UCombo's. This simple arithmetic support makes uncertainty propagation calculations nice.
• Swap the names UFloat and AffineScalarFunc. Now UFloat defines the actual class and AffineScalarFunc is an alias (perhaps it could be deprecated later).
• The UFloat class now stores uncertainty as a UCombo rather than a LinearCombination. Previously uncertainty was roughly recorded as the derivatives of an AffineScalarFunc with respect to Variables. This information was stored and accessed in the derivatives attribute. Now there is no longer a derivatives attribute. There is only error_components which now returns a mapping from UAtom to float indicating the weighting of each UAtom within a UFloat. This is the biggest user-facing conceptual change in this PR.
• It was relatively straightforward to give UFloat a simple hash. This will resolve Pandas sort_values with multiple columns does not work for AffineScalarFunc #186 and Should `Variable.__eq__` be based on `id()` or a separate identifier? #218 and Implement hash for AffineScalarFunc #219. I'll point out that these conversations were major concrete motivators for this refactor (together with a less concrete desire to simplify the codebase)
• Previously AffineScalarFunc and Variable could be tagged with a user-readable tag. Now UFloats cannot be tagged, but UAtoms can.
• Because of the previous architecture there were some confusing behaviors with respect to copying/pickling. In the new framework I think copying and pickling are much more straightforward. The behaviors are different than before, but I argue they are better. You can look at how the tests changed for more details onthis. See also Strange behavior on copying #260.
• The code in unumpy/core.py responsible for extending np.linalg.inv and np.linalg.pinv to operate sensibly on umatrix or arrays of UFloat were rewritten. The old code (1) relied centrally on AffineScalarFunc.derivatives and (2) was quite confusing to understand. In this case I found it easier to rewrite the code than to understand and modify the old code. The old code could only uncertainty-ify functions that took one array as an argument. The new code detect UFloats or arrays containing UFloat's in any argument. By default it uses numerical differentiation, but the function can be passed functions to calculate analytical derivatives.

Some todo items

• Check that performance isn't impacted
• Multiple passes of clean up on the code
• Some passes on the source code for the tests. Many tests were changed, some dramatically. Some tests were added. I think the tests as they are now are probably ok. I think some checks that this PR can go through would be good, but a more thorough addressing of tests should be done in support of resolving Clean up tests #273 in later PRs.
• Correct and clean up comments within the source code. The legacy uncertainties code has a lot of comments and documentation. This PR is a part of a thrust to help simplify the source code so that it is a bit more self-documenting. With this, in the places touched by this PR, I want to slim down any comments, or at the very least make sure they are accurate. Especially with the removal of the derivatives attribute, I think there may be comments in lots of places that are no longer accurate. There are probably places I could add some comments.
• Update the documentation. I haven't touched the docs documentation at all. I think there will need to be a lot of updating there. Off the top of my head I know the docs make reference to the "derivatives of variables" philosophy that is being replaced with the "linear combination of random variables" philosophy. I also know there will be some docs about copying/pickling that need to be updated, and of course docs on derivatives and error_components will need to be updated.
• Bikeshed the naming of the UFloat, UCombo, and UAtom classes.
• Write the changelog entries

Other notes:

• COMMENT FOR REVIEWERS: Obviously I would appreciate wholistic reviews, But I'm especially curious for reviews on changes to the tests that start to illustrate how the public API is changing.
• See this change. The to_uarray_func conversion function assumes inputs are numpy arrays and doesn't "respect" numpy matrices. I made this choice because of the comment on numpy.matrix documentation discouraging their use. See 4.x Release plans #244 (comment). It seems like the maintainers are in some agreement that we can drop matrix support, so maybe consider this a step in that direction.
• I'll update this comment or later ones as I think of more changes or todos. I'll likely use this comment as a start for the changelog.

[wshanks]

I just wanted to note how Python ints work in practice. They are variable in size. There is a 28 byte overhead for all ints. Beyond that, every 30 bits in size adds 4 more bytes. So getting 64 bits will give 36 byte objects (except when you randomly get a number smaller than 2**59). Maybe it would be better to do getrandbits(60) here so the overhead per UAtom is 32 bytes instead of 36 if 60 bits seems like enough randomness. I wondered if randbytes() would be more efficient but bytes has an overhead of 34 bytes instead of the 28 for int. bytes scales linearly in the number of bytes stored but remains less efficient than int at these small sizes (8 bytes / 64 bits would be 42 bytes total). A float would take only 24 bytes but I worry about populating those bytes in an unbiased way.