peps/pep-0242.txt at main · python/peps

Cannot retrieve contributors at this time

237 lines (176 sloc) 8.27 KB

	PEP: 242
	Title: Numeric Kinds
	Author: Paul F. Dubois <paul@pfdubois.com>
	Status: Rejected
	Type: Standards Track
	Content-Type: text/x-rst
	Created: 17-Mar-2001
	Python-Version: 2.2
	Post-History: 17-Apr-2001


	Abstract
	========

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


	Rationale
	=========

	Currently it is impossible in every language except Fortran 90 to
	write a program in a portable way that uses floating point and
	gets roughly the same answer regardless of platform -- or refuses
	to compile if that is not possible. Python currently has only one
	floating point type, equal to a C double in the C implementation.

	No type exists corresponding to single or quad floats. It would
	complicate the language to try to introduce such types directly
	and their subsequent use would not be portable. This proposal is
	similar to the Fortran 90 "kind" solution, adapted to the Python
	environment. With this facility an entire calculation can be
	switched from one level of precision to another by changing a
	single line. If the desired precision does not exist on a
	particular machine, the program will fail rather than get the
	wrong answer. Since coding in this style would involve an early
	call to the routine that will fail, this is the next best thing to
	not compiling.


	Supported Kinds of Ints and Floats
	==================================

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

	Each Python compiler may define as many "kinds" of integer and
	floating point numbers as it likes, except that it must support at
	least two kinds of integer corresponding to the existing int and
	long, 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 processor
	dependent, as at present, except for the "long integer" kind,
	which can hold an arbitrary integer.

	The built-in functions ``int()``, ``long()``, and ``float()`` convert inputs
	to these default kinds as they do at present. (Note that a
	Unicode string is actually a different "kind" of string and that a
	sufficiently knowledgeable person might be able to expand this PEP
	to cover that case.)

	Within each type (integer, floating) the compiler supports a
	linearly-ordered set of kinds, with the ordering determined by the
	ability 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 or
	floating kind object f has the signature ``result = f(x)``, and each
	complex kind object has the signature ``result = f(x, y=0.)``.

	``int_kind(n)``
	For an integer argument ``n >= 1``, return a callable object whose
	result is an integer kind that will hold an integer number in
	the open interval (``-10n``, ``10n``). The kind object accepts
	arguments that are integers including longs. If ``n == 0``,
	returns the kind object corresponding to the Python literal 0.

	``float_kind(nd, n)``
	For ``nd >= 0`` and ``n >= 1``, return a callable object whose result
	is a floating point kind that will hold a floating-point
	number with at least nd digits of precision and a base-10
	exponent in the closed interval ``[-n, n]``. The kind object
	accepts arguments that are integer or float.

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

	The compiler will return a kind object corresponding to the least
	of its available set of kinds for that type that has the desired
	properties. If no kind with the desired qualities exists in a
	given implementation an ``OverflowError`` exception is thrown. A kind
	function converts its argument to the target kind, but if the
	result does not fit in the target kind's range, an ``OverflowError``
	exception is thrown.

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

	1. ``name`` is the name of the kind. The standard kinds are called
	int, long, double.

	2. ``typecode`` is a single-letter string that would be appropriate
	for use with ``Numeric`` or module ``array`` to form an array of this
	kind. The standard types' typecodes are 'i', 'O', 'd'
	respectively.

	3. Integer kinds have these additional attributes: ``MAX``, equal to
	the maximum permissible integer of this kind, or ``None`` for the
	long kind. ``MIN``, equal to the most negative permissible integer
	of this kind, or ``None`` for the long kind.

	4. Float kinds have these additional attributes whose properties
	are equal to the corresponding value for the corresponding C
	type 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). These
	values are of type integer except for ``MAX``, ``MIN``, and ``EPSILON``,
	which are of the Python floating type to which the kind
	corresponds.


	Attributes of Module kinds
	==========================

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

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

	``default_int_kind`` is the kind object corresponding to the Python
	literal 0

	``default_long_kind`` is the kind object corresponding to the Python
	literal 0L

	``default_float_kind`` is the kind object corresponding to the Python
	literal 0.0


	Complex Numbers
	===============

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

	If complex numbers are supported, the following are available in
	module kinds:

	``complex_kind(nd, n)``
	Return a callable object whose result is a complex kind that
	will hold a complex number each of whose components (.real,
	.imag) is of kind ``float_kind(nd, n)``. The kind object will
	accept one argument that is of any integer, real, or complex
	kind, or two arguments, each integer or real.

	``complex_kinds`` is a list of the available complex kinds, sorted
	from lowest to highest kind.

	``default_complex_kind`` is the kind object corresponding to the
	Python literal 0.0j. The name of this kind
	is 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::

	import kinds
	tinyint = 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::

	from myprecision import tinyint, single, double, csingle
	n = tinyint(3)
	x = double(1.e20)
	z = 1.2
	# builtin float gets you the default float kind, properties unknown
	w = 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 higher
	precision by changing the arguments in myprecision.py.

	Comment: note that you aren't promised that single != double; but
	you are promised that ``double(1.e20)`` will hold a number with 15
	decimal digits of precision and a range up to ``10**300`` or that the
	``float_kind`` call will fail.


	Open Issues
	===========

	No open issues have been raised at this time.


	Rejection
	=========

	This PEP has been closed by the author. The kinds module will not
	be added to the standard library.

	There was no opposition to the proposal but only mild interest in
	using it, not enough to justify adding the module to the standard
	library. Instead, it will be made available as a separate
	distribution item at the Numerical Python site. At the next
	release of Numerical Python, it will no longer be a part of the
	Numeric distribution.


	Copyright
	=========

	This document has been placed in the public domain.