Abstract

This proposal gives the user optional control over the precisionand range of numeric computations so that a computation can bewritten once and run anywhere with at least the desired precisionand range. It is backward compatible with existing code. Themeaning of decimal literals is clarified.

Rationale

Currently it is impossible in every language except Fortran 90 towrite a program in a portable way that uses floating point andgets roughly the same answer regardless of platform – or refusesto compile if that is not possible. Python currently has only onefloating point type, equal to a C double in the C implementation.

No type exists corresponding to single or quad floats. It wouldcomplicate the language to try to introduce such types directlyand their subsequent use would not be portable. This proposal issimilar to the Fortran 90 “kind” solution, adapted to the Pythonenvironment. With this facility an entire calculation can beswitched from one level of precision to another by changing asingle line. If the desired precision does not exist on aparticular machine, the program will fail rather than get thewrong answer. Since coding in this style would involve an earlycall to the routine that will fail, this is the next best thing tonot compiling.

Supported Kinds of Ints and Floats

Complex numbers are treated separately below, since Python can bebuilt without them.

Each Python compiler may define as many “kinds” of integer andfloating point numbers as it likes, except that it must support atleast two kinds of integer corresponding to the existing int andlong, and must support at least one kind of floating point number,equivalent to the present float.

The range and precision of these required kinds are processordependent, as at present, except for the “long integer” kind,which can hold an arbitrary integer.

The built-in functionsint(),long(), andfloat() convert inputsto these default kinds as they do at present. (Note that aUnicode string is actually a different “kind” of string and that asufficiently knowledgeable person might be able to expand this PEPto cover that case.)

Within each type (integer, floating) the compiler supports alinearly-ordered set of kinds, with the ordering determined by theability to hold numbers of an increased range and/or precision.

Kind Objects

Two new standard functions are defined in a module named “kinds”.They return callable objects called kind objects. Each int orfloating kind object f has the signatureresult=f(x), and eachcomplex kind object has the signatureresult=f(x,y=0.).

int_kind(n)

For an integer argumentn>=1, return a callable object whoseresult is an integer kind that will hold an integer number inthe open interval (-10**n,10**n). The kind object acceptsarguments that are integers including longs. Ifn==0,returns the kind object corresponding to the Python literal 0.

float_kind(nd,n)

Fornd>=0 andn>=1, return a callable object whose resultis a floating point kind that will hold a floating-pointnumber with at least nd digits of precision and a base-10exponent in the closed interval[-n,n]. The kind objectaccepts arguments that are integer or float.

If nd and n are both zero, returns the kind objectcorresponding to the Python literal 0.0.

The compiler will return a kind object corresponding to the leastof its available set of kinds for that type that has the desiredproperties. If no kind with the desired qualities exists in agiven implementation anOverflowError exception is thrown. A kindfunction converts its argument to the target kind, but if theresult does not fit in the target kind’s range, anOverflowErrorexception is thrown.

Besides their callable behavior, kind objects have attributesgiving the traits of the kind in question.

1. name is the name of the kind. The standard kinds are calledint, long, double.
2. typecode is a single-letter string that would be appropriatefor use withNumeric or modulearray to form an array of thiskind. The standard types’ typecodes are ‘i’, ‘O’, ‘d’respectively.
3. Integer kinds have these additional attributes:MAX, equal tothe maximum permissible integer of this kind, orNone for thelong kind.MIN, equal to the most negative permissible integerof this kind, orNone for the long kind.
4. Float kinds have these additional attributes whose propertiesare equal to the corresponding value for the corresponding Ctype in the standard header file “float.h”.MAX,MIN,DIG,MANT_DIG,EPSILON,MAX_EXP,MAX_10_EXP,MIN_EXP,MIN_10_EXP,RADIX,ROUNDS(==FLT_RADIX,FLT_ROUNDS in float.h). Thesevalues are of type integer except forMAX,MIN, andEPSILON,which are of the Python floating type to which the kindcorresponds.

Attributes of Module kinds

int_kinds is a list of the available integer kinds, sorted from lowestto highest kind. By definition,int_kinds[-1] is the long kind.

float_kinds is a list of the available floating point kinds, sortedfrom lowest to highest kind.

default_int_kind is the kind object corresponding to the Pythonliteral 0

default_long_kind is the kind object corresponding to the Pythonliteral 0L

default_float_kind is the kind object corresponding to the Pythonliteral 0.0

Complex Numbers

If supported, complex numbers have real and imaginary parts thatare floating-point numbers with the same kind. A Python compilermust support a complex analog of each floating point kind itsupports, if it supports complex numbers at all.

If complex numbers are supported, the following are available inmodule kinds:

complex_kind(nd,n)

Return a callable object whose result is a complex kind thatwill hold a complex number each of whose components (.real,.imag) is of kindfloat_kind(nd,n). The kind object willaccept one argument that is of any integer, real, or complexkind, or two arguments, each integer or real.

complex_kinds is a list of the available complex kinds, sortedfrom lowest to highest kind.

default_complex_kind is the kind object corresponding to thePython literal 0.0j. The name of this kindis doublecomplex, and its typecode is ‘D’.

Complex kind objects have these addition attributes:

floatkind is the kind object of the corresponding float type.

Examples

In module myprecision.py:

importkindstinyint=kinds.int_kind(1)single=kinds.float_kind(6,90)double=kinds.float_kind(15,300)csingle=kinds.complex_kind(6,90)

In the rest of my code:

frommyprecisionimporttinyint,single,double,csinglen=tinyint(3)x=double(1.e20)z=1.2# builtin float gets you the default float kind, properties unknownw=x*float(x)# but in the following case we know w has kind "double".w=x*double(z)u=csingle(x+z*1.0j)u2=csingle(x+z,1.0)

Note how that entire code can then be changed to a higherprecision by changing the arguments in myprecision.py.

Comment: note that you aren’t promised that single != double; butyou are promised thatdouble(1.e20) will hold a number with 15decimal digits of precision and a range up to10**300 or that thefloat_kind call will fail.

Open Issues

No open issues have been raised at this time.

Copyright

This document has been placed in the public domain.