QuadrupleLib 0.1.6

QuadrupleLib

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.

Main Features

• Adheres to recommended requirements of IEEE 754 specification
• Implements .NET 8 IBinaryFloatingPointIeee754 generic arithmetic interface
• Implements all basic arithmetic operations (+, -, *, /, %, ++, --)
• Implements all standard rounding functions (Round, Floor, Ceiling)
• Supports all recommended rounding modes for arithmetic
• Implements basic ToString and Parse/TryParse methods
• Supports .NET Core formatting features for ToString and Parse
• Implements conversion methods to & from all standard number types (except decimal)
• Implements IEEERemainder as suggested in IEEE 754
• Implements typical library functions (Pow, Atan2, Log)
• Unit tests to check for specification coverage & overall correctness

Using QuadrupleLib

QuadrupleLib is available as a regularly updated NuGet package, published via my GitHub Actions workflow. Alternatively, see the 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:

global using Float128 = QuadrupleLib.Float128<QuadrupleLib.Accelerators.DefaultAccelerator>;

The Float128 type as defined above includes a full implementation of the .NET 8 IBinaryFloatingPointIeee754<T> 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:

private const string PI = "3.1415926535897932384626433832795028";

private static readonly Float128 _pi = Float128.Parse(PI);
public static Float128 Pi => _pi;

Notes on Hardware Acceleration

Float128<TAccelerator> 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, 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:

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:

dotnet build --no-incremental

Next, to run unit tests, use the following command:

dotnet test --no-build

To build the NuGet package, use the following command:

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.