Floating point classification¶

NPY_NAN¶

This macro is defined to a NaN (Not a Number), and is guaranteed to havethe signbit unset (‘positive’ NaN). The corresponding single and extensionprecision macro are available with the suffix F and L.

NPY_INFINITY¶

This macro is defined to a positive inf. The corresponding single andextension precision macro are available with the suffix F and L.

NPY_PZERO¶

This macro is defined to positive zero. The corresponding single andextension precision macro are available with the suffix F and L.

NPY_NZERO¶

This macro is defined to negative zero (that is with the sign bit set). Thecorresponding single and extension precision macro are available with thesuffix F and L.

intnpy_isnan(x)¶

This is a macro, and is equivalent to C99 isnan: works for single, doubleand extended precision, and return a non 0 value is x is a NaN.

intnpy_isfinite(x)¶

This is a macro, and is equivalent to C99 isfinite: works for single,double and extended precision, and return a non 0 value is x is neither aNaN nor an infinity.

intnpy_isinf(x)¶

This is a macro, and is equivalent to C99 isinf: works for single, doubleand extended precision, and return a non 0 value is x is infinite (positiveand negative).

intnpy_signbit(x)¶

This is a macro, and is equivalent to C99 signbit: works for single, doubleand extended precision, and return a non 0 value is x has the signbit set(that is the number is negative).

doublenpy_copysign(double x, double y)¶

This is a function equivalent to C99 copysign: return x with the same signas y. Works for any value, including inf and nan. Single and extendedprecisions are available with suffix f and l.

New in version 1.4.0.

Useful math constants¶

The following math constants are available in npy_math.h. Single and extendedprecision are also available by adding the F and L suffixes respectively.

NPY_E¶

Base of natural logarithm (e)

NPY_LOG2E¶

Logarithm to base 2 of the Euler constant (\frac{\ln(e)}{\ln(2)})

NPY_LOG10E¶

Logarithm to base 10 of the Euler constant (\frac{\ln(e)}{\ln(10)})

NPY_LOGE2¶

Natural logarithm of 2 (\ln(2))

NPY_LOGE10¶

Natural logarithm of 10 (\ln(10))

NPY_PI¶

Pi (\pi)

NPY_PI_2¶

Pi divided by 2 (\frac{\pi}{2})

NPY_PI_4¶

Pi divided by 4 (\frac{\pi}{4})

NPY_1_PI¶

Reciprocal of pi (\frac{1}{\pi})

NPY_2_PI¶

Two times the reciprocal of pi (\frac{2}{\pi})

NPY_EULER¶

The Euler constant

\lim_{n\rightarrow\infty}({\sum_{k=1}^n{\frac{1}{k}}-\ln n})

Low-level floating point manipulation¶

Those can be useful for precise floating point comparison.

doublenpy_nextafter(double x, double y)¶

This is a function equivalent to C99 nextafter: return next representablefloating point value from x in the direction of y. Single and extendedprecisions are available with suffix f and l.

New in version 1.4.0.

doublenpy_spacing(double x)¶

This is a function equivalent to Fortran intrinsic. Return distance betweenx and next representable floating point value from x, e.g. spacing(1) ==eps. spacing of nan and +/- inf return nan. Single and extended precisionsare available with suffix f and l.

New in version 1.4.0.

voidnpy_set_floatstatus_divbyzero()¶

Set the divide by zero floating point exception

New in version 1.6.0.

voidnpy_set_floatstatus_overflow()¶

Set the overflow floating point exception

New in version 1.6.0.

voidnpy_set_floatstatus_underflow()¶

Set the underflow floating point exception

New in version 1.6.0.

voidnpy_set_floatstatus_invalid()¶

Set the invalid floating point exception

New in version 1.6.0.

intnpy_get_floatstatus()¶

Get floating point status. Returns a bitmask with following possible flags:

• NPY_FPE_DIVIDEBYZERO
• NPY_FPE_OVERFLOW
• NPY_FPE_UNDERFLOW
• NPY_FPE_INVALID

Note thatnpy_get_floatstatus_barrier is preferable as it preventsagressive compiler optimizations reordering the call relative tothe code setting the status, which could lead to incorrect results.

New in version 1.9.0.

intnpy_get_floatstatus_barrier(char*)¶

Get floating point status. A pointer to a local variable is passed in toprevent aggresive compiler optimizations from reodering this function callrelative to the code setting the status, which could lead to incorrectresults.

Returns a bitmask with following possible flags:

• NPY_FPE_DIVIDEBYZERO
• NPY_FPE_OVERFLOW
• NPY_FPE_UNDERFLOW
• NPY_FPE_INVALID

New in version 1.15.0.

intnpy_clear_floatstatus()¶

Clears the floating point status. Returns the previous status mask.

Note thatnpy_clear_floatstatus_barrier is preferable as itprevents agressive compiler optimizations reordering the call relative tothe code setting the status, which could lead to incorrect results.

New in version 1.9.0.

intnpy_clear_floatstatus_barrier(char*)¶

Clears the floating point status. A pointer to a local variable is passed in toprevent aggresive compiler optimizations from reodering this function call.Returns the previous status mask.

New in version 1.15.0.

nComplex functions~~~~~~~~~~~~~~~~~

C99-like complex functions have been added. Those can be used if you wish toimplement portable C extensions. Since we still support platforms without C99complex type, you need to restrict to C90-compatible syntax, e.g.:

/* a = 1 + 2i \*/npy_complexa=npy_cpack(1,2);npy_complexb;b=npy_log(a);

Linking against the core math library in an extension¶

To use the core math library in your own extension, you need to add the npymathcompile and link options to your extension in your setup.py:

>>>fromnumpy.distutils.misc_utilimportget_info>>>info=get_info('npymath')>>>config.add_extension('foo',sources=['foo.c'],extra_info=info)

In other words, the usage of info is exactly the same as when using blas_infoand co.

Half-precision functions¶

The header file <numpy/halffloat.h> provides functions to work withIEEE 754-2008 16-bit floating point values. While this format isnot typically used for numerical computations, it is useful forstoring values which require floating point but do not need much precision.It can also be used as an educational tool to understand the natureof floating point round-off error.

Like for other types, NumPy includes a typedef npy_half for the 16 bitfloat. Unlike for most of the other types, you cannot use this as anormal type in C, since it is a typedef for npy_uint16. For example,1.0 looks like 0x3c00 to C, and if you do an equality comparisonbetween the different signed zeros, you will get -0.0 != 0.0(0x8000 != 0x0000), which is incorrect.

For these reasons, NumPy provides an API to work with npy_half valuesaccessible by including <numpy/halffloat.h> and linking to ‘npymath’.For functions that are not provided directly, such as the arithmeticoperations, the preferred method is to convert to floator double and back again, as in the following example.

npy_halfsum(intn,npy_half*array){floatret=0;while(n--){ret+=npy_half_to_float(*array++);}returnnpy_float_to_half(ret);}

External Links:

• 754-2008 IEEE Standard for Floating-Point Arithmetic
• Half-precision Float Wikipedia Article.
• OpenGL Half Float Pixel Support
• The OpenEXR image format.

NPY_HALF_ZERO¶

This macro is defined to positive zero.

NPY_HALF_PZERO¶

This macro is defined to positive zero.

NPY_HALF_NZERO¶

This macro is defined to negative zero.

NPY_HALF_ONE¶

This macro is defined to 1.0.

NPY_HALF_NEGONE¶

This macro is defined to -1.0.

NPY_HALF_PINF¶

This macro is defined to +inf.

NPY_HALF_NINF¶

This macro is defined to -inf.

NPY_HALF_NAN¶

This macro is defined to a NaN value, guaranteed to have its sign bit unset.

floatnpy_half_to_float(npy_half h)¶

Converts a half-precision float to a single-precision float.

doublenpy_half_to_double(npy_half h)¶

Converts a half-precision float to a double-precision float.

npy_halfnpy_float_to_half(float f)¶

Converts a single-precision float to a half-precision float. Thevalue is rounded to the nearest representable half, with ties goingto the nearest even. If the value is too small or too big, thesystem’s floating point underflow or overflow bit will be set.

npy_halfnpy_double_to_half(double d)¶

Converts a double-precision float to a half-precision float. Thevalue is rounded to the nearest representable half, with ties goingto the nearest even. If the value is too small or too big, thesystem’s floating point underflow or overflow bit will be set.

intnpy_half_eq(npy_half h1, npy_half h2)¶

Compares two half-precision floats (h1 == h2).

intnpy_half_ne(npy_half h1, npy_half h2)¶

Compares two half-precision floats (h1 != h2).

intnpy_half_le(npy_half h1, npy_half h2)¶

Compares two half-precision floats (h1 <= h2).

intnpy_half_lt(npy_half h1, npy_half h2)¶

Compares two half-precision floats (h1 < h2).

intnpy_half_ge(npy_half h1, npy_half h2)¶

Compares two half-precision floats (h1 >= h2).

intnpy_half_gt(npy_half h1, npy_half h2)¶

Compares two half-precision floats (h1 > h2).

intnpy_half_eq_nonan(npy_half h1, npy_half h2)¶

Compares two half-precision floats that are known to not be NaN (h1 == h2). Ifa value is NaN, the result is undefined.

intnpy_half_lt_nonan(npy_half h1, npy_half h2)¶

Compares two half-precision floats that are known to not be NaN (h1 < h2). Ifa value is NaN, the result is undefined.

intnpy_half_le_nonan(npy_half h1, npy_half h2)¶

Compares two half-precision floats that are known to not be NaN (h1 <= h2). Ifa value is NaN, the result is undefined.

intnpy_half_iszero(npy_half h)¶

Tests whether the half-precision float has a value equal to zero. This may be slightlyfaster than calling npy_half_eq(h, NPY_ZERO).

intnpy_half_isnan(npy_half h)¶

Tests whether the half-precision float is a NaN.

intnpy_half_isinf(npy_half h)¶

Tests whether the half-precision float is plus or minus Inf.

intnpy_half_isfinite(npy_half h)¶

Tests whether the half-precision float is finite (not NaN or Inf).

intnpy_half_signbit(npy_half h)¶

Returns 1 is h is negative, 0 otherwise.

npy_halfnpy_half_copysign(npy_half x, npy_half y)¶

Returns the value of x with the sign bit copied from y. Works for any value,including Inf and NaN.

npy_halfnpy_half_spacing(npy_half h)¶

This is the same for half-precision float as npy_spacing and npy_spacingfdescribed in the low-level floating point section.

npy_halfnpy_half_nextafter(npy_half x, npy_half y)¶

This is the same for half-precision float as npy_nextafter and npy_nextafterfdescribed in the low-level floating point section.

npy_uint16npy_floatbits_to_halfbits(npy_uint32 f)¶

Low-level function which converts a 32-bit single-precision float, storedas a uint32, into a 16-bit half-precision float.

npy_uint16npy_doublebits_to_halfbits(npy_uint64 d)¶

Low-level function which converts a 64-bit double-precision float, storedas a uint64, into a 16-bit half-precision float.

npy_uint32npy_halfbits_to_floatbits(npy_uint16 h)¶

Low-level function which converts a 16-bit half-precision floatinto a 32-bit single-precision float, stored as a uint32.

npy_uint64npy_halfbits_to_doublebits(npy_uint16 h)¶

Low-level function which converts a 16-bit half-precision floatinto a 64-bit double-precision float, stored as a uint64.