beginning to add tests

[sfpy.git] / README.md

diff --git a/README.md b/README.md
index 26c69491d417fce383e043567257a669ee9aaa81..3a76ed759591ba1d24279207bc61f10ef2a704fa 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,45 +1,64 @@
 # sfpy
 softfloat and softposit in Python
   * support for softfloat float16, float32, and float64
-  * support for softposit posit8, quire8, posit16, and quire16
-  
+  * 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
 ```
 >>> import sfpy
->>> sfpy.Float32(1.3) + sfpy.Float32(1.4) # <-- construct from doubles
-Float32(2.6999998092651367)
->>> sfpy.Float32(3) # <-- construct from raw bits
-Float32(4.203895392974451e-45)
->>> sfpy.Float32(3).bits
-3
->>> x = sfpy.Float16(0)
+>>> 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
-Float16(0.0)
->>> x += sfpy.Float16(10.0) # <-- in-place operators have better performance
->>> x
-Float16(10.0)
->>> sfpy.Posit16(1.3) + sfpy.Posit16(1.4) # <-- posits work the same way as floats
-Posit16(2.7001953125)
->>> q = sfpy.Quire16(0) # <-- quire is also supported
->>> q
-Quire16(0.0)
->>> q.iqma(sfpy.Posit16(3), sfpy.Posit16(5))
->>> q
-Quire16(3.725290298461914e-09)
->>> q.iqma(sfpy.Posit16(3.0), sfpy.Posit16(5.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
-Quire16(15.0)
+Quire16(0.00089263916015625)
 >>> q.bits
-1080863910568919232
->>> bin(q.bits)
-'0b111100000000000000000000000000000000000000000000000011000000'
+64424509440000
+>>> q.to_posit()
+Posit16(0.00089263916015625)
+>>> q.to_posit().bits
+490
 ```
 
-## Building (on Linux)
-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 libraries `SoftPosit/build/Linux-x86_64-GCC/softposit.a` and `berkeley-softfloat-3/build/Linux-x86_64-GCC/softfloat.a` to be built. Note that in order for Cython to be able to build the shared objects for the module, the static libraries must be compiled with -fPIC, which currently requires modifying the appropriate Makefiles manually. SoftPosit can be build with -fPIC using its python2 and python3 targets.
-
-The package can also be installed to a local Python distribution with pip, i.e. `pip install .` from the top level of the repository using the appropriate pip. This requires that Cython be installed.
+## Building
+See [BUILDING](https://github.com/billzorn/sfpy/blob/master/BUILDING.md).