Just.PreciseMath/README.md

# Just.PreciseMath

Extended-precision floating-point arithmetic for .NET using double-double
representations: a high/low pair of `double` values. The goal is to retain more
precision than a single `double` while using a fixed-size representation,
rather than arbitrary-precision arithmetic.

> **Work in progress.** The public API is incomplete and may change. Numerical
> contracts are covered by regression tests, not an exhaustive accuracy
> certification. The library is not ready for production use.

## DoubleDouble core

`DoubleDouble` stores a normalized high/low pair. Use `new DoubleDouble(value)`
for a single `double`, or `DoubleDouble.FromComponents(high, low)` for arbitrary
components. The factory normalizes finite sums and canonicalizes NaN/infinity
with a positive-zero low component. The two-component constructor is internal
and performs no normalization or validation; it is reserved for trusted,
already-normalized results. Mathematical constants use precomputed high/low pairs
checked against independently computed high-precision values; accessing them does
not perform double-double arithmetic or allocate on the heap.

- Arithmetic: unary `+`/`-`, binary `+`, `-`, `*`, `/`, and both operand orders with
  a `double`. Addition retains residuals under cancellation; multiplication uses
  fused multiply-add; division uses residual corrections. Mixed `double` operators
  use specialized scalar paths rather than promoting the scalar to `DoubleDouble`.
  Their finite fast paths normalize once with a final sum transform; scalar
  division uses one compensated quotient correction within the error contract below.
- Exponent boundaries: bounded `BigInteger` calculations avoid intermediate
  overflow and underflow on the exceptional finite path. Ordinary arithmetic uses
  floating-point transforms without allocations. The stored value remains two
  doubles; this is not an arbitrary-precision API.
- Comparisons use both components. `Equals` treats NaNs as equal and signed zeros
  as equal for collections. `CompareTo` orders NaN before other values. Numerical
  equality and relational operators treat NaN as unordered, like `double`.
- Signed zero is preserved by single-value construction and unary negation.
  `FromComponents` with a zero low input preserves the high zero's
  sign. Exact cancellation of nonzero values yields positive zero. Arithmetic
  special values follow binary64 rules.

Arithmetic is approximate double-double arithmetic, **not a promise of correctly
rounded 106-bit results**. The deterministic rational-oracle tests check a
conservative error bound of `2^-100` relative plus one minimum binary64 subnormal,
with exact component checks for selected representable cases. Near underflow,
extended precision necessarily decreases; overflow produces infinity. Performance
of the allocating exponent-boundary path is not covered by the basic benchmarks.

## Predefined mathematical constants

All constants below are static `DoubleDouble` properties. Each stores the nearest
binary64 high component followed by the nearest binary64 residual, rather than
calculating a ratio, root, or logarithm on access. Names use PascalCase, including
`Pi`, `E`, and `Ln2`.

| Group | Properties and values |
|---|---|
| Circle and common angles | `Pi` (π), `Tau` (2π), `PiOver2`, `PiOver3`, `PiOver4`, `PiOver6` |
| Angular conversion | `DegToRad` (π/180), `RadToDeg` (180/π), `InvPi` (1/π), `InvTau` (1/(2π), radians to turns) |
| Exponential and logarithmic | `E`, `InvE` (1/e), `Ln2` (ln 2), `Ln10` (ln 10) |
| Log-base conversion | `Log2E` (1/ln 2), `Log10E` (1/ln 10), `Log2Of10` (ln 10/ln 2), `Log10Of2` (ln 2/ln 10) |
| Roots and geometry | `Sqrt2`, `Sqrt3`, `Sqrt5`, `InvSqrt2`, `InvSqrt3`, `GoldenRatio` ((1+√5)/2) |
| Gaussian and error-function factors | `SqrtPi`, `InvSqrtPi`, `TwoInvSqrtPi` (2/√π), `SqrtTau` (√(2π)), `InvSqrtTau` (1/√(2π)) |

Multiply by conversion factors instead of recomputing them:

```csharp
using Just.PreciseMath;

DoubleDouble degrees = new(180.0);
DoubleDouble radians = degrees * DoubleDouble.DegToRad;
DoubleDouble convertedDegrees = radians * DoubleDouble.RadToDeg;
DoubleDouble quarterTurn = DoubleDouble.PiOver2;
```

The factors avoid deriving constants at runtime; the multiplication itself remains
approximate DD arithmetic, so conversions are not guaranteed exact round trips.
The list is mathematical and dimensionless, not a table of unit-dependent physical
constants. The natural logarithm function is provided separately by `DDMath.Log`.

## Mathematical functions

The `DDMath` static class provides:

- `Abs(DoubleDouble)`: preserves both components, maps either signed zero to
  positive zero and either infinity to positive infinity, and returns canonical NaN.
  It shares the existing `DoubleDouble.Abs` implementation.
- `Reciprocal(DoubleDouble)`: returns exactly the same high and low component bits
  as `1.0 / value`. It specializes scalar/DD division for a numerator of one,
  omitting only redundant numerator checks while preserving both divisions,
  the FMA sequence, and normalization. Signed zeros map to signed infinities,
  signed infinities to signed zeros, and NaN to canonical NaN. The allocating exact boundary
  path handles extreme exponents; finite overflow produces signed infinity.
  No speedup over scalar/DD division has been measured.
- `Sqrt(DoubleDouble)`: uses power-of-two scaling and an FMA-based Newton correction
  to retain extended precision, including for subnormal inputs, without squaring
  an unscaled estimate near the exponent limits. Signed zero and positive infinity
  are preserved; negative nonzero inputs and NaN return canonical NaN.
- `InvSqrt(DoubleDouble)`: computes the reciprocal square root with power-of-two
  scaling and a compensated Newton step, avoiding double-double division and its
  allocating boundary paths. The estimate's squared-product residual is retained
  with FMA. Signed zeros map to correspondingly signed infinities; positive infinity
  maps to positive zero; negative nonzero inputs and NaN return canonical NaN.
  This is a dedicated algorithm, not a claim of measured speedup over `1.0 / Sqrt(x)`.
- `Pow(DoubleDouble, int)`: exponentiation by squaring with a separately tracked
  binary exponent. Supports the full `int` domain, including `int.MinValue`, and
  reciprocates a bounded significand before final scaling for negative exponents.
  Any value to power zero is one (including NaN and signed zero). Other NaNs
  propagate; zero/infinity signs follow integer-power parity and exponent sign.
- `Pow(DoubleDouble, double)` and `Pow(DoubleDouble, DoubleDouble)`: arbitrary
  real powers, retaining the base's low component and, for the DD overload, the
  exponent's low component. For finite exponents, negative finite bases require integers;
  integrality and odd/even parity use the complete exponent, even above `2^53`.
  Integer-valued exponents within `int` range reuse the integer implementation.
  Other finite cases share `Log`'s range-scaled finite kernel, followed by `Exp`.
  Near-one bases retain tiny low components before multiplication by large powers.
- `Exp(DoubleDouble)`: binary range reduction with three components of `ln(2)`,
  followed by a [12/12] Padé approximation and power-of-two scaling. Both input
  components affect range boundaries; representable subnormals are retained.
  Either zero maps to one, negative infinity to positive zero, positive infinity
  to positive infinity, and NaN to canonical NaN.
- `Log(DoubleDouble)`: natural logarithm using binary range reduction and a
  centered atanh series. The bounded mantissa avoids denominator overflow for
  large inputs; a separate near-one path retains even minimum-subnormal low
  components. Either zero maps to negative infinity, one to positive zero,
  positive infinity to itself, and negative nonzero inputs or NaN to canonical NaN.

```csharp
using Just.PreciseMath;

DoubleDouble root = DDMath.Sqrt(new DoubleDouble(2.0));
DoubleDouble inverseRoot = DDMath.InvSqrt(new DoubleDouble(2.0));
DoubleDouble reciprocal = DDMath.Reciprocal(new DoubleDouble(3.0));
DoubleDouble magnitude = DDMath.Abs(-root);
DoubleDouble smallPower = DDMath.Pow(new DoubleDouble(2.0), -1024);
DoubleDouble exponential = DDMath.Exp(new DoubleDouble(1.0));
DoubleDouble logarithm = DDMath.Log(new DoubleDouble(10.0));
DoubleDouble fractionalPower = DDMath.Pow(new DoubleDouble(2.0), 0.5);
DoubleDouble preciseExponent = DoubleDouble.FromComponents(0.5, 1e-30);
DoubleDouble precisePower = DDMath.Pow(new DoubleDouble(2.0), preciseExponent);
```

Reciprocal tests check bitwise equivalence with `1.0 / value` and independently
check exact rational error against `2^-100` relative plus one minimum binary64
subnormal. They sample every binary64 exponent, both signs, dense and sparse lows,
binade neighbors, and special values; selected powers of two and sparse corrections
also have exact component checks. This preserves division's approximate-accuracy
contract, not a guarantee of correctly rounded results.

Square-root and inverse-square-root tests compare the exact component sum against
a `2^-100` relative error bound using integer inequalities. They include samples at every binary64
exponent, boundary neighbors, both signs of the low component, and exact binary
squares/powers of four. Square-root tests also bracket exact root-rounding midpoints;
both suites exercise half-ulp low-component normalization boundaries.
This is a tested approximate-accuracy contract, not exhaustive coverage
of all component pairs or a guarantee of correctly rounded results.

Logarithm tests compare exact component sums with independently generated
120-digit decimal references, requiring agreement at 450 and 650 digits. They
check `2^-100` relative error plus one minimum binary64 subnormal, with an explicit
reference-rounding allowance. Powers of two cover every finite binary64 exponent;
additional tests cover extreme magnitudes, near-one cancellation, sparse lows of
either sign, and range-reduction transitions. This is sampled approximate accuracy,
not a universal error proof or a correct-rounding guarantee.

Exponential tests use independent high-precision decimal references evaluated at
two precisions, with exact integer comparisons of the stored component sum. They
check `2^-100` relative error plus one minimum binary64 subnormal, with a separately
bounded reference-rounding allowance. Integer-power tests use exact rational
references and high-precision fixtures for large exponents; their tested absolute
error bound is `|exact result| * (|exponent| + 1) * 2^-100 + 2^-1074`, not uniform
relative accuracy independent of the exponent. Both functions are approximate;
precision decreases near underflow and approximation can affect results extremely
close to a rounding boundary. Final scaling uses the existing allocating exact
boundary machinery where necessary. No performance measurements are claimed.

For real powers, `x^±0 = 1` and `1^y = 1`, including NaN in the other operand;
other NaNs propagate. Infinite exponents compare the complete `|x|` with one,
with `(-1)^±∞ = 1`. Zero and infinite bases yield a negative sign only for odd
integer exponents; negative powers exchange zero and infinity. Finite negative
bases with non-integer finite exponents return canonical NaN.

Real-power reference tests check `2^-90` relative error plus one minimum binary64
subnormal for the logarithm/Exp path, with an explicit reference-rounding allowance.
Integer dispatch retains the exponent-dependent bound above. These are tested
approximate-accuracy contracts, not universal error proofs or correct-rounding
guarantees. Reference inputs are exact component sums; logarithms/exponentials
are independently evaluated at 450 and 650 decimal digits.

**Known real-power limitations:** extremely close to the range boundaries, the
logarithm/Exp path can return infinity for a mathematically finite result, or a
minimum subnormal where zero is expected. The latter can also break monotonicity
across integer-exponent dispatch. These issues remain unresolved; passing the
sampled error bounds does not guarantee correct range decisions for every input.

## Conversions and formatting

- Explicit conversions support `double`, `float`, `int`, `long`, and `decimal`
  in both directions. Integer inputs are exact. Decimal inputs use their exact
  coefficient and scale to compute the high component and its residual.
- Integer casts truncate the complete expansion toward zero and throw
  `OverflowException` for nonfinite or out-of-range results. `IConvertible`
  integer conversions instead round to nearest, ties to even, with range checks.
- Binary32 output rounds the complete expansion directly, including low-component
  decisions at midpoints. Decimal output rounds to the greatest fitting scale up
  to 28; nonfinite values and magnitudes above `decimal.MaxValue` throw.
- `IConvertible` reports `TypeCode.Object`, supports conversion to itself, and
  treats only numerical zero as false. Char, DateTime, and enum conversions are
  unsupported and throw `InvalidCastException`.
- `ToString` formats the exact component sum, supports culture-sensitive
  `G`/`g`, `E`/`e`, and `F`/`f`, and rounds ties to even. Precision is bounded to
  0–999; other standard and custom formats throw `FormatException`. Default
  `G32` is **not** shortest-round-trip formatting. NaN, infinities, and signed
  zero are supported without converting through decimal.
- `TryFormat(Span<char>, ...)` implements `ISpanFormattable` with the same formats.
  It currently allocates via `ToString`; insufficient space returns `false`, writes
  zero characters, and leaves the destination unchanged.

`DoubleDouble` implements `ISignedNumber<DoubleDouble>`, including the inherited
`INumberBase` contracts: binary radix, classification, absolute value, magnitude
selection, increment/decrement, and generic numeric conversions. Integer/parity
tests and magnitude comparisons retain both components. Magnitude ties prefer
positive values for maximum and negative values for minimum, including signed zero;
the `Number` variants prefer a number over NaN.

`CreateChecked`, `CreateSaturating`, and `CreateTruncating` support built-in numeric
types and `BigInteger`. Floating overflow produces signed infinity in all modes.
Finite integer output truncates the exact sum, then throws on overflow, clamps,
or retains the low destination-width bits, respectively. Decimal nonchecked output
clamps out-of-range values and maps NaN to zero. These policies are distinct from
the existing casts and `IConvertible` conversions above.

Conversions, parsing, and formatting use allocating `BigInteger` intermediates
where needed to preserve precision; no additional dependency is required.

## Parsing

`Parse` and `TryParse` accept strings and `ReadOnlySpan<char>` and implement
`IParsable<DoubleDouble>` / `ISpanParsable<DoubleDouble>`. This initial parser
preserves high/low precision rather than parsing through `double` or `decimal`.
It converts an exact decimal coefficient/exponent into rounded high and residual
components, then normalizes the pair. It does not promise universally correctly
rounded 106-bit results or a general `ToString` round trip.

```csharp
using System.Globalization;
using Just.PreciseMath;

DoubleDouble value = DoubleDouble.Parse("9007199254740993", CultureInfo.InvariantCulture);
// value.High == 9007199254740992.0; value.Low == 1.0

bool success = DoubleDouble.TryParse("1.25e-2".AsSpan(), CultureInfo.InvariantCulture,
    out DoubleDouble parsed);
```

- Provider-only finite grammar: optional sign, ASCII decimal digits with an optional decimal
  separator, and optional `e`/`E` exponent with sign and digits. At least one
  mantissa digit is required; `.5` and `1.` are accepted with invariant culture.
  Surrounding whitespace is allowed; internal whitespace is not.
- Signs and the decimal separator come from the supplied culture; a null or
  omitted provider uses the current culture. Culture-specific NaN and infinity
  symbols are recognized case-insensitively. The additional alias `inf` accepts an
  optional culture-specific sign (`inf`, `+inf`, `-inf` with invariant culture).
  Exact custom special symbols take precedence over the alias. Special values accept
  surrounding whitespace and signs even with `NumberStyles.None`; ordinary finite
  numbers still obey the supplied style flags. Signed zero is preserved.
- Provider-only overloads reject grouping, currency, and parentheses. Explicit
  `NumberStyles` overloads support decimal flags through `NumberStyles.Any`, including
  grouping, currency, parentheses, and trailing signs; group sizes are not validated.
  Hexadecimal, binary, and undefined style flags throw `ArgumentException`, including
  in `TryParse`. Hexadecimal notation and programming-language digit separators
  remain unsupported.
- Input is limited to **2048 characters**, including surrounding whitespace.
  Huge exponents are bounded before constructing powers of ten. Well-formed
  overflow succeeds with signed infinity; underflow rounds to a subnormal or
  signed zero. A second rounding just below the overflow midpoint stays finite.
- `Parse` throws `ArgumentNullException` for a null string and `FormatException`
  for invalid, unsupported, or oversized input. `TryParse` returns `false` and
  positive `Zero` for those inputs.

## Deferred scope

Natural `DDMath.Log`, `Exp`, and all three `Pow` overloads are implemented.
Logarithms in other bases, generic-math interfaces beyond `ISignedNumber`,
additional text formats/general round-trip formatting, and non-arithmetic performance
benchmarks remain deferred.
Replacing allocating arithmetic boundary fallbacks is also deferred; the current
`BigInteger` paths remain in place. That optimization does not require removing
`BigInteger` from conversions, parsing, formatting, or independent test oracles.

## Build and test

Requires the .NET 10 SDK in the `10.0.1xx` feature band, as selected by `global.json`.
Run from the repository root:

```sh
dotnet restore Just.PreciseMath.slnx --locked-mode
dotnet build Just.PreciseMath.slnx -c Release --no-restore
dotnet test --solution Just.PreciseMath.slnx -c Release --no-build --minimum-expected-tests 1
dotnet format Just.PreciseMath.slnx --verify-no-changes --no-restore
```

Test results and coverage reports are available in the `test-results` artifact
on CI workflow runs.

## Benchmarks

BenchmarkDotNet measures arithmetic throughput, dependent-chain latency, and allocations,
including comparisons of `DoubleDouble`, `decimal`, and `double`, mixed scalar operations,
and exponent-boundary paths. These are performance measurements, not accuracy tests.

After the Release build above, run from the repository root:

```sh
# Discover benchmark methods without running them.
dotnet run --project 2-benchmarks/Just.PreciseMath.Benchmarks -c Release --no-build -- --list flat

# Smoke test; Dry timings are not performance measurements.
dotnet run --project 2-benchmarks/Just.PreciseMath.Benchmarks -c Release --no-build -- --job Dry --filter '*'

# Full measurement run.
dotnet run --project 2-benchmarks/Just.PreciseMath.Benchmarks -c Release --no-build -- --filter '*'
```

Reports are written under the ignored `BenchmarkDotNet.Artifacts/` directory.
Replace `'*'` with a benchmark-name pattern to select a subset; use `--artifacts <path>`
to keep runs separate. Run measurements on an idle machine and inspect BenchmarkDotNet warnings.

## Project structure

- `0-source/Just.PreciseMath/`: library implementation.
- `1-tests/Just.PreciseMath.Tests/`: unit tests.
- `2-benchmarks/Just.PreciseMath.Benchmarks/`: arithmetic benchmarks against `decimal` and `double`.

## Contributing

Follow `.editorconfig` and include regression tests with numerical changes.
Explain the algorithm's assumptions, the source of reference values, and any
error tolerances. Include updated `packages.lock.json` files with dependency changes.

## License

Licensed under the [MIT License](LICENSE).