Merge pull request #80 from ranocha/hr/docs

docs

.github/workflows/Documenter.yml

@@ -38,4 +38,4 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
           DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
-        run: julia --project=docs --color=yes docs/make.jl
+        run: julia --threads=2 --project=docs --color=yes docs/make.jl

README.md

@@ -23,14 +23,87 @@ At the same time, the implementation is optimized to achieve good performance
 without sacrificing flexibility.
 
 
-## Basic Operators
+## Installation
+
+[SummationByPartsOperators.jl](https://github.com/ranocha/SummationByPartsOperators.jl)
+is a registered Julia package. Thus, you can install it from the Julia REPL via
+```julia
+julia> using Pkg; Pkg.add("SummationByPartsOperators")
+```
+
+
+## Basic examples
+
+Compute the derivative on a periodic domain using a central finite difference operator.
+```julia
+julia> using SummationByPartsOperators
+
+julia> using Plots: plot, plot!
+
+julia> D = periodic_derivative_operator(derivative_order=1, accuracy_order=2,
+                                        xmin=0.0, xmax=2.0, N=21)
+Periodic 1st derivative operator of order 2 {T=Float64, Parallel=Val{:serial}}
+on a grid in [0.0, 2.0] using 21 nodes,
+stencils with 1 nodes to the left, 1 nodes to the right, and coefficients from
+  Fornberg (1998)
+  Calculation of Weights in Finite Difference Formulas.
+  SIAM Rev. 40.3, pp. 685-691.
+
+
+julia> x = grid(D); u = sinpi.(x);
+
+julia> plot(x, D * u, label="numerical")
+
+julia> plot!(x, π .* cospi.(x), label="analytical")
+```
+You should see a plot like the following.
+
+<p align="center">
+  <img width="300px" src="https://user-images.githubusercontent.com/12693098/118977199-2ef4b280-b976-11eb-8e02-aec722d75bfa.png">
+</p>
+
+
+Compute the derivative on a bounded domain using an SBP finite difference operator.
+```julia
+julia> using SummationByPartsOperators
+
+julia> using Plots: plot, plot!
+
+julia> D = derivative_operator(MattssonNordström2004(), derivative_order=1, accuracy_order=2,
+                               xmin=0.0, xmax=1.0, N=21)
+SBP 1st derivative operator of order 2 {T=Float64, Parallel=Val{:serial}}
+on a grid in [0.0, 1.0] using 21 nodes
+and coefficients given in
+  Mattsson, Nordström (2004)
+  Summation by parts operators for finite difference approximations of second
+    derivatives.
+  Journal of Computational Physics 199, pp. 503-540.
+
+
+julia> x = grid(D); u = exp.(x);
+
+julia> plot(x, D * u, label="numerical")
+
+julia> plot!(x, exp.(x), label="analytical")
+```
+You should see a plot like the following.
+
+<p align="center">
+  <img width="300px" src="https://user-images.githubusercontent.com/12693098/118978404-93fcd800-b977-11eb-80b3-3dbfce5ecfd6.png">
+</p>
+
+
+
+## Brief overview
 
 The following derivative operators are implemented as "lazy"/matrix-free
 operators, i.e. no large (size of the computational grid) matrix is formed
-explicitly.
+explicitly. They are linear operators and implement the same interface as
+matrices in Julia (at least partially). In particular, `*` and `mul!` are
+supported.
 
 
-### Periodic Domains
+### Periodic domains
 
 - `periodic_derivative_operator(derivative_order, accuracy_order, xmin, xmax, N)`
 
@@ -40,37 +113,64 @@ explicitly.
 - `periodic_derivative_operator(Holoborodko2008(), derivative_order, accuracy_order, xmin, xmax, N)`
 
   These are central finite difference operators using `N` nodes on the
-  interval `[xmin, xmax]` and the coefficients of [Pavel Holoborodko](http://www.holoborodko.com/pavel/numerical-methods/numerical-derivative/smooth-low-noise-differentiators/).
+  interval `[xmin, xmax]` and the coefficients of
+  [Pavel Holoborodko](http://www.holoborodko.com/pavel/numerical-methods/numerical-derivative/smooth-low-noise-differentiators/).
 
 - `fourier_derivative_operator(xmin, xmax, N)`
 
-  Fourier derivative operators are implemented using the fast Fourier transform of [FFTW.jl](https://github.com/JuliaMath/FFTW.jl).
+  Fourier derivative operators are implemented using the fast Fourier transform of
+  [FFTW.jl](https://github.com/JuliaMath/FFTW.jl).
 
+All of these periodic derivative operators support multiplication and addition
+such that polynomials and rational functions of them can be represented efficiently,
+e.g. to solve elliptic problems of the form `u = (D^2 + I) \ f`.
 
-### Finite/Nonperiodic Domains
+
+### Finite (nonperiodic) domains
 
 - `derivative_operator(source_of_coefficients, derivative_order, accuracy_order, xmin, xmax, N)`
 
-  Finite difference SBP operators for first and second derivatives can be obained by using `MattssonNordström2004()` as `source_of_coefficients`.
-  Other sources of coefficients are implemented as well. To obtain a full list for all operators, use `subtypes(SourceOfCoefficients)`.
+  Finite difference SBP operators for first and second derivatives can be obtained
+  by using `MattssonNordström2004()` as `source_of_coefficients`.
+  Other sources of coefficients are implemented as well. To obtain a full list
+  of all operators, use `subtypes(SourceOfCoefficients)`.
 
 - `legendre_derivative_operator(xmin, xmax, N)`
 
   Use Lobatto Legendre polynomial collocation schemes on `N`, i.e.
-  polynomials of degree `N-1`, implemented via [PolynomialBases.jl](https://github.com/ranocha/PolynomialBases.jl).
+  polynomials of degree `N-1`, implemented via
+  [PolynomialBases.jl](https://github.com/ranocha/PolynomialBases.jl).
 
 
-### Dissipation Operators
+### Dissipation operators
 
 Additionally, some artificial dissipation/viscosity operators are implemented.
 The most basic usage is `Di = dissipation_operator(D)`,
 where `D` can be a (periodic, Fourier, Legendre, SBP FD) derivative
 operator. Use `?dissipation_operator` for more details.
 
 
-### Conversion to Other Forms
+### Continuous and discontinuous Galerkin methods
+
+SBP operators on bounded domains can be coupled continuously or discontinuously
+to obtain CG//DG-type methods. You need to create an appropriate `mesh` and
+a basic operator `D` that should be used on each element.
+Then, global CG/DG operators are constructed lazily/matrix-free by calling
+`couple_continuosly(D, mesh)` or
+`couple_discontinuosly(D, mesh, coupling::Union{Val{:plus}, Val{:central}, Val{:minus}}=Val(:central))`.
+Choosing `coupling=Val(:central)` yields a classical SBP operator; the other two
+`coupling` types result in upwind SBP operators. Currently, only uniform meshes
+
+- `UniformMesh1D(xmin::Real, xmax::Real, Nx::Integer)`
+- `UniformPeriodicMesh1D(xmin::Real, xmax::Real, Nx::Integer)`
+
+are implemented.
+
+
+### Conversion to other forms
 
-Sometimes, it can be convenient to obtain an explicit (sparse, banded) matrix form of the operators. Therefore, some conversion functions are supplied, e.g.
+Sometimes, it can be convenient to obtain an explicit (sparse, banded) matrix form
+of the operators. Therefore, some conversion functions are supplied, e.g.
 ```julia
 julia> using SummationByPartsOperators
 
@@ -80,7 +180,7 @@ on a grid in [0.0, 1.0] using 5 nodes
 and coefficients given in
   Mattsson, Nordström (2004)
   Summation by parts operators for finite difference approximations of second
-    derivaties.
+    derivatives.
   Journal of Computational Physics 199, pp.503-540.
 
 
@@ -95,17 +195,12 @@ julia> Matrix(D)
 julia> using SparseArrays
 
 julia> sparse(D)
-5×5 SparseMatrixCSC{Float64,Int64} with 10 stored entries:
-  [1, 1]  =  -4.0
-  [2, 1]  =  -2.0
-  [1, 2]  =  4.0
-  [3, 2]  =  -2.0
-  [2, 3]  =  2.0
-  [4, 3]  =  -2.0
-  [3, 4]  =  2.0
-  [5, 4]  =  -4.0
-  [4, 5]  =  2.0
-  [5, 5]  =  4.0
+5×5 SparseMatrixCSC{Float64, Int64} with 10 stored entries:
+ -4.0   4.0    ⋅     ⋅    ⋅
+ -2.0    ⋅    2.0    ⋅    ⋅
+   ⋅   -2.0    ⋅    2.0   ⋅
+   ⋅     ⋅   -2.0    ⋅   2.0
+   ⋅     ⋅     ⋅   -4.0  4.0
 
 julia> using BandedMatrices
 
@@ -130,6 +225,10 @@ and the [wave equation](https://github.com/ranocha/SummationByPartsOperators.jl/
 Further examples are supplied as
 [tests](https://github.com/ranocha/SummationByPartsOperators.jl/tree/master/test).
 
+The latest documentation is available
+[online](https://ranocha.github.io/SummationByPartsOperators.jl/stable)
+and under [`docs/src`](docs/src).
+
 
 ## Referencing
 
@@ -146,3 +245,11 @@ for your research, please cite it using the bibtex entry
   doi={10.5281/zenodo.4773575}
 }
 ```
+
+
+## License and contributing
+
+This project is licensed under the MIT license (see [LICENSE.md](LICENSE.md)).
+Since it is an open-source project, we are very happy to accept contributions
+from the community. Please refer to [CONTRIBUTING.md](CONTRIBUTING.md) for more
+details.

docs/Project.toml

@@ -1,10 +1,14 @@
 [deps]
+BandedMatrices = "aae01518-5342-5314-be14-df237901396f"
+BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 LaTeXStrings = "b964fa9f-0449-5b57-a5c2-d3ea65f4040f"
 OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 
 [compat]
+BandedMatrices = "0.15, 0.16"
+BenchmarkTools = "0.5, 0.7, 1.0"
 Documenter = "0.26"
 LaTeXStrings = "1.2"
 OrdinaryDiffEq = "5.50"

docs/make.jl

@@ -3,7 +3,8 @@ import Pkg
 using SummationByPartsOperators
 
 # Define module-wide setups such that the respective modules are available in doctests
-DocMeta.setdocmeta!(SummationByPartsOperators, :DocTestSetup, :(using SummationByPartsOperators); recursive=true)
+DocMeta.setdocmeta!(SummationByPartsOperators,
+  :DocTestSetup, :(using SummationByPartsOperators); recursive=true)
 
 open(joinpath(@__DIR__, "src", "license.md"), "w") do io
   println(io, "# License")
@@ -15,6 +16,8 @@ open(joinpath(@__DIR__, "src", "license.md"), "w") do io
 end
 
 open(joinpath(@__DIR__, "src", "contributing.md"), "w") do io
+  println(io, "# Contributing")
+  println(io, "")
   for line in eachline(joinpath(dirname(@__DIR__), "CONTRIBUTING.md"))
     line = replace(line, "[LICENSE.md](LICENSE.md)" => "[License](@ref)")
     println(io, "> ", line)
@@ -23,29 +26,29 @@ end
 
 # Make documentation
 makedocs(
-    modules = [SummationByPartsOperators],
-    sitename="SummationByPartsOperators.jl",
-    format = Documenter.HTML(
-        prettyurls = get(ENV, "CI", nothing) == "true",
-        # assets = ["assets/favicon.ico"],
-        canonical = "https://ranocha.github.io/SummationByPartsOperators.jl/stable"
-    ),
-    # Explicitly specify documentation structure
-    pages = [
-        "Home" => "index.md",
-        # "Getting started" => [
-        #     "Overview" => "overview.md",
-        #     "Visualization" => "visualization.md",
-        # ],
-        "API reference" => "api_reference.md",
-        "Contributing" => "contributing.md",
-        "License" => "license.md"
+  modules = [SummationByPartsOperators],
+  sitename="SummationByPartsOperators.jl",
+  format = Documenter.HTML(
+    prettyurls = get(ENV, "CI", nothing) == "true",
+    canonical = "https://ranocha.github.io/SummationByPartsOperators.jl/stable"
+  ),
+  # Explicitly specify documentation structure
+  pages = [
+    "Home" => "index.md",
+    "Introduction" => "introduction.md",
+    "Tutorials" => [
+      "tutorials/linear_advection.md",
     ],
-    strict = true # to make the GitHub action fail when doctests fail
+    "Benchmarks" => "benchmarks.md",
+    "API reference" => "api_reference.md",
+    "Contributing" => "contributing.md",
+    "License" => "license.md"
+  ],
+  strict = true # to make the GitHub action fail when doctests fail
 )
 
 deploydocs(
-    repo = "github.com/ranocha/SummationByPartsOperators.jl",
-    devbranch = "main",
-    push_preview = true
+  repo = "github.com/ranocha/SummationByPartsOperators.jl",
+  devbranch = "main",
+  push_preview = true
 )