From 84848cff18d87563ddf71c2313058c2504406bff Mon Sep 17 00:00:00 2001 From: Isabelle Santin Date: Fri, 20 Mar 2026 10:06:08 -0500 Subject: [PATCH] Docs: update README to add documentation and guidelines --- README.md | 67 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 64 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 15a9225..bdc198d 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ QuadrupleLib is a modern implementation of the IEEE 754 `binary128` floating point number type for .NET 8 and above based on the `UInt128` built-in. The goal of this project is to create a fully fleshed out 128-bit floating point arithmetic library that includes all of the bells and whistles one could possibly want. -### Project TODOs (Completed) +# Main Features - [x] Adheres to recommended requirements of IEEE 754 specification - [x] Implements .NET 8 `IBinaryFloatingPointIeee754` generic arithmetic interface @@ -14,7 +14,68 @@ QuadrupleLib is a modern implementation of the IEEE 754 `binary128` floating poi - [x] Supports all recommended rounding modes for arithmetic - [x] Implements basic `ToString` and `Parse`/`TryParse` methods - [x] Supports .NET Core formatting features for `ToString` and `Parse` -- [x] Implements conversion methods to & from all standard number types +- [x] Implements conversion methods to & from all standard number types (except `decimal`) - [x] Implements `IEEERemainder` as suggested in IEEE 754 - [x] Implements typical library functions (`Pow`, `Atan2`, `Log`) -- [x] Unit tests to check for specification coverage +- [x] Unit tests to check for specification coverage & overall correctness + +# Using QuadrupleLib + +QuadrupleLib is available as a regularly updated [NuGet package](https://www.nuget.org/packages/QuadrupleLib), published via my GitHub Actions workflow. Alternatively, see the [Releases](https://github.com/IsaMorphic/QuadrupleLib/releases) page for a downloadable version you may use in your local or private feeds. + +## Basic Usage + +To use QuadrupleLib in your project, simply add the `PackageReference` to your `.csproj` file and add the following `using` statement to the top of any single file in your project: + +```csharp +global using Float128 = QuadrupleLib.Float128; +``` + +The `Float128` type as defined above includes a full implementation of the .NET 8 `IBinaryFloatingPointIeee754` generic arithmetic interface. You may use it as thus either generically or concretely. Generally, anywhere you're using `double` or `float` arithmetic, you can use `Float128` as a drop-in replacement and everything will work as expected. + +## Defining `Float128` Constants + +For defining high-precision constants, it is highly recommended that `Float128.Parse` is used with a given `const string`. While literal `double` and `long` values can be implicitly converted to `Float128`, you will not be able to specify the maximum amount of significant digits that you would otherwise be able to using the `Parse` method. See the example below for reference: + +```csharp +private const string PI = "3.1415926535897932384626433832795028"; + +private static readonly Float128 _pi = Float128.Parse(PI); +public static Float128 Pi => _pi; +``` + +## Notes on Hardware Acceleration + +`Float128` is a generic type offered by the library which can accept one of two "accelerators" that are built-in: `DefaultAccelerator` and `SoftwareAccelerator`. The former uses typical hardware accelerated intrinsics for 128-bit multiplication and division operations, while the latter provides a custom, software defined version of the same thing. In almost all cases, you'll want to use `DefaultAccelerator`, unless you are running your code on a platform that does not include intrinsics for 128-bit arithmetic. In those cases, `SoftwareAccelerator` provides a faster alternative that is widely compatible. The most notable example of such a platform is when using QuadrupleLib in conjunction with [ILGPU](https://ilgpu.net), a JIT compiler for running .NET code on the GPU. + +# Development Guide + +Interested in tinkering with the source code? Feel free to fork this repo and/or clone it as a submodule in your project: + +```bash +git submodule add "https://github.com/IsaMorphic/QuadrupleLib.git" "external/QuadrupleLib" +git commit -m "Feature: add QuadrupleLib as submodule" +cd external/QuadrupleLib +``` + +Then, to build the source code, make sure the .NET 10 SDK is installed on your machine, and run: + +```bash +dotnet build --no-incremental +``` + +Next, to run unit tests, use the following command: + +```bash +dotnet test --no-build +``` + +To build the NuGet package, use the following command: + +```bash +dotnet pack --no-build --output build/ +``` + +# Contributing + +Before contributing any changes to the project, make sure that all the standard unit tests are passing. If your changes are a work-in-progress, please mark those PRs as drafts. I will not accept any changes which do not pass all existing unit tests; any new features should include new tests to cover them. Finally, do NOT contribute code written by Copilot or other LLMs. QuadrupleLib is written by humans, for humans.