Number Systems

FPy supports a variety of number systems including multi-precision floating-point and fixed-point numbers.

Philosophy

This library embraces design principles found in the FPCore standard. Most importantly, numerical programs need only be specified by (i) real-number mathematical operations and (ii) rounding. Number formats, e.g., double or float, are not first-class, as in most programming languages. Rather, formats are just side effects of rounding and should be de-emphasized or eliminated entirely. Furthermore, all values within a numerical program should be viewed as (extended) real numbers.

Rounding Contexts

FPy provides a hierarchy of abstract classes describing rounding contexts.

Abstract Contexts

class fpy2.Context

Bases: ABC

Rounding context type.

Most mathematical operators on numbers can be decomposed into two steps:

1. a mathematically-correct operation over real numbers, interpreting numbers as real numbers;

2. a rounding operation to limit the number significant digits and decide how the “lost” digits will affect the final output.

Thus, rounding enforces a particular “format” for numbers, but they should just be considered unbounded real numbers when in isolation. The characteristics of the rounding operation are summarized by this type.

canonical_under(x: Float) → bool

Returns if x is canonical under this context.

This function only considers relevant attributes to judge if a value is canonical. Thus, there may be more than one canonical value for a given number despite the function name. The result of self.normalize() is always canonical.

abstractmethod format() → Format

Returns the number format associated with this context.

The format describes the set of representable values without the rounding rule. Format-only methods on Context (representable_under, etc.) default to delegating to the corresponding method on self.format().

is_equiv(other: Context) → bool: Returns if this context and another context round values to the same set of representable values. Two contexts are equivalent if they produce the same set of representable values.

abstractmethod is_stochastic() → bool

Returns if this context is stochastic.

Stochastic contexts are used for probabilistic rounding.

normal_under(x: Float) → bool

Returns if x is “normal” under this context.

For IEEE-style contexts, this means that x is finite, non-zero, and x.normalize() has full precision.

normalize(x: Float) → Float: Returns the canonical form of x under this context.

representable_under(x: Float | RealFloat) → bool

Returns if x is representable under this context.

Representable is not the same as canonical, but every canonical value must be representable.

abstractmethod round(x, *, exact: bool = False) → Float

Rounds any number according to this context.

If exact=True, then the rounding operation will raise a ValueError if rounding produces an inexact result.

abstractmethod round_at(x, n: int, *, exact: bool = False) → Float

Rounding any number of a representable value with an unnormalized exponent of at minimum n + 1.

Rounding is done by the following rules:

if x is representable and has an unnormalized exponent of at minimum n + 1, then self.round_n(x, n) == x
if x is between two representable values i1 < x < i2 where both i1 and i2 have unnormalized exponents of at minimum n + 1, then the context information determines which value is returned.

If exact=True, then the rounding operation will raise a ValueError if rounding produces an inexact result.

round_integer(x) → Float

Rounds any number to an integer according to this context.

Rounding is done by the following rules:

if x is a representable integer, then self.round_integer(x) == x
if x is between two representable integers i1 < x < i2, then the context information determines which integer is returned.

This is equivalent to self.round_at(x, -1).

abstractmethod round_params() → tuple[int | None, int | None]

Returns the rounding parameters (max_p, min_n) used for rounding under this context.

(p, None) => floating-point style rounding
(p, n) => floating-point style rounding with subnormalization
(None, n) => fixed-point style rounding
(None, None) => real computation; no rounding

These parameters also determine the amount of precision for intermediate round-to-odd operations (provided by MPFR / gmpy2).

abstractmethod with_params(**kwargs) → Self: Returns self but with updated parameters.

class fpy2.OrdinalContext

Bases: Context

Rounding context for formats that map to ordinal numbers.

Most common number formats fall under this category. There exists a bijection between representable values and a subset of the integers.

abstractmethod format() → OrdinalFormat

Returns the number format associated with this context.

The format describes the set of representable values without the rounding rule. Format-only methods on Context (representable_under, etc.) default to delegating to the corresponding method on self.format().

from_ordinal(x: int, infval: bool = False) → Float

Maps an ordinal number to a number.

When infval=True, infinities are mapped to the next (or previous) logical ordinal value after +/-MAX_VAL. This option is only valid when the context has a maximum value.

minval(s: bool = False) → Float

Returns the (signed) representable value with the minimum magnitude under this context.

This value will map to +/-1 through to_ordinal().

next_away_zero(x: Float, allow_inf: bool = False) → Float

Returns the next representable value after x away from zero.

Raises a ValueError if - x is not representable under this context, or - x is NaN, or - x is infinite and allow_inf is False - x == 0

next_down(x: Float, allow_inf: bool = False) → Float

Returns the next representable value after x towards negative infinity.

Raises a ValueError if - x is not representable under this context, or - x is NaN, or - x is infinite and allow_inf is False - x == -inf

next_towards(x: Float, y: Float, allow_inf: bool = False) → Float

Returns the next representable value after x towards y.

Raises a ValueError if - x or y is not representable under this context, or - x or y is NaN, or - x is infinite and allow_inf is False - x == y

next_towards_zero(x: Float, allow_inf: bool = False) → Float

Returns the next representable value after x towards zero.

Raises a ValueError if - x is not representable under this context, or - x is NaN, or - x is infinite and allow_inf is False - x == 0

next_up(x: Float, allow_inf: bool = False) → Float

Returns the next representable value after x towards positive infinity.

Raises a ValueError if - x is not representable under this context, or - x is NaN, or - x is infinite and allow_inf is False - x == +inf

to_fractional_ordinal(x: Float) → Fraction

Maps a number to a (fractional) ordinal number.

Unlike self.to_ordinal(x), the argument x does not have to be representable under this context. If x is representable, then self.to_ordinal(x) == self.to_fractional_ordinal(x). If x is not representable, then self.to_fractional_ordinal(x) is not an integer; it is up to the context to decide how to interpolate between representable numbers.

Raises a ValueError when x.is_nar() is True.

to_ordinal(x: Float, infval: bool = False) → int

Maps a number to an ordinal number.

When infval=True, infinities are mapped to the next (or previous) logical ordinal value after +/-MAX_VAL. This option is only valid when the context has a maximum value.

class fpy2.SizedContext

Bases: OrdinalContext

Rounding context for formats encodable in a fixed size.

These formats may be mapped to ordinal numbers, and they have a (positive) minimum and (positive) maximum value.

property emax: int: The normalized exponent of the maximum representable value under this context.

abstractmethod format() → SizedFormat

Returns the number format associated with this context.

The format describes the set of representable values without the rounding rule. Format-only methods on Context (representable_under, etc.) default to delegating to the corresponding method on self.format().

infval(s: bool = False) → Float: Returns the (signed) value that is the “next” value after the maximum representable value under this context.

largest() → Float: Returns the largest representable value (towards positive infinity) under this context.

maxval(s: bool = False) → Float

Returns the (signed) representable value with the maximum magnitude under this context.

If self.maxval() == 0, then this context cannot represent any finite, non-zero values.

smallest() → Float: Returns the smallest representable value (towards negative infinity) under this context.

class fpy2.EncodableContext

Bases: SizedContext

Rounding context for formats that can be encoded as bitstrings.

Most common number formats fall under this category. These formats define a way to encode a number in memory.

decode(x: int) → Float: Decodes a bitstring as a a number constructed under this context. This operation is context dependent.

encode(x: Float) → int: Encodes a number constructed under this context as a bitstring. This operation is context dependent.

abstractmethod format() → EncodableFormat

Returns the number format associated with this context.

The format describes the set of representable values without the rounding rule. Format-only methods on Context (representable_under, etc.) default to delegating to the corresponding method on self.format().

total_bits() → int: Returns the total number of bits used to encode a number under this context.

FPy provides a number of concrete rounding contexts. Each context implements a particular flavor of rounding.

Floating-Point Contexts

class fpy2.MPFloatContext(pmax: int, rm: RoundingMode = RoundingMode.RNE, num_randbits: int | None = 0, *, rng: Random | Generator | None = None)

Bases: Context

Rounding context for multi-precision floating-point numbers.

This context is parameterized by a fixed precision pmax and a rounding mode rm. It emulates floating-point numbers as implemented by MPFR.

format() → MPFloatFormat

Returns the number format associated with this context.

The format describes the set of representable values without the rounding rule. Format-only methods on Context (representable_under, etc.) default to delegating to the corresponding method on self.format().

classmethod from_format(fmt: MPFloatFormat, *, rm: RoundingMode = RoundingMode.RNE, num_randbits: int | None = 0, rng: Random | Generator | None = None) → MPFloatContext: Creates a context from a MPFloatFormat and rounding parameters.

is_stochastic() → bool

Returns if this context is stochastic.

Stochastic contexts are used for probabilistic rounding.

num_randbits: int | None: number of random bits for stochastic rounding, if applicable

pmax: int: maximum precision

rm: RoundingMode: rounding mode

rng: Random | Generator | None: random number generator for stochastic rounding, if applicable

round(x, *, exact: bool = False) → Float

Rounds any number according to this context.

If exact=True, then the rounding operation will raise a ValueError if rounding produces an inexact result.

round_at(x, n: int, *, exact: bool = False) → Float

Rounding any number of a representable value with an unnormalized exponent of at minimum n + 1.

Rounding is done by the following rules:

if x is representable and has an unnormalized exponent of at minimum n + 1, then self.round_n(x, n) == x
if x is between two representable values i1 < x < i2 where both i1 and i2 have unnormalized exponents of at minimum n + 1, then the context information determines which value is returned.

If exact=True, then the rounding operation will raise a ValueError if rounding produces an inexact result.

round_params() → tuple[int | None, int | None]

Returns the rounding parameters (max_p, min_n) used for rounding under this context.

(p, None) => floating-point style rounding
(p, n) => floating-point style rounding with subnormalization
(None, n) => fixed-point style rounding
(None, None) => real computation; no rounding

These parameters also determine the amount of precision for intermediate round-to-odd operations (provided by MPFR / gmpy2).

with_params(*, pmax: int | Literal[Default.DEFAULT] = DEFAULT, rm: RoundingMode | Literal[Default.DEFAULT] = DEFAULT, num_randbits: int | None | Literal[Default.DEFAULT] = DEFAULT, rng: Random | Generator | None | Literal[Default.DEFAULT] = DEFAULT, **kwargs) → MPFloatContext: Returns self but with updated parameters.

class fpy2.MPSFloatContext(pmax: int, emin: int, rm: RoundingMode = RoundingMode.RNE, num_randbits: int | None = 0, *, rng: Random | Generator | None = None)

Bases: OrdinalContext

Rounding context for multi-precision floating-point numbers with a minimum exponent (and subnormalization).

This context is parameterized by a fixed precision pmax, a minimum (normalized) exponent emin, and a rounding mode rm. It emulates floating-point numbers as implemented by MPFR with subnormalization.

Unlike MPFloatContext, the MPSFloatContext inherits from OrdinalContext since each representable value can be mapped to the ordinals.

emin: int: minimum (normalized exponent)

property expmin: Minimum unnormalized exponent.

format() → MPSFloatFormat

Returns the number format associated with this context.

The format describes the set of representable values without the rounding rule. Format-only methods on Context (representable_under, etc.) default to delegating to the corresponding method on self.format().

classmethod from_format(fmt: MPSFloatFormat, *, rm: RoundingMode = RoundingMode.RNE, num_randbits: int | None = 0, rng: Random | Generator | None = None) → MPSFloatContext: Creates a context from a MPSFloatFormat and rounding parameters.

is_stochastic() → bool

Returns if this context is stochastic.

Stochastic contexts are used for probabilistic rounding.

max_subnormal(s: bool = False) → Float: Returns the largest subnormal value with sign s under this context.

min_normal(s: bool = False) → Float: Returns the smallest normal value with sign s under this context.

min_subnormal(s: bool = False) → Float: Returns the smallest subnormal value with sign s under this context.

property nmin: First unrepresentable digit for every value in the representation.

num_randbits: int | None: number of random bits for stochastic rounding, if applicable

pmax: int: maximum precision

rm: RoundingMode: rounding mode

rng: Random | Generator | None: random number generator for stochastic rounding, if applicable

round(x, *, exact: bool = False) → Float

Rounds any number according to this context.

If exact=True, then the rounding operation will raise a ValueError if rounding produces an inexact result.

round_at(x, n: int, *, exact: bool = False) → Float

Rounding any number of a representable value with an unnormalized exponent of at minimum n + 1.

Rounding is done by the following rules:

if x is representable and has an unnormalized exponent of at minimum n + 1, then self.round_n(x, n) == x
if x is between two representable values i1 < x < i2 where both i1 and i2 have unnormalized exponents of at minimum n + 1, then the context information determines which value is returned.

If exact=True, then the rounding operation will raise a ValueError if rounding produces an inexact result.

round_params()

Returns the rounding parameters (max_p, min_n) used for rounding under this context.

(p, None) => floating-point style rounding
(p, n) => floating-point style rounding with subnormalization
(None, n) => fixed-point style rounding
(None, None) => real computation; no rounding

These parameters also determine the amount of precision for intermediate round-to-odd operations (provided by MPFR / gmpy2).

with_params(*, pmax: int | Literal[Default.DEFAULT] = DEFAULT, emin: int | Literal[Default.DEFAULT] = DEFAULT, rm: RoundingMode | Literal[Default.DEFAULT] = DEFAULT, num_randbits: int | None | Literal[Default.DEFAULT] = DEFAULT, rng: Random | Generator | None | Literal[Default.DEFAULT] = DEFAULT, **kwargs) → MPSFloatContext: Returns self but with updated parameters.

zero(s: bool = False) → Float: Returns a signed 0 under this context.

class fpy2.MPBFloatContext(pmax: int, emin: int, maxval: RealFloat, rm: RoundingMode = RoundingMode.RNE, overflow: OverflowMode = OverflowMode.OVERFLOW, num_randbits: int | None = 0, *, neg_maxval: RealFloat | None = None, rng: Random | Generator | None = None)

Bases: SizedContext

Rounding context for multi-precision floating-point numbers with a minimum exponent (and subnormalization) and a maximum value.

This context is parameterized by a fixed precision pmax, a minimum (normalized) exponent emin, a (positive) maximum value maxval, and a rounding mode rm. A separate negative maximum value may be specified as well, but by default it is set to the negative of maxval.

Unlike MPFloatContext, the MPBFloatContext inherits from SizedContext since the set of representable values may be encoded in a finite amount of space.

property emax: Maximum normalized exponent.

emin: int: minimum (normalized exponent)

property expmax: Maximum unnormalized exponent.

property expmin: Minimum unnormalized exponent.

format() → MPBFloatFormat

Returns the number format associated with this context.

The format describes the set of representable values without the rounding rule. Format-only methods on Context (representable_under, etc.) default to delegating to the corresponding method on self.format().

classmethod from_format(fmt: MPBFloatFormat, *, rm: RoundingMode = RoundingMode.RNE, overflow: OverflowMode | None = None, num_randbits: int | None = 0, rng: Random | Generator | None = None) → MPBFloatContext: Creates a context from a MPBFloatFormat and rounding parameters.

is_stochastic() → bool

Returns if this context is stochastic.

Stochastic contexts are used for probabilistic rounding.

max_normal(s: bool = False) → Float: Returns the largest normal value with sign s under this context.

max_subnormal(s: bool = False) → Float: Returns the largest subnormal value with sign s under this context.

min_normal(s: bool = False) → Float: Returns the smallest normal value with sign s under this context.

min_subnormal(s: bool = False) → Float: Returns the smallest subnormal value with sign s under this context.

neg_maxval: RealFloat: negative maximum value

property nmin: First unrepresentable digit for every value in the representation.

num_randbits: int | None: number of random bits for stochastic rounding, if applicable

overflow: OverflowMode: overflow behavior

pmax: int: maximum precision

pos_maxval: RealFloat: positive maximum value

rm: RoundingMode: rounding mode

rng: Random | Generator | None: random number generator for stochastic rounding, if applicable

round(x, *, exact: bool = False) → Float

Rounds any number according to this context.

If exact=True, then the rounding operation will raise a ValueError if rounding produces an inexact result.

round_at(x, n: int, *, exact: bool = False) → Float

Rounding any number of a representable value with an unnormalized exponent of at minimum n + 1.

Rounding is done by the following rules:

if x is representable and has an unnormalized exponent of at minimum n + 1, then self.round_n(x, n) == x
if x is between two representable values i1 < x < i2 where both i1 and i2 have unnormalized exponents of at minimum n + 1, then the context information determines which value is returned.

If exact=True, then the rounding operation will raise a ValueError if rounding produces an inexact result.

round_params()

Returns the rounding parameters (max_p, min_n) used for rounding under this context.

(p, None) => floating-point style rounding
(p, n) => floating-point style rounding with subnormalization
(None, n) => fixed-point style rounding
(None, None) => real computation; no rounding

These parameters also determine the amount of precision for intermediate round-to-odd operations (provided by MPFR / gmpy2).

with_params(*, pmax: int | Literal[Default.DEFAULT] = DEFAULT, emin: int | Literal[Default.DEFAULT] = DEFAULT, maxval: RealFloat | Literal[Default.DEFAULT] = DEFAULT, rm: RoundingMode | Literal[Default.DEFAULT] = DEFAULT, overflow: OverflowMode | Literal[Default.DEFAULT] = DEFAULT, neg_maxval: RealFloat | Literal[Default.DEFAULT] = DEFAULT, num_randbits: int | None | Literal[Default.DEFAULT] = DEFAULT, rng: Random | Generator | None | Literal[Default.DEFAULT] = DEFAULT, **kwargs) → MPBFloatContext: Returns self but with updated parameters.

zero(s: bool = False) → Float: Returns a signed 0 under this context.

class fpy2.IEEEContext(es: int, nbits: int, rm: RoundingMode = RoundingMode.RNE, overflow: OverflowMode = OverflowMode.OVERFLOW, num_randbits: int | None = 0, *, rng: Random | Generator | None = None)

Bases: EFloatContext

Rounding context for IEEE 754 floating-point values.

This context is parameterized by the size of the exponent field es, the size of the total representation nbits, and the rounding mode rm.

This context is implemented as a subclass of EFloatContext which is a more general definition of IEEE 754-like floating-point numbers.

format() → IEEEFormat

Returns the number format associated with this context.

The format describes the set of representable values without the rounding rule. Format-only methods on Context (representable_under, etc.) default to delegating to the corresponding method on self.format().

classmethod from_format(fmt: EFloatFormat, *, rm: RoundingMode = RoundingMode.RNE, overflow: OverflowMode | None = None, num_randbits: int | None = 0, rng: Random | Generator | None = None, nan_value: Float | None = None, inf_value: Float | None = None) → IEEEContext: Creates a context from an IEEEFormat and rounding parameters.

with_params(*, es: int | Literal[Default.DEFAULT] = DEFAULT, nbits: int | Literal[Default.DEFAULT] = DEFAULT, rm: RoundingMode | Literal[Default.DEFAULT] = DEFAULT, overflow: OverflowMode | Literal[Default.DEFAULT] = DEFAULT, num_randbits: int | None | Literal[Default.DEFAULT] = DEFAULT, rng: Random | Generator | None | Literal[Default.DEFAULT] = DEFAULT, **kwargs) → IEEEContext: Returns self but with updated parameters.

class fpy2.EFloatContext(es: int, nbits: int, enable_inf: bool, nan_kind: EFloatNanKind, eoffset: int, rm: RoundingMode = RoundingMode.RNE, overflow: OverflowMode = OverflowMode.OVERFLOW, num_randbits: int | None = 0, *, rng: Random | Generator | None = None, nan_value: Float | None = None, inf_value: Float | None = None)

Bases: EncodableContext

Rounding context for the “extended” floating-point format as described in Brett Saiki’s blog post. These formats extend the usual IEEE 754 format with three addition parameters:

are infinities enabled?
how are NaNs encoded?
should the exponent be shifted?

See https://uwplse.org/2025/02/17/Small-Floats.html for details.

property emax: The normalized exponent of the maximum representable value under this context.

enable_inf: bool: whether to enable infinities

eoffset: int: the exponent offset

es: int: size of the exponent field

format() → EFloatFormat

Returns the number format associated with this context.

The format describes the set of representable values without the rounding rule. Format-only methods on Context (representable_under, etc.) default to delegating to the corresponding method on self.format().

classmethod from_format(fmt: EFloatFormat, *, rm: RoundingMode = RoundingMode.RNE, overflow: OverflowMode | None = None, num_randbits: int | None = 0, rng: Random | Generator | None = None, nan_value: Float | None = None, inf_value: Float | None = None) → EFloatContext: Creates a context from an EFloatFormat and rounding parameters.

inf_value: Float | None: if Inf is not representable, what value should Inf round to?

is_stochastic() → bool

Returns if this context is stochastic.

Stochastic contexts are used for probabilistic rounding.

nan_kind: EFloatNanKind: how NaNs are encoded

nan_value: Float | None: if NaN is not representable, what value should NaN round to?

nbits: int: size of the total representation

num_randbits: int | None: number of random bits for stochastic rounding, if applicable

overflow: OverflowMode: overflow behavior

rm: RoundingMode: rounding mode

rng: Random | Generator | None: random number generator for stochastic rounding, if applicable

round(x, *, exact: bool = False) → Float

Rounds any number according to this context.

If exact=True, then the rounding operation will raise a ValueError if rounding produces an inexact result.

round_at(x, n, *, exact: bool = False) → Float

Rounding any number of a representable value with an unnormalized exponent of at minimum n + 1.

Rounding is done by the following rules:

if x is representable and has an unnormalized exponent of at minimum n + 1, then self.round_n(x, n) == x
if x is between two representable values i1 < x < i2 where both i1 and i2 have unnormalized exponents of at minimum n + 1, then the context information determines which value is returned.

If exact=True, then the rounding operation will raise a ValueError if rounding produces an inexact result.

round_params()

Returns the rounding parameters (max_p, min_n) used for rounding under this context.

(p, None) => floating-point style rounding
(p, n) => floating-point style rounding with subnormalization
(None, n) => fixed-point style rounding
(None, None) => real computation; no rounding

These parameters also determine the amount of precision for intermediate round-to-odd operations (provided by MPFR / gmpy2).

with_params(*, es: int | Literal[Default.DEFAULT] = DEFAULT, nbits: int | Literal[Default.DEFAULT] = DEFAULT, enable_inf: bool | Literal[Default.DEFAULT] = DEFAULT, nan_kind: EFloatNanKind | Literal[Default.DEFAULT] = DEFAULT, eoffset: int | Literal[Default.DEFAULT] = DEFAULT, rm: RoundingMode | Literal[Default.DEFAULT] = DEFAULT, overflow: OverflowMode | Literal[Default.DEFAULT] = DEFAULT, num_randbits: int | None | Literal[Default.DEFAULT] = DEFAULT, rng: Random | Generator | None | Literal[Default.DEFAULT] = DEFAULT, nan_value: Float | None | Literal[Default.DEFAULT] = DEFAULT, inf_value: Float | None | Literal[Default.DEFAULT] = DEFAULT, **kwargs) → EFloatContext: Returns self but with updated parameters.

class fpy2.ExpContext(nbits: int, eoffset: int = 0, rm: RoundingMode = RoundingMode.RNE, overflow: OverflowMode = OverflowMode.OVERFLOW, *, inf_value: Float | None = None)

Bases: EncodableContext

Rounding context for exponential numbers, i.e., numbers of the form 2^k where k is an integer. The context is parameterized by the size of the representation nbits, an exponent offset eoffset, and the rounding mode rm.

This context implements EncodableContext. The special value NaN is representable and is encoded as all ones.

property emax: int: The normalized exponent of the maximum representable value under this context.

eoffset: int: exponent offset

format() → ExpFormat

Returns the number format associated with this context.

The format describes the set of representable values without the rounding rule. Format-only methods on Context (representable_under, etc.) default to delegating to the corresponding method on self.format().

classmethod from_format(fmt: ExpFormat, *, rm: RoundingMode = RoundingMode.RNE, overflow: OverflowMode | None = None, inf_value: Float | None = None) → ExpContext: Creates a context from an ExpFormat and rounding parameters.

inf_value: Float | None: if Inf is not representable, what value should Inf round to? if not set, then round() will produce NaN.

is_stochastic() → bool

Returns if this context is stochastic.

Stochastic contexts are used for probabilistic rounding.

nbits: int: size of the representation in bits

overflow: OverflowMode: overflow mode

rm: RoundingMode: rounding mode

round(x, *, exact: bool = False) → Float

Rounds any number according to this context.

If exact=True, then the rounding operation will raise a ValueError if rounding produces an inexact result.

round_at(x, n: int, *, exact: bool = False) → Float

Rounding any number of a representable value with an unnormalized exponent of at minimum n + 1.

Rounding is done by the following rules:

if x is representable and has an unnormalized exponent of at minimum n + 1, then self.round_n(x, n) == x
if x is between two representable values i1 < x < i2 where both i1 and i2 have unnormalized exponents of at minimum n + 1, then the context information determines which value is returned.

If exact=True, then the rounding operation will raise a ValueError if rounding produces an inexact result.

round_params() → tuple[int | None, int | None]

Returns the rounding parameters (max_p, min_n) used for rounding under this context.

(p, None) => floating-point style rounding
(p, n) => floating-point style rounding with subnormalization
(None, n) => fixed-point style rounding
(None, None) => real computation; no rounding

These parameters also determine the amount of precision for intermediate round-to-odd operations (provided by MPFR / gmpy2).

with_params(*, nbits: int | Literal[Default.DEFAULT] = DEFAULT, eoffset: int | Literal[Default.DEFAULT] = DEFAULT, rm: RoundingMode | Literal[Default.DEFAULT] = DEFAULT, overflow: OverflowMode | Literal[Default.DEFAULT] = DEFAULT, inf_value: Float | None | Literal[Default.DEFAULT] = DEFAULT, **kwargs) → ExpContext: Returns self but with updated parameters.

Fixed-Point Contexts

class fpy2.MPFixedContext(nmin: int, rm: RoundingMode = RoundingMode.RNE, num_randbits: int | None = 0, *, rng: Random | Generator | None = None, enable_nan: bool = False, enable_inf: bool = False, nan_value: Float | None = None, inf_value: Float | None = None)

Bases: OrdinalContext

Rounding context for mulit-precision fixed-point numbers.

This context is parameterized by the most significant digit that is not representable nmin and a rounding mode rm. It emulates fixed-point numbers with arbitrary precision.

Optionally, specify the following keywords:

enable_nan: if True, then NaN is representable [default: False]
enable_inf: if True, then infinity is representable [default: False]
nan_value: if NaN is not enabled, what value should NaN round to? [default: None]; if not set, then round() will raise a ValueError on NaN.
inf_value: if Inf is not enabled, what value should Inf round to? [default: None]; if not set, then round() will raise a ValueError on infinity.

MPFixedContext inherits from OrdinalContext since each representable value can be mapped to the ordinals.

enable_inf: bool: is infinity representable?

enable_nan: bool: is NaN representable?

property expmin: int: The minimum exponent for this context. This is equal to nmin + 1.

format() → MPFixedFormat

Returns the number format associated with this context.

The format describes the set of representable values without the rounding rule. Format-only methods on Context (representable_under, etc.) default to delegating to the corresponding method on self.format().

classmethod from_format(fmt: MPFixedFormat, *, rm: RoundingMode = RoundingMode.RNE, num_randbits: int | None = 0, rng: Random | Generator | None = None, nan_value: Float | None = None, inf_value: Float | None = None) → MPFixedContext: Creates a context from a MPFixedFormat and rounding parameters.

inf_value: Float | None: if Inf is not enabled, what value should Inf round to? if not set, then round() will raise a ValueError.

is_stochastic() → bool

Returns if this context is stochastic.

Stochastic contexts are used for probabilistic rounding.

nan_value: Float | None: if NaN is not enabled, what value should NaN round to? if not set, then round() will raise a ValueError.

nmin: int: the first unrepresentable digit

num_randbits: int | None: number of random bits for stochastic rounding, if applicable

rm: RoundingMode: rounding mode

rng: Random | Generator | None: random number generator for stochastic rounding, if applicable

round(x, *, exact: bool = False) → Float

Rounds any number according to this context.

If exact=True, then the rounding operation will raise a ValueError if rounding produces an inexact result.

round_at(x, n: int, *, exact: bool = False) → Float

Rounding any number of a representable value with an unnormalized exponent of at minimum n + 1.

Rounding is done by the following rules:

if x is representable and has an unnormalized exponent of at minimum n + 1, then self.round_n(x, n) == x
if x is between two representable values i1 < x < i2 where both i1 and i2 have unnormalized exponents of at minimum n + 1, then the context information determines which value is returned.

If exact=True, then the rounding operation will raise a ValueError if rounding produces an inexact result.

round_params()

Returns the rounding parameters (max_p, min_n) used for rounding under this context.

(p, None) => floating-point style rounding
(p, n) => floating-point style rounding with subnormalization
(None, n) => fixed-point style rounding
(None, None) => real computation; no rounding

These parameters also determine the amount of precision for intermediate round-to-odd operations (provided by MPFR / gmpy2).

with_params(*, nmin: int | Literal[Default.DEFAULT] = DEFAULT, rm: RoundingMode | Literal[Default.DEFAULT] = DEFAULT, enable_nan: bool | Literal[Default.DEFAULT] = DEFAULT, enable_inf: bool | Literal[Default.DEFAULT] = DEFAULT, nan_value: Float | None | Literal[Default.DEFAULT] = DEFAULT, inf_value: Float | None | Literal[Default.DEFAULT] = DEFAULT, num_randbits: int | None | Literal[Default.DEFAULT] = DEFAULT, rng: Random | Generator | None | Literal[Default.DEFAULT] = DEFAULT, **kwargs) → MPFixedContext: Returns self but with updated parameters.

class fpy2.MPBFixedContext(nmin: int, maxval: RealFloat, rm: RoundingMode = RoundingMode.RNE, overflow: OverflowMode = OverflowMode.WRAP, num_randbits: int | None = 0, *, neg_maxval: RealFloat | None = None, rng: Random | Generator | None = None, enable_nan: bool = False, enable_inf: bool = False, nan_value: Float | None = None, inf_value: Float | None = None)

Bases: SizedContext

Rounding context for multi-precision, fixed-point numbers with a maximum value.

This context is parameterized by the most significant digit that is not representable nmin, a (positive) maximum value maxval, and a rounding mode rm. A separate negative maximum value may be specified as well, but by default it is the negative of maxval.

Optionally, specify the following keywords:

enable_nan: if True, then NaN is representable [default: False]
enable_inf: if True, then infinity is representable [default: False]
nan_value: if NaN is not enabled, what value should NaN round to? [default: None]; if not set, then round() will raise a ValueError on NaN.
inf_value: if Inf is not enabled, what value should Inf round to? [default: None]; if not set, then round() will raise a ValueError on infinity.

Unlike MPFixedContext, the MPBFixedContext inherits from SizedContext, since the set of representable numbers is finite.

enable_inf: bool: is infinity representable?

enable_nan: bool: is NaN representable?

property expmin: int: The minimum exponent for this context. This is equal to nmin + 1.

format() → MPBFixedFormat

Returns the number format associated with this context.

The format describes the set of representable values without the rounding rule. Format-only methods on Context (representable_under, etc.) default to delegating to the corresponding method on self.format().

classmethod from_format(fmt: MPBFixedFormat, *, rm: RoundingMode = RoundingMode.RNE, overflow: OverflowMode | None = None, num_randbits: int | None = 0, rng: Random | Generator | None = None, nan_value: Float | None = None, inf_value: Float | None = None) → MPBFixedContext: Creates a context from a MPBFixedFormat and rounding parameters.

inf_value: Float | None: if Inf is not enabled, what value should Inf round to? if not set, then round() will raise a ValueError.

is_stochastic() → bool

Returns if this context is stochastic.

Stochastic contexts are used for probabilistic rounding.

nan_value: Float | None: if NaN is not enabled, what value should NaN round to? if not set, then round() will raise a ValueError.

neg_maxval: RealFloat: negative maximum value

nmin: int: the first unrepresentable digit

num_randbits: int | None: number of random bits for stochastic rounding, if applicable

overflow: OverflowMode: overflow behavior

pos_maxval: RealFloat: positive maximum value

rm: RoundingMode: rounding mode

rng: Random | Generator | None: random number generator for stochastic rounding, if applicable

round(x, *, exact: bool = False)

Rounds any number according to this context.

If exact=True, then the rounding operation will raise a ValueError if rounding produces an inexact result.

round_at(x, n: int, *, exact: bool = False)

Rounding any number of a representable value with an unnormalized exponent of at minimum n + 1.

Rounding is done by the following rules:

if x is representable and has an unnormalized exponent of at minimum n + 1, then self.round_n(x, n) == x
if x is between two representable values i1 < x < i2 where both i1 and i2 have unnormalized exponents of at minimum n + 1, then the context information determines which value is returned.

If exact=True, then the rounding operation will raise a ValueError if rounding produces an inexact result.

round_params()

Returns the rounding parameters (max_p, min_n) used for rounding under this context.

(p, None) => floating-point style rounding
(p, n) => floating-point style rounding with subnormalization
(None, n) => fixed-point style rounding
(None, None) => real computation; no rounding

These parameters also determine the amount of precision for intermediate round-to-odd operations (provided by MPFR / gmpy2).

with_params(*, nmin: int | Literal[Default.DEFAULT] = DEFAULT, maxval: RealFloat | Literal[Default.DEFAULT] = DEFAULT, rm: RoundingMode | Literal[Default.DEFAULT] = DEFAULT, overflow: OverflowMode | Literal[Default.DEFAULT] = DEFAULT, num_randbits: int | None | Literal[Default.DEFAULT] = DEFAULT, neg_maxval: RealFloat | Literal[Default.DEFAULT] = DEFAULT, rng: Random | Generator | None | Literal[Default.DEFAULT] = DEFAULT, enable_nan: bool | Literal[Default.DEFAULT] = DEFAULT, enable_inf: bool | Literal[Default.DEFAULT] = DEFAULT, nan_value: Float | None | Literal[Default.DEFAULT] = DEFAULT, inf_value: Float | None | Literal[Default.DEFAULT] = DEFAULT, **kwargs) → MPBFixedContext: Returns self but with updated parameters.

class fpy2.FixedContext(signed: bool, scale: int, nbits: int, rm: RoundingMode = RoundingMode.RNE, overflow: OverflowMode = OverflowMode.WRAP, num_randbits: int | None = 0, *, rng: Random | Generator | None = None, nan_value: Float | None = None, inf_value: Float | None = None)

Bases: MPBFixedContext, EncodableContext

Rounding context for two’s fixed-width, two’s complement, fixed-point numbers.

This context is parameterized by whether it is signed, signed, the scale factor scale, the total number of bits nbits, the rounding mode rm, and the overflow behavior overflow.

Optionally, specify the following keywords:

nan_value: if NaN is not enabled, what value should NaN round to? [default: None]; if not set, then round() will raise a ValueError on NaN.
inf_value: if Inf is not enabled, what value should Inf round to? [default: None]; if not set, then round() will raise a ValueError on infinity.

Unlike MPBFixedContext, the FixedContext inherits from EncodableContext, since the representation has a well-defined encoding.

format() → FixedFormat

Returns the number format associated with this context.

The format describes the set of representable values without the rounding rule. Format-only methods on Context (representable_under, etc.) default to delegating to the corresponding method on self.format().

classmethod from_format(fmt: MPBFixedFormat, *, rm: RoundingMode = RoundingMode.RNE, overflow: OverflowMode | None = None, num_randbits: int | None = 0, rng: Random | Generator | None = None, nan_value: Float | None = None, inf_value: Float | None = None) → FixedContext: Creates a context from a FixedFormat and rounding parameters.

nbits: int: the total number of bits in the representation

scale: int: the implicit scale factor of the representation

signed: bool: is the representation signed?

with_params(*, signed: bool | Literal[Default.DEFAULT] = DEFAULT, scale: int | Literal[Default.DEFAULT] = DEFAULT, nbits: int | Literal[Default.DEFAULT] = DEFAULT, rm: RoundingMode | Literal[Default.DEFAULT] = DEFAULT, overflow: OverflowMode | Literal[Default.DEFAULT] = DEFAULT, num_randbits: int | None | Literal[Default.DEFAULT] = DEFAULT, rng: Random | Generator | None | Literal[Default.DEFAULT] = DEFAULT, nan_value: Float | None | Literal[Default.DEFAULT] = DEFAULT, inf_value: Float | None | Literal[Default.DEFAULT] = DEFAULT, **kwargs) → FixedContext: Returns self but with updated parameters.

class fpy2.SMFixedContext(scale: int, nbits: int, rm: RoundingMode = RoundingMode.RNE, overflow: OverflowMode = OverflowMode.WRAP, num_randbits: int | None = 0, *, rng: Random | Generator | None = None, nan_value: Float | None = None, inf_value: Float | None = None)

Bases: MPBFixedContext, EncodableContext

Rounding context for fixed-width, sign-magnitude, fixed-point numbers.

This context is parameterized by the scale factor scale, the total number of bits nbits, the rounding mode rm, and the overflow behavior overflow.

Optionally, specify the following keywords:

nan_value: if NaN is not enabled, what value should NaN round to? [default: None]; if not set, then round() will raise a ValueError on NaN.
inf_value: if Inf is not enabled, what value should Inf round to? [default: None]; if not set, then round() will raise a ValueError on infinity.

format() → SMFixedFormat

Returns the number format associated with this context.

The format describes the set of representable values without the rounding rule. Format-only methods on Context (representable_under, etc.) default to delegating to the corresponding method on self.format().

classmethod from_format(fmt: MPBFixedFormat, *, rm: RoundingMode = RoundingMode.RNE, overflow: OverflowMode | None = None, num_randbits: int | None = 0, rng: Random | Generator | None = None, nan_value: Float | None = None, inf_value: Float | None = None) → SMFixedContext: Creates a context from a SMFixedFormat and rounding parameters.

nbits: int: the total number of bits in the representation

scale: int: the implicit scale factor of the representation

with_params(*, scale: int | Literal[Default.DEFAULT] = DEFAULT, nbits: int | Literal[Default.DEFAULT] = DEFAULT, rm: RoundingMode | Literal[Default.DEFAULT] = DEFAULT, overflow: OverflowMode | Literal[Default.DEFAULT] = DEFAULT, num_randbits: int | None | Literal[Default.DEFAULT] = DEFAULT, rng: Random | Generator | None | Literal[Default.DEFAULT] = DEFAULT, nan_value: Float | None | Literal[Default.DEFAULT] = DEFAULT, inf_value: Float | None | Literal[Default.DEFAULT] = DEFAULT, **kwargs): Returns self but with updated parameters.

Common Rounding Contexts

FPy provides a number of aliases for common rounding contexts.

Floating-Point Contexts

fpy2.FP256 = IEEEContext(19, 256, RM.RNE): Alias for the IEEE 754 octuple precision (256-bit) floating point format with round nearest, ties-to-even rounding mode.

fpy2.FP128 = IEEEContext(15, 128, RM.RNE): Alias for the IEEE 754 quadruple precision (128-bit) floating point format with round nearest, ties-to-even rounding mode.

fpy2.FP64 = IEEEContext(11, 64, RM.RNE): Alias for the IEEE 754 double precision (64-bit) floating point format with round nearest, ties-to-even rounding mode.

fpy2.FP32 = fpy2.IEEEContext(8, 32, RM.RNE): Alias for the IEEE 754 single precision (32-bit) floating point format with round nearest, ties-to-even rounding mode.

fpy2.FP16 = IEEEContext(5, 16, RM.RNE): Alias for the IEEE 754 half precision (16-bit) floating point format with round nearest, ties-to-even rounding mode.

fpy2.TF32 = IEEEContext(8, 19, RM.RNE): Alias for Nvidia’s TensorFloat-32 (TF32) floating point format with round nearest, ties-to-even rounding mode.

fpy2.BF16 = IEEEContext(5, 16, RM.RNE): Alias for the BFloat16 (BF16) floating point format with round nearest, ties-to-even rounding mode.

fpy2.S1E5M2 = EFloatContext(5, 8, False, ExtNanKind.NEG_ZERO, -1, RM.RNE)

Alias for Graphcore’s FP8 format with 5 bits of exponent with round nearest, ties-to-even rounding mode.

See Graphcore’s FP8 proposal for more information.

fpy2.S1E4M3 = EFloatContext(4, 8, False, ExtNanKind.NEG_ZERO, -1, RM.RNE)

Alias for Graphcore’s FP8 format with 4 bits of exponent with round nearest, ties-to-even rounding mode.

See Graphcore’s FP8 proposal for more information..

fpy2.MX_E5M2 = IEEEContext(5, 8, RM.RNE)

Alias for the FP8 format with 5 bits of exponent in the Open Compute Project (OCP) Microscaling Formats (MX) specification with round nearest, ties-to-even rounding mode.

See the OCP MX specification for more information.

fpy2.MX_E4M3 = EFloatContext(4, 8, False, ExtNanKind.MAX_VAL, 0, RM.RNE)

Alias for the FP8 format with 4 bits of exponent in the Open Compute Project (OCP) Microscaling Formats (MX) specification with round nearest, ties-to-even rounding mode.

See the OCP MX specification for more information.

fpy2.MX_E3M2 = EFloatContext(3, 6, False, ExtNanKind.NONE, 0, RM.RNE)

Alias for the FP6 format with 3 bits of exponent in the Open Compute Project (OCP) Microscaling Formats (MX) specification with round nearest, ties-to-even rounding mode.

See the OCP MX specification for more information.

fpy2.MX_E2M3 = EFloatContext(2, 6, False, ExtNanKind.NONE, 0, RM.RNE)

Alias for the FP6 format with 2 bits of exponent in the Open Compute Project (OCP) Microscaling Formats (MX) specification with round nearest, ties-to-even rounding mode.

See the OCP MX specification for more information.

fpy2.MX_E2M1 = EFloatContext(2, 4, False, ExtNanKind.NONE, 0, RM.RNE)

Alias for the FP4 format with 2 bits of exponent in the Open Compute Project (OCP) Microscaling Formats (MX) specification with round nearest, ties-to-even rounding mode.

See the OCP MX specification for more information.

fpy2.MX_E8M0 = ExpContext(8, 0)

Alias for the MX scaling format in the Open Compute Project (OCP) Microscaling Formats (MX) specification with round nearest, ties-to-even rounding mode.

This is just the exponent field of a single-precision floating-point value (FP32) with encode(x) == 0xFF representing NaN and encode(x) == 0x00 representing the exponent one below the minimum normal exponent value.

fpy2.MX_INT8 = FixedContext(True, -6, 8, RM.RNE)

Alias for the MX 8-bit integer format in the Open Compute Project (OCP) Microscaling Formats (MX) specification with round nearest, ties-to-even rounding mode.

This implementation uses the standard asymmetric encoding inherited from fixed-point formats, with +MAX_VAL = +1 63/64 and -MAX_VAL = -2.

fpy2.FP8P1 = EFloatContext(7, 8, True, ExtNanKind.NEG_ZERO, 0, RM.RNE)

Alias for the FP8 format with 7 bits of exponent found in a draft proposal by the IEEE P3109 working group with round nearest, ties-to-even rounding mode. Format subject to change.

See the IEEE P3109 working group draft for more information.

fpy2.FP8P2 = EFloatContext(6, 8, True, ExtNanKind.NEG_ZERO, -1, RM.RNE)

Alias for the FP8 format with 6 bits of exponent found in a draft proposal by the IEEE P3109 working group with round nearest, ties-to-even rounding mode. Format subject to change.

See the IEEE P3109 working group draft for more information.

fpy2.FP8P3 = EFloatContext(5, 8, True, ExtNanKind.NEG_ZERO, -1, RM.RNE)

Alias for the FP8 format with 5 bits of exponent found in a draft proposal by the IEEE P3109 working group with round nearest, ties-to-even rounding mode. Format subject to change.

See the IEEE P3109 working group draft for more information.

fpy2.FP8P4 = EFloatContext(4, 8, True, ExtNanKind.NEG_ZERO, -1, RM.RNE)

Alias for the FP8 format with 4 bits of exponent found in a draft proposal by the IEEE P3109 working group with round nearest, ties-to-even rounding mode. Format subject to change.

See the IEEE P3109 working group draft for more information.

fpy2.FP8P5 = EFloatContext(3, 8, True, ExtNanKind.NEG_ZERO, -1, RM.RNE)

Alias for the FP8 format with 3 bits of exponent found in a draft proposal by the IEEE P3109 working group with round nearest, ties-to-even rounding mode. Format subject to change.

See the IEEE P3109 working group draft for more information.

fpy2.FP8P6 = EFloatContext(2, 8, True, ExtNanKind.NEG_ZERO, -1, RM.RNE)

Alias for the FP8 format with 2 bits of exponent found in a draft proposal by the IEEE P3109 working group with round nearest, ties-to-even rounding mode. Format subject to change.

See the IEEE P3109 working group draft for more information.

fpy2.FP8P7 = EFloatContext(1, 8, True, ExtNanKind.NEG_ZERO, -1, RM.RNE)

Alias for the FP8 format with 1 bit of exponent found in a draft proposal by the IEEE P3109 working group with round nearest, ties-to-even rounding mode. Format subject to change.

See the IEEE P3109 working group draft for more information.

Fixed-Point Contexts

fpy2.Integer = MPFixedContext(-1, RM.RTZ)

Alias for an arbitrary-precision integer context with round towards zero rounding mode.

Numbers rounded under this context behave like Python’s native int type.

fpy2.SINT8 = FixedContext(True, 0, 8, RM.RTZ, OF.WRAP)

Alias for a signed 8-bit integer context with round towards zero rounding mode and wrapping overflow behavior.

Rounding infinity or NaN under this context produces an OverflowError.

fpy2.SINT16 = FixedContext(True, 0, 16, RM.RTZ, OF.WRAP)

Alias for a signed 16-bit integer context with round towards zero rounding mode and wrapping overflow behavior.

Rounding infinity or NaN under this context produces an OverflowError.

fpy2.SINT32 = FixedContext(True, 0, 32, RM.RTZ, OF.WRAP)

Alias for a signed 32-bit integer context with round towards zero rounding mode and wrapping overflow behavior.

Rounding infinity or NaN under this context produces an OverflowError.

fpy2.SINT64 = FixedContext(True, 0, 64, RM.RTZ, OF.WRAP)

Alias for a signed 64-bit integer context with round towards zero rounding mode and wrapping overflow behavior.

Rounding infinity or NaN under this context produces an OverflowError.

fpy2.UINT8 = FixedContext(False, 0, 8, RM.RTZ, OF.WRAP)

Alias for an unsigned 8-bit integer context with round towards zero rounding mode and wrapping overflow behavior.

Rounding infinity or NaN under this context produces an OverflowError.

fpy2.UINT16 = FixedContext(False, 0, 16, RM.RTZ, OF.WRAP)

Alias for an unsigned 16-bit integer context with round towards zero rounding mode and wrapping overflow behavior.

Rounding infinity or NaN under this context produces an OverflowError.

fpy2.UINT32 = FixedContext(False, 0, 32, RM.RTZ, OF.WRAP)

Alias for an unsigned 32-bit integer context with round towards zero rounding mode and wrapping overflow behavior.

Rounding infinity or NaN under this context produces an OverflowError.

fpy2.UINT64 = FixedContext(False, 0, 64, RM.RTZ, OF.WRAP)

Alias for an unsigned 64-bit integer context with round towards zero rounding mode and wrapping overflow behavior.

Rounding infinity or NaN under this context produces an OverflowError.

Number Types

FPy only provides two number types.

Bases: Rational

The basic floating-point number.

This type encodes a base-2 number in unnormalized scientific notation: (-1)^s * 2^exp * c where:

s is the sign;

exp is the absolute position of the least-significant bit (LSB), also called the unnormalized exponent; and

c is the integer significand.

There are no constraints on the values of exp and c. Unlike IEEE 754, this number cannot encode infinity or NaN.

This type also contains status flags (Flags) to indicate exceptional events that occured during rounding.

property base: Integer base of this number. Always 2.

bit(n: int) → bool: Returns the value of the digit at the n-th position as a boolean.

property c: int

integer significand

Type:: property

property carry: bool

the rounded result has a different exponent than the exact result.

Type:: Carry flag

compare(other: Self | int | float | Fraction) → Ordering | None

Compare self and other values returning an Optional[Ordering].

For two RealFloat values, the result is never None.

property denominator

The denominator of a rational number in lowest terms.

This denominator should be positive.

property divzero: bool

the operation divided by zero.

Type:: Division by zero flag

property e: int

Normalized exponent of this number.

When self.c == 0 (i.e. the number is zero), this method returns self.exp - 1. In other words, self.c != 0 iff self.e >= self.exp.

The interval [self.exp, self.e] represents the absolute positions of digits in the significand.

property exp: int

absolute position of the LSB

Type:: property

static from_float(x: float)

Creates a new RealFloat value from a Python float.

This conversion is exact.

static from_int(x: int)

Creates a new RealFloat value from a Python int.

This conversion is exact.

static from_rational(x: Rational)

Creates a new RealFloat value from a Fraction.

Raise a ValueError if x is not a dyadic rational.

property inexact: bool

the rounded result is not the same as the exact result.

Type:: Inexact flag

property invalid: bool

the operation produced an invalid result.

Type:: Invalid operation flag

is_identical_to(other: RealFloat) → bool: Is the value encoded identically to another RealFloat value?

is_integer() → bool: Returns whether this value is an integer.

is_more_significant(n: int) → bool

Returns True iff this value only has significant digits above n, that is, every non-zero digit in the number is more significant than n.

When n = -1, this method is equivalent to is_integer().

This method is equivalent to:

_, lo = self.split(n)
return lo.is_zero()

is_negative() → bool: Returns whether this value is negative.

is_nonzero() → bool: Returns whether this value does not represent zero.

is_positive() → bool: Returns whether this value is positive.

is_power_of_two() → bool: Returns whether this value is a power of two, i.e., (-1)^s * 2^e.

is_zero() → bool: Returns whether this value represents zero.

property m: int: Signed significand. This is exactly (-1)^self.s * self.c.

property n: int: Position of the first unrepresentable digit below the significant digits. This is exactly self.exp - 1.

next_away_zero(p: int | None = None, n: int | None = None)

Computes the next number away from zero.

If p or n is specified, then self is normalized accordingly before computing the next value. Otherwise, the step size if 2 ** self.exp even when self.c == 0.

If self == 0, then a ValueError is raised.

next_down(p: int | None = None, n: int | None = None)

Computes the next number towards negative infinity.

If p or n is specified, then self is normalized accordingly before computing the next value. Otherwise, the step size if 2 ** self.exp even when self.c == 0.

next_towards_zero(p: int | None = None, n: int | None = None)

Computes the next number towards zero.

If p or n is specified, then self is normalized accordingly before computing the next value. Otherwise, the step size if 2 ** self.exp even when self.c == 0.

If self == 0, then a ValueError is raised.

next_up(p: int | None = None, n: int | None = None)

Computes the next number towards positive infinity.

If p or n is specified, then self is normalized accordingly before computing the next value. Otherwise, the step size if 2 ** self.exp even when self.c == 0.

normalize(p: int | None = None, n: int | None = None)

Returns a value numerically equivalent to self based on precision p and position n:

None, None: a copy of self, i.e., self.exp == self.normalize().exp, etc.
p, None: a copy of self that has exactly p bits of precision.
None, n: a copy of self where self.exp == n + 1.
p, n: a copy of self such that self.exp >= n + 1 and
has maximal precision up to p bits.

Raises a ValueError if no such value exists, i.e., if the value cannot be represented with the given p and n.

property numerator: The numerator of a rational number in lowest terms.

static one(s: bool = False)

Creates a new RealFloat value representing one.

The sign may be specified with s.

property overflow: bool

the result exceeded the representable range.

Type:: Overflow flag

property p: Minimum number of binary digits required to represent this number.

static power_of_2(exp: int, s: bool = False)

Creates a new RealFloat value representing 2**exp.

The sign may be specified with s.

Creates a copy of self rounded to at most max_p digits of precision or a least absolute digit position min_n, whichever bound is encountered first.

At least one of max_p or min_n must be specified: max_p >= 0 while min_n may be any integer.

If only min_n is given, rounding is performed like fixed-point rounding and the resulting significand may have more than max_p bits (any values can be clamped after this operation). If only min_p is given, rounding is performed liked floating-point without an exponent bound; the integer significand has at most max_p digits. If both are specified, rounding is performed like IEEE 754 floating-point arithmetic; min_n takes precedence, so the value may have less than max_p precision.

When num_randbits=0, the rounding is performed by rounding using the rounding mode specified by rm.

When randbits is specified, the rounding is performed stochastically using randbits rounding bits to decide which way to round. If randbits=None, then all additional bits are considered rounding bits. The rounding mode specified by rm decides how the additional rounding bits are themselves rounded. If randbits=None, rounding is decided by Python’s native random module, otherwise the value is used as the “randomly” sampled bits.

round_at(n: int, p: int | None = None, rm: RoundingMode = RoundingMode.RNE, num_randbits: int | None = 0, *, rng: Random | Generator | None = None, exact: bool = False): Creates a copy of self rounded at absolute digit position n using the rounding mode specified by rm. If exact is True, the result must be exact.

property s: bool

is the sign negative?

Type:: property

split(n: int): Splits self into two RealFloat values where the first value represents the digits above n and the second value represents the digits below and including n.

property tiny_post: bool

the result after rounding (without subnormalization) satisfies |x| < 2^emin.

Type:: Tiny after rounding flag

property tiny_pre: bool

the result before rounding satisfies |x| < 2^emin.

Type:: Tiny before rounding flag

property underflow_post: bool

self.tiny_post and self.inexact.

Type:: Underflow after rounding flag

property underflow_pre: bool

self.tiny_pre and self.inexact.

Type:: Underflow before rounding flag

static zero(s: bool = False)

Creates a new RealFloat value representing zero.

The sign may be specified with s.

Bases: object

The basic floating-point number extended with infinities and NaN.

This type encodes a base-2 number in unnormalized scientific notation (-1)^s * 2^exp * c where:

s is the sign;
exp is the absolute position of the least-significant bit (LSB), also called the unnormalized exponent; and
c is the integer significand.

There are no constraints on the values of exp and c. Unlike RealFloat, this number can encode infinity and NaN.

This type can also encode uncertainty introduced by rounding. The uncertaintly is represented by an interval, also called a rounding envelope. The interval includes this value and extends either below or above it (interval_down). The interval always contains this value and may contain the other endpoint as well (interval_closed). The size of the interval is 2**(exp + interval_size). It must be the case that interval_size <= 0.

Instances of Float are usually constructed under some rounding context, i.e., the result of an operation with rounding. The attribute ctx stores that rounding context if one exists. In general, Float objects should not be manually constructed, but rather through context-based constructors.

as_rational() → Fraction

Converts this value to a Fraction representing the same value.

If the value is not representable, a ValueError is raised.

as_real() → RealFloat: Returns the real part of this number.

property base: Integer base of this number. Always 2.

property c: int: Integer significand.

property carry: bool

the rounded result has a different exponent than the exact result.

Type:: Carry flag

compare(other: Self | RealFloat | int | float | Fraction) → Ordering | None: Compare self and other values returning an Optional[Ordering].

property ctx: None

Rounding context under which this number was constructed.

If None, this number was constructed without a context. In that case, the number is always exact and representable.

property divzero: bool

the operation divided by zero.

Type:: Division by zero flag

property e: int

Normalized exponent of this number.

When self.c == 0 (i.e. the number is zero), this method returns self.exp - 1. In other words, self.c != 0 iff self.e >= self.exp.

The interval [self.exp, self.e] represents the absolute positions of digits in the significand.

property exp: int: Absolute position of the LSB.

static from_float(x: float, ctx: None = None, checked: bool = True)

Converts a native Python float to a Float number.

Optionally specify a rounding context under which to construct this value. If a rounding context is specified, x must be representable under ctx unless checked=False.

static from_int(x: int, ctx: None = None, checked: bool = True)

Converts an integer to a Float number.

Optionally specify a rounding context under which to construct this value. If a rounding context is specified, x must be representable under ctx unless checked=False.

static from_rational(x: Fraction, ctx: None = None, checked: bool = True)

Converts a Fraction to a Float number.

Optionally specify a rounding context under which to construct this value. If a rounding context is specified, x must be representable under ctx unless checked=False.

static from_real(x: RealFloat, ctx: None = None, checked: bool = True)

Converts a RealFloat number to a Float number.

Optionally specify a rounding context under which to construct this value. If a rounding context is specified, x must be representable under ctx unless checked=False.

property inexact: bool

the rounded result is not the same as the exact result.

Type:: Inexact flag

static inf(s: bool = False, ctx: None = None)

Returns a Float representation of infinity.

Optionally specify a rounding context under which to construct this value. If a rounding context is specified, x must be representable under ctx.

property invalid: bool

the operation produced an invalid result.

Type:: Invalid operation flag

is_canonical() → bool

Returns if x is canonical under this context.

This function only considers relevant attributes to judge if a value is canonical. Thus, there may be more than one canonical value for a given number despite the function name. The result of self.normalize() is always canonical.

Raises a ValueError when self.ctx is None.

is_finite() → bool: Returns whether this value is finite.

is_integer() → bool: Returns whether this value is an integer.

is_more_significant(n: int) → bool

Returns True iff this value only has significant digits above n, that is, every non-zero digit in the number is more significant than n.

Raises a ValueError when self.is_nar().

This method is equivalent to:

assert not self.is_nar()
_, lo = self.split(n)
return lo.is_zero()

is_nar() → bool: Return whether this number is infinity or NaN.

is_negative() → bool: Returns whether this value is negative.

is_nonzero() → bool: Returns whether this value is (finite) nonzero.

is_normal() → bool

Returns if this number is “normal”.

For IEEE-style contexts, this means that the number is finite, non-zero, and x.normalize() has full precision.

is_positive() → bool: Returns whether this value is positive.

is_representable() → bool: Checks if this number is representable under the rounding context during its construction. Usually just a sanity check.

is_zero() → bool: Returns whether this value represents zero.

property isinf: bool: Is this number infinite?

property isnan: bool: Is this number NaN?

property m: int: Significand of this number.

property n: int: Position of the first unrepresentable digit below the significant digits. This is exactly self.exp - 1.

static nan(s: bool = False, ctx: None = None)

Returns a Float representation of NaN.

Optionally specify a rounding context under which to construct this value. If a rounding context is specified, x must be representable under ctx.

next_away_zero(allow_inf: bool = False) → Float: Returns the next representable Float value after self away from zero.

next_down(allow_inf: bool = False) → Float: Returns the next representable Float value after self towards negative infinity.

next_towards(other: Float, allow_inf: bool = False) → Float: Returns the next representable Float value after self towards other.

next_towards_zero(allow_inf: bool = False) → Float: Returns the next representable Float value after self towards zero.

next_up(allow_inf: bool = False) → Float: Returns the next representable Float value after self towards positive infinity.

normalize(p: int | None = None, n: int | None = None)

Returns a value numerically equivalent to self based on precision p and position n:

None, None: the canonical representation of self under self.ctx.
p, None: a copy of self that has exactly p bits of precision.
None, n: a copy of self where self.exp == n + 1.
p, n: a copy of self such that self.exp >= n + 1 and
has maximal precision up to p bits.

Raises a ValueError if no such value exists, i.e., if the value cannot be represented with the given p and n.

property overflow: bool

the result exceeded the representable range.

Type:: Overflow flag

property p: Minimum number of binary digits required to represent this number.

round(ctx: None)

Rounds this number under the given context.

This method is equivalent to ctx.round(self).

round_at(ctx: None, n: int)

Rounds this number at the given position.

This method is equivalent to self.ctx.round_at(self, n).

round_integer(ctx: None)

Rounds this number to the nearest integer.

This method is equivalent to self.ctx.round_integer(self).

property s: bool: Is the sign negative?

split(n: int): Splits self into two Float values where the first value represents the digits above n and the second value represents the digits below and including n.

property tiny_post: bool

the result after rounding (without subnormalization) satisfies |x| < 2^emin.

Type:: Tiny after rounding flag

property tiny_pre: bool

the result before rounding satisfies |x| < 2^emin.

Type:: Tiny before rounding flag

property underflow_post: bool

self.tiny_post and self.inexact.

Type:: Underflow after rounding flag

property underflow_pre: bool

self.tiny_pre and self.inexact.

Type:: Underflow before rounding flag

static zero(s: bool = False, ctx: None = None)

Returns a Float representation of zero.

Optionally specify a rounding context under which to construct this value. If a rounding context is specified, x must be representable under ctx.

Rounding Utilities

Additional types for specifying rounding operations.

class fpy2.RoundingMode(*values)

Bases: Enum

Rounding modes for finite-precision operations.

RAZ = 5: round away from zero

RNA = 1: round to nearest, ties away from zero

RNE = 0: round to nearest, ties to even

RTE = 7: round towards even

RTN = 3: round towards negative infinity

RTO = 6: round towards odd

RTP = 2: round towards positive infinity

RTZ = 4: round towards zero

to_direction(s: bool) → tuple[bool, RoundingDirection]: Converts to a nearest flag and RoundingDirection.

class fpy2.RoundingDirection(*values)

Bases: Enum

Rounding directions for finite-precision operations.

RAZ = 1: rounding away from zero

RTE = 2: rounding towards even

RTO = 3: rounding towards odd

RTZ = 0: rounding towards zero

class fpy2.OverflowMode(*values)

Bases: Enum

Overflow behavior for rounding under bounded formats.

This is used to specify what value to produce when a value is larger (in magnitude) than the maximum value. - OVERFLOW: produces infinity or raise an OverflowError - SATURATE: produce the (correctly signed) maximum value - WRAP: produce the modulus over the ordinals - ASSERT: raise an OverflowError

class fpy2.EFloatNanKind(*values)

Bases: IntEnum

Describes how NaN values are encoded for ExtFloatContext rounding contexts.

IEEE_754 = 0

NaNs have the largest exponent

Type:: IEEE 754 compliant

MAX_VAL = 1: NaN has largest exponent and mantissa of all ones

NEG_ZERO = 2: NaN replaces -0

NONE = 3: No NaNs