Factory Functions

Factory functions provide a single entry point for configuring search policies, extrapolation modes, and side selection. They map concise symbols to concrete types, making the API more discoverable and ND configurations more ergonomic.

Zero Performance Cost

All factories are resolved at construction time. They return the same concrete singleton types used internally — zero allocation, zero overhead on hot paths.

Overview

Factory	Keyword	Options	Purpose
`Search`	`search=`	`:auto`, `:binary`, `:linear`, `:linear_binary`	Interval lookup strategy
`Extrap`	`extrap=`	`:none`, `:constant`, `:extend`, `:wrap`	Out-of-domain behavior
`Side`	`side=`	`:nearest`, `:left`, `:right`	Constant interpolation side

Each factory also supports a passthrough method — if you pass an already-constructed type, it's returned unchanged:

Search(:binary)        # → BinarySearch()
Search(BinarySearch())  # → BinarySearch()  (passthrough)

This is useful in generic code where inputs may be either symbols or pre-constructed types.

Search

Controls how interpolants find the correct grid interval for a query point.

Search(:auto)            # AutoSearch() — adapts per query type (default, recommended)
Search(:binary)          # BinarySearch() — O(log n), stateless
Search(:linear_binary)   # LinearBinarySearch{8}() — linear walk with binary fallback
Search(:linear)          # LinearSearch() — expert only, no fallback (see warning below)

# LinearBinarySearch supports a keyword argument
Search(:linear_binary; linear_window=4)   # LinearBinarySearch{4}()

Most users don't need to call `Search()` at all

The default AutoSearch() handles random, sorted, and streaming patterns automatically. For sequential/ODE patterns, just pass hint=Ref(1) — no need to set a search policy.

`:linear` is for experts only

LinearSearch() has no binary fallback — it degrades to O(n) for non-monotonic or distant queries. Use :linear_binary (or just the default :auto) instead. See Search Policies for details.

Keywords are only for `:linear_binary`

Passing keywords to other policies raises an ArgumentError:

Search(:binary; linear_window=8)  # ERROR: ArgumentError

See Search & Hints for detailed policy descriptions and benchmarks.

Extrap

Controls behavior when query points fall outside the data domain.

Extrap(:none)      # NoExtrap() — throw DomainError (default)
Extrap(:constant)  # ConstExtrap() — clamp to boundary values
Extrap(:extend)    # ExtendExtrap() — extend boundary polynomial
Extrap(:wrap)      # WrapExtrap() — periodic coordinate wrapping

See Extrapolation for visual comparisons and detailed behavior.

Side

Controls which neighbor value to use at non-grid-point locations in constant interpolation.

Side(:nearest)  # NearestSide() — nearest neighbor, left tie-break (default)
Side(:left)     # LeftSide() — always use left (floor) value
Side(:right)    # RightSide() — use right (ceiling) value

ND Multi-Arg Form

For N-dimensional interpolation, pass multiple symbols to create a per-axis tuple in a single call. This follows the same pattern as DerivOp(1, 0):

# Instead of writing:
extrap = (ExtendExtrap(), ConstExtrap(), NoExtrap())

# Write:
extrap = Extrap(:extend, :constant, :none)

# Both produce the same Tuple{ExtendExtrap, ConstExtrap, NoExtrap}

All three factories support this:

# 3D example — different policy per axis
itp = cubic_interp((x, y, z), data;
    search = Search(:binary, :linear_binary, :auto),
    extrap = Extrap(:extend, :constant, :none))

# 2D constant interpolation
itp = constant_interp((x, y), data;
    side = Side(:left, :nearest))

Mix & Match

If one axis needs a keyword argument (e.g., custom linear_window), use the tuple form with single-arg factories:

search = (Search(:binary), Search(:linear_binary; linear_window=4))

Two-Tier API

Factories are a convenience layer — direct type constructors remain fully supported:

Level	Style	When to Use
High-level	`Search(:binary)`, `Extrap(:extend)`	Daily usage, discoverability
Low-level	`BinarySearch()`, `ExtendExtrap()`	Library internals, extensions, maximum control

Both levels produce identical results and have identical performance.

Error Messages

Invalid symbols produce helpful ArgumentError messages listing all valid options:

julia> Search(:bianry)
ERROR: ArgumentError: unknown search policy :bianry; valid options are :auto, :binary, :linear, :linear_binary

julia> Extrap(:const)
ERROR: ArgumentError: unknown extrapolation mode :const; valid options are :none, :constant, :extend, :wrap

API Reference

FastInterpolations.Search — Function

Search(policy::Symbol; kwargs...)
Search(s1::Symbol, s2::Symbol, rest::Symbol...)
Search(policy::AbstractSearchPolicy)

Create a search policy for interval lookup.

Returns a concrete AbstractSearchPolicy subtype. The multi-arg form creates a Tuple for ND per-axis configuration (same pattern as DerivOp(1, 0)).

Options

:auto → AutoSearch: adaptive (default) — scalar→binary, vector→linear-binary
:binary → BinarySearch: O(log n), stateless, thread-safe
:linear → LinearSearch: O(1) amortized walk (requires monotonic queries)
:linear_binary → LinearBinarySearch: bounded linear walk with binary fallback

Keywords (single-arg :linear_binary only)

linear_window::Integer=8: maximum linear walk steps before binary fallback. Must be 0 or a power of 2 from (1, 2, 4, 8, 16, 32, 64, 128).

Examples

# 1D
itp = cubic_interp(x, y; search=Search(:binary))
itp = cubic_interp(x, y; search=Search(:linear_binary; linear_window=4))

# ND per-axis (multi-arg form)
itp = cubic_interp((x, y, z), data; search=Search(:binary, :linear_binary, :binary))

# Passthrough — accepts both symbols and policies
Search(:binary)         # → BinarySearch()
Search(BinarySearch())  # → BinarySearch()

source

FastInterpolations.Extrap — Function

Extrap(mode::Symbol)
Extrap(s1::Symbol, s2::Symbol, rest::Symbol...)
Extrap(mode::AbstractExtrap)

Create an extrapolation mode for out-of-domain queries.

Returns a concrete AbstractExtrap subtype. The multi-arg form creates a Tuple for ND per-axis configuration (same pattern as DerivOp(1, 0)).

Options

:none → NoExtrap: throw DomainError for out-of-domain queries
:constant → ConstExtrap: clamp to nearest boundary value
:extend → ExtendExtrap: extend interpolation polynomial beyond domain
:wrap → WrapExtrap: wrap queries into domain (periodic)

Examples

# 1D
itp = cubic_interp(x, y; extrap=Extrap(:extend))

# ND per-axis (multi-arg form)
itp = cubic_interp((x, y, z), data; extrap=Extrap(:extend, :none, :wrap))

# Passthrough
Extrap(:none)        # → NoExtrap()
Extrap(NoExtrap())   # → NoExtrap()

source

FastInterpolations.Side — Function

Side(mode::Symbol)
Side(s1::Symbol, s2::Symbol, rest::Symbol...)
Side(mode::AbstractSide)

Create a side selection mode for constant interpolation.

Returns a concrete AbstractSide subtype. The multi-arg form creates a Tuple for ND per-axis configuration (same pattern as DerivOp(1, 0)).

Options

:nearest → NearestSide: nearest neighbor with left tie-breaking at midpoint
:left → LeftSide: always use left (floor) value
:right → RightSide: use right (ceiling) value, except at grid points

Examples

# 1D
itp = constant_interp(x, y; side=Side(:left))

# ND per-axis (multi-arg form)
itp = constant_interp((x, y), data; side=Side(:left, :nearest))

# Passthrough
Side(:nearest)        # → NearestSide()
Side(NearestSide())   # → NearestSide()

source