beginning to add tests

[sfpy.git] / README.md

diff --git a/README.md b/README.md
index d1814cf217b63302c589dcb4e047a6db1b8397bd..3a76ed759591ba1d24279207bc61f10ef2a704fa 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,34 +1,64 @@
 # sfpy
 softfloat and softposit in Python
-  * support for softposit posit8, quire8, posit16, and quire16
-  * no softfloat support yet, still WIP
-  
+  * support for softfloat float16, float32, and float64
+  * support for softposit posit8, quire8, posit16, quire16, posit32, and quire32
+
+## Installation
+On most linux distros with CPython 2.7, 3.4, 3.5, 3.6, or 3.7, sfpy should work out of the box:
+
+```
+pip install sfpy
+```
+
+Under the hood, sfpy uses Cython to create bindings for the softposit and softfloat C libraries.
+The building instructions are tested on Ubuntu 16.04 - for other platforms they may need some
+adaptation.
+
 ## Demo
 ```
->>> from sfpy import Posit16, Quire16
->>> Posit16(1.3) + Posit16(1.4)
-Posit16(2.7001953125)
->>> x = Posit16(7)
->>> x
-Posit16(1.7881393432617188e-07)
->>> x += Posit16(9)
+>>> import sfpy
+>>> from sfpy import *
+>>> a, b = Float16(1.3), Float16(1.4)
+>>> a * b - a / b
+Float16(0.89208984375)
+>>> sfpy.float.flag_get_inexact()
+True
+>>> a += b
+>>> a
+Float16(2.69921875)
+>>>
+>>> x, y = Posit16(3.0), Posit16(3)
 >>> x
-Posit16(4.76837158203125e-07)
->>> q = Quire16()
->>> q.fdp_add(Posit16(11.0), Posit16(2.0))
+Posit16(3.0)
+>>> x.bits
+22528
+>>> y
+Posit16(2.9802322387695312e-08)
+>>> y.bits
+3
+>>> x * y
+Posit16(8.940696716308594e-08)
+>>> acc = Posit16(0)
+>>> for i in range(10000):
+...   acc = acc.fma(x, y)
+... 
+>>> acc
+Posit16(1.9073486328125e-06)
+>>> acc.bits
+24
+>>> q = Quire16(0)
+>>> for i in range(10000):
+...   q.iqma(x, y)
+... 
 >>> q
-uA.ui : 29056
-Quire16(22.0)
->>> q.p16
-uA.ui : 29056
-Posit16(22.0)
+Quire16(0.00089263916015625)
+>>> q.bits
+64424509440000
+>>> q.to_posit()
+Posit16(0.00089263916015625)
+>>> q.to_posit().bits
+490
 ```
 
-For a basic performance test of the API, try: `python timing.py`
-
 ## Building
-The cython module can be built in place in the usual way:
-`python setup.py build_ext --inplace`
-This requires the submodules to be checked out, and the static library `SoftPosit/build/Linux-x86_64-GCC/softposit.a` to be built. Note that in order for cython to be able to build the shared object for the module, the static library must be compiled with -fPIC, which currently requires modifying the appropriate Makefile manually.
-
-The package can also be installed to a local Python distribution with pip, i.e. `pip install .` using the appropriate pip.
+See [BUILDING](https://github.com/billzorn/sfpy/blob/master/BUILDING.md).