diff options
Diffstat (limited to 'source/luametatex/source/libraries/softposit/README.md')
| -rw-r--r-- | source/luametatex/source/libraries/softposit/README.md | 551 |
1 files changed, 551 insertions, 0 deletions
diff --git a/source/luametatex/source/libraries/softposit/README.md b/source/luametatex/source/libraries/softposit/README.md new file mode 100644 index 000000000..b50b271c5 --- /dev/null +++ b/source/luametatex/source/libraries/softposit/README.md @@ -0,0 +1,551 @@ +# <img src="https://posithub.org/images/NGA_logo.png" width="90" height="50"/> SoftPosit + +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 posit8_t and posit16_t operations are exhaustively tested with exception of p16_mulAdd and q16_fdp_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](#cversion) : The main source code where all other versions are based on. + * [User friendly C++ version](#cppversion) : Documentation can be found below. + * [User friendly Python version](https://gitlab.com/cerlane/SoftPosit-Python/) : https://gitlab.com/cerlane/SoftPosit-Python/ + * [Julia](#jversion) : Currently only simple .so support. Documentation can be found below. + * [Others](#known) + + +## <a name="cversion"/>Fast C version + + +### Examples + +#### A 8-bit example on how to use the code to add: + + +``` +#include "softposit.h" + +int main (int argc, char *argv[]){ + + 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; + +} +``` + + +#### A 16-bit example on how to use the code to multiply: + +``` +#include "softposit.h" + +int main (int argc, char *argv[]){ + + posit16_t pA, pB, pZ; + pA = castP16(0x0FF2); + pB = castP16(0x2123); + + pZ = p16_mul(pA, pB); + + //To check answer by converting it to double + double dZ = convertP16ToDouble(pZ); + printf("dZ: %.15f\n", dZ); + + //To print result in binary + uint16_t uiZ = castUI(pZ); + printBinary((uint64_t*)&uiZ, 16); + + return 0; +} +``` + +#### A 24-bit (es=2) example on how to use the code: + + +``` +#include "softposit.h" + +int main (int argc, char *argv[]){ + + 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; + +} +``` + +#### For deep learning, please use quire. + + +``` +//Convert double to posit +posit16_t pA = convertDoubleToP16(1.02783203125 ); +posit16_t pB = convertDoubleToP16(0.987060546875); +posit16_t pC = convertDoubleToP16(0.4998779296875); +posit16_t pD = convertDoubleToP16(0.8797607421875); + +quire16_t qZ; + +//Set quire to 0 +qZ = q16_clr(qZ); + +//accumulate products without roundings +qZ = q16_fdp_add(qZ, pA, pB); +qZ = q16_fdp_add(qZ, pC, pD); + +//Convert back to posit +posit16_t pZ = q16_to_p16(qZ); + +//To check answer +double dZ = convertP16ToDouble(pZ); +``` + +### Build and link + +#### Build - softposit.a + + +Please note that only 64-bit systems are supported. For Mac OSX and Linux, the same Makefile is used. + +Note that architecture specific optimisation is removed. To get maximum speed, please update OPTIMISATION flag in build/Linux-x86_64-GCC/Makefile. + + +``` +cd SoftPosit/build/Linux-x86_64-GCC +make -j6 all + +``` + +#### Link - softposit.a + + +If your source code is for example "main.c" and you want to create an executable "main". +Assume that SoftPosit is installed and installed in the same directory (installing in the same directory is NOT recommended). + +``` +gcc -lm -o main \ + main.c SoftPosit/build/Linux-x86_64-GCC/softposit.a -ISoftPosit/source/include -O2 + +``` + +### Features + + +#### Main Posit Functionalities: + + +Add : + + posit16_t p16_add(posit16_t, posit16_t) + + posit8_t p8_add(posit8_t, posit8_t) + +Subtract : + + posit16_t p16_sub(posit16_t, posit16_t) + + posit8_t p8_sub(posit8_t, posit8_t) + + +Divide : + + posit16_t p16_div(posit16_t, posit16_t) + + posit8_t p8_div(posit8_t, posit8_t) + +Multiply : + + posit16_t p16_mul(posit16_t, posit16_t) + + posit8_t p8_mul(posit8_t, posit8_t) + + +Fused Multiply Add : + + 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 + + +#### Main Quire Functionalities + + +Fused dot product-add : + + 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 + +Fused dot product-subtract : + + quire16_t q16_fdp_sub(quire16_t, posit16_t, posit16_t) + + quire8_t q8_fdp_sub(quire8_t, posit8_t, posit8_t) + +Set quire variable to zero : + + quire16_t q16_clr(quire16_t) + + quire8_t q8_clr(quire8_t) + +Convert quire to posit : + + posit16_t q16_to_p16(quire16_t) + + posit8_t q8_to_p8(quire8_t) + + +#### Functionalites in Posit Standard + + +Square root : + + posit16_t p16_sqrt(posit16_t) + + posit8_t p8_sqrt(posit8_t) + +Round to nearest integer : + + posit16_t p16_roundToInt(posit16_t) + + posit8_t p8_roundToInt(posit8_t) + +Check equal : + + bool p16_eq( posit16_t, posit16_t ) + + bool p8_eq( posit8_t, posit8_t ) + +Check less than equal : + + bool p16_le( posit16_t, posit16_t ) + + bool p8_le( posit8_t, posit8_t ) + +Check less than : + + bool p16_lt( posit16_t, posit16_t ) + + bool p8_lt( posit8_t, posit8_t ) + +Convert posit to integer (32 bits) : + + int_fast32_t p16_to_i32( posit16_t ) + + int_fast32_t p8_to_i32( posit8_t ) + +Convert posit to long long integer (64 bits) : + + int_fast64_t p16_to_i64( posit16_t) + + int_fast64_t p8_to_i64( posit8_t) + +Convert unsigned integer (32 bits) to posit: + + posit16_t ui32_to_p16( uint32_t a ) + + posit8_t ui32_to_p8( uint32_t a ) + +Convert unsigned long long int (64 bits) to posit: + + posit16_t ui64_to_p16( uint64_t a ) + + posit8_t ui64_to_p8( uint64_t a ) + +Convert integer (32 bits) to posit: + + posit16_t i32_to_p16( int32_t a ) + + posit8_t i32_to_p8( uint32_t a ) + +Convert long integer (64 bits) to posit: + + posit16_t i64_to_p16( int64_t a ) + + posit8_t i64_to_p8( uint64_t a ) + +Convert posit to unsigned integer (32 bits) : + + uint_fast32_t p16_to_ui32( posit16_t ) + + uint_fast32_t p8_to_ui32( posit8_t ) + +Convert posit to unsigned long long integer (64 bits) : + + uint_fast64_t p16_to_ui64( posit16_t) + + uint_fast64_t p8_to_ui64( posit8_t) + +Convert posit to integer (32 bits) : + + uint_fast32_t p16_to_i32( posit16_t ) + + uint_fast32_t p8_to_i32( posit8_t ) + +Convert posit to long long integer (64 bits) : + + uint_fast64_t p16_to_i64( posit16_t) + + uint_fast64_t p8_to_i64( posit8_t) + +Convert posit to posit of another size : + + 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 ) + + + +#### Helper Functionalites (NOT in Posit Standard) + +Convert posit to double (64 bits) : + + double convertP16ToDouble(posit16_t) + + double convertP8ToDouble(posit8_t) + +Convert double (64 bits) to posit : + + posit16_t convertDoubleToP16(double) + + posit8_t convertDoubleToP8(double) + +Cast binary expressed in unsigned integer to posit : + + posit16_t castP16(uint16_t) + + posit8_t castP8(uint8_t) + +Cast posit into binary expressed in unsigned integer + + uint16_t castUI(posit16_t) + + uint8_t castUI(posit8_t) + + +## <a name="cppversion"/>Easy to use C++ version + + +### Build and Link + +**Build and link your C++ program to SoftPosit.a (C)** + +Please compile your executable with g++ and not gcc. + +``` +g++ -std=gnu++11 -o main \ + ../source/testmain.cpp \ + ../../SoftPosit/source/../build/Linux-x86_64-GCC/softposit.a \ + -I../../SoftPosit/source/../build/Linux-x86_64-GCC -O2 +``` + +### Example + +#### Example of testmain.cpp + +``` +#include "softposit_cpp.h" + +int main(int argc, char *argv[]){ + posit16 x = 1; + posit16 y = 1.5; + posit8 x8 = 1; + quire16 q; + quire8 q8; + + x += p16(1.5)*5.1; + + printf("%.13f sizeof: %d\n", x.toDouble(), sizeof(posit16)); + + x = q.qma(4, 1.2).toPosit(); + printf("%.13f sizeof: %d\n", x.toDouble(), sizeof(quire16)); + + x8 = q8.qma(4, 1.2).toPosit(); + printf("%.13f sizeof: %d\n", x8.toDouble(), sizeof(quire8)); + + std::cout << x; + + return 0; +} + + +``` + +### Functionalities + +#### Main functionalities + +* Posit types: posit16, posit8 +* Fused-multiply-add: + * posit16 fma(posit16, posit16, posit16) + * posit18 fma(posit18, posit18, posit8) +* Square root: + * posit16 sqrt(posit16) + * posit8 sqrt(posit8) +* roundToInt: + * posit16 rint(posit16) + * posit8 rint(posit8) +* Supported operators + * \+ + * += + * \- + * \-= + * * + * *= + * / + * /= + * << + * <<= + * >> + * >>= + * & + * &= + * | + * |= + * ^ + * ^= + * && + * || + * ++ + * -- + * == + * ~ + * ! + * != + * * + * < + * *= + * <= +* Posit to Double: + * double (instance of posit).toDouble() +* Double to Posit: + * posit16 p16(double) + * posit8 p8(double) +* Posit to NaR: + * posit16 (instance of posit16).toNaR() + * posit8 (instance of posit8).toNaR() + +#### Quire functionalities (particularly for deep learning) + +* Quire types: quire16, quire8 (when declared, quire is initiated to zero) +* Clear quire to zero: + * (instance of quire16).clr() +* Quire multiply add (fused) + * (instance of quire16).fma(quire16) + * (instance of quire8).fma(quire8) +* Quire multiply subtract (fused) + * (instance of quire16).fms(quire16) + * (instance of quire8).fms(quire8) +* Convert quire to Posit + * posit16 (instance of quire16).toPosit() + * posit8 (instance of quire8).toPosit() +* Check if quire is NaR + * bool (instance of quire).isNaR() + +## <a name="jversion"/>Julia + +* [Julia implementation] (https://github.com/milankl/SoftPosit.jl) 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 + +``` + +## <a href="known"/>Known implementations on top of SoftPosit + +* [Andrey Zgarbul's Rust implementation](https://crates.io/crates/softposit) +* [Milan Klöwer's Julia implementation](https://github.com/milankl/SoftPosit.jl) +* [SpeedGo Computing's TensorFlow](https://github.com/xman/tensorflow/tree/posit) +* [SpeedGo Computing's Numpy](https://github.com/xman/numpy-posit) +* [Cerlane Leong's SoftPosit-Python](https://gitlab.com/cerlane/SoftPosit-Python) +* [David Thien's SoftPosit bindings Racket](https://github.com/DavidThien/softposit-rkt) +* [Bill Zorn's SoftPosit and SoftFloat Python](https://pypi.org/project/sfpy/) + + |