Add documentation about solving PDEs (#57)

* push preview and some doc fixes * add sentence about docs previews in PRs * some more at-refs * limit number of characters per line in README * add info to README * first part * some fixes * continue * continue * continue * fix * add note about analytical vs automatic differentiation and custom PDEs * add part about time-dependent PDEs * fix typo * some fixes * don't number the equations * use consistent notation * add and * some small fixes * small fixes
JoshuaLampert · Jun 27, 2024 · a116bb2 · a116bb2
1 parent 4c17fd4
commit a116bb2
Show file tree

Hide file tree

Showing 14 changed files with 355 additions and 40 deletions.
diff --git a/.github/workflows/DocPreviewCleanup.yml b/.github/workflows/DocPreviewCleanup.yml
@@ -0,0 +1,33 @@
+name: Doc Preview Cleanup
+
+on:
+  pull_request:
+    types: [closed]
+
+# Ensure that only one "Doc Preview Cleanup" workflow is force pushing at a time
+concurrency:
+  group: doc-preview-cleanup
+  cancel-in-progress: false
+
+jobs:
+  doc-preview-cleanup:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@v4
+        with:
+          ref: gh-pages
+      - name: Delete preview and history + push changes
+        run: |
+          if [ -d "${preview_dir}" ]; then
+              git config user.name "Documenter.jl"
+              git config user.email "[email protected]"
+              git rm -rf "${preview_dir}"
+              git commit -m "delete preview"
+              git branch gh-pages-new $(echo "delete history" | git commit-tree HEAD^{tree})
+              git push --force origin gh-pages-new:gh-pages
+          fi
+        env:
+          preview_dir: previews/PR${{ github.event.number }}
diff --git a/README.md b/README.md
@@ -7,11 +7,17 @@
 [![Aqua QA](https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg)](https://github.com/JuliaTesting/Aqua.jl)
 [![License: MIT](https://img.shields.io/badge/License-MIT-success.svg)](https://opensource.org/licenses/MIT)
 
-**KernelInterpolation.jl** is a [Julia](https://julialang.org/) package that implements methods for multivariate interpolation in arbitrary dimension based on symmetric (conditionally) positive-definite kernels with a focus on radial-basis functions.
+**KernelInterpolation.jl** is a [Julia](https://julialang.org/) package that
+implements methods for multivariate interpolation in arbitrary dimension based on symmetric (conditionally) positive-definite kernels
+with a focus on radial-basis functions. It can be used for classical interpolation of scattered data, as well as for generalized
+(Hermite-Birkhoff) interpolation by using a meshfree collocation approach. This can be used to solve partial differential equations both
+stationary ones and time-dependent ones by using some time integration method from [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl).
 
 ## Installation
 
-If you have not yet installed Julia, then you first need to [download Julia](https://julialang.org/downloads/). Please [follow the instructions for your operating system](https://julialang.org/downloads/platform/). KernelInterpolation.jl works with Julia v1.10 and newer. You can install KernelInterpolation.jl by executing the following commands from the Julia REPL
+If you have not yet installed Julia, then you first need to [download Julia](https://julialang.org/downloads/). Please
+[follow the instructions for your operating system](https://julialang.org/downloads/platform/). KernelInterpolation.jl
+works with Julia v1.10 and newer. You can install KernelInterpolation.jl by executing the following commands from the Julia REPL
 
 ```julia
 julia> using Pkg
@@ -27,6 +33,11 @@ julia> using Pkg
 julia> Pkg.add("Plots")
 ```
 
+To create special node sets, you might also want to install [QuasiMonteCarlo.jl](https://github.com/SciML/QuasiMonteCarlo.jl) and
+for solving time-dependent partial differential equations [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) in a
+similar way as above for Plots.jl. See the documentation for more examples on how to use these packages in combination with
+KernelInterpolation.jl.
+
 ## Usage
 
 In the Julia REPL, first load the package KernelInterpolation.jl
@@ -35,27 +46,38 @@ In the Julia REPL, first load the package KernelInterpolation.jl
 julia> using KernelInterpolation
 ```
 
-In order to interpolate discrete function values of a (potentially) multivariate function $f: \mathbb{R}^d\to \mathbb{R}$, we first need a set of nodes $X = \\{x_1,\ldots,x_n\\}\subset\mathbb{R}^d$, where the function values of $f$ are known. In KernelInterpolation.jl we can, e.g., construct a homogeneous grid on a hypercube in 2 dimensions by calling
+In order to interpolate discrete function values of a (potentially) multivariate function $f: \mathbb{R}^d\to \mathbb{R}$, we
+first need a set of nodes $X = \\{x_1,\ldots,x_n\\}\subset\mathbb{R}^d$, where the function values of $f$ are known. In KernelInterpolation.jl
+we can, e.g., construct a homogeneous grid on a hypercube in 2 dimensions by calling
 
 ```julia
 julia> nodeset = homogeneous_hypercube(5, (-2, -1), (2, 1))
 ```
 
-Here, we specified that the hypercube has 5 nodes along each of the 2 dimensions (i.e. in total we have $5^2 = 25$ nodes) and that the boundaries of the cube are given by the lower left corner located at $(-2, -1)$ and the upper right corner at $(2, 1)$. Similarly, `NodeSet`s can be constructed by the functions `random_hypercube`, `random_hypercube_boundary`, `homogeneous_hypercube_boundary`, `random_hypersphere` or `random_hypersphere_boundary` or by directly passing a set of nodes to the constructor of `NodeSet`. Besides the `nodeset`, we need the function values at the nodes. Let's say, we want to reconstruct the function $f(x) = \sin(x_1\cdot x_2)$. Then, we can create the vector of function values by
+Here, we specified that the hypercube has 5 nodes along each of the 2 dimensions (i.e. in total we have $5^2 = 25$ nodes) and that the
+boundaries of the cube are given by the lower left corner located at $(-2, -1)$ and the upper right corner at $(2, 1)$. Similarly,
+`NodeSet`s can be constructed by the functions `random_hypercube`, `random_hypercube_boundary`,
+`homogeneous_hypercube_boundary`, `random_hypersphere` or `random_hypersphere_boundary` or by directly passing
+a set of nodes to the constructor of `NodeSet`. Besides the `nodeset`, we need the function values at the nodes. Let's say, we
+want to reconstruct the function $f(x) = \sin(x_1\cdot x_2)$. Then, we can create the vector of function values by
 
 ```julia
 julia> f(x) = sin(x[1]*x[2])
 julia> ff = f.(nodeset)
 ```
 
-Finally, we obtain the `Interpolation` object by calling `interpolate`, where we specify the kernel function that is used for the reconstruction. Here, we take a Gaussian $\phi(r) = \exp(-(\varepsilon r)^2)$ with shape parameter $\varepsilon = 1/2$ as radial-symmetric basis function:
+Finally, we obtain the `Interpolation` object by calling `interpolate`, where we specify the kernel function that is used
+for the reconstruction. Here, we take a Gaussian $\phi(r) = \exp(-(\varepsilon r)^2)$ with shape parameter $\varepsilon = 1/2$ as
+radial-symmetric basis function:
 
 ```julia
 julia> kernel = GaussKernel{dim(nodeset)}(shape_parameter = 0.5)
 julia> itp = interpolate(nodeset, ff, kernel)
 ```
 
-If the `kernel` is only conditionally positive definite, the interpolant will be augmented by a polynomial of the corresponding order of the kernel. Another order can also be passed explicitly with the keyword argument `m` of `interpolate`. The result `itp` is an object that is callable on any point $x\in\mathbb{R}^d$, e.g.,
+If the `kernel` is only conditionally positive definite, the interpolant will be augmented by a polynomial of the corresponding order of
+the kernel. Another order can also be passed explicitly with the keyword argument `m` of `interpolate`. The result `itp`
+is an object that is callable on any point $x\in\mathbb{R}^d$, e.g.,
 
 ```julia
 julia> itp([-1.3, 0.26])
@@ -65,6 +87,8 @@ julia> f([-1.3, 0.26])
 -0.33160091709280176
 ```
 
+For more sophisticated examples also involving solving stationary or time-dependent partial differential equations, see the
+[documentation](https://joshualampert.github.io/KernelInterpolation.jl/dev/pdes).
 More examples can be found in the [`examples/`](https://github.com/JoshuaLampert/KernelInterpolation.jl/tree/main/examples) subdirectory.
 
 ### Visualization
@@ -81,7 +105,8 @@ A `NodeSet` can simply be plotted by calling
 julia> plot(nodeset)
 ```
 
-An `Interpolation` object can be plotted by providing a `NodeSet` at which the interpolation is evaluated. Continuing the example from above, we can visualize the resulting interpolant on a finer grid
+An `Interpolation` object can be plotted by providing a `NodeSet` at which the interpolation is evaluated. Continuing
+the example from above, we can visualize the resulting interpolant on a finer grid
 
 ```julia
 julia> nodeset_fine = homogeneous_hypercube(20, 2, (-2, -1), (2, 1))
@@ -94,10 +119,15 @@ To visualize the true solution `f` in the same plot as a surface plot we can cal
 julia> plot!(nodeset_fine, f, st = :surface)
 ```
 
+KernelInterpolation.jl also supports exporting (and importing) VTK files, which can be visualized using tools
+such as [ParaView](https://www.paraview.org/) or [VisIt](https://visit-dav.github.io/visit-website/). See the documentation
+for more details.
+
 ## Authors
 
 The package is developed and maintained by Joshua Lampert (University of Hamburg).
 
 ## License and contributing
 
-KernelInterpolation.jl is published under the MIT license (see [License](https://github.com/JoshuaLampert/KernelInterpolation.jl/blob/main/LICENSE)). We are pleased to accept contributions from everyone, preferably in the form of a PR.
+KernelInterpolation.jl is published under the MIT license (see [License](https://github.com/JoshuaLampert/KernelInterpolation.jl/blob/main/LICENSE)).
+We are pleased to accept contributions from everyone, preferably in the form of a PR.
diff --git a/docs/make.jl b/docs/make.jl
@@ -20,11 +20,12 @@ makedocs(;
              "Guide" => [
                  "Sets of nodes" => "nodesets.md",
                  "Interpolation" => "interpolation.md",
-                 "Solving PDEs by collocation" => "pde.md"],
+                 "Solving PDEs by collocation" => "pdes.md"],
              "Development" => "development.md",
              "Reference" => "ref.md",
              "License" => "license.md"])
 
 deploydocs(;
            repo = "github.com/JoshuaLampert/KernelInterpolation.jl",
-           devbranch = "main")
+           devbranch = "main",
+           push_preview = true)
diff --git a/docs/src/development.md b/docs/src/development.md
@@ -19,7 +19,7 @@ cd KernelInterpolation.jl
 mkdir run
 cd run
 julia --project=. -e 'using Pkg; Pkg.develop(PackageSpec(path=".."))' # Install local KernelInterpolation.jl clone
-julia --project=. -e 'using Pkg; Pkg.add(["Plots", "QuasiMonteCarlo"])' # Install additional packages
+julia --project=. -e 'using Pkg; Pkg.add(["Plots", "QuasiMonteCarlo", "OrdinaryDiffEq"])' # Install additional packages
 ```
 
 If you use other packages for executing KernelInterpolation.jl, you can add them to the project in the `run`
@@ -48,3 +48,6 @@ julia --project=docs --color=yes docs/make.jl
 ```
 
 The resulting `.html` files can then be found in `docs/build/` and you can look at them by opening them in a browser.
+For pull requests from the main repository (i.e. not from a fork), the documentation is automatically built and can
+be previewed under `https://joshualampert.github.io/KernelInterpolation.jl/previews/PRXXX/` where `XXX` is the number
+of the pull request.
diff --git a/docs/src/index.md b/docs/src/index.md
@@ -7,11 +7,17 @@
 [![Aqua QA](https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg)](https://github.com/JuliaTesting/Aqua.jl)
 [![License: MIT](https://img.shields.io/badge/License-MIT-success.svg)](https://opensource.org/licenses/MIT)
 
-[**KernelInterpolation.jl**](https://github.com/JoshuaLampert/KernelInterpolation.jl) is a [Julia](https://julialang.org/) package that implements methods for multivariate interpolation in arbitrary dimension based on symmetric (conditionally) positive-definite kernels with a focus on radial-basis functions.
+[**KernelInterpolation.jl**](https://github.com/JoshuaLampert/KernelInterpolation.jl) is a [Julia](https://julialang.org/) package that
+implements methods for multivariate interpolation in arbitrary dimension based on symmetric (conditionally) positive-definite kernels
+with a focus on radial-basis functions. It can be used for classical interpolation of scattered data, as well as for generalized
+(Hermite-Birkhoff) interpolation by using a meshfree collocation approach. This can be used to solve partial differential equations both
+stationary ones and time-dependent ones by using some time integration method from [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl).
 
 ## Installation
 
-If you have not yet installed Julia, then you first need to [download Julia](https://julialang.org/downloads/). Please [follow the instructions for your operating system](https://julialang.org/downloads/platform/). KernelInterpolation.jl works with Julia v1.10 and newer. You can install KernelInterpolation.jl by executing the following commands from the Julia REPL
+If you have not yet installed Julia, then you first need to [download Julia](https://julialang.org/downloads/). Please
+[follow the instructions for your operating system](https://julialang.org/downloads/platform/). KernelInterpolation.jl
+works with Julia v1.10 and newer. You can install KernelInterpolation.jl by executing the following commands from the Julia REPL
 
 ```julia
 julia> using Pkg
@@ -27,6 +33,11 @@ julia> using Pkg
 julia> Pkg.add("Plots")
 ```
 
+To create special node sets, you might also want to install [QuasiMonteCarlo.jl](https://github.com/SciML/QuasiMonteCarlo.jl) and
+for solving time-dependent partial differential equations [OrdinaryDiffEq.jl](https://github.com/SciML/OrdinaryDiffEq.jl) in a
+similar way as above for Plots.jl. See the documentation for more examples on how to use these packages in combination with
+KernelInterpolation.jl.
+
 ## Usage
 
 In the Julia REPL, first load the package KernelInterpolation.jl
@@ -35,27 +46,38 @@ In the Julia REPL, first load the package KernelInterpolation.jl
 julia> using KernelInterpolation
 ```
 
-In order to interpolate discrete function values of a (potentially) multivariate function $f: \mathbb{R}^d\to \mathbb{R}$, we first need a set of nodes $X = \{x_1,\ldots,x_n\}\subset\mathbb{R}^d$, where the function values of $f$ are known. In KernelInterpolation.jl we can, e.g., construct a homogeneous grid on a hypercube in 2 dimensions by calling
+In order to interpolate discrete function values of a (potentially) multivariate function $f: \mathbb{R}^d\to \mathbb{R}$, we
+first need a set of nodes $X = \{x_1,\ldots,x_n\}\subset\mathbb{R}^d$, where the function values of $f$ are known. In KernelInterpolation.jl
+we can, e.g., construct a homogeneous grid on a hypercube in 2 dimensions by calling
 
 ```julia
 julia> nodeset = homogeneous_hypercube(5, (-2, -1), (2, 1))
 ```
 
-Here, we specified that the hypercube has 5 nodes along each of the 2 dimensions (i.e. in total we have $5^2 = 25$ nodes) and that the boundaries of the cube are given by the lower left corner located at $(-2, -1)$ and the upper right corner at $(2, 1)$. Similarly, [`NodeSet`](@ref)s can be constructed by the functions [`random_hypercube`](@ref), [`random_hypercube_boundary`](@ref), [`homogeneous_hypercube_boundary`](@ref), [`random_hypersphere`](@ref) or [`random_hypersphere_boundary`](@ref) or by directly passing a set of nodes to the constructor of `NodeSet`. Besides the `nodeset`, we need the function values at the nodes. Let's say, we want to reconstruct the function $f(x) = \sin(x_1\cdot x_2)$. Then, we can create the vector of function values by
+Here, we specified that the hypercube has 5 nodes along each of the 2 dimensions (i.e. in total we have $5^2 = 25$ nodes) and that the
+boundaries of the cube are given by the lower left corner located at $(-2, -1)$ and the upper right corner at $(2, 1)$. Similarly,
+[`NodeSet`](@ref)s can be constructed by the functions [`random_hypercube`](@ref), [`random_hypercube_boundary`](@ref),
+[`homogeneous_hypercube_boundary`](@ref), [`random_hypersphere`](@ref) or [`random_hypersphere_boundary`](@ref) or by directly passing
+a set of nodes to the constructor of [`NodeSet`](@ref). Besides the `nodeset`, we need the function values at the nodes. Let's say, we
+want to reconstruct the function $f(x) = \sin(x_1\cdot x_2)$. Then, we can create the vector of function values by
 
 ```julia
 julia> f(x) = sin(x[1]*x[2])
 julia> ff = f.(nodeset)
 ```
 
-Finally, we obtain the `Interpolation` object by calling [`interpolate`](@ref), where we specify the kernel function that is used for the reconstruction. Here, we take a Gaussian $\phi(r) = \exp(-(\varepsilon r)^2)$ with shape parameter $\varepsilon = 1/2$ as radial-symmetric basis function:
+Finally, we obtain the [`Interpolation`](@ref) object by calling [`interpolate`](@ref), where we specify the kernel function that is used
+for the reconstruction. Here, we take a Gaussian $\phi(r) = \exp(-(\varepsilon r)^2)$ with shape parameter $\varepsilon = 1/2$ as
+radial-symmetric basis function:
 
 ```julia
 julia> kernel = GaussKernel{dim(nodeset)}(shape_parameter = 0.5)
 julia> itp = interpolate(nodeset, ff, kernel)
 ```
 
-If the `kernel` is only conditionally positive definite, the interpolant will be augmented by a polynomial of the corresponding order of the kernel. Another order can also be passed explicitly with the keyword argument `m` of `interpolate`. The result `itp` is an object that is callable on any point $x\in\mathbb{R}^d$, e.g.,
+If the `kernel` is only conditionally positive definite, the interpolant will be augmented by a polynomial of the corresponding order of
+the kernel. Another order can also be passed explicitly with the keyword argument `m` of [`interpolate`](@ref). The result `itp` is an
+object that is callable on any point $x\in\mathbb{R}^d$, e.g.,
 
 ```julia
 julia> itp([-1.3, 0.26])
@@ -65,6 +87,10 @@ julia> f([-1.3, 0.26])
 -0.33160091709280176
 ```
 
+For more sophisticated examples also involving solving stationary or time-dependent partial differential equations, see the
+[documentation](https://joshualampert.github.io/KernelInterpolation.jl/dev/pdes).
+More examples can be found in the [`examples/`](https://github.com/JoshuaLampert/KernelInterpolation.jl/tree/main/examples) subdirectory.
+
 More examples can be found in the [`examples/`](https://github.com/JoshuaLampert/KernelInterpolation.jl/tree/main/examples) subdirectory.
 
 ### Visualization
@@ -75,13 +101,14 @@ In order to visualize the results, you need to have [Plots.jl](https://github.co
 julia> using Plots
 ```
 
-A `NodeSet` can simply be plotted by calling
+A [`NodeSet`](@ref) can simply be plotted by calling
 
 ```julia
 julia> plot(nodeset)
 ```
 
-An `Interpolation` object can be plotted by providing a `NodeSet` at which the interpolation is evaluated. Continuing the example from above, we can visualize the resulting interpolant on a finer grid
+An [`Interpolation`](@ref) object can be plotted by providing a [`NodeSet`](@ref) at which the interpolation is evaluated. Continuing
+the example from above, we can visualize the resulting interpolant on a finer grid
 
 ```julia
 julia> nodeset_fine = homogeneous_hypercube(20, 2, (-2, -1), (2, 1))
@@ -94,10 +121,15 @@ To visualize the true solution `f` in the same plot as a surface plot we can cal
 julia> plot!(nodeset_fine, f, st = :surface)
 ```
 
+KernelInterpolation.jl also supports exporting (and importing) VTK files, which can be visualized using tools
+such as [ParaView](https://www.paraview.org/) or [VisIt](https://visit-dav.github.io/visit-website/). See the documentation
+for more details.
+
 ## Authors
 
 The package is developed and maintained by Joshua Lampert (University of Hamburg).
 
 ## License and contributing
 
-KernelInterpolation.jl is published under the MIT license (see [License](https://github.com/JoshuaLampert/KernelInterpolation.jl/blob/main/LICENSE)). We are pleased to accept contributions from everyone, preferably in the form of a PR.
+KernelInterpolation.jl is published under the MIT license (see [License](https://github.com/JoshuaLampert/KernelInterpolation.jl/blob/main/LICENSE)).
+We are pleased to accept contributions from everyone, preferably in the form of a PR.