MonotonicSplines

High-performance monotonic splines in Julia.

struct InvRQSpline{T<:Real,N,...} <: Function

Represents the inverse of RQSpline.

InvRQSpline holds the same spline knot parameters as the corresponding RQSpline.

Users should not instantiate InvRQSpline directly, use InverseFunctions.inverse(RQSpline(...)) instead.

struct RQSpline{T<:Real,N,...} <: Function

Represents a rational quadratic spline function or a set of such functions for multiple dimensions and samples.

Implements the splines originally proposed by Gregory and Delbourgo (https://doi.org/10.1093/imanum/2.2.123)

Constructors:

RQSpline(pX::AbstractVector{<:Real}, pY::AbstractVector{<:Real}, dYdX::AbstractVector{<:Real})
RQSpline(pX::AbstractArray{<:Real,3}, pY::AbstractArray{<:Real,3}, dYdX::AbstractArray{<:Real,3})

Fields:

• pX: An array that holds the x-position of the spline knots.

• pY: An array that holds the y-position of the spline knots.

• dYdX: An array that holds the derivative at the spline knots.

pX, pY and dYdX may be

• vectors of length K+1, representing a one-dimensional spline with K segments, or

• three-dimensional arrays of the shape K+1 x n_dims x n_samples, representing a set of splines for different dimensions and input samples.

Requirements for the fields:

Each spline is continued with the identity function beyond its first and last knot. So to ensure the continuity and differentiability of the splines, the first and last knots must lie on the diagonal through 0, and the derivatives at these knots must be 1. Formally: For parameter vectors pX[1] == pY[1] and pX[end] == pY[end] and dYdX[1] == dYdX[end] == 1 must hold. For 3 dimensional parameter arrays pX[1,:,:] == pY[1,:,:] and pX[end,:,:] == pY[end,:,:] and dYdX[1,:,:] .== dYdX[end,:,:] .== 1 must be true.

RQSpline supports the InverseFunctions, ChangesOfVariables, and Functors APIs.

Example:

using MonotonicSplines

f = RQSpline(posX, posX, dY_dX)
Y = f(X)

using InverseFunctions: inverse
X ≈ inverse(f)(Y)

using ChangesOfVariables: with_logabsdet_jacobian
Y, LADJ = with_logabsdet_jacobian(f, X)

When instantiated as a set of multi-dimension/samples splines, RQSpline uses the package KernelAbstractions for parallel CPU or GPU processing. Custom ChainRulesCore rules are provided for effecient automatic differentation.

Random spline generation is supported and RQSpline comes with specialized support for Plots:

using MonotonicSplines, Plots, InverseFunctions
f = rand(RQSpline)
plot(f); plot!(inverse(f))
plot(f, xlims = (-6, 6)); plot!(inverse(f), xlims = (-6, 6))

MonotonicSplines.estimate_dYdX(pX::AbstractVector{<:Real}, pY::AbstractVector{<:Real})

Get estimates for derivatives at the given knot points pX, pY.

The resulting derivatives can be used directly, but are also useful as initial values, when optimizing spline derivative parameters based on application-specific criteria.

Uses a linear estimate for the first and last knot and a 2nd order polynomial estimate over three knots for the other knots.

Example:

dYdX = MonotonicSplines.estimate_dYdX(pX, pY)
f = RQSpline(pX, pY, dYdX)

When an RQSpline is intended to be used beyong the first and last knot, the first and last derivative should be one, so in that case use

f = RQSpline(pX, pY, vcat(1, dYdX[begin+1:end-1], 1))

MonotonicSplines.rqs_forward(x::Real, pX::AbstractVector{<:Real}, pY::AbstractVector{<:Real}, dYdX::AbstractVector{<:Real})
MonotonicSplines.rqs_forward(X::AbstractArray{<:Real,2}, pX::AbstractArray{<:Real,3}, pY::AbstractArray{<:Real,3}, dYdX::AbstractArray{<:Real,3})

Apply the rational quadratic spline function(s) defined by the parameters pX (pX), pY (pY), and dYdX (dYdX), to the input(s) X.

See RQSpline for more details.

MonotonicSplines.rqs_inverse(x::Real, pX::AbstractVector{<:Real}, pY::AbstractVector{<:Real}, dYdX::AbstractVector{<:Real})
MonotonicSplines.rqs_inverse(X::AbstractArray{<:Real,2}, pX::AbstractArray{<:Real,3}, pY::AbstractArray{<:Real,3}, dYdX::AbstractArray{<:Real,3})

Apply the inverse of the rational quadratic spline function(s) defined by the parameters pX (pX), pY (pY), and dYdX (dYdX), to the input(s) X.

See InvRQSpline for more details.

MonotonicSplines.rqs_params_from_nn(θ_raw::AbstractArray, n_dims_trafo::Integer, B::Real = 5.)

Process the raw output parameters of a neural network to generate parameters for a set of rational quadratic spline functions.

Arguments

• θ_raw: A matrix where each column represents the raw parameters for a sample.
• n_dims_trafo: The number of spline functions for which parameters are to be produced.
• B: Sets the rage of the splines.

Returns

• A tuple pX, pY, dYdX containing the positions of and derivatives at the spline knots. The parameters are stored in a K+1 x n_spline_functions_per_sample x n_samples array.