Add maths module for Parameters & DescriptorNumbers with variance and bounds propagation

[markbujehein]

Summary

This adds es.math, a set of maths functions that take a DescriptorNumber or a Parameter and return a new object of the base class. Each result carries:

• value: evaluated by Scipp, which also validates units.
• variance: propagated to first order (delta method).
• fitting bounds: the exact range the function can reach when its argument stays inside its own bounds. Only a Parameter result has bounds.

The functions are:

• Trig: sin, cos, tan, sinc, arcsin, arccos, arctan, arctan2, plus the aliases asin, acos, atan and atan2.
• Hyperbolic: sinh, cosh, tanh, arcsinh, arccosh, arctanh, plus the aliases asinh, acosh and atanh.
• Other: exp, log, log10, sqrt, erf, erfc.

The implementation is in easyscience.variable.math. easyscience.math is a thin re-export, so es.math.sin(angle) works. The names are also exported from easyscience.variable.

Motivation

This work is motivated by the needs discussed in

• Add support for more math functions for Parameters and DescriptorNumbers #297
• Support more functions for Parameters such as sin and cos #201
• `ADR suggestion`: Support trigonometric functions in `Parameter`s #212

Design

• Spec-driven dispatch. Each function is an immutable _MathOp spec (Scipp function, domain, bounds strategy). One dispatcher, _apply, handles all of them, so adding a function means adding a spec rather than new control flow.
• Input and result types. Every function accepts a DescriptorNumber or a Parameter, including user subclasses.
  • The result is a Parameter if any argument is a Parameter, and a DescriptorNumber otherwise. It is always the base class, never a subclass.
  • A DescriptorNumber argument counts as the point [value, value] when bounds are derived.
  • Unary functions are typed with a TypeVar. arctan2 has three overloads, so mixed calls type-check.
• Exact bounds. Bounds come from the endpoints and critical points, not a sampled grid. A grid could miss an extremum and make Parameter.from_scipp raise. Degrees are converted to radians for trig bounds.
• Strict values, permissive bounds.
  • A value outside the function's domain, or a non-finite result, raises ValueError, because it would break a fit loop.
  • Bounds never raise. They are clipped to the domain, infinite bounds are accepted, and bounds that collapse to a single number are padded by a relative 2e-9.
  • tan handles asymptotes per side. For example, [0, 90] deg gives [0, inf), and a lower bound exactly on an asymptote gives -inf.
• Variance. Scipp handles most functions. erf, erfc and arctan2 use a Jacobian because Scipp doesn't support them. tan rejects values near an asymptote, where the variance would blow up.

Other changes

• Top-level __all__ fix. easyscience/__init__.py and variable/__init__.py listed the objects themselves, including the __version__ string, instead of their names. As a result, from easyscience import * raised AttributeError. Both now list strings, and variable.__all__ includes math.__all__.
• es.math and the top-level __all__. math is imported so es.math works, but it is deliberately left out of the top-level __all__. A star import would otherwise shadow the stdlib math. A test covers this.
• from_scipp return type. It now returns Self (PEP 673) in descriptor_number.py, so calling it on a subclass such as Parameter type-checks.
• Docs. New docs/api-reference/math.md, nav entry and index entry. All 20 public functions have docstring examples that were executed and cross-checked against independent formulas. The docstrings follow the repo's docstring-lint rules.
• Lint and format housekeeping, unrelated to the maths code.
  • Docstring-only lint fixes in fitting/sampler.py and fitting/minimizers/minimizer_bumps.py. No code changes.
  • Re-formatting of pixi.toml, pyproject.toml and prettierrc.toml. Whitespace, comment spacing and key layout only.
  • These could be split into their own PR if a smaller diff is preferred.

Tests

• tests/unit/variable/test_math.py: unit tests for values, bounds, variance, domain errors, units, input and result classes, subclasses, mixed arctan2 arguments, the unit keyword, the guards and the namespace. They are written in the repo's WHEN / THEN / EXPECT style.
• tests/integration/fitting/test_math_in_fit.py: es.math used inside models (straight line, angle in degrees, quadrature, Gaussian peak with a derived width) across minimizers.
• A strict xfail documents the known limitation described below.

Known limitations and notes for reviewers

• Correlations are ignored. Variances assume uncorrelated inputs, because a Parameter stores a variance but no covariance. A function of strongly correlated fit parameters can be off by a large factor. The strict xfail test documents this, and the module docstring explains it.
• Results are snapshots. A result doesn't follow later changes to its inputs. Inside a model, derive it in __call__, not __init__. The module docstring has a worked example.
• Open points for the lead developer. These are marked NOTE() and TODO() in math.py:
  • The 1σ thresholds for the tan guards.
  • Snapshot results are not fixed.
  • The cost per evaluation.
  • The hard-coded tolerance in the bounds padding.
• pixi.lock. 419828c modifies pixi.lock. It looks like the result of running pixi install, so please check whether it should stay in this PR. Seems like Pixi is updating the lock file to a newer format.
• Out of scope. This PR does not yet address the issues mentioned in:
  • Speed up calculations of dependent parameters by bypassing unit handling #298
  • Propagate variances correctly in dependency expressions #299

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.05%. Comparing base (511a8e4) to head (db1f696).

Additional details and impacted files

@@             Coverage Diff             @@
##           develop     #329      +/-   ##
===========================================
+ Coverage    83.24%   84.05%   +0.81%     
===========================================
  Files           63       64       +1     
  Lines         5324     5595     +271     
===========================================
+ Hits          4432     4703     +271     
  Misses         892      892              

Flag	Coverage Δ
unittests	84.05% <100.00%> (+0.81%)	⬆️

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

Files with missing lines	Coverage Δ
src/easyscience/__init__.py	100.00% <100.00%> (ø)
.../easyscience/fitting/minimizers/minimizer_bumps.py	99.27% <ø> (ø)
src/easyscience/fitting/sampler.py	100.00% <ø> (ø)
src/easyscience/math.py	100.00% <100.00%> (ø)
src/easyscience/variable/__init__.py	100.00% <ø> (ø)
src/easyscience/variable/descriptor_number.py	95.42% <100.00%> (+0.01%)	⬆️

[rozyczko]

Minor comments added. Consider combining both math.py modules into one, as mentioned.

[markbujehein]

@rozyczko fully agree. I just pushed the requested changes and rebased #331 to match

[rozyczko]

@rozyczko fully agree. I just pushed the requested changes and rebased #331 to match

I'm fine with changes, but it would probably be good to ask @damskii9992 to look at it as well