Add predefined datatypes for bfloat16 data #5402

jhendersonHDF · 2025-03-21T23:05:29Z

Adds predefined datatypes for little- and big-endian bfloat16 data

Does not add support for any native bfloat16 types; datatype conversions are performed in software

Also adds missing float16 predefined types to fortran

jhendersonHDF · 2025-03-21T23:06:00Z

Essentially finished, pending CI results and some potential testing on a big-endian system

jhendersonHDF · 2025-03-21T23:06:41Z

doxygen/dox/DDLBNF200.dox

            H5T_IEEE_F32BE     | H5T_IEEE_F32LE     |
            H5T_IEEE_F64BE     | H5T_IEEE_F64LE     |
-            H5T_NATIVE_FLOAT16 | H5T_NATIVE_FLOAT   | 
+            H5T_FLT_BF16BE     | H5T_FLT_BF16LE     |


Open to any alternative names that seem more fitting, but this type is distinct from the IEEE standard, so I basically created a new category for alternative floating-point formats.

Perhaps "FLOAT" instead of "FLT"?

Seems reasonable to me

Agree - I like "FLOAT" better also

Actually, maybe "NONSTD", since it's a contrast to the "IEEE" label?

So... H5T_NONSTD_BF16 or H5T_NONSTD_BFLOAT16? I like "FLOAT" explicitly.

The issue I see with that is that it's not unlikely that these types get adopted into some standard in the future, whether it's IEEE or not.

jhendersonHDF · 2025-03-21T23:09:41Z

src/H5Tnative.c

+            if (NULL == (bf16_be_dt = H5I_object(H5T_FLT_BF16BE)))
+                HGOTO_ERROR(H5E_ARGS, H5E_BADTYPE, NULL, "not a data type");
+
+            /* Promote bfloat16 to float instead of float16, as it


bfloat16 types should be promoted to float instead of float16, as the type is the same size as float16, but a different format. Converting between bfloat16 and float is also very simple (by design).

jhendersonHDF · 2025-03-21T23:12:11Z

tools/lib/h5tools_type.c

-            if (size == 2)
-                p_type = H5Tcopy(H5T_IEEE_F16LE);
+            if (size == 2) {
+                if (true == H5Tequal(tid, H5T_IEEE_F16LE) || true == H5Tequal(tid, H5T_IEEE_F16BE))


Had to make sure the correct type between float16 and bfloat16 is picked so that the data comes out correctly.

jhendersonHDF · 2025-03-21T23:14:12Z

tools/test/h5dump/h5dumpgentest.c

+    hsize_t dims[2], adims[1];
+
+    /*
+     * bfloat16 keeps approximately the same range as the IEEE 32-bit


Eventually better tests can be written, but for now this PR just adds support for predefined types and doesn't add support for a native type. GCC and Clang both have support for a __bf16 type at this point though, so it should be doable in the future.

qkoziol · 2025-03-22T02:12:57Z

I'll try to review tomorrow and get you some feedback

epourmal · 2025-03-24T17:18:58Z

It was my undesrtanding that middle part "_IEEE_" or similar represents architecture or a standard. Should we follow the same rule here?

…

On Mon, Mar 24, 2025 at 12:11 PM Quincey Koziol ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In doxygen/dox/DDLBNF200.dox <#5402 (comment)>: > H5T_IEEE_F32BE | H5T_IEEE_F32LE | H5T_IEEE_F64BE | H5T_IEEE_F64LE | - H5T_NATIVE_FLOAT16 | H5T_NATIVE_FLOAT | + H5T_FLT_BF16BE | H5T_FLT_BF16LE | Agree - I like "FLOAT" better also — Reply to this email directly, view it on GitHub <#5402 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ADLFT3POWBKSASYVAQ4VSTD2WA4CRAVCNFSM6AAAAABZRCFMH2VHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZDOMJRGEZTANZUHA> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

qkoziol · 2025-03-24T17:20:58Z

It was my undesrtanding that middle part "IEEE" or similar represents architecture or a standard. Should we follow the same rule here?
…
On Mon, Mar 24, 2025 at 12:11 PM Quincey Koziol @.> wrote: @.* commented on this pull request. ------------------------------ In doxygen/dox/DDLBNF200.dox <#5402 (comment)>: > H5T_IEEE_F32BE | H5T_IEEE_F32LE | H5T_IEEE_F64BE | H5T_IEEE_F64LE | - H5T_NATIVE_FLOAT16 | H5T_NATIVE_FLOAT | + H5T_FLT_BF16BE | H5T_FLT_BF16LE | Agree - I like "FLOAT" better also — Reply to this email directly, view it on GitHub <#5402 (comment)>, or unsubscribe https://github.com/notifications/unsubscribe-auth/ADLFT3POWBKSASYVAQ4VSTD2WA4CRAVCNFSM6AAAAABZRCFMH2VHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZDOMJRGEZTANZUHA . You are receiving this because you are subscribed to this thread.Message ID: @.***>

Right - that was why I thought "NONSTD" might be better

qkoziol · 2025-03-24T17:38:23Z

Maybe "NONSTD_BFLOAT16" ?

jhendersonHDF · 2025-03-24T17:40:07Z

It was my undesrtanding that middle part "IEEE" or similar represents architecture or a standard. Should we follow the same rule here?

I'm not sure that this is necessarily the case and I'd argue we should consider abandoning that. For example, H5T_STD_B32BE doesn't really mean anything, because AFAIK there's really no standard type for this. C23 does appear to introduce those, but we don't target C23 yet.

jhendersonHDF · 2025-03-24T17:42:02Z

Maybe "NONSTD_BFLOAT16" ?

That name is a bit weird to me because bfloat16 is the standard. There's no other standard for the type, it's just that the standard isn't an IEEE standard.

jhendersonHDF · 2025-03-24T17:43:54Z

Also consider I plan to add support for FP8, FP6 and FP4 following this PR, and in each case the formats essentially are the standard until they have wider adoption. https://arxiv.org/abs/2209.05433 for example.

qkoziol · 2025-03-24T17:44:15Z

Since Google created it, maybe "GOOGLE_BFLOAT16" ?

ajelenak · 2025-03-24T17:45:35Z

I was thinking the same...

epourmal · 2025-03-24T17:53:09Z

Also consider I plan to add support for FP8, FP6 and FP4 following this PR, and in each case the formats essentially are the standard until they have wider adoption. https://arxiv.org/abs/2209.05433 for example.

Frankly speaking, I would drop middle part for these types and document their implementation. I would vote against introducing GOOGLE.

jhendersonHDF · 2025-03-24T17:55:41Z

Since Google created it, maybe "GOOGLE_BFLOAT16" ?

Perhaps. The reason I used BF16 on the end part was just to match our existing conventions like H5T_IEEE_F32LE, especially because there will be types like F8E4M3 (FP8 with 4 exponent bits and 3 mantissa bits). That said, I also like FLOAT being spelled out explicitly, but I still think it's much more natural to just use H5T_FLOAT_ so that we don't tie the names to any particular standard, architecture or company unless it makes sense to. I see this as "one datatype of class H5T_FLOAT is called H5T_FLOAT_BF16". I'd definitely like to avoid the STD vs. NONSTD naming if possible, because I'm fairly certain these types will be adopted into some standard in the future.

ajelenak · 2025-03-24T18:26:34Z

I was ok with H5T_FLOAT_BF16 to begin with but enjoy discussing alternative naming options.

jhendersonHDF · 2025-03-25T18:44:41Z

For the time being, I'm going to proceed on the other datatypes using H5T_FLOAT_ names until we come to a resolution.

I propose that we use a convention of H5T_<TYPE_CLASS>_<OPTIONAL(?)_ARCH_OR_STANDARD>_<SPECIFICS> going forward and welcome any feedback if others think differently. This leads to names like H5T_FLOAT_INTEL_F32, H5T_FLOAT_IEEE_F32LE, H5T_INTEGER_I32BE, etc. The question mark on optional is because I'm thinking it might be worth it to always mention a standard or architecture to be consistent, leading to, for example, H5T_INTEGER_C_I32BE for int32_t. Note that this is already the convention I used for predefined complex datatypes (H5T_COMPLEX_IEEE_F32LE, for example). I believe this form does a better job of actually distinguishing what a particular datatype is. For example, H5T_IEEE_F32LE tells you that the datatype comes from or relates to an IEEE standard, but you rely on the "F32" part to tell you that it's a floating-point type. If additional non-floating-point types are added to IEEE standards, this may get confusing. For example, if we wanted to add support for the decimal floating-point types, I imagine we'd currently use something like H5T_IEEE_D32LE (maybe H5T_IEEE_DF32LE). However, that "D" would be somewhat in conflict with the current H5T_UNIX_D32LE and related types, where "D" apparently represents time data. If an IEEE standard included time types (for whatever reason), this would just complicate things more. A different letter than "D" could of course be picked to represent decimal floating-point datatypes, but I feel adding the type class gives context to anything in the "specifics" part of the name and helps deal with any conflict between lettering. It may also be worth revisiting what exactly should be in the "specifics" part of the name.

epourmal · 2025-03-25T20:03:30Z

Makes sense, but I would leave old types as they are and use new standard only for the new types.

jhendersonHDF · 2025-03-25T20:43:57Z

Makes sense, but I would leave old types as they are and use new standard only for the new types.

I certainly wouldn't want to go changing old type names as it would be nothing but a source of annoyance (though we can always introduce new macros that just point to the old names if we wanted).

Copilot

Pull Request Overview

This PR adds support for predefined datatypes for bfloat16 data (both little- and big-endian) and includes missing float16 predefined types for Fortran. Key changes include updates to native type retrieval in src/H5Tnative.c, new datatype definitions in Java JNI and C++ bindings, and corresponding updates in documentation and tests.

Reviewed Changes

Copilot reviewed 48 out of 48 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/H5Tnative.c	Updated H5T__get_native_float signature and incorporated bfloat16 support logic.
src/H5Tmodule.h & src/H5T.c	Defined new macros and initialized new datatype IDs for bfloat16.
java/src/jni/h5util.c	Added conditional branches for bfloat16 in datatype resolution.
java/src/jni/h5Constants.c, HDF5Constants.java	Added JNI constant definitions for the new bfloat16 datatypes.
hl/, fortran/, doxygen/, c++/src/	Updated tests, parsers, documentation, and language bindings to reflect the new datatypes.

java/src/jni/h5util.c

Adds predefined datatypes for little- and big-endian bfloat16 data Does not add support for any native bfloat16 types; datatype conversions are performed in software

jhendersonHDF commented Mar 21, 2025

View reviewed changes

nbagha1 removed Component - High-Level Library labels Apr 2, 2025

brtnfld removed the Type - New Feature label May 12, 2025

nbagha1 added this to HDF5 - TRIAGE & TRACK May 24, 2025

github-project-automation bot moved this to To be triaged in HDF5 - TRIAGE & TRACK May 24, 2025

nbagha1 moved this from To be triaged to In progress in HDF5 - TRIAGE & TRACK May 24, 2025

nbagha1 added this to the Release 2.0.0 milestone May 27, 2025

jhendersonHDF force-pushed the feature/bfloat16_predefined branch 2 times, most recently from adc8a52 to 8563514 Compare June 1, 2025 23:52

jhendersonHDF marked this pull request as ready for review June 2, 2025 00:23

jhendersonHDF requested review from byrnHDF, derobins, brtnfld, epourmal, lrknox, fortnern, vchoi-hdfgroup, bmribler, glennsong09 and mattjala as code owners June 2, 2025 00:23

gheber requested a review from Copilot June 11, 2025 22:28

Copilot AI reviewed Jun 11, 2025

View reviewed changes

java/src/jni/h5util.c Outdated Show resolved Hide resolved

java/src/jni/h5util.c Outdated Show resolved Hide resolved

jhendersonHDF force-pushed the feature/bfloat16_predefined branch 2 times, most recently from da4a32c to 408c6bc Compare June 16, 2025 20:42

brtnfld requested a review from qkoziol June 19, 2025 18:09

jhendersonHDF force-pushed the feature/bfloat16_predefined branch from 408c6bc to 10d9991 Compare June 19, 2025 18:55

Add predefined datatypes for bfloat16 data

d4bbe19

Adds predefined datatypes for little- and big-endian bfloat16 data Does not add support for any native bfloat16 types; datatype conversions are performed in software

jhendersonHDF force-pushed the feature/bfloat16_predefined branch from 10d9991 to d4bbe19 Compare June 19, 2025 19:31

Uh oh!

Add predefined datatypes for bfloat16 data #5402

Are you sure you want to change the base?

Add predefined datatypes for bfloat16 data #5402

Uh oh!

Conversation

jhendersonHDF commented Mar 21, 2025

Uh oh!

jhendersonHDF commented Mar 21, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

qkoziol commented Mar 22, 2025

Uh oh!

epourmal commented Mar 24, 2025 via email

Uh oh!

qkoziol commented Mar 24, 2025

Uh oh!

qkoziol commented Mar 24, 2025

Uh oh!

jhendersonHDF commented Mar 24, 2025

Uh oh!

jhendersonHDF commented Mar 24, 2025

Uh oh!

jhendersonHDF commented Mar 24, 2025

Uh oh!

qkoziol commented Mar 24, 2025

Uh oh!

ajelenak commented Mar 24, 2025

Uh oh!

epourmal commented Mar 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jhendersonHDF commented Mar 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ajelenak commented Mar 24, 2025

Uh oh!

jhendersonHDF commented Mar 25, 2025

Uh oh!

epourmal commented Mar 25, 2025

Uh oh!

jhendersonHDF commented Mar 25, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

epourmal commented Mar 24, 2025 •

edited

Loading

jhendersonHDF commented Mar 24, 2025 •

edited

Loading