From ae35381fab693bc40fc5fb433307030e9fad6990 Mon Sep 17 00:00:00 2001 From: Sathvik Bhagavan Date: Sun, 18 Feb 2024 07:21:55 +0000 Subject: [PATCH 1/6] docs: add docstrings for all methods --- src/interpolation_caches.jl | 137 +++++++++++++++++++++++++++++++++--- 1 file changed, 128 insertions(+), 9 deletions(-) diff --git a/src/interpolation_caches.jl b/src/interpolation_caches.jl index c28dba90..3317d86b 100644 --- a/src/interpolation_caches.jl +++ b/src/interpolation_caches.jl @@ -1,4 +1,16 @@ -### Linear Interpolation +""" + LinearInterpolation(u, t; extrapolate = false) + +It is the method of interpolating between the data points using a linear polynomial. For any point, two data points one each side are chosen and connected with a line. +Extrapolation extends the last linear polynomial on each side. + +## Arguments +- `u`: data points. +- `t`: time points. + +## Keyword Arguments +- `extrapolate`: boolean value to allow extrapolation. Defaults to `false`. +""" struct LinearInterpolation{uType, tType, FT, T} <: AbstractInterpolation{FT, T} u::uType t::tType @@ -13,7 +25,20 @@ function LinearInterpolation(u, t; extrapolate = false) LinearInterpolation{true}(u, t, extrapolate) end -### Quadratic Interpolation +""" + QuadraticInterpolation(u, t, mode = :Forward; extrapolate = false) + +It is the method of interpolating between the data points using quadratic polynomials. For any point, three data points nearby are taken to fit a quadratic polynomial. +Extrapolation extends the last quadratic polynomial on each side. + +## Arguments +- `u`: data points. +- `t`: time points. +- `mode`: `:Forward` or `:Backward`. If `:Forward`, two data points ahead of the point and one data point behind is taken for interpolation. If `:Backward`, two data points behind and one ahead is taken for interpolation. + +## Keyword Arguments +- `extrapolate`: boolean value to allow extrapolation. Defaults to `false`. +""" struct QuadraticInterpolation{uType, tType, FT, T} <: AbstractInterpolation{FT, T} u::uType t::tType @@ -35,7 +60,19 @@ function QuadraticInterpolation(u, t; extrapolate = false) QuadraticInterpolation(u, t, :Forward; extrapolate) end -### Lagrange Interpolation +""" + LagrangeInterpolation(u, t, n = length(t) - 1; extrapolate = false) + +It is the method of interpolation using Lagrange polynomials of (k-1)th order passing through all the data points where k is the number of data points. + +## Arguments +- `u`: data points. +- `t`: time points. +- `n`: order of the polynomial. Currently only (k-1)th order where k is the number of data points. + +## Keyword Arguments +- `extrapolate`: boolean value to allow extrapolation. Defaults to `false`. +""" struct LagrangeInterpolation{uType, tType, FT, T, bcacheType} <: AbstractInterpolation{FT, T} u::uType @@ -65,7 +102,19 @@ function LagrangeInterpolation(u, t, n = nothing; extrapolate = false) LagrangeInterpolation{true}(u, t, n, extrapolate) end -### Akima Interpolation +""" + AkimaInterpolation(u, t; extrapolate = false) + +It is a spline interpolation built from cubic polynomials. It forms a continuously differentiable function. For more details, refer: https://en.wikipedia.org/wiki/Akima_spline. +Extrapolation extends the last cubic polynomial on each side. + +## Arguments +- `u`: data points. +- `t`: time points. + +## Keyword Arguments +- `extrapolate`: boolean value to allow extrapolation. Defaults to `false`. +""" struct AkimaInterpolation{uType, tType, bType, cType, dType, FT, T} <: AbstractInterpolation{FT, T} u::uType @@ -110,7 +159,21 @@ function AkimaInterpolation(u, t; extrapolate = false) AkimaInterpolation{true}(u, t, b, c, d, extrapolate) end -### ConstantInterpolation Interpolation +""" + ConstantInterpolation(u, t; dir = :left, extrapolate = false) + +It is the method of interpolating using a constant polynomial. For any point, two adjacent data points are found on either side (left and right). The value at that point depends on `dir`. +If it is `:left`, then the value at the left point is chosen and if it is `:right`, the value at the right point is chosen. +Extrapolation extends the last constant polynomial at the end points on each side. + +## Arguments +- `u`: data points. +- `t`: time points. + +## Keyword Arguments +- `dir`: indicates which value should be used for interpolation (`:left` or `:right`). +- `extrapolate`: boolean value to allow extrapolation. Defaults to `false`. +""" struct ConstantInterpolation{uType, tType, dirType, FT, T} <: AbstractInterpolation{FT, T} u::uType t::tType @@ -128,7 +191,19 @@ end Base.@deprecate_binding ZeroSpline ConstantInterpolation -### QuadraticSpline Interpolation +""" + QuadraticSpline(u, t; extrapolate = false) + +It is a spline interpolation using piecewise quadratic polynomials between each pair of data points. Its first derivative is also continuous. +Extrapolation extends the last quadratic polynomial on each side. + +## Arguments +- `u`: data points. +- `t`: time points. + +## Keyword Arguments +- `extrapolate`: boolean value to allow extrapolation. Defaults to `false`. +""" struct QuadraticSpline{uType, tType, tAType, dType, zType, FT, T} <: AbstractInterpolation{FT, T} u::uType @@ -183,7 +258,19 @@ function QuadraticSpline(u::uType, t; extrapolate = false) where {uType <: Abstr QuadraticSpline{true}(u, t, tA, d, z, extrapolate) end -# Cubic Spline Interpolation +""" + QuadraticSpline(u, t; extrapolate = false) + +It is a spline interpolation using piecewise cubic polynomials between each pair of data points. Its first and second derivative is also continuous. +Extrapolation extends the last cubic polynomial on each side. + +## Arguments +- `u`: data points. +- `t`: time points. + +## Keyword Arguments +- `extrapolate`: boolean value to allow extrapolation. Defaults to `false`. +""" struct CubicSpline{uType, tType, hType, zType, FT, T} <: AbstractInterpolation{FT, T} u::uType t::tType @@ -240,7 +327,22 @@ function CubicSpline(u::uType, t; extrapolate = false) where {uType <: AbstractV CubicSpline{true}(u, t, h[1:(n + 1)], z, extrapolate) end -### BSpline Curve Interpolation +""" + BSplineInterpolation(u, t, d, pVecType, knotVecType; extrapolate = false) + +It is a curve defined by the linear combination of `n` basis functions of degree `d` where `n` is the number of data points. For more information, refer https://pages.mtu.edu/~shene/COURSES/cs3621/NOTES/spline/B-spline/bspline-curve.html. +Extrapolation is a constant polynomial of the end points on each side. + +## Arguments +- `u`: data points. +- `t`: time points. +- `d`: degree of the piecewise polynomial. +- `pVecType`: symbol to parameters vector, `:Uniform` for uniform spaced parameters and `:ArcLen` for parameters generated by chord length method. +- `knotVecType`: symbol to knot vector, `:Uniform` for uniform knot vector, `:Average` for average spaced knot vector. + +## Keyword Arguments +- `extrapolate`: boolean value to allow extrapolation. Defaults to `false`. +""" struct BSplineInterpolation{uType, tType, pType, kType, cType, FT, T} <: AbstractInterpolation{FT, T} u::uType @@ -337,7 +439,24 @@ function BSplineInterpolation(u, t, d, pVecType, knotVecType; extrapolate = fals BSplineInterpolation{true}(u, t, d, p, k, c, pVecType, knotVecType, extrapolate) end -### BSpline Curve Approx +""" + BSplineApprox(u, t, d, h, pVecType, knotVecType; extrapolate = false) + +It is a regression based B-spline. The argument choices are the same as the `BSplineInterpolation`, with the additional parameter `h < length(t)` which is the number of control points to use, with smaller `h` indicating more smoothing. +For more information, refer http://www.cad.zju.edu.cn/home/zhx/GM/009/00-bsia.pdf. +Extrapolation is a constant polynomial of the end points on each side. + +## Arguments +- `u`: data points. +- `t`: time points. +- `d`: degree of the piecewise polynomial. +- `h`: number of control points to use. +- `pVecType`: symbol to parameters vector, `:Uniform` for uniform spaced parameters and `:ArcLen` for parameters generated by chord length method. +- `knotVecType`: symbol to knot vector, `:Uniform` for uniform knot vector, `:Average` for average spaced knot vector. + +## Keyword Arguments +- `extrapolate`: boolean value to allow extrapolation. Defaults to `false`. +""" struct BSplineApprox{uType, tType, pType, kType, cType, FT, T} <: AbstractInterpolation{FT, T} u::uType From 149255f1c729c534199b556db91cc00c567c4ecd Mon Sep 17 00:00:00 2001 From: Sathvik Bhagavan Date: Sun, 18 Feb 2024 07:23:33 +0000 Subject: [PATCH 2/6] refactor: constructor of Lagrange Interpolation --- src/interpolation_caches.jl | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/src/interpolation_caches.jl b/src/interpolation_caches.jl index 3317d86b..12f5e532 100644 --- a/src/interpolation_caches.jl +++ b/src/interpolation_caches.jl @@ -91,11 +91,8 @@ struct LagrangeInterpolation{uType, tType, FT, T, bcacheType} <: end end -function LagrangeInterpolation(u, t, n = nothing; extrapolate = false) +function LagrangeInterpolation(u, t, n = length(t) - 1; extrapolate = false) u, t = munge_data(u, t) - if isnothing(n) - n = length(t) - 1 # degree - end if n != length(t) - 1 error("Currently only n=length(t) - 1 is supported") end From dea0e35e2984ac37ea4f6cccd99e9b0402778013 Mon Sep 17 00:00:00 2001 From: Sathvik Bhagavan Date: Sun, 18 Feb 2024 08:48:50 +0000 Subject: [PATCH 3/6] docs: remove reference of sort! function as it is a base function --- src/interpolation_utils.jl | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/interpolation_utils.jl b/src/interpolation_utils.jl index dbbeca84..1693c942 100644 --- a/src/interpolation_utils.jl +++ b/src/interpolation_utils.jl @@ -81,7 +81,7 @@ purpose of using this function first would be to accelerate convergence in those by using correlated `guess`es for repeated calls. The best `guess` for the next call of this function would be the index returned by the previous call to `searchsorted`. -See [`sort!`](@ref) for an explanation of the keyword arguments `by`, `lt` and `rev`. +See `sort!` for an explanation of the keyword arguments `by`, `lt` and `rev`. """ function bracketstrictlymontonic(v::AbstractVector, x, From 8eed0ebaca5a12d4011b85dd92aea59792581485 Mon Sep 17 00:00:00 2001 From: Sathvik Bhagavan Date: Sun, 18 Feb 2024 08:49:23 +0000 Subject: [PATCH 4/6] refactor: remove unused @shorthands akima --- src/plot_rec.jl | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/src/plot_rec.jl b/src/plot_rec.jl index ac8e3f45..93b86574 100644 --- a/src/plot_rec.jl +++ b/src/plot_rec.jl @@ -225,14 +225,3 @@ end y := ny end -################################################################################ -# Shorthands # -################################################################################ - -""" - akima(u, t) - akima!(u, t) - -Plot the Akima interpolation of the given data. -""" -@shorthands akima From e44da2257a07c78acf4b8bf463cb764326da7eb8 Mon Sep 17 00:00:00 2001 From: Sathvik Bhagavan Date: Sun, 18 Feb 2024 08:49:45 +0000 Subject: [PATCH 5/6] docs: add the docstrings in the manual --- docs/make.jl | 4 ++-- docs/src/manual.md | 19 +++++++++++++++++++ 2 files changed, 21 insertions(+), 2 deletions(-) create mode 100644 docs/src/manual.md diff --git a/docs/make.jl b/docs/make.jl index a6989dad..8a2835d7 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -10,9 +10,9 @@ makedocs(modules = [DataInterpolations], clean = true, doctest = false, linkcheck = true, - warnonly = [:missing_docs], format = Documenter.HTML(assets = ["assets/favicon.ico"], canonical = "https://docs.sciml.ai/DataInterpolations/stable/"), - pages = ["index.md", "Methods" => "methods.md", "Interface" => "interface.md"]) + pages = ["index.md", "Methods" => "methods.md", + "Interface" => "interface.md", "Manual" => "manual.md"]) deploydocs(repo = "github.com/SciML/DataInterpolations.jl"; push_preview = true) diff --git a/docs/src/manual.md b/docs/src/manual.md new file mode 100644 index 00000000..b001b026 --- /dev/null +++ b/docs/src/manual.md @@ -0,0 +1,19 @@ +# Methods + +```@docs +LinearInterpolation +QuadraticInterpolation +LagrangeInterpolation +AkimaInterpolation +ConstantInterpolation +QuadraticSpline +CubicSpline +BSplineInterpolation +BSplineApprox +``` + +# Utility Functions + +```@docs +DataInterpolations.bracketstrictlymontonic +``` \ No newline at end of file From dc45dc04b2842844369dd82850a7bd7bc58dbc09 Mon Sep 17 00:00:00 2001 From: Sathvik Bhagavan Date: Sun, 18 Feb 2024 08:52:15 +0000 Subject: [PATCH 6/6] chore: format files --- docs/src/manual.md | 2 +- src/plot_rec.jl | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/src/manual.md b/docs/src/manual.md index b001b026..c33f1d78 100644 --- a/docs/src/manual.md +++ b/docs/src/manual.md @@ -16,4 +16,4 @@ BSplineApprox ```@docs DataInterpolations.bracketstrictlymontonic -``` \ No newline at end of file +``` diff --git a/src/plot_rec.jl b/src/plot_rec.jl index 93b86574..a7bd8afc 100644 --- a/src/plot_rec.jl +++ b/src/plot_rec.jl @@ -224,4 +224,3 @@ end x := nx y := ny end -