Code covered by the BSD License  

Highlights from
IEEE 754r Half Precision floating point converter

5.0

5.0 | 2 ratings Rate this file 71 Downloads (last 30 days) File Size: 15.1 KB File ID: #23173

IEEE 754r Half Precision floating point converter

by

 

04 Mar 2009 (Updated )

Converts MATLAB or C variables to/from IEEE 754r Half Precision floating point bit pattern.

| Watch this File

File Information
Description

halfprecision converts the input argument to/from a half precision floating point bit pattern corresponding to IEEE 754r. The bit pattern is stored in a uint16 class variable. Please note that halfprecision is *not* a class (yet). That is, you cannot do any arithmetic with the half precision bit patterns. halfprecision is simply a function that converts the IEEE 754r half precision bit pattern to/from other numeric MATLAB variables. I am working on a class based on this halfprecision function that *will* allow you to do arithmetic operations and functions directly on the variables, but that will not be uploaded to the FEX for at least another 2-3 weeks. In the meantime, you can always take the half precision bit patterns, convert them to single or double, do the operation, and then convert the result back manually. In fact, that is all the class functions I am writing will do anyway, since I have no desire to write bit level floating point code.

The half precision bit pattern is as follows:
 
  1 bit sign bit
  5 bits exponent, biased by 15
  10 bits mantissa, hidden leading bit, normalized to 1.0
 
Special floating point bit patterns recognized and supported:
 
  All exponent bits zero:
  - If all mantissa bits are zero, then number is zero (possibly signed)
  - Otherwise, number is a denormalized bit pattern (leading bit is present)
 
  All exponent bits set to 1:
  - If all mantissa bits are zero, then number is +Infinity or -Infinity
  - Otherwise, number is NaN (Not a Number)

More details of this floating point format can be found here:

  http://en.wikipedia.org/wiki/Half_precision
 
Building:
 
halfprecision requires that a mex routine be built (one time only). This process is typically self-building the first time you call the function as long as you have the files halfprecision.m and halfprecision.c in the same directory somewhere on the MATLAB path. If you need to manually build the mex function, here are the commands:

  >> mex -setup
    (then follow instructions to select a C / C++ compiler of your choice)
  >> mex halfprecision.c

If you have an older version of MATLAB, you may need to use this command:

  >> mex -DDEFINEMWSIZE halfprecision.c
 
Syntax
 
  B = halfprecision(A)
  C = halfprecision(B,S)
      halfprecision(B,'disp')
 
Description
 
  A = a MATLAB numeric array, char array, or logical array.

  B = the variable A converted into half precision floating point bit pattern.
      The bit pattern will be returned as a uint16 class variable. The values
      displayed are simply the bit pattern interpreted as if it were an unsigned
      16-bit integer. To see the halfprecision values, use the 'disp' option, which
      simply converts the bit patterns into a single class and then displays them.

  C = the half precision floating point bit pattern in B converted into class S.
      B must be a uint16 or int16 class variable.

  S = char string naming the desired class (e.g., 'single', 'int32', etc.)
      If S = 'disp', then the floating point bit values are simply displayed.

Also supplied are two companion functions, halfprecisionmax and halfprecisionmin. They don't take any input arguments and simply return the max and min half precision bit patterns.
 
Examples
  
  >> a = [-inf -1e30 -1.2 NaN 1.2 1e30 inf]
  a =
  1.0e+030 *
      -Inf -1.0000 -0.0000 NaN 0.0000 1.0000 Inf
 
  >> b = halfprecision(a)
  b =
  64512 64512 48333 65024 15565 31744 31744
 
  >> halfprecision(b,'disp')
      -Inf -Inf -1.2002 NaN 1.2002 Inf Inf
 
  >> halfprecision(b,'double')
  ans =
      -Inf -Inf -1.2002 NaN 1.2002 Inf Inf
 
  >> 2^(-24)
  ans =
  5.9605e-008
 
  >> halfprecision(ans)
  ans =
      1
 
  >> halfprecision(ans,'disp')
  5.9605e-008
 
  >> 2^(-25)
  ans =
  2.9802e-008
 
  >> halfprecision(ans)
  ans =
      1
 
  >> halfprecision(ans,'disp')
  5.9605e-008
 
  >> 2^(-26)
  ans =
   1.4901e-008
 
  >> halfprecision(ans)
  ans =
      0
 
  >> halfprecision(ans,'disp')
     0
 
Note that the special cases of -Inf, +Inf, and NaN are handled correctly. Also, note that the -1e30 and 1e30 values overflow the half precision format and are converted into half precision -Inf and +Inf values, and stay that way when they are converted back into doubles.
 
For the denormalized cases, note that 2^(-24) is the smallest number that can be represented in half precision exactly. 2^(-25) will convert to 2^(-24) because of the rounding algorithm used, and 2^(-26) is too small and underflows to zero.

Caveat: I have only tested this code on a PC, which is Little Endian. I put in code to handle Big Endian machines, but I do not have a way to test it, so I can't say for sure that it will work properly. Let me know if you have problems.

Acknowledgements

This file inspired Terra Sar X And Tan Dem X Tools.

MATLAB release MATLAB 7.4 (R2007a)
Other requirements Any C/C++ compiler, such as the built-in lcc compiler.
Tags for This File   Please login to tag files.
Please login to add a comment or rating.
Comments and Ratings (6)
07 Apr 2014 Nick L

+1 @james.tursa's help:
On my 64-bit Linux machine, I was getting the "not IEEE 754" error until I added #include <stdint.h> and the four #define macros to halfprecision.c. The re-compiled halfprecision() seems to work as advertised after that.

11 Mar 2014 David Young  
10 Sep 2012 Michael

Hello,

when i run
mex halfprecision.c
halfprecision.c: In function ‘mexFunction’:
halfprecision.c:314: warning: passing argument 4 of ‘mexCallMATLAB’ from incompatible pointer type

Any help is much appreciated, because halfprecision(a) (see example) results in: 'Floating point bit pattern is not IEEE 754'

Thanks,
michael

03 Feb 2012 Sebastiaan

Thanks, works perfectly! Actually looking forward for TMW to include half and quadruple precision.

21 Nov 2009 James Tursa

Also this:

#include <stdint.h>

21 Nov 2009 James Tursa

I just got a report from a 64-bit linux user that the ieehalfprecision.c code did not work as posted, but he did get it to work by changing some types as follows:

#define INT16_TYPE int16_t
#define UINT16_TYPE uint16_t
#define INT32_TYPE int32_t
#define UINT32_TYPE uint32_t

I do not have a 64-bit system to test with, but I would assume this works as long as your compiler supports the int16_t etc types.

Updates
01 Aug 2009

An addition file is included, ieeehalfprecision.c, that contains C code to convert between IEEE double, single, and half precision floating point formats. The intended use is for standalone C code that does not rely on MATLAB mex.h.

Contact us