Make StorageMath public, and add Cbrt, RootN and Hypot

[matt-edmondson]

Fixes #239

StorageMath.Sqrt is the piece of this library that System.Numerics does not offer: a root at the precision of an arbitrary INumber<T>, with no IRootFunctions<T> constraint — which is the whole trick, since decimal could not have satisfied that constraint anyway. It was internal, and the generated quantities were its only callers, so an application computing a norm the generator does not emit had to reimplement it.

What changed

The class and Sqrt are public, with what they guarantee written into the XML docs rather than left to be discovered, since this is the point at which the shape freezes:

• MaximumIterations = 256, and the ArithmeticException on a root that does not settle
• the double round trip for the binary floating point and integer primitives — Sqrt<double> is Math.Sqrt, not a refinement of it
• the floor for integer types
• OverflowException rather than NaN for a negative value on a type that has no NaN

IsRoundedThroughDouble, Seed and TryRootThroughDouble stay private, as the issue asks. This takes option 1 from the issue's "one thing to agree before merging" — a public static class with static methods, the smallest diff and the shape that is already there. Option 3, an IStorageMath<T> a caller could substitute, is deliberately not taken here: it is worth having only once there is a higher-precision root to inject (ktsu-dev/PreciseNumber#80), and it can be added later over these methods without them becoming a second way to do the same thing. Say the word if you would rather have it now, before this ships.

Cbrt, RootN and Hypot ship alongside, on the same seeding and the same loop, since they are what a caller asks for next:

• RootN refines by x = (((n - 1) * x) + (value / x^(n - 1))) / n; a value outside the range of double is scaled by powers of 2^n into [1, 2^n) for its seed, the same trick Sqrt plays with powers of four.
• Cbrt and RootN take the double route only for the binary floating point primitives, and refine every integer type in integer arithmetic. So their floor is exact rather than whatever Math.Pow happened to round to — Cbrt(27) == 3, not 2.
• Every power is taken checked, because a narrow type can hold a value whose estimate^(n-1) it cannot, and an estimate that wrapped would send the steps somewhere arbitrary. A degree so high that the type cannot hold 2^n is answered before any of that: no value the type holds has a root of two or more.
• Hypot computes a fractional type as larger * Sqrt(1 + (smaller / larger)²), so a pair whose squares leave the range of the type still has its hypotenuse — Hypot(1e20m, 1e20m) answers where 1e20m * 1e20m throws. An integer type squares and sums directly, since the ratio of two integers is not a ratio.

Exp, Log and trig stay out, as the issue scopes them: they need a series and belong to the storage type.

Sqrt itself is untouched — visibility and documentation only — so every existing quantity result is unchanged.

Tests

StorageMathTests grows 13 test methods, and the class is now 43 tests:

• TheRootsArePublicAndTheirWorkingsAreNot asserts the surface in both directions — the four methods public, the nine private helpers not. Making the class internal again fails it; the rest of the new tests do not compile at all without the change.
• the primitives are asserted against Math.Cbrt and double.Hypot directly, so a change to their results fails here
• decimal is asserted at its own precision (cubing the refined root lands nearer 2 than cubing the double one), and on exact cubes including negative ones
• BigInteger well beyond the range of double: Cbrt(10^300), RootN(10^500, 5), and the neighbours either side that pin the floor
• the narrow-type edges: RootN(100, 20), RootN(int.MaxValue, 40), and a degree below one throwing

Verification

• dotnet build over the solution: clean, no warnings (this repo builds warnings as errors, across net8.0–net10.0)
• full suite: 1274 tests, 0 failed (8 skipped, all Windows-only path tests)
• reverting StorageMath.cs and rebuilding fails the new tests, as above

CLAUDE.md, docs/physics-generator.md and the package README record the new surface.

🤖 Generated with Claude Code

https://claude.ai/code/session_01A9Ke7x6EeGyKHfPHncbNrP

---

Generated by Claude Code

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
88.8% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud