diff --git a/docs/_sources/index.txt b/docs/_sources/index.txt index beabcd0..234d6d0 100644 --- a/docs/_sources/index.txt +++ b/docs/_sources/index.txt @@ -5,6 +5,132 @@ PyMPF .. toctree:: :maxdepth: 2 +The PyMPF library contains two modules intended for most users: + +* floats (arbitrary precision IEEE-754 floating point, see + :class:`mpf.floats.MPF`) +* rationals (rational numbers, see :class:`mpf.rationals.Rational`) + +It also contains the following modules indended for internal use and +the SMT-LIB testcase generator: + +* bitvectors (very simple bitvector support, only literal printing currently) +* interval_q (rational intervals) +* bisect (binary search) + +Fast tutorial +------------- + +Import the relevant classes. Most likely you want to do this: + +>>> from mpf.rationals import Rational +>>> from mpf.floats import * + +You can now create a float like this (here we create a single +precision float): + +>>> x = MPF(8, 24) + +To quickly see what we have we can use the +:func:`mpf.floats.MPF.to_python_string` member function. + +>>> x.to_python_string() +'0.0' + +To set the float to a specific value, such as :math:`\frac{1}{3}` we +can use the :func:`mpf.floats.MPF.from_rational` member +function. Since we convert from rationals to floats we might need to +round. + +>>> x.from_rational(RM_RNE, Rational(1, 3)) +>>> x.to_python_string() +'0.3333333432674407958984375' + +PyMPF supports all rounding modes defined by IEEE-754: + +* RM_RNE (Round nearest even: to break ties, round to the nearest + floating point number whos bit-pattern is even. This is the default + on most desktop processors and programming languages.) + +* RM_RNA (Round nearest away: to break ties, round to the floating + point number furthest away from zero. Note that this is unsupported + on most hardware (including i686 and amd64), other floating point + libraries (e.g. MPFR). + +* RM_RTZ (Round to zero: always round towards zero) + +* RM_RTP (Round to positive: always round towards :math:`+\infty`) + +* RM_RTN (Round to negative: always round towards :math:`-\infty`) + +One of the main use-cases for this library is to generate test-cases +for SMT-LIB. To create an SMT-LIB literal you can use the +:func:`mpf.floats.MPF.smtlib_literal` function: + +>>> x.smtlib_literal() +'(fp #b0 #b01111101 #b01010101010101010101011)' + +The MPF class supports all floating-point comparisons: + +>>> y = MPF(8, 24) +>>> x > y +True + +>>> y.set_nan() +>>> x > y +False + +Note that equality considers +0 and -0 to be equal. You can use the +:func:`mpf.floats.smtlib_eq` if you want bitwise equality: + +>>> z = MPF(8, 24) +>>> z.set_zero(1) +>>> y.set_zero(0) +>>> y == z +True +>>> smtlib_eq(y, z) +False + +To set values you can use the following functions: + +* :func:`mpf.floats.MPF.from_rational` set to value closest to given rational + +* :func:`mpf.floats.MPF.set_zero` set to +0 (if sign is 0) or -0 (if + sign is 1) + +* :func:`mpf.floats.MPF.set_infinite` set to :math:`+\infty` (if sign + is 0) or :math:`-\infty` (if sign is 1) + +* :func:`mpf.floats.MPF.set_nan` set to NaN. PyMPF does not support + the distinction between signalling and non-signalling NaNs, + similarly to SMT-LIB. + +Finally, to do arithmetic, you can use the fp_* functions. Most take a +rounding mode and two parameters: + +>>> x.from_rational(RM_RNE, Rational(1, 10)) +>>> y.from_rational(RM_RNE, Rational(10)) +>>> z = fp_mul(RM_RNE, x, y) +>>> z.to_python_string() +'1.0' + +Here an example demonstrating accumulated rounding errors: + +>>> y.set_zero(0) +>>> for i in range(10): +>>> y = fp_add(RM_RNE, y, x) +>>> print(y.to_python_string()) +0.100000001490116119384765625 +0.20000000298023223876953125 +0.300000011920928955078125 +0.4000000059604644775390625 +0.5 +0.60000002384185791015625 +0.7000000476837158203125 +0.80000007152557373046875 +0.900000095367431640625 +1.00000011920928955078125 + ========= Rationals ========= @@ -20,3 +146,19 @@ MPF .. automodule:: mpf.floats :members: :special-members: + +========= +Changelog +========= + +1.0 +--- + +1.0.3 +^^^^^ +* Add basic documentation (fast tutorial, and basic descriptions of + MPF and Rational classes). + +1.0.2 +^^^^^ +* First public release on PyPI. diff --git a/docs/index.html b/docs/index.html index 3f9e6f5..431205f 100644 --- a/docs/index.html +++ b/docs/index.html @@ -51,6 +51,126 @@

Navigation

PyMPF

+

The PyMPF library contains two modules intended for most users:

+ +

It also contains the following modules indended for internal use and +the SMT-LIB testcase generator:

+ +
+

Fast tutorial

+

Import the relevant classes. Most likely you want to do this:

+
>>> from mpf.rationals import Rational
+>>> from mpf.floats import *
+
+
+

You can now create a float like this (here we create a single +precision float):

+
>>> x = MPF(8, 24)
+
+
+

To quickly see what we have we can use the +mpf.floats.MPF.to_python_string() member function.

+
>>> x.to_python_string()
+'0.0'
+
+
+

To set the float to a specific value, such as \(\frac{1}{3}\) we +can use the mpf.floats.MPF.from_rational() member +function. Since we convert from rationals to floats we might need to +round.

+
>>> x.from_rational(RM_RNE, Rational(1, 3))
+>>> x.to_python_string()
+'0.3333333432674407958984375'
+
+
+

PyMPF supports all rounding modes defined by IEEE-754:

+ +

One of the main use-cases for this library is to generate test-cases +for SMT-LIB. To create an SMT-LIB literal you can use the +mpf.floats.MPF.smtlib_literal() function:

+
>>> x.smtlib_literal()
+'(fp #b0 #b01111101 #b01010101010101010101011)'
+
+
+

The MPF class supports all floating-point comparisons:

+
>>> y = MPF(8, 24)
+>>> x > y
+True
+
+
+
>>> y.set_nan()
+>>> x > y
+False
+
+
+

Note that equality considers +0 and -0 to be equal. You can use the +mpf.floats.smtlib_eq() if you want bitwise equality:

+
>>> z = MPF(8, 24)
+>>> z.set_zero(1)
+>>> y.set_zero(0)
+>>> y == z
+True
+>>> smtlib_eq(y, z)
+False
+
+
+

To set values you can use the following functions:

+ +

Finally, to do arithmetic, you can use the fp_* functions. Most take a +rounding mode and two parameters:

+
>>> x.from_rational(RM_RNE, Rational(1, 10))
+>>> y.from_rational(RM_RNE, Rational(10))
+>>> z = fp_mul(RM_RNE, x, y)
+>>> z.to_python_string()
+'1.0'
+
+
+

Here an example demonstrating accumulated rounding errors:

+
>>> y.set_zero(0)
+>>> for i in range(10):
+>>>     y = fp_add(RM_RNE, y, x)
+>>>     print(y.to_python_string())
+0.100000001490116119384765625
+0.20000000298023223876953125
+0.300000011920928955078125
+0.4000000059604644775390625
+0.5
+0.60000002384185791015625
+0.7000000476837158203125
+0.80000007152557373046875
+0.900000095367431640625
+1.00000011920928955078125
+
+
+

Rationals

@@ -772,6 +892,25 @@

PyMPF

Bit-wise equality

+

+
+

Changelog

+
+

1.0

+
+

1.0.3

+
    +
  • Add basic documentation (fast tutorial, and basic descriptions of +MPF and Rational classes).
    • +
+
+
+

1.0.2

+
    +
  • First public release on PyPI.
    • +
+
+
@@ -782,9 +921,20 @@

PyMPF

Table Of Contents

diff --git a/docs/searchindex.js b/docs/searchindex.js index 9c5711d..7e7c0a3 100644 --- a/docs/searchindex.js +++ b/docs/searchindex.js @@ -1 +1 @@ -Search.setIndex({envversion:50,filenames:["index"],objects:{"mpf.floats":{MPF:[0,1,1,""],fp_add:[0,4,1,""],fp_div:[0,4,1,""],fp_fma:[0,4,1,""],fp_from_float:[0,4,1,""],fp_from_int:[0,4,1,""],fp_from_sbv:[0,4,1,""],fp_from_ubv:[0,4,1,""],fp_max:[0,4,1,""],fp_min:[0,4,1,""],fp_mul:[0,4,1,""],fp_nextDown:[0,4,1,""],fp_nextUp:[0,4,1,""],fp_rem:[0,4,1,""],fp_roundToIntegral:[0,4,1,""],fp_sqrt:[0,4,1,""],fp_sub:[0,4,1,""],fp_to_int:[0,4,1,""],fp_to_sbv:[0,4,1,""],fp_to_ubv:[0,4,1,""],smtlib_eq:[0,4,1,""]},"mpf.floats.MPF":{__abs__:[0,2,1,""],__eq__:[0,2,1,""],__ge__:[0,2,1,""],__gt__:[0,2,1,""],__le__:[0,2,1,""],__lt__:[0,2,1,""],__neg__:[0,2,1,""],__weakref__:[0,3,1,""],compatible:[0,2,1,""],from_rational:[0,2,1,""],isFinite:[0,2,1,""],isInfinite:[0,2,1,""],isIntegral:[0,2,1,""],isNaN:[0,2,1,""],isNegative:[0,2,1,""],isNormal:[0,2,1,""],isPositive:[0,2,1,""],isSubnormal:[0,2,1,""],isZero:[0,2,1,""],new_mpf:[0,2,1,""],pack:[0,2,1,""],set_infinite:[0,2,1,""],set_nan:[0,2,1,""],set_sign_bit:[0,2,1,""],set_zero:[0,2,1,""],smtlib_from_binary_interchange:[0,2,1,""],smtlib_from_float:[0,2,1,""],smtlib_from_int:[0,2,1,""],smtlib_from_real:[0,2,1,""],smtlib_from_sbv:[0,2,1,""],smtlib_from_ubv:[0,2,1,""],smtlib_literal:[0,2,1,""],smtlib_literals:[0,2,1,""],smtlib_random_literal:[0,2,1,""],smtlib_sort:[0,2,1,""],smtlib_to_int:[0,2,1,""],smtlib_to_real:[0,2,1,""],to_int:[0,2,1,""],to_python_float:[0,2,1,""],to_python_string:[0,2,1,""],to_rational:[0,2,1,""],unpack:[0,2,1,""]},"mpf.rationals":{Rational:[0,1,1,""],q_from_decimal_fragments:[0,4,1,""],q_pow2:[0,4,1,""],q_round_rna:[0,4,1,""],q_round_rne:[0,4,1,""],q_round_rtn:[0,4,1,""],q_round_rtp:[0,4,1,""],q_round_rtz:[0,4,1,""],q_round_to_nearest:[0,4,1,""]},"mpf.rationals.Rational":{__abs__:[0,2,1,""],__add__:[0,2,1,""],__eq__:[0,2,1,""],__ge__:[0,2,1,""],__gt__:[0,2,1,""],__le__:[0,2,1,""],__lt__:[0,2,1,""],__mul__:[0,2,1,""],__ne__:[0,2,1,""],__neg__:[0,2,1,""],__pow__:[0,2,1,""],__sub__:[0,2,1,""],__truediv__:[0,2,1,""],__weakref__:[0,3,1,""],isIntegral:[0,2,1,""],isNegative:[0,2,1,""],isZero:[0,2,1,""],to_decimal_string:[0,2,1,""],to_python_float:[0,2,1,""],to_python_int:[0,2,1,""],to_smtlib:[0,2,1,""]},mpf:{floats:[0,0,0,"-"],rationals:[0,0,0,"-"]}},objnames:{"0":["py","module","Python module"],"1":["py","class","Python class"],"2":["py","method","Python method"],"3":["py","attribute","Python attribute"],"4":["py","function","Python function"]},objtypes:{"0":"py:module","1":"py:class","2":"py:method","3":"py:attribute","4":"py:function"},terms:{"0x3f800000":0,"23e":0,"case":0,"class":0,"default":0,"float":0,"function":0,"int":0,"long":0,"new":0,"return":0,"true":0,__abs__:0,__add__:0,__eq__:0,__ge__:0,__gt__:0,__le__:0,__lt__:0,__mul__:0,__ne__:0,__neg__:0,__pow__:0,__sub__:0,__truediv__:0,__weakref__:0,absolut:0,accord:0,add:0,adding:0,addit:0,addition:0,all:0,allow:0,also:0,altern:0,alwai:0,ani:0,anoth:0,appli:0,appropri:0,arbitrari:0,assertionerror:0,awai:0,b000:0,b00:0,between:0,binari:0,bit:0,bitvec:0,bitvector:0,build:0,calcul:0,call:0,can:0,choos:0,chosen:0,close:0,closest:0,compact:0,comparison:0,compat:0,complic:0,comput:0,consid:0,constructor:0,convers:0,convert:0,copi:0,correct:0,correctli:0,correspond:0,creat:0,deal:0,decim:0,defin:0,denomin:0,describ:0,differ:0,difficult:0,directli:0,divid:0,divis:0,doe:0,equal:0,equaliti:0,equival:0,even:0,exactli:0,exampl:0,except:0,exp_part:0,expect:0,expon:0,exponenti:0,express:0,fail:0,fals:0,fast:0,favour:0,finit:0,first:0,float128:0,float16:0,float32:0,float64:0,float_info:0,floatingpoint:0,follow:0,form:0,format:0,fp_add:0,fp_div:0,fp_fma:0,fp_from_float:0,fp_from_int:0,fp_from_sbv:0,fp_from_ubv:0,fp_max:0,fp_min:0,fp_mul:0,fp_nextdown:0,fp_nextup:0,fp_rem:0,fp_roundtointegr:0,fp_sqrt:0,fp_sub:0,fp_to_int:0,fp_to_sbv:0,fp_to_ubv:0,fraction:0,fraction_part:0,fragment:0,from:0,from_rat:0,fuse:0,give:0,given:0,greater:0,hand:0,handl:0,have:0,hidden:0,howev:0,ieee:0,implement:0,includ:0,include:0,inequal:0,infin:0,infinit:0,infiniti:0,initi:0,instead:0,integ:0,integer_part:0,integr:0,interchang:0,interpret:0,invers:0,isfinit:0,isinfinit:0,isintegr:0,isnan:0,isneg:0,isnorm:0,isposit:0,issubnorm:0,iszero:0,left:0,less:0,lib:0,librari:0,list:0,liter:0,lower:0,main:0,map:0,maximum:0,memori:0,might:0,minimum:0,mode:0,modul:0,more:0,mpfr:0,multipl:0,multipli:0,must:0,nan:0,nearest:0,neg:0,negat:0,new_mpf:0,non:0,normal:0,normalis:0,note:0,now:0,number:0,numer:0,object:0,onto:0,operand:0,oppos:0,opposit:0,other:0,otherwis:0,pack:0,pattern:0,perform:0,plu:0,point:0,posit:0,possibl:0,precis:0,predecessor:0,preserv:0,problem:0,propag:0,python:0,q_from_decimal_frag:0,q_pow2:0,q_round_rn:0,q_round_rna:0,q_round_rtn:0,q_round_rtp:0,q_round_rtz:0,q_round_to_nearest:0,rais:0,randomli:0,real:0,refer:0,reli:0,remaind:0,replac:0,repres:0,represent:0,result:0,right:0,root:0,round:0,rtn:0,same:0,section:0,see:0,semant:0,set:0,set_infinit:0,set_nan:0,set_sign_bit:0,set_zero:0,should:0,side:0,sign:0,significand:0,simpl:0,sinc:0,singl:0,smt:0,smtlib:0,smtlib_eq:0,smtlib_from_binary_interchang:0,smtlib_from_float:0,smtlib_from_int:0,smtlib_from_r:0,smtlib_from_sbv:0,smtlib_from_ubv:0,smtlib_liter:0,smtlib_random_liter:0,smtlib_sort:0,smtlib_to_int:0,smtlib_to_r:0,solver:0,someth:0,sort:0,special:0,squar:0,string:0,subclass:0,subnorm:0,substract:0,successor:0,termin:0,test:0,than:0,thi:0,thrown:0,tiebreak:0,to_decimal_str:0,to_fp:0,to_int:0,to_python_float:0,to_python_int:0,to_python_str:0,to_rat:0,to_smtlib:0,total:0,toward:0,tupl:0,two:0,understand:0,unpack:0,unsign:0,upper:0,use:0,valid:0,valu:0,veri:0,want:0,weak:0,when:0,where:0,which:0,width:0,wise:0,without:0,x00000000:0,you:0,zero:0},titles:["PyMPF"],titleterms:{mpf:0,pympf:0,ration:0,todo:0}}) \ No newline at end of file +Search.setIndex({envversion:50,filenames:["index"],objects:{"mpf.floats":{MPF:[0,1,1,""],fp_add:[0,4,1,""],fp_div:[0,4,1,""],fp_fma:[0,4,1,""],fp_from_float:[0,4,1,""],fp_from_int:[0,4,1,""],fp_from_sbv:[0,4,1,""],fp_from_ubv:[0,4,1,""],fp_max:[0,4,1,""],fp_min:[0,4,1,""],fp_mul:[0,4,1,""],fp_nextDown:[0,4,1,""],fp_nextUp:[0,4,1,""],fp_rem:[0,4,1,""],fp_roundToIntegral:[0,4,1,""],fp_sqrt:[0,4,1,""],fp_sub:[0,4,1,""],fp_to_int:[0,4,1,""],fp_to_sbv:[0,4,1,""],fp_to_ubv:[0,4,1,""],smtlib_eq:[0,4,1,""]},"mpf.floats.MPF":{__abs__:[0,2,1,""],__eq__:[0,2,1,""],__ge__:[0,2,1,""],__gt__:[0,2,1,""],__le__:[0,2,1,""],__lt__:[0,2,1,""],__neg__:[0,2,1,""],__weakref__:[0,3,1,""],compatible:[0,2,1,""],from_rational:[0,2,1,""],isFinite:[0,2,1,""],isInfinite:[0,2,1,""],isIntegral:[0,2,1,""],isNaN:[0,2,1,""],isNegative:[0,2,1,""],isNormal:[0,2,1,""],isPositive:[0,2,1,""],isSubnormal:[0,2,1,""],isZero:[0,2,1,""],new_mpf:[0,2,1,""],pack:[0,2,1,""],set_infinite:[0,2,1,""],set_nan:[0,2,1,""],set_sign_bit:[0,2,1,""],set_zero:[0,2,1,""],smtlib_from_binary_interchange:[0,2,1,""],smtlib_from_float:[0,2,1,""],smtlib_from_int:[0,2,1,""],smtlib_from_real:[0,2,1,""],smtlib_from_sbv:[0,2,1,""],smtlib_from_ubv:[0,2,1,""],smtlib_literal:[0,2,1,""],smtlib_literals:[0,2,1,""],smtlib_random_literal:[0,2,1,""],smtlib_sort:[0,2,1,""],smtlib_to_int:[0,2,1,""],smtlib_to_real:[0,2,1,""],to_int:[0,2,1,""],to_python_float:[0,2,1,""],to_python_string:[0,2,1,""],to_rational:[0,2,1,""],unpack:[0,2,1,""]},"mpf.rationals":{Rational:[0,1,1,""],q_from_decimal_fragments:[0,4,1,""],q_pow2:[0,4,1,""],q_round_rna:[0,4,1,""],q_round_rne:[0,4,1,""],q_round_rtn:[0,4,1,""],q_round_rtp:[0,4,1,""],q_round_rtz:[0,4,1,""],q_round_to_nearest:[0,4,1,""]},"mpf.rationals.Rational":{__abs__:[0,2,1,""],__add__:[0,2,1,""],__eq__:[0,2,1,""],__ge__:[0,2,1,""],__gt__:[0,2,1,""],__le__:[0,2,1,""],__lt__:[0,2,1,""],__mul__:[0,2,1,""],__ne__:[0,2,1,""],__neg__:[0,2,1,""],__pow__:[0,2,1,""],__sub__:[0,2,1,""],__truediv__:[0,2,1,""],__weakref__:[0,3,1,""],isIntegral:[0,2,1,""],isNegative:[0,2,1,""],isZero:[0,2,1,""],to_decimal_string:[0,2,1,""],to_python_float:[0,2,1,""],to_python_int:[0,2,1,""],to_smtlib:[0,2,1,""]},mpf:{floats:[0,0,0,"-"],rationals:[0,0,0,"-"]}},objnames:{"0":["py","module","Python module"],"1":["py","class","Python class"],"2":["py","method","Python method"],"3":["py","attribute","Python attribute"],"4":["py","function","Python function"]},objtypes:{"0":"py:module","1":"py:class","2":"py:method","3":"py:attribute","4":"py:function"},terms:{"0x3f800000":0,"23e":0,"break":0,"case":0,"class":0,"default":0,"final":0,"float":0,"function":0,"import":0,"int":0,"long":0,"new":0,"public":0,"return":0,"true":0,__abs__:0,__add__:0,__eq__:0,__ge__:0,__gt__:0,__le__:0,__lt__:0,__mul__:0,__ne__:0,__neg__:0,__pow__:0,__sub__:0,__truediv__:0,__weakref__:0,absolut:0,accord:0,accumul:0,add:0,adding:0,addit:0,addition:0,all:0,allow:0,also:0,altern:0,alwai:0,amd64:0,ani:0,anoth:0,appli:0,appropri:0,arbitrari:0,arithmet:0,assertionerror:0,awai:0,b000:0,b00:0,b01010101010101010101011:0,b01111101:0,basic:0,between:0,binari:0,bisect:0,bit:0,bitvec:0,bitvector:0,bitwis:0,build:0,calcul:0,call:0,can:0,choos:0,chosen:0,close:0,closest:0,compact:0,comparison:0,compat:0,complic:0,comput:0,consid:0,constructor:0,contain:0,convers:0,convert:0,copi:0,correct:0,correctli:0,correspond:0,creat:0,current:0,deal:0,decim:0,defin:0,demonstr:0,denomin:0,describ:0,descript:0,desktop:0,differ:0,difficult:0,directli:0,distinct:0,divid:0,divis:0,document:0,doe:0,equal:0,equaliti:0,equival:0,error:0,even:0,exactli:0,exampl:0,except:0,exp_part:0,expect:0,expon:0,exponenti:0,express:0,fail:0,fals:0,favour:0,finit:0,first:0,float128:0,float16:0,float32:0,float64:0,float_info:0,floatingpoint:0,follow:0,form:0,format:0,fp_:0,fp_add:0,fp_div:0,fp_fma:0,fp_from_float:0,fp_from_int:0,fp_from_sbv:0,fp_from_ubv:0,fp_max:0,fp_min:0,fp_mul:0,fp_nextdown:0,fp_nextup:0,fp_rem:0,fp_roundtointegr:0,fp_sqrt:0,fp_sub:0,fp_to_int:0,fp_to_sbv:0,fp_to_ubv:0,fraction:0,fraction_part:0,fragment:0,from:0,from_rat:0,furthest:0,fuse:0,gener:0,give:0,given:0,greater:0,hand:0,handl:0,hardwar:0,have:0,here:0,hidden:0,howev:0,i686:0,ieee:0,implement:0,includ:0,include:0,indend:0,inequal:0,infin:0,infinit:0,infiniti:0,initi:0,instead:0,integ:0,integer_part:0,integr:0,intend:0,interchang:0,intern:0,interpret:0,interv:0,interval_q:0,invers:0,isfinit:0,isinfinit:0,isintegr:0,isnan:0,isneg:0,isnorm:0,isposit:0,issubnorm:0,iszero:0,languag:0,left:0,less:0,lib:0,librari:0,like:0,list:0,liter:0,lower:0,main:0,map:0,maximum:0,member:0,memori:0,might:0,minimum:0,mode:0,modul:0,more:0,most:0,mpfr:0,multipl:0,multipli:0,must:0,nan:0,nearest:0,need:0,neg:0,negat:0,new_mpf:0,non:0,normal:0,normalis:0,note:0,now:0,number:0,numer:0,object:0,one:0,onli:0,onto:0,operand:0,oppos:0,opposit:0,other:0,otherwis:0,pack:0,paramet:0,pattern:0,perform:0,plu:0,point:0,posit:0,possibl:0,precis:0,predecessor:0,preserv:0,print:0,problem:0,processor:0,program:0,propag:0,pypi:0,python:0,q_from_decimal_frag:0,q_pow2:0,q_round_rn:0,q_round_rna:0,q_round_rtn:0,q_round_rtp:0,q_round_rtz:0,q_round_to_nearest:0,quickli:0,rais:0,randomli:0,rang:0,real:0,refer:0,releas:0,relev:0,reli:0,remaind:0,replac:0,repres:0,represent:0,result:0,right:0,rm_rna:0,rm_rne:0,rm_rtn:0,rm_rtp:0,rm_rtz:0,root:0,round:0,rtn:0,same:0,search:0,section:0,see:0,semant:0,set:0,set_infinit:0,set_nan:0,set_sign_bit:0,set_zero:0,should:0,side:0,sign:0,signal:0,significand:0,similarli:0,simpl:0,sinc:0,singl:0,smt:0,smtlib:0,smtlib_eq:0,smtlib_from_binary_interchang:0,smtlib_from_float:0,smtlib_from_int:0,smtlib_from_r:0,smtlib_from_sbv:0,smtlib_from_ubv:0,smtlib_liter:0,smtlib_random_liter:0,smtlib_sort:0,smtlib_to_int:0,smtlib_to_r:0,solver:0,someth:0,sort:0,special:0,specif:0,squar:0,string:0,subclass:0,subnorm:0,substract:0,successor:0,support:0,take:0,termin:0,test:0,testcas:0,than:0,thi:0,thrown:0,tiebreak:0,to_decimal_str:0,to_fp:0,to_int:0,to_python_float:0,to_python_int:0,to_python_str:0,to_rat:0,to_smtlib:0,total:0,toward:0,tupl:0,two:0,understand:0,unpack:0,unsign:0,unsupport:0,upper:0,use:0,user:0,valid:0,valu:0,veri:0,want:0,weak:0,what:0,when:0,where:0,which:0,who:0,width:0,wise:0,without:0,x00000000:0,you:0,zero:0},titles:["PyMPF"],titleterms:{changelog:0,fast:0,mpf:0,pympf:0,ration:0,todo:0,tutori:0}}) \ No newline at end of file diff --git a/index.rst b/index.rst index beabcd0..234d6d0 100644 --- a/index.rst +++ b/index.rst @@ -5,6 +5,132 @@ PyMPF .. toctree:: :maxdepth: 2 +The PyMPF library contains two modules intended for most users: + +* floats (arbitrary precision IEEE-754 floating point, see + :class:`mpf.floats.MPF`) +* rationals (rational numbers, see :class:`mpf.rationals.Rational`) + +It also contains the following modules indended for internal use and +the SMT-LIB testcase generator: + +* bitvectors (very simple bitvector support, only literal printing currently) +* interval_q (rational intervals) +* bisect (binary search) + +Fast tutorial +------------- + +Import the relevant classes. Most likely you want to do this: + +>>> from mpf.rationals import Rational +>>> from mpf.floats import * + +You can now create a float like this (here we create a single +precision float): + +>>> x = MPF(8, 24) + +To quickly see what we have we can use the +:func:`mpf.floats.MPF.to_python_string` member function. + +>>> x.to_python_string() +'0.0' + +To set the float to a specific value, such as :math:`\frac{1}{3}` we +can use the :func:`mpf.floats.MPF.from_rational` member +function. Since we convert from rationals to floats we might need to +round. + +>>> x.from_rational(RM_RNE, Rational(1, 3)) +>>> x.to_python_string() +'0.3333333432674407958984375' + +PyMPF supports all rounding modes defined by IEEE-754: + +* RM_RNE (Round nearest even: to break ties, round to the nearest + floating point number whos bit-pattern is even. This is the default + on most desktop processors and programming languages.) + +* RM_RNA (Round nearest away: to break ties, round to the floating + point number furthest away from zero. Note that this is unsupported + on most hardware (including i686 and amd64), other floating point + libraries (e.g. MPFR). + +* RM_RTZ (Round to zero: always round towards zero) + +* RM_RTP (Round to positive: always round towards :math:`+\infty`) + +* RM_RTN (Round to negative: always round towards :math:`-\infty`) + +One of the main use-cases for this library is to generate test-cases +for SMT-LIB. To create an SMT-LIB literal you can use the +:func:`mpf.floats.MPF.smtlib_literal` function: + +>>> x.smtlib_literal() +'(fp #b0 #b01111101 #b01010101010101010101011)' + +The MPF class supports all floating-point comparisons: + +>>> y = MPF(8, 24) +>>> x > y +True + +>>> y.set_nan() +>>> x > y +False + +Note that equality considers +0 and -0 to be equal. You can use the +:func:`mpf.floats.smtlib_eq` if you want bitwise equality: + +>>> z = MPF(8, 24) +>>> z.set_zero(1) +>>> y.set_zero(0) +>>> y == z +True +>>> smtlib_eq(y, z) +False + +To set values you can use the following functions: + +* :func:`mpf.floats.MPF.from_rational` set to value closest to given rational + +* :func:`mpf.floats.MPF.set_zero` set to +0 (if sign is 0) or -0 (if + sign is 1) + +* :func:`mpf.floats.MPF.set_infinite` set to :math:`+\infty` (if sign + is 0) or :math:`-\infty` (if sign is 1) + +* :func:`mpf.floats.MPF.set_nan` set to NaN. PyMPF does not support + the distinction between signalling and non-signalling NaNs, + similarly to SMT-LIB. + +Finally, to do arithmetic, you can use the fp_* functions. Most take a +rounding mode and two parameters: + +>>> x.from_rational(RM_RNE, Rational(1, 10)) +>>> y.from_rational(RM_RNE, Rational(10)) +>>> z = fp_mul(RM_RNE, x, y) +>>> z.to_python_string() +'1.0' + +Here an example demonstrating accumulated rounding errors: + +>>> y.set_zero(0) +>>> for i in range(10): +>>> y = fp_add(RM_RNE, y, x) +>>> print(y.to_python_string()) +0.100000001490116119384765625 +0.20000000298023223876953125 +0.300000011920928955078125 +0.4000000059604644775390625 +0.5 +0.60000002384185791015625 +0.7000000476837158203125 +0.80000007152557373046875 +0.900000095367431640625 +1.00000011920928955078125 + ========= Rationals ========= @@ -20,3 +146,19 @@ MPF .. automodule:: mpf.floats :members: :special-members: + +========= +Changelog +========= + +1.0 +--- + +1.0.3 +^^^^^ +* Add basic documentation (fast tutorial, and basic descriptions of + MPF and Rational classes). + +1.0.2 +^^^^^ +* First public release on PyPI.