Type Promotion Rules

FastInterpolations.jl uses a unified, two-tier promotion strategy throughout its construction and evaluation paths:

1. Promotable scalars (_PromotableValue): standard Julia numeric types where Julia's convert and promote_type are always well-defined. These are promoted automatically.
2. Duck types: custom value types (e.g., SVector, ForwardDiff.Dual, Measurement) where no general conversion to a grid float type exists. These are preserved as-is.

The distinction is encoded in a single union:

const _PromotableValue = Union{Integer, AbstractFloat, Rational, Complex}

Every promotion decision in the codebase checks T <: _PromotableValue at compile time (inside @inline functions), so the check is zero-cost — dead branches are eliminated by the compiler.

Grid Type Promotion

Function: _promote_grid_float(::Type{Tg}, ::Type{Tv}) -> Type{<:AbstractFloat}

The grid type Tg is always an AbstractFloat. Its precision is determined by the wider of the raw grid element type and the value type, but only when the value type is promotable.

_PromotableValue  →  float(promote_type(Tg_raw, real_eltype(Tv)))   # widen to wider precision
duck type         →  float(Tg_raw)                                   # grid precision only

Examples:

Rationale: when both grid and values are standard numerics, computing in the narrower type would silently lose precision. Widening to float(promote_type(...)) makes the precision loss visible and avoids per-element conversion overhead in hot evaluation paths.

Value Type (Tv) Determination

Function: _value_type(::Type{Tv_raw}, ::Type{Tg}) -> Type

After Tg is determined, Tv is resolved via three dispatch methods (listed most-to-least specific):

# Method 1 — Complex (most specific, dispatches before the _PromotableValue fallback)
_value_type(::Type{Complex{T}}, ::Type{Tg}) where {T<:Real, Tg<:AbstractFloat} = Complex{Tg}

# Method 2 — All other _PromotableValue (Integer, AbstractFloat, Rational)
_value_type(::Type{T}, ::Type{Tg}) where {T<:_PromotableValue, Tg<:AbstractFloat} = Tg

# Method 3 — Duck types (SVector, Dual, Measurement, ...)
_value_type(::Type{T}, ::Type{Tg}) where {T, Tg<:AbstractFloat} = T

Dispatch priority: why Complex is handled separately

Complex <: _PromotableValue, so without the dedicated method, Complex{Float32} would dispatch to Method 2 and return bare Tg (e.g., Float64) — stripping the Complex wrapper. Method 1 is more specific and dispatches first, returning Complex{Tg} to preserve the complex structure while adapting only the float precision.

Summary of rules

Examples

Fill Value Promotion (FillExtrap)

Type: FillExtrap{T} <: AbstractExtrap Functions: _promote_extrap, _promote_extraps_nd

Why FillExtrap is parametric

FillExtrap{T} stores fill_value::T. The {T} parameter is required for eval-path type stability: _constant_extrap_result returns e.fill_value directly, and the compiler must know its type at compile time to avoid heap allocation. Without {T}, fill_value::Any would cause boxing on every out-of-domain query.

Outer constructors

FillExtrap(v::Real)                      # → FillExtrap{typeof(float(v))}(float(v))
FillExtrap(v::Complex{T<:AbstractFloat}) # → FillExtrap{Complex{T}}(v)
FillExtrap(v)                            # → FillExtrap{typeof(v)}(v)  [auto-gen, duck types]

The Real constructor converts via float() immediately, so FillExtrap(0) and FillExtrap(1//3) both produce FillExtrap{Float64} — FillExtrap{Integer} or FillExtrap{Rational} are not reachable through the public API.

Promotion at interpolant construction

When an interpolant is built with known Tv, fill values are promoted to match using the same _PromotableValue pattern:

# _PromotableValue: auto-convert (always safe, convert is well-defined)
_promote_extrap(e::FillExtrap{<:_PromotableValue}, ::Type{Tv}) =
    FillExtrap{Tv}(convert(Tv, e.fill_value))

# Duck types: pass through unchanged (user is responsible for correct type)
_promote_extrap(e::FillExtrap, ::Type) = e

# All other AbstractExtrap (ClampExtrap, NoExtrap, etc.): pass through
_promote_extrap(e::AbstractExtrap, ::Type) = e

ND fill value constraint

In ND interpolation, all axes that use FillExtrap must share the same fill value — the OOB short-circuit returns a single scalar result regardless of which axis triggered it. This is validated at _resolve_extrap_nd time (before promotion) via _validate_fill_values_nd.

Two-Phase Extrap Setup (ND)

ND interpolant construction separates extrap handling into two ordered phases:

Phase 1: _resolve_extrap_nd(extrap, bcs, Val(N))
          - Shape normalization: scalar → ntuple, tuple length check
          - Periodic BC compatibility check
          - Fill value consistency validation (===, on original values)
          → NTuple{N, AbstractExtrap}

Phase 2: _promote_extraps_nd(extrap_vals, Tv)
          - Per-axis _promote_extrap call (unrolled via @generated)
          → NTuple{N, AbstractExtrap} with fill values matching Tv

Summary Table

Related Source Files