Class: BFloat16Array

• Inheritance
• Description
• Class protocol
  • queries
• Instance protocol
  • accessing
  • queries

Inheritance:

   Object
   |
   +--Collection
      |
      +--SequenceableCollection
         |
         +--ArrayedCollection
            |
            +--UninterpretedBytes
               |
               +--AbstractNumberVector
                  |
                  +--UnboxedFloatArray
                     |
                     +--BFloat16Array

Package:

stx:libbasic2

Category:

Collections-Arrayed

Version:

rev: 1.15 date: 2022/03/24 07:22:05

user: cg

file: BFloat16Array.st directory: libbasic2

module: stx stc-classLibrary: libbasic2

Description:

BFloat16Arrays store half precision (16bit) bfloats (and nothing else).
These are similar to HalfFloats, but have a full 8bit exponent and a very
reduced mantissa (8 bit).
Thus, they have the same number range as single precision floats, but much less precision.
(as opposed to HalfFloats, which provide slighly more precision, but a smaller range).

BFloat16s are heavily used in machine learning and graphic (GPU) algorithms, 
and some modern CPUs support them natively in hardware.

Notice, that BFloat16s are not supported as first class objects by the ST/X system;
i.e. outside of a BFloat16Array, these values are represented as floats
or doubles. When accessing a BFloat16Array's element via getters/setters,
shortFloat (i.e. single precision 32bit floats) are exchanged.

Be aware that the precision of a bfloat16 is very very limited,
although the numeric range is that of a single precision-float.

Citation form wikipedia:
    Bfloat16 is designed to maintain the number range from the 32-bit IEEE 754 
    single-precision floating-point format (binary32), 
    while reducing the precision from 24 bits to 8 bits. 
    This means that the precision is between two and three decimal digits, 
    and bfloat16 can represent finite values up to about 3.4 × 10^38.

BFloat16Arrays can be used as literals i.e. you can enter BFloat16Array-constants as: 
    #fb16( element1 element2 .... elementN ) 
for example:
    #fb16(1 2.0 3 4.0)

[memory requirements:]
    OBJ-HEADER + (size * 2)

[complexity:]
    see Array

copyright
COPYRIGHT (c) 2020 by Claus Gittinger
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

Class protocol:

 elementByteSize

for bit-like containers, return the number of bytes stored per element.
Here, 2 is returned

 epsilon

return the maximum relative spacing of elements of mySelf
(i.e. the value-delta of the least significant bit)

Usage example(s):

HalfFloatArray epsilon printStringScientific BFloat16Array epsilon printStringScientific

 fmax

return the largest value that instances of me can represent

 fmin

return the smallest normalized non-zero value that instances of me can represent

 literalTokenPrefix

 precision

answer the precision (the number of bits in the mantissa) of my elements (in bits)
This is a bfloat16, where only the fraction from the normalized mantissa is stored
and so there is a hidden bit and the mantissa is actually represented by 8 binary digits
(although only 7 are needed in the binary representation).
any hidden bit is included here

Instance protocol:

 at: index

redefined to return the 16bit element as a float (bfloat16 conversion).
(because as seen by the Smalltalk VM, I am holding 16bit unsigned ints)

 at: index put: aFloat

redefined to store the float arg into a bfloat16.
(because as seen by the Smalltalk VM, I am holding 16bit unsigned ints)

Usage example(s):

|v| v := BFloat16Array new:5. v at:1 put:10. v at:2 put:1.234. v at:3 put:0xFFFFFFFFFFFFFFFF. v at:4 put:(1/4). v at:5 put:(3 + 4i). 'will fail'.

 defaultElement