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).

fortnern · 2025-03-25T21:14:24Z

I don't think the C standard specifies the exact integer format, or even that it's two's complement, so we shouldn't name types "C". I'm not sure there's a better name for "normal" integer types than STD, but I might be wrong. Adding new names for consistency is fine, and something like H5T_INTEGER_U32LE is probably fine, though H5T_INTEGER_I32LE seems redundant. Maybe _S32LE or just _32LE?

jhendersonHDF · 2025-03-25T21:25:58Z

or even that it's two's complement

Note that this is the case in C23 at least.

so we shouldn't name types "C"

I tend to agree, it's just that STD doesn't really particularly mean anything.

though H5T_INTEGER_I32LE seems redundant.

Agree. Also why I mentioned we may want to revisit what should go in the "specifics" part of the name if we use the convention. FLOAT_XXX_F32LE is just as redundant, so maybe the single letter on the end of these isn't needed and we should consider something else?

brtnfld · 2025-04-02T17:58:10Z

Jordan, is this a summary of what you are proposing:


H5T_<TYPE_CLASS>_<OPTIONAL_QUALIFIER>_<SPECIFICS>

    H5T_<TYPE_CLASS>: This explicitly states the data type (e.g., FLOAT, INTEGER, COMPLEX).
    _<OPTIONAL_QUALIFIER>: This qualifier provides additional context, such as:
        Architecture: (e.g., INTEL)
        Specific Organization: (e.g. GOOGLE)
        Standard: (e.g. IEEE)
        This section can be omitted if the datatype is very common or there is no specific qualifier.
    _<SPECIFICS>: This details the specific format (e.g., BF16, F32LE, I32BE, F8E4M3).

jhendersonHDF · 2025-04-02T18:07:59Z

Jordan, is this a summary of what you are proposing:

H5T_<TYPE_CLASS><OPTIONAL_QUALIFIER>

H5T_<TYPE_CLASS>: This explicitly states the data type (e.g., FLOAT, INTEGER, COMPLEX).
_<OPTIONAL_QUALIFIER>: This qualifier provides additional context, such as:
    Architecture: (e.g., INTEL)
    Specific Organization: (e.g. GOOGLE)
    Standard: (e.g. IEEE)
    This section can be omitted if the datatype is very common or there is no specific qualifier.
_<SPECIFICS>: This details the specific format (e.g., BF16, F32LE, I32BE, F8E4M3).

Yes, this looks like a good summary. Thanks!

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

byrnHDF assigned jhendersonHDF Apr 1, 2025

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 from a8d7eeb to e93ad7f Compare June 1, 2025 23:50

Add predefined datatypes for bfloat16 data

8563514

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 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

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!

fortnern commented Mar 25, 2025

Uh oh!

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

Uh oh!

Uh oh!

brtnfld commented Apr 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

jhendersonHDF commented Apr 2, 2025

Uh oh!

Uh oh!

epourmal commented Mar 24, 2025 •

edited

Loading

jhendersonHDF commented Mar 24, 2025 •

edited

Loading

jhendersonHDF commented Mar 25, 2025 •

edited

Loading

brtnfld commented Apr 2, 2025 •

edited

Loading