# API

## Scalar Functions

gfloat.decode_float(fi, i)

  Given `FormatInfo` and integer code point, decode to a `FloatValue`

  Parameters:

    - fi (FormatInfo) – Floating point format descriptor.

    - i (int) – Integer code point, in the range \(0 \le i < 2^{k}\), where \(k\) = `fi.k`

  Returns:

    Decoded float value

  Raises:

    ValueError – If `i` is outside the range of valid code points in `fi`.

gfloat.round_float(fi, v, rnd=RoundMode.TiesToEven, sat=False)

  Round input to the given `FormatInfo`, given rounding mode and saturation flag

  An input NaN will convert to a NaN in the target. An input Infinity will convert to the largest float if `sat`, otherwise to an Inf, if present, otherwise to a NaN. Negative zero will be returned if the format has negative zero, otherwise zero.

  Parameters:

    - fi (FormatInfo) – Describes the target format

    - v (float) – Input value to be rounded

    - rnd (RoundMode) – Rounding mode to use

    - sat (bool) – Saturation flag: if True, round overflowed values to fi.max

  Returns:

    A float which is one of the values in the format.

  Raises:

    ValueError – The target format cannot represent the input (e.g. converting a NaN, or an Inf when the target has no NaN or Inf, and `sat` is false)

gfloat.encode_float(fi, v)

  Encode input to the given `FormatInfo`.

  Will round toward zero if `v` is not in the value set. Will saturate to Inf, NaN, fi.max in order of precedence. Encode -0 to 0 if not fi.has_nz

  For other roundings and saturations, call `round_float()` first.

  Parameters:

    - fi (FormatInfo) – Describes the target format

    - v (float) – The value to be encoded.

  Returns:

    The integer code point

## Block format functions

gfloat.decode_block(fi, block)

  Decode a `block` of integer codepoints in Block Format `fi`

  The scale is encoded in the first value of `block`, with the remaining values encoding the block elements.

  The size of the iterable is not checked against the format descriptor.

  Parameters:

    - fi (BlockFormatInfo) – Describes the block format

    - block (Iterable[int]) – Input block

  Returns:

    A sequence of floats representing the encoded values.

gfloat.encode_block(fi, scale, vals, round=RoundMode.TiesToEven)

  Encode float `vals` into block Format described by `fi`

  The `scale` is explicitly passed, and the `vals` are assumed to already be multiplied by 1/scale. That is, this is pure encoding, scaling is computed and applied elsewhere (see e.g. `quantize_block()`).

  It is checked for overflow in the target format, and will raise an exception if it does.

  Parameters:

    - fi (BlockFormatInfo) – Describes the target block format

    - scale (float) – Scale to be recorded in the block

    - vals (Iterable[float]) – Input block

    - round (RoundMode) – Rounding mode to use, defaults to TiesToEven

  Returns:

    A sequence of ints representing the encoded values.

  Raises:

    ValueError – The scale overflows the target scale encoding format.

gfloat.quantize_block(fi, vals, compute_scale, round=RoundMode.TiesToEven)

  Encode and decode a block of `vals` of bytes into block format described by `fi`

  Parameters:

    - fi (BlockFormatInfo) – Describes the target block format

    - vals (numpy.array) – Input block

    - compute_scale ((float, ArrayLike) -> float) – Callable to compute the scale, defaults to `compute_scale_amax()`

    - round (RoundMode) – Rounding mode to use, defaults to TiesToEven

  Returns:

    An array of floats representing the quantized values.

  Raises:

    ValueError – The scale overflows the target scale encoding format.

gfloat.compute_scale_amax(emax, vals)

  Compute a scale factor such that `vals` can be scaled to the range [0, 2**emax]. That is, scale is computed such that the largest exponent in the array vals * scale will be emax.

  The scale is clipped to the range 2**[-127, 127].

  If all values are zero, any scale value smaller than emax would be accurate, but returning the smallest possible means that quick checks on the magnitude to identify near-zero blocks will also find the all-zero blocks.

  Parameters:

    - emax (float) – Maximum exponent to appear in vals * scale

    - vals (ArrayLike) – Input block

  Returns:

    A float such that vals * scale has exponents less than or equal to emax.

  Note

  If all vals are zero, 1.0 is returned.

## Classes

class gfloat.FormatInfo

  Class describing a floating-point format, parametrized by width, precision, and special value encoding rules.

  name

    Short name for the format, e.g. binary32, bfloat16

  k

    Number of bits in the format

  precision

    Number of significand bits (including implicit leading bit)

  emax

    Largest exponent, emax, which shall equal floor(log_2(maxFinite))

  has_nz

    Set if format encodes -0 at (sgn=1,exp=0,significand=0). If False, that encoding decodes to a NaN labelled NaN_0

  has_infs

    Set if format includes +/- Infinity. If set, the non-nan value with the highest encoding for each sign (s) is replaced by (s)Inf.

  num_high_nans

    Number of NaNs that are encoded in the highest encodings for each sign

  has_subnormals

    Set if format encodes subnormals

  is_signed

    Set if the format has a sign bit

  is_twos_complement

    Set if the format uses two’s complement encoding for the significand

  property tSignificandBits

    The number of trailing significand bits, t

  property expBits

    The number of exponent bits, w

  property signBits

    The number of sign bits, s

  property expBias

    The exponent bias derived from (p,emax)

    This is the bias that should be applied so that

      \(floor(log_2(maxFinite)) = emax\)

  property bits

    The number of bits occupied by the type.

  property eps

    The difference between 1.0 and the smallest representable float larger than 1.0. For example, for 64-bit binary floats in the IEEE-754 standard, `eps = 2**-52`, approximately 2.22e-16.

  property epsneg

    The difference between 1.0 and the largest representable float less than 1.0. For example, for 64-bit binary floats in the IEEE-754 standard, `epsneg = 2**-53`, approximately 1.11e-16.

  property iexp

    The number of bits in the exponent portion of the floating point representation.

  property machep

    The exponent that yields eps.

  property max

    The largest representable number.

  property maxexp

    The smallest positive power of the base (2) that causes overflow.

  property min

    The smallest representable number, typically `-max`.

  property num_nans

    The number of code points which decode to NaN

  property code_of_nan

    Return a codepoint for a NaN

  property code_of_posinf

    Return a codepoint for positive infinity

  property code_of_neginf

    Return a codepoint for negative infinity

  property code_of_zero

    Return a codepoint for (non-negative) zero

  property has_zero

    Does the format have zero?

    This is false if the mantissa is 0 width and we don’t have subnormals - essentially the mantissa is always decoded as 1. If we have subnormals, the only subnormal is zero, and the mantissa is always decoded as 0.

  property code_of_negzero

    Return a codepoint for negative zero

  property code_of_max

    Return a codepoint for fi.max

  property code_of_min

    Return a codepoint for fi.min

  property smallest_normal

    The smallest positive floating point number with 1 as leading bit in the significand following IEEE-754.

  property smallest_subnormal

    The smallest positive floating point number with 0 as leading bit in the significand following IEEE-754.

  property smallest

    The smallest positive floating point number.

  property is_all_subnormal

    Are all encoded values subnormal?

class gfloat.FloatClass

  Enum for the classification of a FloatValue.

  NORMAL = 1

    A positive or negative normalized non-zero value

  SUBNORMAL = 2

    A positive or negative subnormal value

  ZERO = 3

    A positive or negative zero value

  INFINITE = 4

    A positive or negative infinity (+/-Inf)

  NAN = 5

    Not a Number (NaN)

class gfloat.RoundMode

  Enum for IEEE-754 rounding modes.

  Result r is obtained from input v depending on rounding mode as follows

  TowardZero = 1

    \(\max \{ r ~ s.t. ~ |r| \le |v| \}\)

  TowardNegative = 2

    \(\max \{ r ~ s.t. ~ r \le v \}\)

  TowardPositive = 3

    \(\min \{ r ~ s.t. ~ r \ge v \}\)

  TiesToEven = 4

    Round to nearest, ties to even

  TiesToAway = 5

    Round to nearest, ties away from zero

class gfloat.FloatValue

  A floating-point value decoded in great detail.

  code

    Integer code point

  fval

    Value. Assumed to be exactly round-trippable to python float. This is true for all <64bit formats known in 2023.

  exp

    Raw exponent without bias

  expval

    Exponent, bias subtracted

  significand

    Significand as an integer

  fsignificand

    Significand as a float in the range [0,2)

  signbit

    1 => negative, 0 => positive

    Type:

      Sign bit

  fclass

    See FloatClass

class gfloat.BlockFormatInfo

  BlockFormatInfo(name: str, etype: gfloat.types.FormatInfo, k: int, stype: gfloat.types.FormatInfo)

  name

    Short name for the format, e.g. BlockFP8

  etype

    Element data type

  k

    Scaling block size

  stype

    Scale datatype

  property element_bits

    The number of bits in each element, d

  property scale_bits

    The number of bits in the scale, w

  property block_size_bytes

    The number of bytes in a block

## Pretty printers

gfloat.float_pow2str(v, min_exponent=-inf)

  Render floating point values as exact fractions times a power of two.

  Example: float_pow2str(127.0) is “127/64*2^6”,

  That is (a significand between 1 and 2) times (a power of two).

  If min_exponent is supplied, then values with exponent below min_exponent, are printed as fractions less than 1, with exponent set to min_exponent. This is typically used to represent subnormal values.

gfloat.float_tilde_unless_roundtrip_str(v, width=14, d=8)

  Return a string representation of `v`, in base 10, with maximum width `width` and decimal digits `d`