Struct Quire 

pub struct Quire<const N: u32, const ES: u32, const SIZE: usize>(/* private fields */);

A quire, for a posit type with N bits and ES exponent bits, which is SIZE bytes long.

A quire is a fixed-point accumulator that enables sums and dot products of posits to be calculated with no intermediate rounding whatsoever. This has tremendous practical uses, from solving systems of equations to evaluating neural networks.

The SIZE is bounded from below based on the minimum size necessary to hold the product of two posits. Above this, the more extra space, the more terms can be accumulated without the risk of overflow (in practice the standard suggests ≈30 extra bits, corresponding to over a billion terms). It is also required to be a multiple of 8 (64 bits) for performance reasons (this requirement will be relaxed in the future).

If the quire SIZE is smaller than the minimum size necessary for an N bit posit with ES exponent bits, or if that size is not a multiple of 8, a compilation error is raised.

Type aliases are provided at the crate root for the quire types defined in the standard.

Example

// A 256-bit (32-byte) quire for a posit with 16 bits and 1 exponent bit
type Foo = Quire<16, 1, 32>;

// Compute sums and products in the quire with *no* loss of precision.
let mut quire = q16::ZERO;
quire += p16::MAX;
quire += p16::round_from(0.1);
quire -= p16::MAX;
let result: p16 = (&quire).round_into();  // Only the final step rounds

// Correct result with the quire, no issues with rounding errors.
assert_eq!(result, p16::round_from(0.1));

// The same sum without the quire would give a wrong result, due to double rounding.
let posit = (p16::MAX + p16::round_from(0.1)) - p16::MAX;
assert_eq!(posit, p16::ZERO);

Implementations

impl<const N: u32, const ES: u32, const SIZE: usize> Quire<N, ES, SIZE>

pub const BITS: u32

The quire size in bits.

Example

assert_eq!(q16::BITS, 256);

pub const SIZE: usize

The quire size in bytes.

Example

assert_eq!(q16::SIZE, 32);

pub const MIN_SIZE: usize

The minimum size of a quire for Posit<N, ES, Int>.

Example

assert_eq!(q16::MIN_SIZE, 29);

pub const PROD_LIMIT: u32

The minimum number of operations on the quire that can lead to overflow is 2 ^PROD_LIMIT; any number of [Self::add_prod] calls smaller than that is guaranteed not to overflow.

Example

assert_eq!(q32::PROD_LIMIT, 31);  // Can do at least 2^31 - 1 products without overflow

pub const SUM_LIMIT: u32

The minimum number of additions of posits that can lead to overflow is 2 ^SUM_LIMIT; any number of += or -= operations smaller than that is guaranteed not to overflow.

Example

assert_eq!(q32::SUM_LIMIT, 151);  // Can sum at least 2^151 - 1 terms without overflow

pub const ZERO: Self

A quire that represents the posit number 0.

pub const NAR: Self

A quire that represents the posit value NaR.

pub const fn from_bits(bytes: [u8; SIZE]) -> Self

Construct a quire from its raw bit representation, in big endian order.

Example

let quire = q8::from_bits([0,0,0,0, 0,0,0,0,0,1, 0,0,0,0,0,0]);
assert_eq!(p8::round_from(&quire), p8::ONE);

pub const fn is_nar(&self) -> bool

Checks whether self represents a NaR value.

Example

assert!(q32::NAR.is_nar());

Trait Implementations

impl<const N: u32, const ES: u32, Int: Int, const SIZE: usize> AddAssign<&Posit<N, ES, Int>> for Quire<N, ES, SIZE>

fn add_assign(&mut self, rhs: &Posit<N, ES, Int>)

Standard: “qAddP”.

Example

let mut quire = q16::from(p16::ONE);
quire += p16::round_from(0.42);
assert_eq!(p16::round_from(1.42), (&quire).round_into())

impl<const N: u32, const ES: u32, Int: Int, const SIZE: usize> AddAssign<Posit<N, ES, Int>> for Quire<N, ES, SIZE>

fn add_assign(&mut self, rhs: Posit<N, ES, Int>)

Standard: “qAddP”.

Example

let mut quire = q16::from(p16::ONE);
quire += p16::round_from(0.42);
assert_eq!(p16::round_from(1.42), (&quire).round_into())

impl<const N: u32, const ES: u32, const SIZE: usize> Clone for Quire<N, ES, SIZE>

fn clone(&self) -> Quire<N, ES, SIZE>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<const N: u32, const ES: u32, const SIZE: usize> Debug for Quire<N, ES, SIZE>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<const N: u32, const ES: u32, Int: Int, const SIZE: usize> From<Posit<N, ES, Int>> for Quire<N, ES, SIZE>

fn from(value: Posit<N, ES, Int>) -> Self

Create a quire from a posit value.

Standard: “pToQ”.

Example

let posit = p16::round_from(123);
let quire = q16::from(posit);

impl<const N: u32, const ES: u32, const SIZE: usize> Hash for Quire<N, ES, SIZE>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<const N: u32, const ES: u32, Int: Int, const SIZE: usize> RoundFrom<&Quire<N, ES, SIZE>> for Posit<N, ES, Int>

fn round_from(value: &Quire<N, ES, SIZE>) -> Self

Round a quire back to a posit. This is the final step to do after a series of calculations in the quire, and the only step that actually rounds.

Standard: “qToP”.

Example

let mut quire = q16::from(p16::MAX);
quire += p16::round_from(0.1);
quire -= p16::MAX;
let result: p16 = (&quire).round_into();
assert_eq!(result, p16::round_from(0.1))

impl<const N: u32, const ES: u32, Int: Int, const SIZE: usize> SubAssign<&Posit<N, ES, Int>> for Quire<N, ES, SIZE>

fn sub_assign(&mut self, rhs: &Posit<N, ES, Int>)

Standard: “qSubP”.

Example

let mut quire = q16::from(p16::ONE);
quire -= p16::round_from(0.42);
assert_eq!(p16::round_from(0.58), (&quire).round_into())

impl<const N: u32, const ES: u32, Int: Int, const SIZE: usize> SubAssign<Posit<N, ES, Int>> for Quire<N, ES, SIZE>

fn sub_assign(&mut self, rhs: Posit<N, ES, Int>)

Standard: “qSubP”.

Example

let mut quire = q16::from(p16::ONE);
quire -= p16::round_from(0.42);
assert_eq!(p16::round_from(0.58), (&quire).round_into())