Conversion

cvt(::Type{T}, x, mode::RoundingMode, policy::OverflowPolicy) -> T

Central conversion funnel. Every scalar conversion into a Microfloat — constructors, convert, broadcasts, and the packed vector paths — reduces to a call of this function, with the rounding mode and overflow policy as positional, dispatchable arguments.

cvt is the extension surface for optimized conversions. To specialize, add a method on any subset of (T, typeof(x), mode, policy):

• Bit-twiddling / table specializations add ordinary methods, e.g. Microfloats.cvt(::Type{Float8_E4M3}, x::Float4_E2M1FN, ::RoundingMode, ::OverflowPolicy). See @cvt_table for a generated lookup-table shortcut.
• Device backends (package extensions) use overlay method tables (e.g. CUDACore.@device_override) on exactly the (T, source, mode, policy) signatures the hardware supports natively; every other combination falls through to the portable methods below.

The always-correct reference path is cvt_generic; specialized methods that need a partial fallback should call it (not cvt, which on overlay method tables would recurse into the override itself).

cvt(::Type{F}, x::Microfloat) -> F

Widening half of the conversion funnel: every conversion out of a Microfloat into Float16, BFloat16, Float32 or Float64 reduces to a call of this method, the same way conversions into a Microfloat reduce to the four-argument form.

Every Microfloat is exactly representable in BFloat16 (at most 7 significand bits and 8 exponent bits), and so in Float32 and Float64: widening never rounds, which is why this form takes no rounding mode or overflow policy. Float16 has a narrower exponent range than some formats (Float8_E8M0FNU); it receives the exact Float32 value rounded by Float16(::Float32).

@microfloat registers a method per type that computes it with a branch-free bit-twiddle over the destination's bits where one is cheap (see max_twiddle_cost), and with the generic lookup otherwise; Float64 extends the Float32 result. Like the narrowing form this is the extension surface for device backends, which override it for the destinations their hardware widens to natively.

cvt(::Type{SVector{N,T}}, xs::NTuple{N,Any}, mode, policy) -> SVector{N,T}
cvt(::Type{NVector{T,N}}, xs::NTuple{N,Any}, mode, policy) -> NVector{T,N}

Vector forms of the conversion funnel: convert N source lanes in one call, into one byte per lane (SVector) or densely packed (BitPacking.NVector). The SVector default is lanewise (cvt_lanes); the NVector default converts through the SVector form and packs. Packing is layout only and folds away, so specialize the SVector form for multi-lane hardware conversions (e.g. PTX cvt x2 instructions in device overlays): that serves both destinations. Specialize the NVector form only for conversions that work on dense storage directly, such as bit-twiddling over packed sources.

Source containers (SVector, NVector, any StaticArray vector) normalize to NTuple first; packed→packed specializations may intercept the NVector-source signature before it is unpacked.

cvt(::Type{SVector{N,F}}, xs::NTuple{N,T}) -> SVector{N,F}

Vector form of the widening funnel: N lanes of microfloat T to N wide lanes (F is Float16, BFloat16, Float32 or Float64). Packed (NVector) and unpacked (SVector) sources normalize to a tuple of lanes; the default is lanewise through the scalar widening funnel. Specialize it for multi-lane hardware conversions, e.g. PTX cvt.rn.bf16x2.e4m3x2 in device overlays. Packing and unpacking a source is layout only and folds away, so a specialization on the tuple form serves every source container.

cvt_generic(::Type{T}, x::Float32, mode::RoundingMode, policy::OverflowPolicy) -> T

The generic reference implementation behind cvt: bit-level rounding from Float32 into any Microfloat layout, for every supported rounding mode and overflow policy. Specialized cvt methods (and device overrides) call this directly when their fast path does not apply.

cvt_twiddle(::Type{T}, x::Float32, mode::RoundingMode, policy::OverflowPolicy) -> T

Branch-free narrowing from Float32, the default cvt method for Float32 sources (and so for every source that converts to Float32 first). Results, and errors, are identical to cvt_generic, which it calls for modes it does not cover.

Target normals round the Float32 bits directly: an integer add rounds the significand at the target's last significand bit, carrying into the exponent, and a subtraction rebiases. Target subnormals round |x| scaled to units of the smallest subnormal, which the FPU does exactly. Everything else is a select, so the only branches are the error checks, which the compiler removes for formats that cannot fail (e.g. signed formats with NaN).

cvt_lanes(::Type{SVector{N,T}}, xs::NTuple{N,Any}, mode, policy) -> SVector{N,T}
cvt_lanes(::Type{NVector{T,N}}, xs::NTuple{N,Any}, mode, policy) -> NVector{T,N}

Reference lanewise implementation of the vector conversion funnel: converts each lane through the scalar cvt funnel (so per-lane specializations and device overrides still apply), then builds the vector. Vectorized cvt specializations call this when their fast path does not cover the requested combination.

WideFloat

The floating-point destinations of the widening funnel: Float16, BFloat16, Float32 and Float64.

@cvt_table Src => Dst

Register an optimized method on the conversion funnel cvt for converting microfloat Src values to microfloat Dst.

Expands to a @generated method of Microfloats.cvt. Once per (mode, policy) combination actually used, it runs every Src bit pattern through cvt_generic and compiles the resulting table into the cheapest equivalent code, so results are identical to the generic path:

• a branch-free bit-twiddle when the table is piecewise linear in a few pieces, as for exact widenings like Float4_E2M1FN => Float8_E4M3FN (each piece is a shift and an add, selected by comparing the source bits);
• otherwise a single 2^bitwidth(Src)-entry table lookup.

Which counts as "a few" is max_twiddle_cost, which device backends lower.

Combinations where the generic path throws (e.g. signed source into unsigned target) keep the runtime path and its errors.

Invoke after both types are defined. Microfloats registers methods for all pairs of built-in types; user-defined @microfloat types can opt in:

@microfloat MyFloat6 exponent=3 significand=2
Microfloats.@cvt_table MyFloat6 => Float8_E4M3
Microfloats.@cvt_table Float8_E4M3 => MyFloat6

To hand-optimize a pair instead, define the Microfloats.cvt method for it directly rather than invoking @cvt_table for that pair.

max_twiddle_cost() -> Int

Largest cost of a bit-twiddle that generated conversion methods (see @cvt_table) prefer over a table lookup: its pieces, plus one if it moves a sign bit. Each piece is a shift, an add, a compare and a select. On CPUs the twiddle vectorizes where a lookup is a gather, and wins by a wide margin up to about twice this many pieces. Device backends override it: on GPUs a load from a small constant table hits the read-only cache and beats all but the shortest twiddles.