77 lines
3.9 KiB
Markdown
77 lines
3.9 KiB
Markdown
# 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](review-legacy/Review-Revisited-DoubleDouble.md)
|
|
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.
|
|
|
|
```sh
|
|
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
|
|
```
|
|
|
|
Commit each project's `packages.lock.json` with dependency changes. CI caches
|
|
NuGet packages using those lock files and always runs `dotnet restore --locked-mode`,
|
|
including on cache hits. After intentional dependency updates, run
|
|
`dotnet restore --force-evaluate` and review the updated lock files before committing.
|
|
Gitea's runner cache must be reachable from the job container, with persistent
|
|
storage if the runner itself is recreated. No build outputs are cached.
|
|
|
|
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:
|
|
|
|
```sh
|
|
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](LICENSE), included in the package.
|
|
Do not publish this scaffold as a usable numerical library.
|