HALF-PRECISION FLOATING-POINT LIBRARY (Version 2.2.0) ----------------------------------------------------- This is a C++ header-only library to provide an IEEE 754 conformant 16-bit half-precision floating-point type along with corresponding arithmetic operators, type conversions and common mathematical functions. It aims for both efficiency and ease of use, trying to accurately mimic the behaviour of the built-in floating-point types at the best performance possible. INSTALLATION AND REQUIREMENTS ----------------------------- Conveniently, the library consists of just a single header file containing all the functionality, which can be directly included by your projects, without the neccessity to build anything or link to anything. Whereas this library is fully C++98-compatible, it can profit from certain C++11 features. Support for those features is checked automatically at compile (or rather preprocessing) time, but can be explicitly enabled or disabled by predefining the corresponding preprocessor symbols to either 1 or 0 yourself before including half.hpp. This is useful when the automatic detection fails (for more exotic implementations) or when a feature should be explicitly disabled: - 'long long' integer type for mathematical functions returning 'long long' results (enabled for VC++ 2003 and icc 11.1 and newer, gcc and clang, overridable with 'HALF_ENABLE_CPP11_LONG_LONG'). - Static assertions for extended compile-time checks (enabled for VC++ 2010, gcc 4.3, clang 2.9, icc 11.1 and newer, overridable with 'HALF_ENABLE_CPP11_STATIC_ASSERT'). - Generalized constant expressions (enabled for VC++ 2015, gcc 4.6, clang 3.1, icc 14.0 and newer, overridable with 'HALF_ENABLE_CPP11_CONSTEXPR'). - noexcept exception specifications (enabled for VC++ 2015, gcc 4.6, clang 3.0, icc 14.0 and newer, overridable with 'HALF_ENABLE_CPP11_NOEXCEPT'). - User-defined literals for half-precision literals to work (enabled for VC++ 2015, gcc 4.7, clang 3.1, icc 15.0 and newer, overridable with 'HALF_ENABLE_CPP11_USER_LITERALS'). - Thread-local storage for per-thread floating-point exception flags (enabled for VC++ 2015, gcc 4.8, clang 3.3, icc 15.0 and newer, overridable with 'HALF_ENABLE_CPP11_THREAD_LOCAL'). - Type traits and template meta-programming features from (enabled for VC++ 2010, libstdc++ 4.3, libc++ and newer, overridable with 'HALF_ENABLE_CPP11_TYPE_TRAITS'). - Special integer types from (enabled for VC++ 2010, libstdc++ 4.3, libc++ and newer, overridable with 'HALF_ENABLE_CPP11_CSTDINT'). - Certain C++11 single-precision mathematical functions from for floating-point classification during conversions from higher precision types (enabled for VC++ 2013, libstdc++ 4.3, libc++ and newer, overridable with 'HALF_ENABLE_CPP11_CMATH'). - Floating-point environment control from for possible exception propagation to the built-in floating-point platform (enabled for VC++ 2013, libstdc++ 4.3, libc++ and newer, overridable with 'HALF_ENABLE_CPP11_CFENV'). - Hash functor 'std::hash' from (enabled for VC++ 2010, libstdc++ 4.3, libc++ and newer, overridable with 'HALF_ENABLE_CPP11_HASH'). The library has been tested successfully with Visual C++ 2005-2015, gcc 4-8 and clang 3-8 on 32- and 64-bit x86 systems. Please contact me if you have any problems, suggestions or even just success testing it on other platforms. DOCUMENTATION ------------- What follows are some general words about the usage of the library and its implementation. For a complete documentation of its interface consult the corresponding website http://half.sourceforge.net. You may also generate the complete developer documentation from the library's only include file's doxygen comments, but this is more relevant to developers rather than mere users. BASIC USAGE To make use of the library just include its only header file half.hpp, which defines all half-precision functionality inside the 'half_float' namespace. The actual 16-bit half-precision data type is represented by the 'half' type, which uses the standard IEEE representation with 1 sign bit, 5 exponent bits and 11 mantissa bits (including the hidden bit) and supports all types of special values, like subnormal values, infinity and NaNs. This type behaves like the built-in floating-point types as much as possible, supporting the usual arithmetic, comparison and streaming operators, which makes its use pretty straight-forward: using half_float::half; half a(3.4), b(5); half c = a * b; c += 3; if(c > a) std::cout << c << std::endl; Additionally the 'half_float' namespace also defines half-precision versions for all mathematical functions of the C++ standard library, which can be used directly through ADL: half a(-3.14159); half s = sin(abs(a)); long l = lround(s); You may also specify explicit half-precision literals, since the library provides a user-defined literal inside the 'half_float::literal' namespace, which you just need to import (assuming support for C++11 user-defined literals): using namespace half_float::literal; half x = 1.0_h; Furthermore the library provides proper specializations for 'std::numeric_limits', defining various implementation properties, and 'std::hash' for hashing half-precision numbers (assuming support for C++11 'std::hash'). Similar to the corresponding preprocessor symbols from the library also defines the 'HUGE_VALH' constant and maybe the 'FP_FAST_FMAH' symbol. CONVERSIONS AND ROUNDING The half is explicitly constructible/convertible from a single-precision float argument. Thus it is also explicitly constructible/convertible from any type implicitly convertible to float, but constructing it from types like double or int will involve the usual warnings arising when implicitly converting those to float because of the lost precision. On the one hand those warnings are intentional, because converting those types to half neccessarily also reduces precision. But on the other hand they are raised for explicit conversions from those types, when the user knows what he is doing. So if those warnings keep bugging you, then you won't get around first explicitly converting to float before converting to half, or use the 'half_cast' described below. In addition you can also directly assign float values to halfs. In contrast to the float-to-half conversion, which reduces precision, the conversion from half to float (and thus to any other type implicitly convertible from float) is implicit, because all values represetable with half-precision are also representable with single-precision. This way the half-to-float conversion behaves similar to the builtin float-to-double conversion and all arithmetic expressions involving both half-precision and single-precision arguments will be of single-precision type. This way you can also directly use the mathematical functions of the C++ standard library, though in this case you will invoke the single-precision versions which will also return single-precision values, which is (even if maybe performing the exact same computation, see below) not as conceptually clean when working in a half-precision environment. The default rounding mode for conversions between half and more precise types as well as for rounding results of arithmetic operations and mathematical functions rounds to the nearest representable value. But by predefining the 'HALF_ROUND_STYLE' preprocessor symbol this default can be overridden with one of the other standard rounding modes using their respective constants or the equivalent values of 'std::float_round_style' (it can even be synchronized with the built-in single-precision implementation by defining it to 'std::numeric_limits::round_style'): - 'std::round_indeterminate' (-1) for the fastest rounding. - 'std::round_toward_zero' (0) for rounding toward zero. - 'std::round_to_nearest' (1) for rounding to the nearest value (default). - 'std::round_toward_infinity' (2) for rounding toward positive infinity. - 'std::round_toward_neg_infinity' (3) for rounding toward negative infinity. In addition to changing the overall default rounding mode one can also use the 'half_cast'. This converts between half and any built-in arithmetic type using a configurable rounding mode (or the default rounding mode if none is specified). In addition to a configurable rounding mode, 'half_cast' has another big difference to a mere 'static_cast': Any conversions are performed directly using the given rounding mode, without any intermediate conversion to/from 'float'. This is especially relevant for conversions to integer types, which don't necessarily truncate anymore. But also for conversions from 'double' or 'long double' this may produce more precise results than a pre-conversion to 'float' using the single-precision implementation's current rounding mode would. half a = half_cast(4.2); half b = half_cast::round_style>(4.2f); assert( half_cast( 0.7_h ) == 1 ); assert( half_cast( 4097 ) == 4096.0_h ); assert( half_cast( 4097 ) == 4100.0_h ); assert( half_cast( std::numeric_limits::min() ) > 0.0_h ); ACCURACY AND PERFORMANCE From version 2.0 onward the library is implemented without employing the underlying floating-point implementation of the system (except for conversions, of course), providing an entirely self-contained half-precision implementation with results independent from the system's existing single- or double-precision implementation and its rounding behaviour. As to accuracy, many of the operators and functions provided by this library are exact to rounding for all rounding modes, i.e. the error to the exact result is at most 0.5 ULP (unit in the last place) for rounding to nearest and less than 1 ULP for all other rounding modes. This holds for all the operations required by the IEEE 754 standard and many more. Specifically the following functions might exhibit a deviation from the correctly rounded exact result by 1 ULP for a select few input values: 'expm1', 'log1p', 'pow', 'atan2', 'erf', 'erfc', 'lgamma', 'tgamma' (for more details see the documentation of the individual functions). All other functions and operators are always exact to rounding or independent of the rounding mode altogether. The increased IEEE-conformance and cleanliness of this implementation comes with a certain performance cost compared to doing computations and mathematical functions in hardware-accelerated single-precision. On average and depending on the platform, the arithemtic operators are about 75% as fast and the mathematical functions about 33-50% as fast as performing the corresponding operations in single-precision and converting between the inputs and outputs. However, directly computing with half-precision values is a rather rare use-case and usually using actual 'float' values for all computations and temproraries and using 'half's only for storage is the recommended way. But nevertheless the goal of this library was to provide a complete and conceptually clean IEEE-confromant half-precision implementation and in the few cases when you do need to compute directly in half-precision you do so for a reason and want accurate results. If necessary, this internal implementation can be overridden by predefining the 'HALF_ARITHMETIC_TYPE' preprocessor symbol to one of the built-in floating-point types ('float', 'double' or 'long double'), which will cause the library to use this type for computing arithmetic operations and mathematical functions (if available). However, due to using the platform's floating-point implementation (and its rounding behaviour) internally, this might cause results to deviate from the specified half-precision rounding mode. It will of course also inhibit the automatic exception detection described below. The conversion operations between half-precision and single-precision types can also make use of the F16C extension for x86 processors by using the corresponding compiler intrinsics from . Support for this is checked at compile-time by looking for the '__F16C__' macro which at least gcc and clang define based on the target platform. It can also be enabled manually by predefining the 'HALF_ENABLE_F16C_INTRINSICS' preprocessor symbol to 1, or 0 for explicitly disabling it. However, this will directly use the corresponding intrinsics for conversion without checking if they are available at runtime (possibly crashing if they are not), so make sure they are supported on the target platform before enabling this. EXCEPTION HANDLING The half-precision implementation supports all 5 required floating-point exceptions from the IEEE standard to indicate erroneous inputs or inexact results during operations. These are represented by exception flags which actually use the same values as the corresponding 'FE_...' flags defined in C++11's header if supported, specifically: - 'FE_INVALID' for invalid inputs to an operation. - 'FE_DIVBYZERO' for finite inputs producing infinite results. - 'FE_OVERFLOW' if a result is too large to represent finitely. - 'FE_UNDERFLOW' for a subnormal or zero result after rounding. - 'FE_INEXACT' if a result needed rounding to be representable. - 'FE_ALL_EXCEPT' as a convenient OR of all possible exception flags. The internal exception flag state will start with all flags cleared and is maintained per thread if C++11 thread-local storage is supported, otherwise it will be maintained globally and will theoretically NOT be thread-safe (while practically being as thread-safe as a simple integer variable can be). These flags can be managed explicitly using the library's error handling functions, which again try to mimic the built-in functions for handling floating-point exceptions from . You can clear them with 'feclearexcept' (which is the only way a flag can be cleared), test them with 'fetestexcept', explicitly raise errors with 'feraiseexcept' and save and restore their state using 'fegetexceptflag' and 'fesetexceptflag'. You can also throw corresponding C++ exceptions based on the current flag state using 'fethrowexcept'. However, any automatic exception detection and handling during half-precision operations and functions is DISABLED by default, since it comes with a minor performance overhead due to runtime checks, and reacting to IEEE floating-point exceptions is rarely ever needed in application code. But the library fully supports IEEE-conformant detection of floating-point exceptions and various ways for handling them, which can be enabled by pre-defining the corresponding preprocessor symbols to 1. They can be enabled individually or all at once and they will be processed in the order they are listed here: - 'HALF_ERRHANDLING_FLAGS' sets the internal exception flags described above whenever the corresponding exception occurs. - 'HALF_ERRHANDLING_ERRNO' sets the value of 'errno' from similar to the behaviour of the built-in floating-point types when 'MATH_ERRNO' is used. - 'HALF_ERRHANDLING_FENV' will propagate exceptions to the built-in floating-point implementation using 'std::feraiseexcept' if support for C++11 floating-point control is enabled. However, this does not synchronize exceptions: neither will clearing propagate nor will it work in reverse. - 'HALF_ERRHANDLING_THROW_...' can be defined to a string literal which will be used as description message for a C++ exception that is thrown whenever a 'FE_...' exception occurs, similar to the behaviour of 'fethrowexcept'. If any of the above error handling is activated, non-quiet operations on half-precision values will also raise a 'FE_INVALID' exception whenever they encounter a signaling NaN value, in addition to transforming the value into a quiet NaN. If error handling is disabled, signaling NaNs will be treated like quiet NaNs (while still getting explicitly quieted if propagated to the result). There can also be additional treatment of overflow and underflow errors after they have been processed as above, which is ENABLED by default (but of course only takes effect if any other exception handling is activated) unless overridden by pre-defining the corresponding preprocessor symbol to 0: - 'HALF_ERRHANDLING_OVERFLOW_TO_INEXACT' will cause overflow errors to also raise a 'FE_INEXACT' exception. - 'HALF_ERRHANDLING_UNDERFLOW_TO_INEXACT' will cause underflow errors to also raise a 'FE_INEXACT' exception. This will also slightly change the behaviour of the underflow exception, which will ONLY be raised if the result is actually inexact due to underflow. If this is disabled, underflow exceptions will be raised for ANY (possibly exact) subnormal result. CREDITS AND CONTACT ------------------- This library is developed by CHRISTIAN RAU and released under the MIT License (see LICENSE.txt). If you have any questions or problems with it, feel free to contact me at rauy@users.sourceforge.net. Additional credit goes to JEROEN VAN DER ZIJP for his paper on "Fast Half Float Conversions", whose algorithms have been used in the library for converting between half-precision and single-precision values.