SoftPosit

This is a fork of the original SoftPosit repository created by Cerlane Leong. We would like to thank the original authors for their work.

Quick Reference

Basic Types

```c

include "softposit.h"

posit8t p8; // 8-bit posit (0 exponent bits) posit16t p16; // 16-bit posit (1 exponent bit)
posit32_t p32; // 32-bit posit (2 exponent bits)

quire8t q8; // 8-bit quire (for accumulation) quire16t q16; // 16-bit quire quire32_t q32; // 32-bit quire ```

Common Operations

```c // Arithmetic posit16t sum = p16add(a, b); // a + b posit16t diff = p16sub(a, b); // a - b
posit16t prod = p16mul(a, b); // a * b posit16t quot = p16div(a, b); // a / b posit16t fma = p16mulAdd(a, b, c); // a*b + c

// Conversions posit16t p = convertDoubleToP16(3.14159); double d = convertP16ToDouble(p); posit8t p8 = p16top8(p);

// Comparisons
bool equal = p16eq(a, b); // a == b bool less = p16lt(a, b); // a < b bool lesseq = p16le(a, b); // a <= b

// Math functions (experimental) posit16t root = p16sqrt(p); posit16t sine = p16sinpi(p); posit16t logarithm = p16_ln(p); ```

Table of Contents

• Quick Start
• Development Workflow
• Advanced Build Options
• Experimental Features
• Project Structure
• Compatibility and Testing
• Quick Reference
• C API Documentation
• C++ API Documentation
• Python Wrapper
• Julia Integration
• Known Implementations

Quick Start

Prerequisites

• CMake 3.1 or higher
• C/C++ Compiler: GCC, Clang, or MSVC
• clang-format-14 (for code formatting)

Building and Testing

```bash

Clone the repository

git clone https://github.com/Posit-Foundation/soft-posit-cpp.git cd soft-posit-cpp

Create build directory and configure

mkdir build && cd build cmake .. -DCMAKEBUILDTYPE=Release -DBUILDTESTS=ON -DBUILDBENCHMARKS=ON

Build the library

make -j$(nproc) # Linux

make -j$(sysctl -n hw.ncpu) # macOS

Run all tests

make check

Run all benchmarks

make bench ```

Development Workflow

Supported Branches

Our CI/CD workflows run on:

• main - Stable release branch
• refactor-cpp-soft-posits - Active development branch

Pull requests targeting either of these branches will trigger automated builds, tests, and code quality checks.

Code Formatting

This project uses clang-format-14 for consistent code formatting. Before submitting any changes:

1. Format your code:

```bash # Format all C/C++ files ./format_code.sh

# Or manually with clang-format-14 find . -name ".c" -o -name ".cpp" -o -name ".h" -o -name ".hpp" | \ xargs clang-format-14 -i ```

1. Verify formatting:

bash clang-format-14 --dry-run --Werror src/ include/ tests/ examples/

The formatting configuration is defined in .clang-format.

Continuous Integration

Our automated workflows include:

• Build Validation: Cross-platform builds (Ubuntu, macOS)
• Comprehensive Testing: All posit operations and edge cases
• Code Quality Checks:
  • clang-format style enforcement
• Performance Benchmarks: Automated performance regression detection

Contributing

1. Fork the repository and create a feature branch from refactor-cpp-soft-posits
2. Make your changes following the coding standards
3. Format your code using ./format_code.sh
4. Run tests locally: cd build && make check
5. Submit a pull request targeting refactor-cpp-soft-posits or main

All pull requests must pass:

• ✅ Build validation on Ubuntu and macOS
• ✅ Complete test suite
• ✅ Code formatting checks (clang-format-14)

Advanced Build Options

Build Configuration

```bash

Development build with debug symbols

cmake .. -DCMAKEBUILDTYPE=Debug -DBUILD_TESTS=ON

Release build with optimizations

cmake .. -DCMAKEBUILDTYPE=Release -DBUILDTESTS=ON -DBUILDBENCHMARKS=ON

Build with experimental features

cmake .. -DENABLEEXPERIMENTALTESTS=ON

Custom installation directory

cmake .. -DCMAKEINSTALLPREFIX=/usr/local ```

CMake Options

| Option | Default | Description | |--------|---------|-------------| | BUILD_TESTS | ON | Build test executables | | BUILD_BENCHMARKS | OFF | Build benchmark executables | | ENABLE_EXPERIMENTAL_TESTS | OFF | Enable tests for experimental features | | BUILD_SHARED_LIBS | OFF | Build shared libraries instead of static |

Installation

```bash

Install the library and headers

cd build make install

Create distribution packages

make package ```

Legacy Build Information

Note: The legacy Makefile-based build system is deprecated. Please use CMake as shown above.

Experimental Features

Some advanced mathematical functions are under active development and can be enabled with the ENABLE_EXPERIMENTAL_TESTS option:

bash cmake .. -DENABLE_EXPERIMENTAL_TESTS=ON

Experimental functions include:

• Trigonometric: sin_pi, cos_pi, tan_pi
• Inverse trigonometric: asin_pi, acos_pi, atan_pi
• Logarithmic: log2, ln
• Exponential: exp, exp2
• Rounding: ceil, floor

⚠️ Warning: Experimental functions may not be fully tested or optimized. Use with caution in production code.

This version (0.4.1) supports:

32-bit with two exponent bit (posit32_t).  -> Not exhaustively tested

16-bit with one exponent bit (posit16_t). 

8-bit with zero exponent bit (posit8_t). 

2-bit to 32-bit with two exponent bits (posit_2_t) -> Not fast : Using 32-bits in the background to store all sizes.
    Exhaustively tested for X=(2:32) : pX2_rint, pX2_to_pX2, pX2_to_i32/64, pX2_to_ui32/64, pX2_sqrt, ui/i32_to_pX2
    Exhaustively tested for X=(2:13) : ui64_to_pX2, i64_to_pX2
    Exhaustively tested for X=(2:20) : pX2_add, pX2_sub, pX2_mul, pX2_div
    Exhaustively tested for X=(2:21) : pX2_mul
    Exhaustively tested for X=(2:15) : pX2_mulAdd
    Exhaustively tested for X=(2:14) : quireX2_fdp_add, quireX2_fdp_sub (using quire32 as the underlying code)

This code is tested on

• GNU gcc (SUSE Linux) 4.8.5
• Apple LLVM version 9.1.0 (clang-902.0.39.2)
• Windows 10 (Mingw-w64)

Please note that the same Makefile in build/Linux-x86_64-GCC is used for all 3 operating systems.

All posit8t and posit16t operations are exhaustively tested with exception of p16mulAdd and q16fdp_add/sub operations.

posit32_t operations are still being tested exhaustively for correctness. It will take weeks to months before these tests complete.

Versions are offered

• Fast C version : The main source code where all other versions are based on.
• User friendly C++ version : Documentation can be found below.
• User friendly Python version : https://gitlab.com/cerlane/SoftPosit-Python/
• Julia : Currently only simple .so support. Documentation can be found below.
• Others

Fast C version

posit8_t pA, pB, pZ;
pA = castP8(0xF2);
pB = castP8(0x23);

pZ = p8_add(pA, pB);

//To check answer by converting it to double
double dZ = convertP8ToDouble(pZ);
printf("dZ: %.15f\n", dZ);

//To print result in binary
uint8_t uiZ = castUI(pZ);
printBinary((uint64_t*)&uiZ, 8);

return 0;

posit16_t pA, pB, pZ;
pA = castP16(0x0FF2);
pB = castP16(0x2123);

pZ = p16_mul(pA, pB);

//To print result in binary
uint16_t uiZ = castUI(pZ);
printBinary((uint64_t*)&uiZ, 16);

return 0;

posit_2_t pA, pB, pZ;
pA.v = 0xF2; //this is to set the bits (method 1)
pB = castPX2(0x23); //this is to set the bits (method 2)

pZ = pX2_add(pA, pB, 24);

//To check answer by converting it to double
double dZ = convertPX2ToDouble(pZ);
printf("dZ: %.40f\n", dZ);

//To print result in binary
printBinaryPX((uint32_t*)&pZ.v, 24);

//To print result as double
printf("result: %.40f\n", convertPX2ToDouble(pZ));

return 0;

 posit16_t p16_add(posit16_t, posit16_t)

 posit8_t p8_add(posit8_t, posit8_t)

posit16_t p16_sub(posit16_t, posit16_t)

posit8_t p8_sub(posit8_t, posit8_t)

posit16_t p16_div(posit16_t, posit16_t)

posit8_t p8_div(posit8_t, posit8_t)

posit16_t p16_mul(posit16_t, posit16_t)

posit8_t p8_mul(posit8_t, posit8_t)

posit16_t p16_mulAdd(posit16_t, posit16_t, posit16_t)

posit8_t p8_mulAdd(posit8_t, posit8_t, posit8_t)


Note: p16_mulAdd(a, b, c) <=> a*b + c

quire16_t q16_fdp_add(quire16_t, posit16_t, posit16_t)

quire8_t q16_fdp_add(quire8_t, posit8_t, posit8_t)

Note: q8_fdp_add (a, b, c) <=> a + b*c

quire16_t q16_fdp_sub(quire16_t, posit16_t, posit16_t)

quire8_t q8_fdp_sub(quire8_t, posit8_t, posit8_t)

quire16_t q16_clr(quire16_t)

quire8_t q8_clr(quire8_t)

posit16_t q16_to_p16(quire16_t)

posit8_t q8_to_p8(quire8_t)

posit16_t p16_sqrt(posit16_t)

posit8_t p8_sqrt(posit8_t)

posit16_t p16_roundToInt(posit16_t)

posit8_t p8_roundToInt(posit8_t)

bool p16_eq( posit16_t, posit16_t )

bool p8_eq( posit8_t, posit8_t )

bool p16_le( posit16_t, posit16_t )

bool p8_le( posit8_t, posit8_t )

bool p16_lt( posit16_t, posit16_t )

bool p8_lt( posit8_t, posit8_t )

int_fast32_t p16_to_i32( posit16_t )

int_fast32_t p8_to_i32( posit8_t )

int_fast64_t p16_to_i64( posit16_t)

int_fast64_t p8_to_i64( posit8_t)

posit16_t ui32_to_p16( uint32_t a )

posit8_t ui32_to_p8( uint32_t a )

posit16_t ui64_to_p16( uint64_t a )

posit8_t ui64_to_p8( uint64_t a )

posit16_t i32_to_p16( int32_t a )

posit8_t i32_to_p8( uint32_t a )

posit16_t i64_to_p16( int64_t a )

posit8_t i64_to_p8( uint64_t a )

uint_fast32_t p16_to_ui32( posit16_t )

uint_fast32_t p8_to_ui32( posit8_t )

uint_fast64_t p16_to_ui64( posit16_t)

uint_fast64_t p8_to_ui64( posit8_t)

uint_fast32_t p16_to_i32( posit16_t )

uint_fast32_t p8_to_i32( posit8_t )

uint_fast64_t p16_to_i64( posit16_t)

uint_fast64_t p8_to_i64( posit8_t)

posit8_t p16_to_p8( posit16_t )

posit32_t p16_to_p32( posit16_t )

posit16_t p8_to_p16( posit8_t )

posit32_t p8_to_p32( posit8_t )

double convertP16ToDouble(posit16_t)

double convertP8ToDouble(posit8_t)

posit16_t convertDoubleToP16(double)

posit8_t convertDoubleToP8(double)

posit16_t castP16(uint16_t)

posit8_t castP8(uint8_t)

uint16_t castUI(posit16_t)

uint8_t castUI(posit8_t)

Easy to use C++ version

Julia

• Julia implementation on top of SoftPosit

Install via Julia package manager

```

add https://github.com/milankl/SoftPosit.jl

```

Credits to Milan Klöwer.

Behind the scene

Build shared library

cd SoftPosit/build/Linux_x86_64_GCC/ make -j6 julia

Simple Tests

``` julia> t = ccall((:convertDoubleToP16, "/path/to/SoftPosit/build/Linux-x86_64-GCC/softposit.so"), UInt16, (Float64,),1.0) 0x4000

julia> t = ccall((:convertDoubleToP16, "/path/to/SoftPosit/build/Linux-x86_64-GCC/softposit.so"), UInt16, (Float64,),-1.0) 0xc000

```

Known implementations on top of SoftPosit

• Andrey Zgarbul's Rust implementation
• Milan Klöwer's Julia implementation
• SpeedGo Computing's TensorFlow
• SpeedGo Computing's Numpy
• Cerlane Leong's SoftPosit-Python
• David Thien's SoftPosit bindings Racket
• Bill Zorn's SoftPosit and SoftFloat Python

SoftPosit Python Wrapper

This package provides Python bindings for the SoftPosit library, which implements the posit number format.

What are Posits?

Posits are a new number format proposed by John L. Gustafson as an alternative to IEEE 754 floating-point numbers. They offer several advantages:

• Higher accuracy with fewer bits
• Graceful underflow to zero
• No separate handling for infinities, NaN, or subnormals
• Consistent behavior across all bit widths
• Faster and simpler hardware implementation

Installation

Prerequisites

• CMake (version 3.1 or higher)
• C++ compiler (GCC, Clang, MSVC)
• Python 3.6+

Installation from Source

1. Clone the repository:

bash git clone https://github.com/cjdelisle/SoftPosit.git cd SoftPosit/python

1. Install the package:

```bash # Option 1: Development installation pip install -e .

# Option 2: Regular installation pip install . ```

1. Verify the installation:

python import softposit p8 = softposit.posit8(3.5) print(p8) # Should print 3.5

Usage

The wrapper provides three main posit types:

• posit8: 8-bit posit numbers
• posit16: 16-bit posit numbers
• posit32: 32-bit posit numbers

Basic Operations

```python import softposit

Create posit numbers

p8 = softposit.posit8(3.14) p16 = softposit.posit16(2.718) p32 = softposit.posit32(1.414)

Arithmetic operations

sump8 = p8 + 1.5 # Adding float diffp16 = p16 - p16/2 # Subtraction prodp32 = p32 * 2 # Multiplication divp8 = p8 / 2 # Division

Conversion between types

p16fromp8 = softposit.posit16(p8) p32fromp16 = softposit.posit32(p16)

Conversion to Python types

floatval = float(p8) intval = int(p32)

Print values

print(f"p8 = {p8}") print(f"p16 = {p16}") print(f"p32 = {p32}") print(f"p8 + 1.5 = {sump8}") print(f"p16 - p16/2 = {diffp16}") print(f"p32 * 2 = {prodp32}") print(f"p8 / 2 = {divp8}") ```

Numerical Properties

Posit numbers have different precision characteristics than floats. Here's an example showing the precision differences:

```python import softposit

Original value (exact in decimal)

value = 1/3 # 0.3333...

Create posit representations

p8 = softposit.posit8(value) p16 = softposit.posit16(value) p32 = softposit.posit32(value)

Print values and errors

print(f"Original value: {value}") print(f"posit8: {p8} (error: {abs(float(p8) - value)})") print(f"posit16: {p16} (error: {abs(float(p16) - value)})") print(f"posit32: {p32} (error: {abs(float(p32) - value)})") ```

Examples

The package includes several example files:

• basic_test.py: Basic functionality test
• softposit_example.py: Comprehensive usage examples
• test_softposit.py: More extensive tests

Run these examples to explore the capabilities of the posit number format:

bash python softposit_example.py

Troubleshooting

ImportError: No module named '_softposit'

If you see this error, it means the C extension module was not properly installed. Try:

1. Reinstalling the package with pip install -e .
2. Check that your Python version matches the one used during compilation
3. Make sure the shared library libsoftposit.so (or libsoftposit.dylib on macOS) is in your library path

Performance Considerations

Posit operations in this Python wrapper are implemented in C/C++ for performance, but there's still overhead from Python bindings. For maximum performance in numerical code, consider using arrays of posits and native C++ code.

License

This package is released under the same license as the original SoftPosit library.

Project Structure

soft-posit-cpp/ ├── src/ # Core C implementation ├── include/ # Public header files ├── tests/ # Comprehensive test suites │ ├── p8_tests/ # posit8 tests │ ├── p16_tests/ # posit16 tests │ ├── p32_tests/ # posit32 tests │ └── common_tests/ # Shared utilities ├── examples/ # Usage examples and demos ├── benchmarks/ # Performance benchmarks ├── python/ # Python wrapper (optional) ├── .github/workflows/ # CI/CD pipeline definitions └── cmake/ # CMake modules and configuration

Compatibility and Testing

Platform Support

• Linux: Ubuntu 20.04+, tested with GCC 9+ and Clang 10+
• macOS: macOS 11+, tested with Apple Clang 12+
• Windows: Experimental support (contributions welcome)

Test Coverage

• ✅ posit8: Exhaustively tested (all operations)
• ✅ posit16: Extensively tested (most operations)
• 🔄 posit32: Comprehensive testing in progress
• ✅ Quire operations: Fully tested for posit8/posit16
• ✅ Type conversions: All combinations tested

Our automated test suite runs ~1M+ test cases across different posit sizes and operations.