Skip to content

feat(python): add bfloat16 and bfloat16_array support#3329

Open
asadjan4611 wants to merge 10 commits intoapache:mainfrom
asadjan4611:feat/python-bfloat16-support
Open

feat(python): add bfloat16 and bfloat16_array support#3329
asadjan4611 wants to merge 10 commits intoapache:mainfrom
asadjan4611:feat/python-bfloat16-support

Conversation

@asadjan4611
Copy link

@asadjan4611 asadjan4611 commented Feb 12, 2026

Why?

This PR implements bfloat16 (Brain Float 16) and bfloat16_array support for Fory Python runtime and codegen, addressing issue #3289. This enables using bfloat16 in FDL to reduce payload size while keeping a wide exponent range, which is common in ML/AI workflows.

What does this PR do?

This PR adds comprehensive bfloat16 support to Fory Python:

Core Implementation

  • BFloat16 Type: Cython implementation with IEEE 754 compliant float32↔bfloat16 conversions (round-to-nearest, ties-to-even)
  • BFloat16Array: Python-visible array type backed by array.array('H') for packed contiguous storage
  • Serializers: Both scalar (BFloat16Serializer) and array (BFloat16ArraySerializer) serializers
  • Type Registration: Registered with TypeId.BFLOAT16 (18) and TypeId.BFLOAT16_ARRAY (54)

Integration Points

  • Buffer Operations: Added write_bfloat16() and read_bfloat16() methods
  • Codegen Support: Added bfloat16 to codegen type mapping
  • Row Format: Added bfloat16() factory function (temporarily maps to float16 until C++ row format supports it)
  • Type System: Fully integrated into Fory type resolver

Testing

  • 11 comprehensive test cases covering:
    • Basic operations and conversions
    • Special values (NaN, ±Inf, ±0)
    • Serialization round-trips
    • Array operations
    • Integration with dataclasses, lists, and maps
    • Type registration verification

Code Quality

  • Follows existing float16 implementation patterns
  • Matches project code standards and style
  • All files include proper Apache 2.0 license headers
  • No linter errors

Related issues

Does this PR introduce any user-facing change?

  • Does this PR introduce any public API change?
    • Yes: Adds BFloat16, BFloat16Array types and bfloat16() factory function
  • Does this PR introduce any binary protocol compatibility change?
    • No: Uses existing TypeId.BFLOAT16 (18) already defined in protocol spec

Implementation Details

Wire Format

  • Encodes bfloat16 as 2 bytes representing raw IEEE 754 bfloat16 bit pattern
  • Little endian byte order (matches existing float32/float64 behavior)
  • NaN/Inf/±0/subnormal values round-trip correctly at bit level

Type System

  • Type ID: 18 (BFLOAT16) - already defined in xlang serialization spec
  • Array Type ID: 54 (BFLOAT16_ARRAY)
  • Protocol compliant with existing xlang serialization format

Performance

  • Uses Cython for performance-critical conversion operations
  • Zero-copy array operations using array.array('H')
  • Follows same optimization patterns as existing float16 implementation

@asadjan4611
feat(python): add bfloat16 and bfloat16_array support
8c7d5c3 
- Add BFloat16 Cython type with IEEE 754 compliant conversions
- Add BFloat16Array class backed by array.array('H')
- Implement serializers for scalar and array types
- Register types in type resolver (TypeId.BFLOAT16 = 18, TypeId.BFLOAT16_ARRAY = 54)
- Add buffer read/write methods for bfloat16
- Add codegen support for bfloat16
- Add row format support (with temporary float16 mapping until C++ support)
- Add comprehensive test suite with 11 test cases covering all edge cases
- Follow existing float16 implementation patterns

Fixes apache#3289
@asadjan4611
style(python): fix code formatting for bfloat16 implementation
c89d86e 
- Change single quotes to double quotes (ruff format requirement)
- Remove trailing whitespace
- Add blank lines after imports (PEP 8)
- Remove unused import (pyfory)
- Fix closing parenthesis alignment
@asadjan4611
fix(python): remove trailing newline in bfloat16_array.py to match co…
b2bb7c6 
…de style
@asadjan4611
fix(python): resolve Cython compilation errors for bfloat16
6537f74 
- Remove invalid Cython type casts (<BFloat16>) in serialization.pyx and primitive.pxi
- Use isinstance() check instead of type casting for Python classes
- Fix bfloat16() function to use float16() as temporary workaround until C++ support is added
- Comment out bfloat16() declaration in libformat.pxd with TODO for future C++ implementation
@asadjan4611
fix(python): use memcpy for safe type punning in bfloat16 conversion
b6793a5 
Replace unsafe pointer casts with memcpy to ensure cross-platform
compatibility across all OS versions (Windows, Linux, macOS) and
architectures (x86_64, ARM). This fixes strict aliasing violations
that cause compilation failures on ARM and newer compilers.
@asadjan4611
fix(python): use explicit size constant for ARM compatibility
e387339 
Replace sizeof(float) with explicit constant 4 in memcpy calls to ensure
cross-platform compatibility, especially on ARM architectures where
sizeof() may cause compilation issues. This matches the project's
pattern of using explicit size constants (as seen in types.py).

Fixes build failures on:
- ubuntu-24.04-arm (aarch64)
- macos-arm64 (Apple Silicon)
- ubuntu-24.04-arm with Python 3.13
@asadjan4611
fix(python): correct row schema Arrow conversion type ids
71241ba
@asadjan4611
fix(python): build and export bfloat16 python module
8066ace
@asadjan4611
docs(python): document bfloat16 support and stabilize pure mode seria…
8ed6f57 
…lizers
@asadjan4611
fix(python): configure bazel shell for windows editable builds
9fcb74d
@asadjan4611
Copy link
Author

asadjan4611 commented Feb 13, 2026

@chaokunyang please review my PR and this is very interesting Project and i learn a lot of things from this issue .

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@chaokunyang chaokunyang Awaiting requested review from chaokunyang chaokunyang is a code owner

At least 1 approving review is required to merge this pull request.

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Python] add bfloat16 and bfloat16_array (Cython, no numpy)

1 participant

@asadjan4611