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.