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:
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
B = halfprecision(A)
C = halfprecision(B,S)
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.
>> a = [-inf -1e30 -1.2 NaN 1.2 1e30 inf]
-Inf -1.0000 -0.0000 NaN 0.0000 1.0000 Inf
>> b = halfprecision(a)
64512 64512 48333 65024 15565 31744 31744
-Inf -Inf -1.2002 NaN 1.2002 Inf Inf
-Inf -Inf -1.2002 NaN 1.2002 Inf Inf
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.
I had additional issues building on Linux, fist of all gcc assumes files ending in.c are C files, and throws an error because comments are C++ comments. Fixed by changing the file extension to .cpp
Also get a compile error from gcc which can be fixed by calling as:
mex -v CXXFLAGS='$CXXFLAGS -fpermissive' halfprecision.cpp
The problem is with the call to mexCallMATLAB on line 320 which expects the fourth arg (prhs) to be const.
+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.
when i run
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, works perfectly! Actually looking forward for TMW to include half and quadruple precision.
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.
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.