Axes

AbstractAnalyticAxis{T} <: AbstractVector{T}

An axis whose coordinate is a formula of its index, and whose formula inverts in closed form.

The third axis kind. An AbstractUniformAxis carries a constant spacing in its type; a plain Vector has nothing but its samples. A stretched vertical coordinate is neither: the spacing genuinely varies, so it is not uniform, but the samples are n evaluations of two or three parameters, and storing them stores a formula's output.

A subtype implements three methods:

• Base.length(a)
• coordinate(a, ξ) — the coordinate at continuous index ξ, agreeing with a[i] at every integer i
• index_at(a, x) — its inverse, the continuous index whose coordinate is x

and gets indexing, the O(1) endpoint reductions, and — through the inverse — locate, nearest_index and the interpolation weights without a search. Locating a coordinate on a stretched Vector bisects in O(log n); here the inverse names the cell directly and one comparison against the neighbouring face settles the rounding.

The coordinate must be strictly monotone in ξ, which makes the inverse single-valued. A constructor checks it once. Where index_at cannot answer — a coordinate outside the formula's domain, which a far-extrapolated face can be — it returns a non-finite value and the caller falls back to the search, reaching the same answer.

AbstractUniformAxis{T} <: AbstractRange{T}

Supertype for axes whose spacing is constant and known from their type. Default: UniformAxis.

To add one, implement the three methods AbstractRange already requires — Base.first, Base.step and Base.length — and everything else here follows: indexing, the O(1) reductions, slicing, reversal, and the affine arithmetic. None of the generic methods touch a field, so a subtype may store whatever it likes under whatever names.

Implement similar_axis as well to have derived axes keep the subtype; the fallback returns a plain UniformAxis.

ConstantVector(value, n)

n copies of value, stored as that value and a length. A uniform axis's per-cell width is one.

A genuine AbstractVector: indexing, iteration, broadcasting and collect behave as for fill(value, n). getindex folds to a constant and every reduction below is closed-form.

GeometricAxis(origin, Δ, ratio, n)
GeometricAxis{T}(origin, Δ, ratio, n)

n samples whose successive gaps are Δ, Δ·r, Δ·r², … — the stretched grid a boundary layer or a model's vertical levels are built on — held as four numbers.

x(ξ) = origin + Δ·(r^(ξ-1) − 1)/(r − 1)

so x(1) = origin and x(i+1) − x(i) = Δ·r^(i-1). The inverse is a logarithm, so locating a coordinate is O(1).

r > 0 and r ≠ 1. At r == 1 the gaps are constant, which is a UniformAxis; that type carries the spacing where this one hides it in a parameter.

See UniformSpacing.

PowerAxis(origin, extent, exponent, n)
PowerAxis{T}(origin, extent, exponent, n)

n samples spanning origin to origin + extent with the index mapped through a power:

x(ξ) = origin + extent·((ξ-1)/(n-1))^p

p == 1 is uniform, p > 1 clusters samples near origin, and p < 1 clusters them near the far end — the shape ocean depth levels and a stretched radial coordinate are usually given. The inverse is a root, so locating a coordinate on it is O(1).

n ≥ 2, p > 0, and a nonzero extent.

UniformAxis(origin, Δ, n)
UniformAxis{T}(origin, Δ, n)

n samples at origin + (i-1)·Δ, stored as those three numbers.

Preferred over range/StepRangeLen for a grid axis:

• range(0f0; step = 0.1f0, length = n) is a StepRangeLen{Float32, Float64, Float64, Int} — Float32 elements over a Float64 offset and step. UniformAxis{T} computes in T throughout.
• StepRangeLen indexes through TwicePrecision arithmetic, buying an exactness a grid axis does not need; UniformAxis indexes with one multiply and one add.
• isbits, so moving an axis to another storage backend is free.

Δ may be negative, for a descending axis. n must be non-negative.

Unlike LinRange this does not pin last to a prescribed endpoint: on a grid the spacing is the primary datum.

An AbstractRange: that gets Base's searchsorted in closed form, so a lookup is O(1) in the axis length, and isa AbstractRange dispatch from other packages.

UniformSpacing()
NonuniformSpacing()

Whether an axis's spacing is known from its type. spacing_trait returns one of these, so a method can dispatch on it.

coordinate(a, ξ) -> T

The coordinate of AbstractAnalyticAxis a at continuous index ξ, equal to a[i] at every integer index. A half-integer ξ is the midpoint in index space; this package's faces are midpoints in coordinate space, so the two coincide only on a uniform axis. What is extended here is the formula.

index_at(a, x) -> T

The continuous index at which AbstractAnalyticAxis a has coordinate x: the inverse of coordinate, and the reason a query on such an axis needs no search.

Returns a non-finite value where x lies outside the formula's domain, which callers take as "no closed-form answer" and fall back to bisection.

isuniform(x) -> Bool

Whether x has UniformSpacing. Const-folds, so it is free to branch on in a hot loop.

similar_axis(a, origin, Δ, n) -> AbstractUniformAxis

The axis of a's own kind with the given origin, spacing and length: the hook every derived axis goes through — a slice, a reversal, 2a, a .+ c.

Defaults to a UniformAxis, so a subtype that does not define it still gets correct results, just not its own type back.

spacing(x) -> Number

The constant spacing of a uniform axis, read from its type. Signed, so a descending axis reports a negative spacing. Raises for an axis that is not isuniform.

spacing_trait(x) -> UniformSpacing() | NonuniformSpacing()

The axis's spacing trait. UniformAxis and any AbstractRange carry a constant step in their type; every other array is nonuniform.

The question is answered by the type: a Vector holding an arithmetic sequence is NonuniformSpacing(). No code path here inspects values to decide it.

uniform_axis(x) -> UniformAxis
uniform_axis(T, x) -> UniformAxis{T}

The UniformAxis equal to x, for any axis whose spacing is known from its type. A nonuniform vector raises, because it has no uniform form: replacing its coordinates with a fitted sequence is a decision only its owner can make, and they can build the axis directly.

wrap_sign(x) -> ±1

+1 for an ascending axis and -1 for a descending one: the sign that turns a period magnitude into the wrapped neighbour's offset in index order. A descending axis is routine in stored data, and its wrapped neighbour lies at x[1] - period, not x[1] + period.