Just.PreciseMath/README.md

Just.PreciseMath

WIP — initial library implementation and one smoke test; numerical correctness is not yet validated.

A .NET 10 library being developed for extended-precision floating-point arithmetic using double-double representations (a high/low pair of double values), with common mathematical functions. This is fixed extended precision, not arbitrary precision; accuracy guarantees and the public API are not settled.

Planned scope

• Double-double arithmetic, constants, comparisons, conversions, and formatting.
• Common functions including Abs, Sqrt, Pow, Exp, and Log.
• Correctness tests against higher-precision references and performance benchmarks.

The consolidated legacy review is the starting point. Priorities are normalization and special-value contracts (NaN, infinities, signed zero), corrected constants and scalar subtraction, consistent comparisons, precision-preserving conversions/formatting, and range-safe arithmetic and transcendental functions, including cancellation and subnormal cases. The files in review-legacy/ contain known defects: they are reference material only, are not compiled, and should not be used in production.

Layout

• 0-source/Just.PreciseMath/ — library and package metadata.
• 1-tests/Just.PreciseMath.Tests/ — xUnit v3, Shouldly, and MTP-native Coverlet.
• 2-benchmarks/Just.PreciseMath.Benchmarks/ — BenchmarkDotNet scaffold.
• review-legacy/ — original implementation and numerical reviews.

Development

Use the .NET 10 SDK selected by global.json (10.0.1xx, latest installed patch). Shared settings enable nullable analysis, .NET 10 recommended analyzers, build-time code-style checks, and warnings as errors. .editorconfig retains advisory style preferences alongside explicitly enforced warning/error rules.

dotnet restore Just.PreciseMath.slnx
dotnet build Just.PreciseMath.slnx -c Release --no-restore
dotnet test --solution Just.PreciseMath.slnx -c Release --no-build
dotnet format Just.PreciseMath.slnx --verify-no-changes --no-restore

The initial smoke test checks that DoubleDouble.One exposes high and low components of 1.0 and 0.0. It exercises the test/coverage pipeline, not the numerical accuracy of the planned library.

CI collects TRX test results and Cobertura coverage for Just.PreciseMath only, excluding test dependencies, and requires at least one test. The test-results artifact contains TRX test results and timestamped Cobertura XML coverage reports, retained for three days. Open the workflow run in Gitea Actions and download that artifact. Upload is attempted even when tests fail; no badges or repository-write token are needed.

To generate the same reports locally:

dotnet test --solution Just.PreciseMath.slnx -c Release --no-build --minimum-expected-tests 1 --report-xunit-trx --coverlet --coverlet-output-format cobertura --coverlet-include "[Just.PreciseMath]*"

Reports are written under each test project's bin/Release/net10.0/TestResults/. The benchmark project deliberately builds as a library without source files; add an entry point and benchmark cases, then change OutputType to Exe and run it in Release without a debugger. No performance results exist yet.

Package metadata uses the development version 0.1.0-dev. Licensed under the MIT License, included in the package. Do not publish this scaffold as a usable numerical library.