Quarter.hpp

// Copyright (c) 2022 Graphcore Ltd. All rights reserved.
 
/* Quarter precision floating-point type definitions for IPU host software.
 *
 * The Quarter type is a single byte floating-point format internal to poplar.
 * The format is fully defined at runtime using an independently allocated
 * metadata variable. Typically a single metadata variable can be used to define
 * the format for an arbitrary number of elements of type Quarter. The metadata
 * is of type QuarterMetadata and it includes the following information:
 *  - An enumeration that defines the number of bits of the Quarter data that
 *    is used for sign, mantissa and exponent.
 *  - A signed scale factor.
 *
 * The scale factor needs to be applied appropriately when converting from
 * Quarter to float or vice-versa. In the following code, `d` is of type
 * float, `q` is of type Quarter, and QuarterMetadata uses scale factor `s`.
 *    d = q * pow(2, s)
 *    q = d * pow(2, -s)
 */
 
#ifndef poplar_Quarter_hpp_
#define poplar_Quarter_hpp_
 
#include <iosfwd>
 
namespace poplar {
 
class QuarterMetadata {
public:
  enum class Format { F143, F152 };
 
  QuarterMetadata() = default;
 
  explicit QuarterMetadata(const Format fmt, const signed char scale)
      : value(pack(fmt, scale)){};
 
  explicit QuarterMetadata(unsigned char value) : value(value){};
 
  QuarterMetadata(const QuarterMetadata &other) : value(other.value){};
 
  QuarterMetadata &operator=(const QuarterMetadata &other);
 
  bool operator==(const QuarterMetadata other) const;
 
  bool operator!=(const QuarterMetadata other) const;
 
  // Get the binary representation of the underlying value
  unsigned char getBinary() const { return value; };
 
  unsigned char &data() { return value; };
 
  const unsigned char &data() const { return value; };
 
  Format getFormat() const;
 
  signed char getScale() const;
 
  std::string toString() const;
 
private:
  unsigned char pack(const Format fmt, const signed char scale) const;
 
  unsigned char value;
};
 
std::ostream &operator<<(std::ostream &os, const QuarterMetadata &md);
 
} // namespace poplar
 
#endif // poplar_Quarter_hpp_