Update README and documentation (#499)

* Update README.md, fix badges, rearrange sections, list more packages

* Move Development Status to the bottom, above Contributing in README

* Update documentation index.md

* Add separate other packages page

* Rearrange badges like documentation

* Update NEWS.md

* Add NEWS.md to the documentation

* Given an example of performant usage in the introduction page.

* Apply suggestions from @ranocha

Co-authored-by: Hendrik Ranocha <[email protected]>

* Simplify initial example

* Update README.md

Co-authored-by: ederag <[email protected]>

* Update docs/src/index.md

Co-authored-by: ederag <[email protected]>

* Fix collocation misspelling in docs/src/other_packages.md

* Add Interpolations to docs Project

* Resort other packages

* Move convenience construction first in docs

* Add extra information on grids, scaling, and extrapolation to explain examples.

* Fix cross references

Co-authored-by: Hendrik Ranocha <[email protected]>
Co-authored-by: ederag <[email protected]>

Author: 3 people

NEWS.md

@@ -1,3 +1,14 @@
+For a comprehensive list of changes, see [Releases](https://github.com/JuliaMath/Interpolations.jl/releases).
+
+# v0.14.0
+
+Breaking changes:
+
+## Implement inplace `GriddedInterpolation` ([#496](https://github.com/JuliaMath/Interpolations.jl/pull/496), for [#495](https://github.com/JuliaMath/Interpolations.jl/issues/495))
+- `interpolate` now copies the coefficients for `GriddedInterpolation`.
+- `interpolate!` now does not copy the coefficients for `GriddedInterpolation`.
+- The third argument of `GriddedInterpolation` describes the array type of the coefficients rather than the element type of `Array`.
+
 # v0.9.0
 
 Breaking changes:

README.md

@@ -1,56 +1,41 @@
-# Interpolations
+# Interpolations.jl
 
-[![Build Status](https://travis-ci.org/JuliaMath/Interpolations.jl.svg?branch=master)](https://travis-ci.org/JuliaMath/Interpolations.jl)
-[![](https://img.shields.io/badge/docs-latest-blue.svg)](http://juliamath.github.io/Interpolations.jl/latest)
-
-**NEWS** This package is currently under new maintainership. Please be patient while the new maintainer learns the new package. If you would like to volunteer, please mention this in an issue.
-
-**NEWS** v0.9 was a breaking release. See the [news](NEWS.md) for details on how to update.
+[![version](https://juliahub.com/docs/Interpolations/version.svg)](https://juliahub.com/ui/Packages/Interpolations/VpKVx)
+[![pkgeval](https://juliahub.com/docs/Interpolations/pkgeval.svg)](https://juliahub.com/ui/Packages/Interpolations/VpKVx)
+[![Build Status](https://github.com/JuliaMath/Interpolations.jl/actions/workflows/CI.yml/badge.svg?branch=master)](https://github.com/JuliaMath/Interpolations.jl/actions/workflows/CI.yml?query=branch%3Amaster)
+[![deps](https://juliahub.com/docs/Interpolations/deps.svg)](https://juliahub.com/ui/Packages/Interpolations/VpKVx?t=2)
+[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](http://juliamath.github.io/Interpolations.jl/stable)
+[![Latest](https://img.shields.io/badge/docs-latest-blue.svg)](http://juliamath.github.io/Interpolations.jl/latest)
 
 This package implements a variety of interpolation schemes for the
 Julia language.  It has the goals of ease-of-use, broad algorithmic
 support, and exceptional performance.
 
-Currently this package's support is best
-for [B-splines](https://en.wikipedia.org/wiki/B-spline) and also
-supports irregular grids.  However, the API has been designed with
+Currently this package supports
+[B-splines](https://en.wikipedia.org/wiki/B-spline) and also
+irregular grids.  The API has been designed with
 intent to support more options. Initial support for Lanczos
 interpolation was recently added. Pull-requests are more than welcome!
 It should be noted that the API may continue to evolve over time.
 
-Other interpolation packages for Julia include:
-- [Dierckx.jl](https://github.com/kbarbary/Dierckx.jl)
-- [GridInterpolations.jl](https://github.com/sisl/GridInterpolations.jl)
-- [ApproXD.jl](https://github.com/floswald/ApproXD.jl)
-- [PCHIPInterpolation.jl](https://github.com/gerlero/PCHIPInterpolation.jl) for monotonic interpolation
-- [DIVAnd.jl](https://github.com/gher-ulg/DIVAnd.jl) for N-dimensional smoothing interpolation 
-
-Some of these packages support methods that `Interpolations` does not,
-so if you can't find what you need here, check one of them or submit a
-pull request here.
-
 At the bottom of this page, you can find a "performance shootout"
 among these methods (as well as SciPy's `RegularGridInterpolator`).
 
-
 ## Installation
 
-Just
+Interpolations.jl can be installed via the following invocation
+since it is a registered Julia package.
 
 ```julia
 using Pkg
 Pkg.add("Interpolations")
 ```
 
-from the Julia REPL.
-
-
 ## Example Usage
 Create a grid `xs` and an array `A` of values to be interpolated
 ```julia
 xs = 1:0.2:5
-f(x) = log(x)
-A = [f(x) for x in xs]
+A = log.(xs)
 ```
 Create linear interpolation object without extrapolation
 ```julia
@@ -71,6 +56,39 @@ More examples, such as plotting and cubic interpolation, can be found at the [co
 
 ![interpolation plot example](docs/src/assets/plotsjl_interpolation_example.png)
 
+## Other Interpolation Packages
+
+Other interpolation packages for Julia include:
+
+- [ApproXD.jl](https://github.com/floswald/ApproXD.jl) implements B-spline and linear interpolation in Julia.
+- [BarycentricInterpolation.jl](https://github.com/dawbarton/BarycentricInterpolation.jl) implements the Barycentric formula for polynomial interpolation on equispaced points and Chebyshev points of the first and second kind.
+- [BasicInterpolators.jl](https://github.com/markmbaum/BasicInterpolators.jl) provides a collection of common interpolation recipes for basic applications.
+- [BSplineKit.jl](https://github.com/jipolanco/BSplineKit.jl) offers tools for B-spline based Galerkin and collocation methods, including for interpolation and approximation.
+- [Curves.jl](https://github.com/lungben/Curves.jl) supports log-interpolation via immutable `Curve` objects.
+- [DataInterpolations.jl](https://github.com/PumasAI/DataInterpolations.jl) is a library for performing interpolations of one-dimensional data.
+- [Dierckx.jl](https://github.com/kbarbary/Dierckx.jl) is a wrapper for the dierckx Fortran library, which also underlies `scipy.interpolate`.
+- [DIVAnd.jl](https://github.com/gher-ulg/DIVAnd.jl) for N-dimensional smoothing interpolation. 
+- [FastChebInterp.jl](https://github.com/stevengj/FastChebInterp.jl) does fast multidimensional Chebyshev interpolation on a hypercube using separable grid of interpolation points.
+- [FEMBasis.jl](https://github.com/JuliaFEM/FEMBasis.jl) contains interpolation routines for standard finite element function spaces.
+- [FineShift.jl](https://github.com/emmt/FineShift.jl) does fast sub-sample shifting of multidimensional arrays.
+- [FourierTools.jl](https://github.com/bionanoimaging/FourierTools.jl) includes sinc interpolation for up and down sampling.
+- [GridInterpolations.jl](https://github.com/sisl/GridInterpolations.jl) performs multivariate interpolation on a rectilinear grid.
+- [InterpolationKernels.jl](https://github.com/emmt/InterpolationKernels.jl) provides a library of interpolation kernels.
+- [KissSmoothing.jl](https://github.com/francescoalemanno/KissSmoothing.jl) implements denoising and a Radial Basis Function estimation procedure.
+- [LinearInterpolations.jl](https://github.com/jw3126/LinearInterpolations.jl) allows for interpolation using weighted averages allowing probability distributions, rotations, and other Lie groups to be interpolated.
+- [LinearInterpolators.jl](https://github.com/emmt/LinearInterpolators.jl) provides linear interpolation methods for Julia based on InterpolationKernels.jl, above.
+- [LocalFunctionApproximation.jl](https://github.com/sisl/LocalFunctionApproximation.jl) provides local function approximators that interpolates a scalar-valued function across a vector space.
+- [PCHIPInterpolation.jl](https://github.com/gerlero/PCHIPInterpolation.jl) for monotonic interpolation.
+- [PiecewiseLinearApprox.jl](https://github.com/RJDennis/PiecewiseLinearApprox.jl) performs piecewise linear interpolation over an arbitrary number of dimensions.
+- [ScatteredInterpolation.jl](https://github.com/eljungsk/ScatteredInterpolation.jl) interpolates scattered data in arbitrary dimensions.
+
+Some of these packages support methods that `Interpolations` does not,
+so if you can't find what you need here, check one of them or submit a
+pull request here.
+
+If you would like to list a registered package that is related to interpolation, please create a Github issue.
+
+
 ## Performance shootout
 
 In the `perf` directory, you can find a script that tests
@@ -136,6 +154,20 @@ they ran more than 20 seconds (far longer than any other test).  Both
 performed much better in 2d, interestingly.  You can see that
 Interpolations wins in every case, sometimes by a very large margin.
 
+## Development Status
+
+This package is being maintained but not actively developed. Maintenance is
+focused on fixing bugs and issues with the current code base. New features are
+welcome via pull requests and will be reviewed and released in a timely fashion.
+
+If you would like to become involved in maintenance or active development of
+the package please feel free to get in touch via a Github issue.
+
+This package follows semantic version in that documented features should not
+break without changing the minor version.
+
+See the [news](NEWS.md) for details on how to update between breaking releases,
+indicated by changes in minor versions.
 
 ## Contributing
 

docs/Project.toml

@@ -1,5 +1,6 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Interpolations = "a98d9a8b-a2ab-59e6-89dd-64a1c18fca59"
 
 [compat]
 Documenter = "0.27"

docs/make.jl

@@ -4,13 +4,16 @@ sitename="Interpolations.jl",
 modules=[Interpolations],
 format=Documenter.HTML(prettyurls = get(ENV, "CI", nothing)=="true"),
 pages=["Home" => "index.md",
+        "Convenience Constructors" => "convenience-construction.md",
         "General usage" => "interpolations.md",
         "Interpolation algorithms" => "control.md",
         "Extrapolation" => "extrapolation.md",
-        "Convenience Constructors" => "convenience-construction.md",
         "Knot Iteration" => "iterate.md",
         "Developer documentation" => "devdocs.md",
-        "Library" => "api.md"],
+        "Library" => "api.md",
+        "News and Changes" => "NEWS.md",
+        "Other Interpolation Packages" => "other_packages.md",
+],
 strict=true,
 )
 

docs/src/convenience-construction.md

@@ -113,4 +113,4 @@ plot!(legend = :bottomleft)
 ```
 
 And the generated plot is:
-![interpolation plot example](assets/plotsjl_interpolation_example.png)
+![interpolation plot example](assets/plotsjl_interpolation_example.png)

docs/src/extrapolation.md

@@ -36,4 +36,4 @@ etp0 = extrapolate(itp0, Periodic())
 etp1 = extrapolate(itp1, Periodic())
 etp2 = extrapolate(itp2, Periodic())
 etp3 = extrapolate(itp3, Periodic())
-```
+```

docs/src/index.md

@@ -1,48 +1,46 @@
 
 # Interpolations
 
-[![Build Status](https://travis-ci.org/JuliaMath/Interpolations.jl.svg?branch=master)](https://travis-ci.org/JuliaMath/Interpolations.jl)
-[![PkgEval Status](http://pkg.julialang.org/badges/Interpolations_0.4.svg)](http://pkg.julialang.org/?pkg=Interpolations)
-[![Interpolations](http://pkg.julialang.org/badges/Interpolations_0.5.svg)](http://pkg.julialang.org/?pkg=Interpolations)
+[![version](https://juliahub.com/docs/Interpolations/version.svg)](https://juliahub.com/ui/Packages/Interpolations/VpKVx)
+[![pkgeval](https://juliahub.com/docs/Interpolations/pkgeval.svg)](https://juliahub.com/ui/Packages/Interpolations/VpKVx)
+[![Build Status](https://github.com/JuliaMath/Interpolations.jl/actions/workflows/CI.yml/badge.svg?branch=master)](https://github.com/JuliaMath/Interpolations.jl/actions/workflows/CI.yml?query=branch%3Amaster)
+[![deps](https://juliahub.com/docs/Interpolations/deps.svg)](https://juliahub.com/ui/Packages/Interpolations/VpKVx?t=2)
+[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](http://juliamath.github.io/Interpolations.jl/stable)
+[![Latest](https://img.shields.io/badge/docs-latest-blue.svg)](http://juliamath.github.io/Interpolations.jl/latest)
 
-**NEWS** v0.9 was a breaking release. See the [news](NEWS.md) for details on how to update.
-
-This package implements a variety of interpolation schemes for the
+The package [Interpolations.jl](https://github.com/JuliaMath/Interpolations.jl/)
+implements a variety of interpolation schemes for the
 Julia language.  It has the goals of ease-of-use, broad algorithmic
 support, and exceptional performance.
 
-Currently this package's support is best
-for [B-splines](https://en.wikipedia.org/wiki/B-spline) and also
-supports irregular grids.  However, the API has been designed with
+Currently this package supports
+[B-splines](https://en.wikipedia.org/wiki/B-spline) and
+irregular grids.  The API has been designed with
 intent to support more options. Pull-requests are more than welcome!
 It should be noted that the API may continue to evolve over time.
 
-Other interpolation packages for Julia include:
-- [Dierckx.jl](https://github.com/kbarbary/Dierckx.jl)
-- [GridInterpolations.jl](https://github.com/sisl/GridInterpolations.jl)
-- [ApproXD.jl](https://github.com/floswald/ApproXD.jl)
+There are many other interpolation packages implemented in Julia.
+For a listing, see [Other Interpolation Packages](@ref).
 
 Some of these packages support methods that `Interpolations` does not,
 so if you can't find what you need here, check one of them or submit a
 pull request here.
 
 ## Installation
 
-Just
+Interpolations.jl can be installed via the following invocation
+since it is a registered Julia package.
 
-```
+```julia
 using Pkg
 Pkg.add("Interpolations")
 ```
 
-from the Julia REPL.
-
 ## Example Usage
 Create a grid `xs` and an array `A` of values to be interpolated
 ```julia
 xs = 1:0.2:5
-f(x) = log(x)
-A = [f(x) for x in xs]
+A = log.(xs)
 ```
 Create linear interpolation object without extrapolation
 ```julia
@@ -53,6 +51,61 @@ interp_linear(0.9) # outside grid: error
 ```
 Create linear interpolation object with extrapolation
 ```julia
-interp_linear_extrap = LinearInterpolation(xs, A,extrapolation_bc=Line()) 
+interp_linear_extrap = LinearInterpolation(xs, A, extrapolation_bc=Line()) 
 interp_linear_extrap(0.9) # outside grid: linear extrapolation
 ```
+
+
+## Performant Example Usage
+
+The above use of `LinearInterpolation` is actually a short hand for a
+composition of `interpolate`, `scale`, and `extrapolate`. You may not need all
+of the the scaling and extrapolation features.
+
+```julia
+interp_linear = extrapolate(scale(interpolate(A, BSpline(Linear())), xs))
+```
+
+If we know we do not need the extrapolation portion, we can use the following.
+
+```julia
+scaled_itp = scale(interpolate(A, BSpline(Linear())), xs)
+```
+
+We can also remove the scaling for further performance if integer valued knots
+and regular grids are sufficient.
+
+```julia
+itp = interpolate(A, BSpline(Linear()))
+```
+
+Removing the scaling or extrapolation will help accelerate interpolation by
+removing unneeded operations and branches. This can permit the use of advanced
+processor Single Instruction/Multiple Data (SIMD) capabilities.
+
+## Regular Grids
+
+Interpolations.jl is optimized for use with regular grids with uniform spacing.
+The highest performance is achieved when the knots are an `AbstractUnitRange`
+such as `2:5` or `Base.OneTo(9)`. The default case if no knots are specified is to
+assign the knots as a `UnitRange` starting at `1`.
+
+## Scaling
+
+If the knots are not unit spaced or start at a distinct value other than `1`,
+then the `scale` function can be used. While this increases the flexibility of
+the interpolation, some performance penalty is acquired.
+See [Scaled BSplines](@ref) for further information.
+
+## Irregular Grids
+
+If the knots are irregularly spaced, then the ranges between knots will have to
+be scaled as in the `Gridded` interpolation type. See [Gridded interpolation](@ref)
+for additional details.
+
+## Points outside the knots
+
+For points not between knots, extrapolation can be used. This introduces a
+branch into the code that checks whether the point to be queried is inside or
+outside of the knots. This branch can inhibit the use of vectorized SIMD
+computation, resulting in a reduction of performance. See [Extrapolation](@ref).

docs/src/other_packages.md

@@ -0,0 +1,33 @@
+# Other Interpolation Packages
+
+Other interpolation packages for Julia include:
+
+- [ApproXD.jl](https://github.com/floswald/ApproXD.jl) implements B-spline and linear interpolation in Julia.
+- [BarycentricInterpolation.jl](https://github.com/dawbarton/BarycentricInterpolation.jl) implements the Barycentric formula for polynomial interpolation on equispaced points and Chebyshev points of the first and second kind.
+- [BasicInterpolators.jl](https://github.com/markmbaum/BasicInterpolators.jl) provides a collection of common interpolation recipes for basic applications.
+- [BSplineKit.jl](https://github.com/jipolanco/BSplineKit.jl) offers tools for B-spline based Galerkin and collocation methods, including for interpolation and approximation.
+- [Curves.jl](https://github.com/lungben/Curves.jl) supports log-interpolation via immutable `Curve` objects.
+- [DataInterpolations.jl](https://github.com/PumasAI/DataInterpolations.jl) is a library for performing interpolations of one-dimensional data.
+- [Dierckx.jl](https://github.com/kbarbary/Dierckx.jl) is a wrapper for the dierckx Fortran library, which also underlies `scipy.interpolate`.
+- [DIVAnd.jl](https://github.com/gher-ulg/DIVAnd.jl) for N-dimensional smoothing interpolation. 
+- [FastChebInterp.jl](https://github.com/stevengj/FastChebInterp.jl) does fast multidimensional Chebyshev interpolation on a hypercube using separable grid of interpolation points.
+- [FEMBasis.jl](https://github.com/JuliaFEM/FEMBasis.jl) contains interpolation routines for standard finite element function spaces.
+- [FineShift.jl](https://github.com/emmt/FineShift.jl) does fast sub-sample shifting of multidimensional arrays.
+- [FourierTools.jl](https://github.com/bionanoimaging/FourierTools.jl) includes sinc interpolation for up and down sampling.
+- [GridInterpolations.jl](https://github.com/sisl/GridInterpolations.jl) performs multivariate interpolation on a rectilinear grid.
+- [InterpolationKernels.jl](https://github.com/emmt/InterpolationKernels.jl) provides a library of interpolation kernels.
+- [KissSmoothing.jl](https://github.com/francescoalemanno/KissSmoothing.jl) implements denoising and a Radial Basis Function estimation procedure.
+- [LinearInterpolations.jl](https://github.com/jw3126/LinearInterpolations.jl) allows for interpolation using weighted averages allowing probability distributions, rotations, and other Lie groups to be interpolated.
+- [LinearInterpolators.jl](https://github.com/emmt/LinearInterpolators.jl) provides linear interpolation methods for Julia based on InterpolationKernels.jl, above.
+- [LocalFunctionApproximation.jl](https://github.com/sisl/LocalFunctionApproximation.jl) provides local function approximators that interpolates a scalar-valued function across a vector space.
+- [PCHIPInterpolation.jl](https://github.com/gerlero/PCHIPInterpolation.jl) for monotonic interpolation.
+- [PiecewiseLinearApprox.jl](https://github.com/RJDennis/PiecewiseLinearApprox.jl) performs piecewise linear interpolation over an arbitrary number of dimensions.
+- [ScatteredInterpolation.jl](https://github.com/eljungsk/ScatteredInterpolation.jl) interpolates scattered data in arbitrary dimensions.
+
+Some of these packages support methods that `Interpolations` does not,
+so if you can't find what you need here, check one of them or submit a
+pull request here.
+
+If you would like to list a registered package that is related to interpolation, please create a Github issue.
+
+