bigfloat
The BigFloat
class implements multiple-precision binary floating-point numbers. Each BigFloat
instance has both a value and a precision; the precision is an integer giving the number of significant bits used to store the value. A finite nonzero BigFloat
instance with precision p can be thought of as a (sign, significand, exponent) triple (s, m, e), representing the value (-1)s * m * 2e, where m is a value in the range [0.5, 1.0) stored with p bits of precision. Thus m is of the form n/2*p for some integer n with 2(p-1) <= n < 2*p.
In addition to nonzero finite numbers, BigFloat
instances can also represent positive and negative infinity, positive and negative zero, and NaNs.
BigFloat
instances should be treated as immutable.
Construct a new BigFloat
instance from an integer, string, float or another BigFloat
instance, using the rounding-mode and output format (precision, exponent bounds and subnormalization) given by the current context. If the context keyword argument is given, its value should be a Context
instance and its attributes override those of the current context.
value can be an integer, string, float, or another BigFloat
instance. In all cases the given value is rounded to the format (determined by precision, exponent limits and subnormalization) given by the current context, using the rounding mode specified by the current context. The integer 0 is always converted to positive zero.
as_integer_ratio(self)
Return a pair (n, d) of integers such that n and d are relatively prime, d is positive, and the value of self is exactly n/d.
If self is an infinity or nan then ValueError is raised. Negative and positive zero are both converted to (0, 1).
copy_abs(self)
Return a copy of self with the sign bit unset.
In contrast to abs(self)
, self.copy_abs()
makes no use of the context, and the result has the same precision as the original.
copy_neg(self)
Return a copy of self with the opposite sign bit.
In constract to neg(self)
, self.copy_neg()
makes no use of the context, and the result has the same precision as the original.
exact(cls, value, precision=None)
A class method to construct a new BigFloat
instance from an integer, string, float or another BigFloat
instance, doing an exact conversion where possible. Unlike the usual BigFloat
constructor, this alternative constructor makes no use of the current context and will not affect the current flags.
If value is an integer, float or BigFloat
, then the precision keyword must not be given, and the conversion is exact. The resulting BigFloat
has a precision sufficiently large to hold the converted value exactly. If value is a string, then the precision argument must be given. The string is converted using the given precision and the RoundTiesToEven
rounding mode.
fromhex(cls, value, context=None)
Class method that constructs a new BigFloat
instance from a hexadecimal string. Rounds to the current context using the given precision. If the context keyword argument is given, its value should be a Context
instance and its attributes override those of the current context.
hex(self)
Return a hexadecimal representation of a BigFloat
. The advantage of the hexadecimal representation is that it represents the value of the BigFloat
exactly.
precision
Precision of a BigFloat
instance, in bits.
The BigFloat
type has a full complement of special methods. Here are some brief notes on those methods, indicating possible deviations from expected behaviour.
- The repr of a
BigFloat
instancex
is independent of the current context, and has the property thateval(repr(x))
recoversx
exactly. - The '+' ,'-', '', '/', '//', '%' and '*' binary operators are supported. The '/' operator implements true division, regardless of whether
from __future__ import division
is in effect or not. The result of '%' has the same sign as the second argument, so follows the existing Python semantics for '%' on Python floats. - For the above operators, mixed-type operations involving a
BigFloat
and an integer or float are permitted. These behave as though the nonBigFloat
operand is first converted to aBigFloat
with no loss of accuracy. - The '+' and '-' unary operators and built-in
abs
function are supported. Note that these all round to the current context; in particular, '+x' is not necessarily equal to 'x' for aBigFloat
instancex
. - The six comparison operators '==', '<=', '<', '!=', '>', '>=' are supported. Comparisons involving NaNs always return False, except in the case of '!=' where they always return True. Again, comparisons with integers or floats are permitted, with the integer or float being converted exactly before the comparison; the context does not affect the result of a comparison.
- Conversions to int and long always round towards zero; conversions to float always use the
ROUND_TIES_TO_EVEN
rounding mode. Conversion to bool returns False for a nonzeroBigFloat
and True otherwise. None of these conversions is affected by the current context. - On Python 3,
round
,math.floor
,math.ceil
andmath.trunc
all behave as expected, returning the appropriate integer. They are unaffected by the current context. Note that Python 2 does not provided type-specific support for these four functions; the functions will all work on Python, but only by doing an implicit conversion to the built-infloat
type first. BigFloat
instances are hashable. The hash function obeys the rule that objects that compare equal should hash equal; in particular, ifx == n
for someBigFloat
instancex
and some Python int or longn
thenhash(x) == hash(n)
, and similarly for floats.BigFloat
instances supportstr.format
-based formatting, as described in PEP 3101. The format specifier is much as described in the PEP, except that there's additional support for hexadecimal and binary output, and for specification of a rounding mode. The general form of the format specifier looks like this:[[fill]align][sign][#][0][minimumwidth][.precision][rounding][type]
The
type
field is a single letter, which may be any of the following. The'e'
,'E'
,'f'
,'F'
,'g'
,'G'
and'%'
types behave in the same way as for regular floats. Only the'a'
,'A'
and'b'
formats are particular toBigFloat
instances. The type may also be omitted, in which casestr
-style formatting is performed.'a'
Output in hexadecimal format. 'A'
Upper case variant of 'a'
.'b'
Output in binary format. 'e'
Scientific format. 'E'
Upper case variant of 'e'
.'f'
Fixed-point format. 'F'
Upper case variant of 'f'
.'g'
Friendly format. 'G'
Upper case variant of 'g'
.'%'
Like 'f'
, but formatted as a percentage.The optional
rounding
field consists of a single letter describing the rounding direction to be used when converting aBigFloat
instance to a decimal value. The default is to use round-ties-to-even. Valid values for this field are described in the table below.'U'
Round toward positive 'D'
Round toward negative 'Y'
Round away from zero 'Z'
Round toward zero 'N'
Round ties to even Examples:
>>> from bigfloat import sqrt >>> "{0:.6f}".format(sqrt(2)) '1.414214' >>> "{0:.6Df}".format(sqrt(2)) # round down '1.414213' >>> "{0:.^+20.6e}".format(sqrt(2)) '...+1.414214e+00....' >>> "{0:a}".format(sqrt(2)) '0x1.6a09e667f3bcdp+0' >>> "{0:b}".format(sqrt(2)) '1.0110101000001001111001100110011111110011101111001101p+0'
A Context
object is a simple immutable object that packages together attributes describing a floating-point format, together with a rounding mode.
Create a new Context
object with the given attributes. Not all attributes need to be specified. Note that all attributes of the generated Context
are read-only. Attributes that are unset for this Context
instance return None
.
precision
Precision of the floating-point format, given in bits. This should be an integer in the range [PRECISION_MIN
, PRECISION_MAX
].
emax
Maximum exponent allowed for this format. The largest finite number representable in the context self is (1-2**-self.precision) * 2**self.emax
.
emin
Minimum exponent allowed for this format. The smallest positive number representable in the context self is 0.5 * 2**self.emin
.
Note
There's nothing to stop you defining a context with emin > emax, but don't expect to get sensible results if you do this.
subnormalize
A boolean value: True if the format has gradual underflow, and False otherwise. With gradual underflow, all finite floating-point numbers have a value that's an integer multiple of 2**(emin-1).
rounding
The rounding mode of this Context
, for example ROUND_TIES_TO_EVEN
. The available rounding modes are described in the rounding modes
section. Note that the values RoundTiesToEven
, etc. exported by the bigfloat
package are Context
instances, not rounding modes, so cannot be used directly here.
Context
instances can be added. If x
and y
are Context
instances then x + y
is the Context
whose attributes combine those of x
and y
. In the case that both x
and y
have a particular attribute set, the value for y
takes precedence:
>>> x = Context(precision=200, rounding=ROUND_TIES_TO_EVEN) >>> y = Context(precision=53, subnormalize=True) >>> x + y Context(precision=53, subnormalize=True, rounding=ROUND_TIES_TO_EVEN) >>> y + x Context(precision=200, subnormalize=True, rounding=ROUND_TIES_TO_EVEN)
Context
instances can be used in with statements to alter the current context. In effect, :
with c:
<block>
behaves roughly like :
old_context = getcontext()
setcontext(c)
<block>
setcontext(old_context)
except that nesting of with statements works as you'd expect, and the old context is guaranteed to be restored even if an exception occurs during execution of the block.
Note that for Context
instances x
and y
, :
with x + y:
<block>
is exactly equivalent to :
with x:
with y:
<block>
The bigfloat package defines a number of predefined Context
instances.
DefaultContext
The context that's in use when the bigfloat package is first imported. It has precision of 53, large exponent bounds, no subnormalization, and the RoundTiesToEven rounding mode.
EmptyContext
Equal to Context()
. Occasionally useful where a context is syntactically required for a with statement, but no change to the current context is desired. For example:
if <want_extra_precision>:
c = extra_precision(10)
else:
c = EmptyContext
with c:
<do calculation>
half_precision
single_precision
double_precision
quadruple_precision
These Context
instances correspond to the binary16, binary32, binary64 and binary128 interchange formats described in IEEE 754-2008 (section 3.6). They're all special cases of the IEEEContext
function.
IEEEContext
precision
rounding
RoundTiesToEven
RoundTowardZero
RoundAwayFromZero
RoundTowardPositive
RoundTowardNegative
Context
objects corresponding to the five available rounding modes. RoundTiesToEven
rounds the result of an operation or function to the nearest representable BigFloat
, with ties rounded to the BigFloat
whose least significant bit is zero. RoundTowardZero
rounds results towards zero. RoundAwayFromZero
rounds results away from zero. RoundTowardPositive
rounds results towards positive infinity, and RoundTowardsNegative
rounds results towards negative infinity.
PRECISION_MIN
PRECISION_MAX
Minimum and maximum precision that's valid for Context
and BigFloat
instances. In the current implementation, PRECISION_MIN
is 2
and PRECISION_MAX
is 2**31-1
.
EMIN_MIN
EMIN_MAX
Minimum and maximum allowed values for the Context
emin attribute. In the current implementation, EMIN_MIN == -EMIN_MAX == 1-2**30
.
EMAX_MIN
EMAX_MAX
Minimum and maximum allowed values for the Context
emax attribute. In the current implementation, -EMAX_MIN == EMAX_MAX == 2**30-1
.
There can be many Context
objects in existence at one time, but there's only ever one current context. The current context is given by a thread-local Context
instance. Whenever the BigFloat
constructor is called, or any arithmetic operation or standard function computation is performed, the current context is consulted to determine:
- The format that the result of the operation or function should take (as specified by the
precision
,emax
,emin
andsubnormalize
attributes of the context), and - The rounding mode to use when computing the result, as specified by the
rounding
attribute of the current context.
If an additional context
keyword argument is given to the operation, function or constructor, then attributes from the context override the corresponding attributes in the current context. For example, :
sqrt(x, context=my_context)
is equivalent to :
with my_context:
sqrt(x)
The current context can be read and written directly using the getcontext
and setcontext
functions.
getcontext()
setcontext(context)
It's usually neater to make a temporary change to the context using a with statement, as described above. There's also one convenience function that's often useful in calculations:
extra_precision
ROUND_TIES_TO_EVEN
This is the default rounding mode. The number to be rounded is mapped to the nearest representable value. In the case where that number is exactly midway between the two closest representable values, it is mapped to the value with least significant bit set to zero.
ROUND_TOWARD_ZERO
The number to be rounded is mapped to the nearest representable value that's smaller than or equal to the original number in absolute value.
ROUND_AWAY_FROM_ZERO
The number to be rounded is mapped to the nearest representable value that's greater than or equal to the original number in absolute value.
ROUND_TOWARD_POSITIVE
The number to be rounded is mapped to the nearest representable value greater than or equal to the original number.
ROUND_TOWARD_NEGATIVE
The number to be rounded is mapped to the nearest representable value less than or equal to the original number.
All functions in this section follow the same rules:
- Arguments can be
BigFloat
instances, integers or floats, unless otherwise specified. - Integer or float arguments are converted exactly to
BigFloat
instances. - The format of the result and the rounding mode used to obtain that result are taken from the current context.
- Attributes of the current context can be overridden by supplying an explicit
context
keyword argument. - Results are correctly rounded.
add
sub
mul
div
pow
fmod
floordiv
mod
remainder
dim
pos
neg
abs
fma
fms
sqr
sqrt
rec_sqrt
cbrt
root
hypot
exp
exp2
exp10
log
log2
log10
expm1
log1p
cos
sin
tan
sec
csc
cot
The above six trigonometric functions are inefficient for large arguments (for example, x
larger than BigFloat('1e1000000')
), since reducing x
correctly modulo π requires computing π to high precision. Input arguments are in radians, not degrees.
acos
asin
atan
These functions return a result in radians.
atan2
cosh
sinh
tanh
sech
csch
coth
acosh
asinh
atanh
eint
li2
gamma
lngamma
lgamma
zeta
zeta_ui
erf
erfc
j0
j1
jn
y0
y1
yn
agm
factorial
const_catalan
const_euler
const_log2
const_pi
max
min
copysign
frac
ceil
floor
round
trunc
These are the functions exported by the bigfloat
package that don't fit into the above section, for one reason or another.
These functions provide three-way comparisons.
sgn
cmp
cmpabs
The following functions match the functionality of the builtin Python comparison operators.
greater
greaterequal
less
lessequal
equal
notequal
0.4 The notequal
function was added in version 0.4.
There are two additional comparison functions that don't correspond to any of the Python comparison operators.
lessgreater
unordered
The following functions all accept a single BigFloat
instance (or a float, or an integer) and return a boolean value. They make no use of the current context, and do not affect the state of the flags.
is_nan
is_inf
is_zero
is_finite
is_negative
is_integer
next_up
next_down
Underflow
Underflow flag. Set whenever the result of an operation underflows. The meaning of this flag differs depending on whether the subnormalize attribute is true for the operation context. In the language of IEEE 754, we use the after rounding semantics. The Underflow flag is set on underflow even when the result of an operation is exact.
In detail: let c
be the context that's in effect for an operation, function or BigFloat
construction. Let x
be the result of the operation, rounded to the context precision with the context rounding mode, but as though the exponent were unbounded.
If c.subnormalize is False, the Underflow flag is set if and only if x
is nonzero, finite, and strictly smaller than 2**(c.emin-1)
in absolute value. If c.subnormalize is True, the Underflow flag is set if and only if x
is nonzero, finite, and strictly smaller than 2**(c.emin+c.precision-2)
in absolute value.
Overflow
Set whenever the result of an operation overflows. An operation performed in a context c
overflows if the result computed as if with unbounded exponent range is finite and greater than or equal to 2**c.emax
in absolute value.
ZeroDivision
Set whenever an exact infinite result is obtained from finite inputs. Despite the name, this flag is not just set for divisions by zero. For example, log(0)
will set the ZeroDivision flag.
Inexact
Inexact flag. Set whenever the result of an operation is not exactly equal to the true mathematical result.
NanFlag
NaN flag. Set whever the result of an operation gives a NaN result.
clear_flag
set_flag
test_flag
get_flagstate
set_flagstate
MPFR_VERSION_STRING
The version of the MPFR library being used, as a string.
MPFR_VERSION
The version of the MPFR library being used, as an integer.
MPFR_VERSION_MAJOR
An integer giving the major level of the MPFR version.
MPFR_VERSION_MINOR
An integer giving the minor level of the MPFR version.
MPFR_VERSION_PATCHLEVEL
An integer giving the patch level of the MPFR version.