Общедоступный API

# ChainRulesCore.rrule — Method

ChainRulesCore.rrule(itp::AbstractInterpolation, x...)

Метод rrule из пакета ChainRulesCore.jl для интеграции с библиотеками автоматического дифференцирования. Обратите внимание, что он возвращает только градиент относительно точки расчета x, но не данные внутри itp.

# Interpolations.bounds — Method

bounds(itp::AbstractInterpolation)

Возвращает границы bounds области itp в виде кортежа пар (min, max) для каждой координаты. Лучше всего это пояснить на примере:

julia> itp = interpolate([1 2 3; 4 5 6], BSpline(Linear()));

julia> bounds(itp)
((1, 2), (1, 3))

julia> data = 1:3;

julia> knots = ([10, 11, 13.5],);

julia> itp = interpolate(knots, data, Gridded(Linear()));

julia> bounds(itp)
((10.0, 13.5),)

# Interpolations.constant_interpolation — Function

etp = constant_interpolation(knots, A; extrapolation_bc=Throw())

Краткая форма записи для extrapolate(interpolate(knots, A, scheme), extrapolation_bc), где scheme — это либо BSpline(Constant()), либо Gridded(Constant()) в зависимости от того, является ли knots диапазонами или векторами.

При необходимости используйте interpolate или extrapolate явным образом вместо этого удобного конструктора. При отсутствии экстраполяции производительность повышается.

# Interpolations.cubic_spline_interpolation — Function

etp = cubic_spline_interpolation(knots, A; bc=Line(OnGrid()), extrapolation_bc=Throw())

Краткая форма записи для extrapolate(scale(interpolate(A, BSpline(Cubic(bc))),knots), extrapolation_bc).

При необходимости используйте interpolate, scale или extrapolate явным образом вместо этого удобного конструктора. При отсутствии масштабирования или экстраполяции производительность повышается.

# Interpolations.extrapolate — Method

extrapolate(itp, scheme) добавляет экстраполяцию к объекту интерполяции согласно указанной схеме.

Схема может иметь одно из следующих значений.

Throw — если индексы выходят за допустимые границы, выдается ошибка BoundsError;
Flat — константная экстраполяция по ближайшему значению в границах допустимого интервала;
Line — линейная экстраполяция (заключенный в оболочку объект интерполяции должен поддерживать градиент);
Reflect — экстраполяция с отражением (индексы должны поддерживать mod);
Periodic — периодическая экстраполяция (индексы должны поддерживать mod).

Схемы также можно объединять в кортежи. Например, схема (Line(), Flat()) использует линейную экстраполяцию по первому измерению и константную по второму.

Наконец, можно задать разные режимы экстраполяции в разных направлениях. При Line(),Flat(, Flat()) экстраполяция по первому измерению будет линейной, если индекс слишком маленький, но константной, если он слишком большой, а по второму измерению всегда будет константной.

# Interpolations.extrapolate — Method

extrapolate(itp, fillvalue) создает объект экстраполяции, который возвращает fillvalue, когда индексы в itp(x1,x2,...) выходят за допустимые границы.

# Interpolations.interpolate! — Method

Версия interpolate, выполняемая на месте. Уничтожает входной массив A и может усекать область в конечных точках.

# Interpolations.interpolate — Method

itp = interpolate(A, interpmode, gridstyle, λ, k)

Интерполирует массив A в режиме, определяемом аргументами interpmode и gridstyle, с регуляризацией согласно [1] порядка k с константой λ. interpmode может иметь одно из следующих значений:

BSpline(NoInterp())
BSpline(Linear())
BSpline(Quadratic(BC())) (см. описание типа BoundaryCondition)
BSpline(Cubic(BC()))

Значением может быть также кортеж таких значений, если по каждой оси должна использоваться особая интерполяционная схема.

Аргумент gridstyle должен иметь одно из следующих значений: OnGrid() или OnCell().

k соответствует производной, на которую накладывается штраф. В пределе λ->∞ интерполяционная функция представляет собой многочлен порядка k-1. Значение 2 является наиболее общим.

Значение λ должно быть неотрицательным. Если оно равно нулю, происходит интерполяция без регуляризации.

[1] https://projecteuclid.org/euclid.ss/1038425655.

# Interpolations.interpolate — Method

itp = interpolate(A, interpmode)

Интерполирует массив A в режиме, определяемом аргументом interpmode. interpmode может иметь одно из следующих значений:

NoInterp()
BSpline(Constant())
BSpline(Linear())
BSpline(Quadratic(bc)) (см. описание типа BoundaryCondition)
BSpline(Cubic(bc))

# Interpolations.interpolate — Method

itp = interpolate((nodes1, nodes2, ...), A, interpmode)

Интерполирует массив A на неравномерной, но прямоугольной сетке, определяемой аргументом nodes, в режиме, определяемом аргументом interpmode.

interpmode может иметь одно из следующих значений:

NoInterp()
Gridded(Constant())
Gridded(Linear())

# Interpolations.knots — Method

knots(itp::AbstractInterpolation)
knots(etp::AbstractExtrapolation)

Возвращает итератор по позициям узлов для AbstractInterpolation или AbstractExtrapolation.

Итератор будет выдавать скалярные значения для интерполяций по одному измерению и кортежи координат для интерполяций более высокой размерности. Итерация по большему количеству измерений рассчитывается как произведение узлов по каждому измерению.

То есть Iterator.product(узлы по 1-му измерению, узлы по 2-му измерению, …)

Экстраполяции с граничными условиями Periodic или Reflect выдают бесконечные последовательности узлов.

Пример

julia> using Interpolations;

julia> etp = linear_interpolation([1.0, 1.2, 2.3, 3.0], rand(4); extrapolation_bc=Periodic());

julia> Iterators.take(knots(etp), 5) |> collect
5-element Vector{Float64}:
 1.0
 1.2
 2.3
 3.0
 3.2

# Interpolations.knotsbetween — Method

knotsbetween(iter; start, stop)
knotsbetween(iter, start, stop)

Выполняет итерацию по всем узлам iter, соответствующим условию start < k < stop.

Значением iter может быть объект AbstractInterpolation или результат выполнения метода knots (то есть объект KnotIterator или ProductIterator, являющийся оболочкой для KnotIterator).

Если аргумент start не указан, итерация начинается с первого узла. Если не указан ни аргумент start, ни аргумент stop, происходит ошибка ArgumentError.

Если таких узлов не существует, возвращается KnotIterator длиной 0.

Пример

julia> using Interpolations;

julia> etp = linear_interpolation([1.0, 1.2, 2.3, 3.0], rand(4); extrapolation_bc=Periodic());

julia> knotsbetween(etp; start=38, stop=42) |> collect
6-element Vector{Float64}:
 38.3
 39.0
 39.2
 40.3
 41.0
 41.2

# Interpolations.linear_interpolation — Function

etp = linear_interpolation(knots, A; extrapolation_bc=Throw())

Краткая форма записи для одного из следующих вызовов:

extrapolate(scale(interpolate(A, BSpline(Linear())), knots), extrapolation_bc)
extrapolate(interpolate(knots, A, Gridded(Linear())), extrapolation_bc),

в зависимости от того, содержит ли knots диапазоны или векторы.

# Interpolations.scale — Method

scale(itp, xs, ys, ...) масштабирует существующий объект интерполяции так, чтобы было возможным индексирование с использованием координатных осей, отличных от единичных диапазонов. Для этого объект интерполяции заключается в оболочку, а при индексировании индексы приводятся от предоставленных осей к единичным диапазонам.

Параметры xs и т. д. должны быть либо диапазонами, либо linspace, причем для каждого измерения в объекте интерполяции должен быть один диапазон координат или linspace.

Для каждого измерения NoInterp в объекте интерполяции диапазон должен быть в точности равен 1:size(itp, d).

# Interpolations.AkimaMonotonicInterpolation — Type

AkimaMonotonicInterpolation

Монотонная интерполяция методом, предложенным в работе Акимы (1970), A New Method of Interpolation and Smooth Curve Fitting Based on Local Procedures, doi: 10.1145/321607.321609.

Тангенсы определяются в окрестности каждой заданной точки, результаты близки к нарисованным вручную кривым

# Interpolations.BSpline — Type

BSpline(degree)

Флаг, означающий интерполяцию BSpline (B-сплайн на целочисленной сетке) по соответствующей оси. degree может иметь одно из следующих значений: Constant, Linear, Quadratic или Cubic.

# Interpolations.CardinalMonotonicInterpolation — Type

CardinalMonotonicInterpolation(tension)

Кубические фундаментальные сплайны с использованием параметра tension (натяжение), значение которого должно находиться в интервале [0,1]. Кубические фундаментальные сплайны могут давать выбросы для немонотонных данных (увеличение натяжения снижает выбросы).

# Interpolations.Constant — Type

Постоянные B-сплайны служат для интерполяции по алгоритму ближайшего соседа и фактически возвращают A[round(Int,x)] при интерполяции без масштабирования. Масштабирование может привести к неточному определению положения соседних элементов из-за ограниченной числовой точности.

Constant{Previous} выполняет интерполяцию к предыдущему значению, что эквивалентно A[floor(Int,x)] без масштабирования. Constant{Next} выполняет интерполяцию к следующему значению, что эквивалентно A[ceil(Int,x)] без масштабирования.

# Interpolations.Cubic — Type

Cubic(bc::BoundaryCondition)

Указывает, что для соответствующей оси должна использоваться кубическая интерполяция.

Расширенная справка

При условии равномерных узлов с интервалом 1 i-й фрагмент кубического сплайна, реализуемого таким способом, определяется следующим образом:

y_i(x) = cm p(x-i) + c q(x-i) + cp q(1- (x-i)) + cpp p(1 - (x-i))

где

p(δx) = 1/6 * (1-δx)^3
q(δx) = 2/3 - δx^2 + 1/2 δx^3

и значения cX для X ∈ {m, _, p, pp} являются предварительно отфильтрованными коэффициентами.

На будущее имейте в виду, что это выражение развертывается в следующий многочлен:

y_i(x) = 1/6 cm (1+i-x)^3 + c (2/3 - (x-i)^2 + 1/2 (x-i)^3) +
         cp (2/3 - (1+i-x)^2 + 1/2 (1+i-x)^3) + 1/6 cpp (x-i)^3

При выводе граничных условий используются производные y_0'(x) и y_0''(x)

# Interpolations.CubicHermite — Type

 CubicHermite

Этот тип намеренно не отражен в документации, так как его интерфейс должен кардинально измениться в будущем так, чтобы он согласовывался с интерфейсом AbstractInterpolation. Этот API следует считать крайне нестабильным и поэтому закрытым; в доработанном выпуске в его код могут быть внесены критические изменения.

# Interpolations.FiniteDifferenceMonotonicInterpolation — Type

FiniteDifferenceMonotonicInterpolation

Классическая кубическая интерполяция без параметра натяжения. Метод конечных разностей может давать выбросы для немонотонных данных.

# Interpolations.Flat — Type

Flat(gt) задает угловой коэффициент экстраполяции равным нулю.

# Interpolations.FritschButlandMonotonicInterpolation — Type

FritschButlandMonotonicInterpolation

Монотонная интерполяция методом, предложенным в работе Фритча (Fritsch) и Бутленда (Butland) (1984), A Method for Constructing Local Monotone Piecewise Cubic Interpolants, doi: 10.1137/0905021.

Выполняется быстрее, чем FritschCarlsonMonotonicInterpolation (требуется только один проход), но имеет несколько большее «натяжение».

# Interpolations.FritschCarlsonMonotonicInterpolation — Type

FritschCarlsonMonotonicInterpolation

Монотонная интерполяция методом, предложенным в работе Фритча (Fritsch) и Карлсона (Carlson) (1980), Monotone Piecewise Cubic Interpolation, doi: 10.1137/0717021.

Тангенсы сначала инициализируются, а затем корректируются, если не являются монотонными. Может давать выбросы для немонотонных данных.

# Interpolations.InPlace — Type

InPlace(gt) — это граничное условие, которое позволяет выполнять предварительную фильтрацию на месте (обычное требуется заполнение).

# Interpolations.InPlaceQ — Type

InPlaceQ(gt) аналогично InPlace(gt), но является точным, когда интерполируемые значения получаются из базового квадратичного уравнения. В первую очередь полезно для тестирования, так как обеспечивает почти точное (на уровне машинной точности) сравнение с истинным значением.

# Interpolations.Lanczos — Type

Lanczos{N}(a=4)

Повторная выборка методом Ланцоша с помощью ядра с масштабным параметром a и поддержкой N соседних элементов.

Такая форма интерполяции представляет собой попросту дискретную свертку выборок с помощью ядра Ланцоша размером a. Размер непосредственно влияет на то, насколько «отдаленная» информация учитывается при интерполяции, и связан со временем выполнения зависимостью O(N^2). Альтернативная реализация, соответствующая алгоритму lanczos4 из OpenCV, доступна в Lanczos4OpenCV.

# Interpolations.Lanczos4OpenCV — Type

Lanczos4OpenCV()

Альтернативная реализация повторной выборки методом Ланцоша с использованием алгоритма lanczos4 из OpenCV: https://github.com/opencv/opencv/blob/de15636724967faf62c2d1bce26f4335e4b359e5/modules/imgproc/src/resize.cpp#L917-L946

# Interpolations.Line — Type

Line(gt) использует постоянный угловой коэффициент для экстраполяции.

# Interpolations.Linear — Type

Linear()

Указывает, что для соответствующей оси должна использоваться линейная интерполяция.

Расширенная справка

При условии равномерных узлов с интервалом 1 i-й фрагмент линейного B-сплайна, реализуемого таким способом, определяется следующим образом:

y_i(x) = c p(x) + cp p(1-x)

где

p(δx) = x

и значения cX для X ∈ {_, p} являются коэффициентами.

Линейные B-сплайны интерполируются естественным образом и не требуют предварительной фильтрации, поэтому указывать граничные условия не требуется.

Хотя данный метод реализован немного иначе, чтобы можно было использовать общий фреймворк для B-сплайнов, итоговый интерполянт — это просто кусочно-линейная функция, соединяющая каждую пару соседних точек данных.

# Interpolations.LinearMonotonicInterpolation — Type

LinearMonotonicInterpolation

Простая линейная интерполяция.

# Interpolations.Nearest — Type

Параметр по умолчанию для Constant, выполняющий интерполяцию по алгоритму ближайшего соседа. Может также указываться в виде

Constant() === Constant{Nearest}()

# Interpolations.Next — Type

Параметр для Constant, выполняющий интерполяции по алгоритму следующего соседа. Применяется следующим образом.

Constant{Next}()

# Interpolations.NoInterp — Type

NoInterp() указывает, что для соответствующей оси должно использоваться целочисленное индексирование (интерполяция не производится).

# Interpolations.OnCell — Type

OnCell() указывает, что граничное условие применяется в половине шага сетки перед первым узлом и после последнего.

# Interpolations.OnGrid — Type

OnGrid() указывает, что граничное условие применяется в первом и последнем узлах.

# Interpolations.Periodic — Type

Periodic(gt) применяет периодические граничные условия.

# Interpolations.Previous — Type

Параметр для Constant, выполняющий интерполяции по алгоритму предыдущего соседа. Применяется следующим образом. ´´´ Constant{Previous}() ´´´

# Interpolations.Quadratic — Type

Quadratic(bc::BoundaryCondition)

Указывает, что для соответствующей оси должна использоваться квадратичная интерполяция.

Расширенная справка

При условии равномерных узлов с интервалом 1 i-й фрагмент квадратичного сплайна, реализуемого таким способом, определяется следующим образом:

y_i(x) = cm p(x-i) + c q(x) + cp p(1-(x-i))

где

p(δx) = (δx - 1)^2 / 2
q(δx) = 3/4 - δx^2

и значения cX для X ∈ {m,_,p} являются предварительно отфильтрованными коэффициентами.

На будущее имейте в виду, что это выражение развертывается в следующий многочлен:

y_i(x) = cm * 1/2 * (x-i-1)^2 + c * (3/4 - x + i)^2 + cp * 1/2 * (x-i)^2

При выводе граничных условий используются производные y_1'(x-1) и y_1''(x-1)

# Interpolations.Reflect — Type

Reflect(gt) применяет отражательные граничные условия.

# Interpolations.SteffenMonotonicInterpolation — Type

SteffenMonotonicInterpolation

Монотонная интерполяция методом, предложенным в работе Стеффена (Steffen) (1990), A Simple Method for Monotonic Interpolation in One Dimension, http://adsabs.harvard.edu/abs/1990A%26A…239..443S

Только один проход; результат обычно представляет собой нечто среднее между результатами методов FritschCarlson и FritschButland.

# Interpolations.Throw — Type

Throw(gt) вызывает ошибку при выходе интерполяции за границы.

Внутренний API

# Interpolations.boundstep — Function

Возвращает половину ширины одного шага диапазона.

Эта функция служит для вычисления верхней и нижней границ объектов интерполяции OnCell.

# Interpolations.count_interp_dims — Method

n = count_interp_dims(ITP)

Подсчитывает количество измерений, по которым интерполируется тип ITP. Измерения NoInterp не учитываются.

# Interpolations.deduplicate_knots! — Method

Interpolations.deduplicate_knots!(knots; move_knots = false)

Makes knots unique by incrementing repeated but otherwise sorted knots using `nextfloat`.
If keyword `move_knots` is true, then `nextfloat` will be applied successively until knots
are unique. Otherwise, a warning will be issued.

# Пример

```jldoctest
julia> knots = [-8.0, 0.0, 20.0, 20.0]
4-element Vector{Float64}:
-8.0
0.0
20.0
20.0

julia> Interpolations.deduplicate_knots!(knots)
4-element Vector{Float64}:
-8.0
0.0
20.0
20.000000000000004

julia> Interpolations.deduplicate_knots!([1.0, 1.0, 1.0, nextfloat(1.0), nextfloat(1.0)]; move_knots = true)
5-element Vector{Float64}:
1.0
1.0000000000000002
1.0000000000000004
1.0000000000000007
1.0000000000000009
```

# Interpolations.gradient_weights — Function

w = gradient_weights(degree, δx)

Вычисляет веса для интерполяции градиента со смещением δx от «базовой» позиции. degree описывает интерполяционную схему.

Пример

julia> Interpolations.gradient_weights(Linear(), 0.2)
(-1.0, 1.0)

Определяет градиент линейной интерполяции со смещением 3,2 как y[4] - y[3].

# Interpolations.hessian_weights — Function

w = hessian_weights(degree, δx)

Вычисляет веса для интерполяции гессиана со смещением δx от «базовой» позиции. degree описывает интерполяционную схему.

Пример

julia> Interpolations.hessian_weights(Linear(), 0.2)
(0.0, 0.0)

Для линейной интерполяции используются отрезки прямой, поэтому вторая производная равна нулю.

# Interpolations.inner_system_diags — Function

dl, d, du = inner_system_diags{T,IT}(::Type{T}, n::Int, ::Type{IT})

Вспомогательная функция для создания системы уравнений предварительной фильтрации: генерирует диагонали для трехдиагональной матрицы размером n на n с типом элементов T, соответствующим типу интерполяции IT.

dl, d и du предназначены для использования, например, в таком вызове: M = Tridiagonal(dl, d, du).

# Interpolations.inner_system_diags — Method

Cubic: непрерывность значения функции, выдаваемого первой и второй производной.

2/3 1/6
1/6 2/3 1/6
    1/6 2/3 1/6
       ⋱  ⋱   ⋱

# Interpolations.lanczos — Method

lanczos(x, a, n=a)

Реализация ядра Ланцоша

# Interpolations.nextknotidx — Method

nextknotidx(iter::KnotIterator, x)

Возвращает индекс первого узла, соответствующего условию x < k, или nothing, если такого узла нет.

Новые граничные условия должны определяться следующим образом.

nextknotidx(::Type{<:NewBoundaryCondition}, knots::Vector, x)

Здесь knots — это iter.knots, а NewBoundaryCondition — новые граничные условия. Этот метод должен работать со значениями x, как находящимися внутри границ, так и экстраполированными.

# Interpolations.prefiltering_system — Function

M, b = prefiltering_system{T,TC,GT<:GridType,D<:Degree}m(::T, ::Type{TC}, n::Int, ::Type{D}, ::Type{GT})

Для заданных типов элементов (T, TC) и интерполяционной схемы (GT, D), а также количества строк в выходных данных (n) вычисляет систему, используемую для предварительной фильтрации коэффициентов сплайна. Граничные условия определяют значения в первой и последней строках.

Некоторые из граничных условий требуют, чтобы в этих строках были нетридиагональные элементы (например, элемент [1,3] матрицы). Для обеспечения эффективного решения тридиагональных систем используется тождество матрицы Вудбери, добавляющее дополнительные элементы не по трем главным диагоналям.

Отфильтрованные коэффициенты получаются путем решения системы уравнений

M * c = v + b

где c — искомые коэффициенты, а v — точки данных.