Current situation
float16, npy_half, is currently handled through a set of helper functions
located in numpy/halffloat.h and implemented in npymath. This requires
linking against the libnpymath.a, a static library. Linking against a
static library is problematic as a static library built with one compiler
often cannot be linked with an application built with a different compiler.
See #20880 <https://github.com/numpy/numpy/issues/20880>.
Goal
Expose halffloat.h functionality through the regular NumPy C-API as NpyHalf*,
without requiring the linking of npymath explicitly as a step toward
removing the npymath static library altogether.
Proposed ImplementationSummary
- I propose to add a new NumPy C-API file in the multiarray C extension
directory as NpyHalf*, with the primary design objective to eliminate
the need for an explicit link to libnpymath.a.
Implementation Specifics
-
All functionality currently available in include/halffloat.h will be
duplicated into multiarray/*.h, which will be the primary entrance point
of the API. Whether the include/halffloat.h functionality will be
duplicated in its own file, or incorporated into an existing header, is
still an open question.
-
The naming convention will be NpyHalf* for all API functions. See
appendix A for an explicit list of functions currently contained in
include/halffloat.h.
-
Functionality will be identical to include/halffloat.h.but the interface
will be inline with the existing C-API patterns and may not be a one to one
copy of the interface present in include/halffloat.h.
-
All API functions will be added to code_generators/numpy_api.py beginning
at location 369, and counting up. Versioning will be MinVersion("2.4").
With code_generators/cversions.txt updated with new hashing information.
-
The contents of npymath relevant to ensuring proper working of NpyHalf* will
be ported and contained in the multiarray directory.
-
If I identify any shared functions used in include/halffloat.h that may
assist in the removal of npymath static library altogether I'll contain
the functions in a suitable header file.
Error Handling and Semantics
-
Error handling will follow the normal NumPy conventions.
-
Current semantics, behavior of code that use include/halffloat.h will
remain unchanged and continue to produce identical results.
Documentation
-
New C-API documentation will be added as needed.
-
Documentation requiring include/halffloat.h and npymath will be updated
with language that the new NpyHalf* functions are preferred. With
additional language to require accessing import_array() for access to
NpyHalf* API functionality.
Testing and Benchmarking
-
A review of current tests seems to indicate a lack of float16 specific
tests. I will develop and add tests to cover NpyHalf* functions.
-
Benchmarking will be completed so as not to unduly decrease performance.
NumPy Internals Update
- There are several internal self contained NumPy functions that point
to include/halffloat.h and npymath. For the sake of completeness I will
update and refactor these functions to the new API.
Conclusion and Community Feedback
- I'm planning to begin work on adding a new NumPy C-API file in the
multiarray C extension directory as NpyHalf* soon.
- I have posted this as issue #30280
<https://github.com/numpy/numpy/issues/30280>, in addition to this
email. Any feedback is, as always, much appreciated.
Appendix A - List of Functions in include/halffloat.h
/* include/halffloat.h */
float npy_half_to_float(npy_half h);double npy_half_to_double(npy_half
h);npy_half npy_float_to_half(float f);npy_half
npy_double_to_half(double d);�/* Comparisons */int
npy_half_eq(npy_half h1, npy_half h2);int npy_half_ne(npy_half h1,
npy_half h2);int npy_half_le(npy_half h1, npy_half h2);int
npy_half_lt(npy_half h1, npy_half h2);int npy_half_ge(npy_half h1,
npy_half h2);int npy_half_gt(npy_half h1, npy_half h2);/* faster
*_nonan variants for when you know h1 and h2 are not NaN */int
npy_half_eq_nonan(npy_half h1, npy_half h2);int
npy_half_lt_nonan(npy_half h1, npy_half h2);int
npy_half_le_nonan(npy_half h1, npy_half h2);�/* Miscellaneous
functions */int npy_half_iszero(npy_half h);int
npy_half_isnan(npy_half h);int npy_half_isinf(npy_half h);int
npy_half_isfinite(npy_half h);int npy_half_signbit(npy_half
h);npy_half npy_half_copysign(npy_half x, npy_half y);npy_half
npy_half_spacing(npy_half h);npy_half npy_half_nextafter(npy_half x,
npy_half y);npy_half npy_half_divmod(npy_half x, npy_half y, npy_half
*modulus);
/* Bit-level conversions */npy_uint16
npy_floatbits_to_halfbits(npy_uint32 f);npy_uint16
npy_doublebits_to_halfbits(npy_uint64 d);npy_uint32
npy_halfbits_to_floatbits(npy_uint16 h);npy_uint64
npy_halfbits_to_doublebits(npy_uint16 h);
--
Amelia Thurdekoos
Staff Software Engineer, Quansight
Quansight | Your Data Experts
w: www.quansight.org <http://quansight.org/>
e: [email protected]
<https://www.linkedin.com/company/quansight/>
<https://www.instagram.com/quansightai/>
<https://bsky.app/profile/quansight.com> <https://twitter.com/quansightai>
_______________________________________________
NumPy-Discussion mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/numpy-discussion.python.org
Member address: [email protected]
