[markbujehein]

Summary

This adds es.math, a set of maths functions that take Parameter objects and return a new Parameter. 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.

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.
• 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 in 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.

Tests

• tests/unit/variable/test_math.py: unit tests for values, bounds, variance, domain errors, units 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

[markbujehein]

As far as I can tell, the workflows .github/workflows/docs.yml and .github/workflows/tutorial-tests.yml will inherently fail for any PR from a fork

Not sure what's is going on with .github/workflows/lint-format.yml, but seems to be related to the ongoing refactoring (?)