Note

Check the version number of this documentation against the gfloat version you are using. “Latest” refers to the head on https://github.com/graphcore-research/gfloat, while pypi versions installed using pip install will have corresponding vX.Y.Z tags.

# GFloat: Generic floating point formats in Python

GFloat is designed to allow experimentation with a variety of floating-point formats in Python. Formats are parameterized by the primary IEEE-754 parameters of:

> - Width in bits (k)

> - Precision (p)

> - Maximum exponent (emax)

with additional fields defining the encoding of infinities, Not-a-number (NaN) values, and negative zero, among others (see `gfloat.FormatInfo`.)

This allows an implementation of generic floating point encode/decode logic, handling various current and proposed floating point types:

> - IEEE 754: Binary16, Binary32

> - OCP Float8: E5M2, E4M3, and MX formats

> - IEEE WG P3109: P{p} for p in 1..7

The library favours readability and extensibility over speed - for fast implementations of these datatypes see, for example, ml_dtypes, bitstring, MX PyTorch Emulation Library.

To get started with the library, we recommend perusing the notebooks, otherwise you may wish to jump straight into the API.

- Notebooks
  - GFloat Basics
    - List all the values in a format
    - Additional format info: special values, min, max, dynamic range
    - How do subnormals affect dynamic range?
  - Collect value statistics for formats
    - Statistics collected
    - Emit HTML table
  - Making value tables
    - Define some helpers.
      - Render with underscores separating s_e_m
      - Render a binary16 value
      - Print one table row
    - Make HTML table
      - OCP E2M3
  - And here’s a 6-bit “IEEE-754” float:
    - OCP Formats: E5M2, E4M3
    - IEEE WG P3109 {P} formats
- API
  - Scalar Functions
    - `decode_float()`
    - `round_float()`
    - `encode_float()`
  - Block format functions
    - `decode_block()`
    - `encode_block()`
    - `quantize_block()`
    - `compute_scale_amax()`
  - Classes
    - `FormatInfo`
      - `FormatInfo.name`
      - `FormatInfo.k`
      - `FormatInfo.precision`
      - `FormatInfo.emax`
      - `FormatInfo.has_nz`
      - `FormatInfo.has_infs`
      - `FormatInfo.num_high_nans`
      - `FormatInfo.has_subnormals`
      - `FormatInfo.is_signed`
      - `FormatInfo.is_twos_complement`
      - `FormatInfo.tSignificandBits`
      - `FormatInfo.expBits`
      - `FormatInfo.signBits`
      - `FormatInfo.expBias`
      - `FormatInfo.bits`
      - `FormatInfo.eps`
      - `FormatInfo.epsneg`
      - `FormatInfo.iexp`
      - `FormatInfo.machep`
      - `FormatInfo.max`
      - `FormatInfo.maxexp`
      - `FormatInfo.min`
      - `FormatInfo.num_nans`
      - `FormatInfo.code_of_nan`
      - `FormatInfo.code_of_posinf`
      - `FormatInfo.code_of_neginf`
      - `FormatInfo.code_of_zero`
      - `FormatInfo.has_zero`
      - `FormatInfo.code_of_negzero`
      - `FormatInfo.code_of_max`
      - `FormatInfo.code_of_min`
      - `FormatInfo.smallest_normal`
      - `FormatInfo.smallest_subnormal`
      - `FormatInfo.smallest`
      - `FormatInfo.is_all_subnormal`
    - `FloatClass`
      - `FloatClass.NORMAL`
      - `FloatClass.SUBNORMAL`
      - `FloatClass.ZERO`
      - `FloatClass.INFINITE`
      - `FloatClass.NAN`
    - `RoundMode`
      - `RoundMode.TowardZero`
      - `RoundMode.TowardNegative`
      - `RoundMode.TowardPositive`
      - `RoundMode.TiesToEven`
      - `RoundMode.TiesToAway`
    - `FloatValue`
      - `FloatValue.code`
      - `FloatValue.fval`
      - `FloatValue.exp`
      - `FloatValue.expval`
      - `FloatValue.significand`
      - `FloatValue.fsignificand`
      - `FloatValue.signbit`
      - `FloatValue.fclass`
    - `BlockFormatInfo`
      - `BlockFormatInfo.name`
      - `BlockFormatInfo.etype`
      - `BlockFormatInfo.k`
      - `BlockFormatInfo.stype`
      - `BlockFormatInfo.element_bits`
      - `BlockFormatInfo.scale_bits`
      - `BlockFormatInfo.block_size_bytes`
  - Pretty printers
    - `float_pow2str()`
    - `float_tilde_unless_roundtrip_str()`
- Defined Formats
  - IEEE 754 Formats
    - `format_info_binary16`
    - `format_info_binary32`
    - `format_info_binary64`
  - BFloat16
    - `format_info_bfloat16`
  - Open Compute Platform (OCP) Formats
    - `format_info_ocp_e5m2`
    - `format_info_ocp_e4m3`
    - `format_info_ocp_e3m2`
    - `format_info_ocp_e2m3`
    - `format_info_ocp_e2m1`
    - `format_info_ocp_e8m0`
    - `format_info_ocp_int8`
  - IEEE WG P3109 Formats
    - `format_info_p3109()`
  - Block Formats
    - `format_info_mxfp8_e5m2`
    - `format_info_mxfp8_e4m3`
    - `format_info_mxfp6_e3m2`
    - `format_info_mxfp6_e2m3`
    - `format_info_mxfp4_e2m1`
    - `format_info_mxint8`

# Index and Search

- Index

- Search Page