Skip to content

Commit

Permalink
Merge pull request #22538 from rgommers/getinfo-npymath
Browse files Browse the repository at this point in the history 
DOC: update libnpymath docs on its status and how to consume it
  • Loading branch information
@mattip
mattip committed Nov 6, 2022
2 parents 2081f29 + ec37b2b commit fcafb65
Show file tree
Hide file tree
Showing 2 changed files with 66 additions and 37 deletions.
98 changes: 63 additions & 35 deletions doc/source/reference/c-api/coremath.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,6 @@ NumPy core libraries

.. sectionauthor:: David Cournapeau

.. versionadded:: 1.3.0

Starting from numpy 1.3.0, we are working on separating the pure C,
"computational" code from the python dependent code. The goal is twofolds:
making the code cleaner, and enabling code reuse by other extensions outside
Expand All @@ -16,10 +14,19 @@ NumPy core math library
The numpy core math library ('npymath') is a first step in this direction. This
library contains most math-related C99 functionality, which can be used on
platforms where C99 is not well supported. The core math functions have the
same API as the C99 ones, except for the npy_* prefix.
same API as the C99 ones, except for the ``npy_*`` prefix.

The available functions are defined in ``<numpy/npy_math.h>`` - please refer to
this header when in doubt.

.. note::

The available functions are defined in <numpy/npy_math.h> - please refer to this header when
in doubt.
An effort is underway to make ``npymath`` smaller (since C99 compatibility
of compilers has improved over time) and more easily vendorable or usable as
a header-only dependency. That will avoid problems with shipping a static
library built with a compiler which may not match the compiler used by a
downstream package or end user. See
`gh-20880 <https://github.com/numpy/numpy/issues/20880>`__ for details.

Floating point classification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down Expand Up @@ -75,8 +82,6 @@ Floating point classification
as y. Works for any value, including inf and nan. Single and extended
precisions are available with suffix f and l.

.. versionadded:: 1.4.0

Useful math constants
~~~~~~~~~~~~~~~~~~~~~

Expand Down Expand Up @@ -140,41 +145,29 @@ Those can be useful for precise floating point comparison.
floating point value from x in the direction of y. Single and extended
precisions are available with suffix f and l.
.. versionadded:: 1.4.0
.. c:function:: double npy_spacing(double x)
This is a function equivalent to Fortran intrinsic. Return distance between
x and next representable floating point value from x, e.g. spacing(1) ==
eps. spacing of nan and +/- inf return nan. Single and extended precisions
are available with suffix f and l.
.. versionadded:: 1.4.0
.. c:function:: void npy_set_floatstatus_divbyzero()
Set the divide by zero floating point exception
.. versionadded:: 1.6.0
.. c:function:: void npy_set_floatstatus_overflow()
Set the overflow floating point exception
.. versionadded:: 1.6.0
.. c:function:: void npy_set_floatstatus_underflow()
Set the underflow floating point exception
.. versionadded:: 1.6.0
.. c:function:: void npy_set_floatstatus_invalid()
Set the invalid floating point exception
.. versionadded:: 1.6.0
.. c:function:: int npy_get_floatstatus()
Get floating point status. Returns a bitmask with following possible flags:
Expand All @@ -188,8 +181,6 @@ Those can be useful for precise floating point comparison.
aggressive compiler optimizations reordering the call relative to
the code setting the status, which could lead to incorrect results.
.. versionadded:: 1.9.0
.. c:function:: int npy_get_floatstatus_barrier(char*)
Get floating point status. A pointer to a local variable is passed in to
Expand All @@ -214,8 +205,6 @@ Those can be useful for precise floating point comparison.
prevents aggressive compiler optimizations reordering the call relative to
the code setting the status, which could lead to incorrect results.
.. versionadded:: 1.9.0
.. c:function:: int npy_clear_floatstatus_barrier(char*)
Clears the floating point status. A pointer to a local variable is passed in to
Expand All @@ -227,11 +216,10 @@ Those can be useful for precise floating point comparison.
Complex functions
~~~~~~~~~~~~~~~~~
.. versionadded:: 1.4.0
C99-like complex functions have been added. Those can be used if you wish to
implement portable C extensions. Since we still support platforms without C99
complex type, you need to restrict to C90-compatible syntax, e.g.:
complex type (most importantly Windows, where MSVC doesn't support C99 complex
types as of Nov 2022), you need to restrict to C90-compatible syntax, e.g.:
.. code-block:: c
Expand All @@ -241,13 +229,31 @@ complex type, you need to restrict to C90-compatible syntax, e.g.:
b = npy_log(a);
.. _linking-npymath:

Linking against the core math library in an extension
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 1.4.0
To use the core math library that NumPy ships as a static library in your own
Python extension, you need to add the npymath compile and link options to your
extension. The exact steps to take will depend on the build system you are using.
The generic steps to take are:

1. Add the numpy include directory (= the value of ``np.get_include()``) to
your include directories,
2. The ``npymath`` static library resides in the ``lib`` directory right next
to numpy's include directory (i.e., ``pathlib.Path(np.get_include()) / '..'
/ 'lib'``). Add that to your library search directories,
3. Link with ``libnpymath`` and ``libm``.

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

Keep in mind that when you are cross compiling, you must use the ``numpy``
for the platform you are building for, not the native one for the build
machine. Otherwise you pick up a static library built for the wrong
architecture.

When you build with ``numpy.distutils`` (deprecated), then use this in your ``setup.py``:

.. hidden in a comment so as to be included in refguide but not rendered documentation
>>> import numpy.distutils.misc_util
Expand All @@ -258,15 +264,37 @@ compile and link options to your extension in your setup.py:
>>> 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_info
and co.
In other words, the usage of ``info`` is exactly the same as when using
``blas_info`` and co.

When you are building with `Meson <https://mesonbuild.com>`__, use::

# Note that this will get easier in the future, when Meson has
# support for numpy built in; most of this can then be replaced
# by `dependency('numpy')`.
incdir_numpy = run_command(py3,
[
'-c',
'import os; os.chdir(".."); import numpy; print(numpy.get_include())'
],
check: true
).stdout().strip()

inc_np = include_directories(incdir_numpy)

cc = meson.get_compiler('c')
npymath_path = incdir_numpy / '..' / 'lib'
npymath_lib = cc.find_library('npymath', dirs: npymath_path)

py3.extension_module('module_name',
...
include_directories: inc_np,
dependencies: [npymath_lib],

Half-precision functions
~~~~~~~~~~~~~~~~~~~~~~~~

.. versionadded:: 1.6.0

The header file <numpy/halffloat.h> provides functions to work with
The header file ``<numpy/halffloat.h>`` provides functions to work with
IEEE 754-2008 16-bit floating point values. While this format is
not typically used for numerical computations, it is useful for
storing values which require floating point but do not need much precision.
Expand All @@ -281,7 +309,7 @@ between 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 values
accessible by including <numpy/halffloat.h> and linking to 'npymath'.
accessible by including ``<numpy/halffloat.h>`` and linking to ``npymath``.
For functions that are not provided directly, such as the arithmetic
operations, the preferred method is to convert to float
or double and back again, as in the following example.
Expand Down
5 changes: 3 additions & 2 deletions doc/source/reference/random/c-api.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,9 @@ C API for random
Access to various distributions below is available via Cython or C-wrapper
libraries like CFFI. All the functions accept a :c:type:`bitgen_t` as their
first argument. To access these from Cython or C, you must link with the
``npyrandom`` library which is part of the NumPy distribution, located in
``numpy/random/lib``.
``npyrandom`` static library which is part of the NumPy distribution, located
in ``numpy/random/lib``. Note that you must *also* link with ``npymath``,
see :ref:`linking-npymath`.


.. c:type:: bitgen_t
Expand Down

0 comments on commit fcafb65

Please sign in to comment.