Templates for specific problems (#47)

.github/workflows/CI.yml

@@ -14,21 +14,27 @@ jobs:
   test:
     name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
     runs-on: ${{ matrix.os }}
-    env:
-      JULIA_NUM_THREADS: ${{ matrix.julia-threads }}
     strategy:
       fail-fast: false
       matrix:
         version:
           - '1'
           - '1.6'
         os:
-          - ubuntu-latest
+          - ubuntu-20.04 # https://github.com/actions/runner-images/discussions/7188
         arch:
           - x64
     steps:
+      - name: Increase swapfile
+        run: |
+          sudo swapoff -a
+          sudo fallocate -l 8G /swapfile
+          sudo chmod 600 /swapfile
+          sudo mkswap /swapfile
+          sudo swapon /swapfile
+          sudo swapon --show      
       - name: Checkout repository for access
-        uses: actions/checkout@v2
+        uses: actions/checkout@v4
 
       - name: Setup Julia
         uses: julia-actions/setup-julia@v1
@@ -61,7 +67,7 @@ jobs:
       contents: write
       statuses: write
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - uses: julia-actions/setup-julia@v1
         with:
           version: '1'

.gitignore

@@ -22,4 +22,9 @@ docs/src/tutorials/reaction_diffusion_equation_with_a_time_dependent_dirichlet_b
 docs/src/tutorials/diffusion_equation_on_a_square_plate.md
 docs/src/tutorials/equilibrium_temperature_distribution_with_mixed_boundary_conditions_and_using_ensembleproblems.md
 docs/src/tutorials/diffusion_equation_in_a_wedge_with_mixed_boundary_conditions.md
-docs/src/tutorials/solving_mazes_with_laplaces_equation.md
+docs/src/tutorials/solving_mazes_with_laplaces_equation.md
+docs/src/wyos/laplaces_equation.md
+docs/src/wyos/mean_exit_time.md
+docs/src/wyos/linear_reaction_diffusion_equations.md
+docs/src/wyos/poissons_equation.md
+docs/src/wyos/diffusion_equations.md

Project.toml

@@ -1,7 +1,7 @@
 name = "FiniteVolumeMethod"
 uuid = "d4f04ab7-4f65-4d72-8a28-7087bc7f46f4"
 authors = ["Daniel VandenHeuvel <[email protected]>"]
-version = "1.0.1"
+version = "1.1.0"
 
 [deps]
 ChunkSplitters = "ae650224-84b6-46f8-82ea-d812ca08434e"

README.md

@@ -11,11 +11,19 @@ $$
 \dfrac{\partial u(\boldsymbol x, t)}{\partial t} + \boldsymbol{\nabla} \boldsymbol{\cdot} \boldsymbol{q}(\boldsymbol x, t, u) = S(\boldsymbol x, t, u), \quad (x, y)^{\mkern-1.5mu\mathsf{T}} \in \Omega \subset \mathbb R^2,t>0,
 $$
 
-in two dimensions using the finite volume method, with support also provided for steady-state problems and for systems of PDEs of the above form. 
+in two dimensions using the finite volume method, with support also provided for steady-state problems and for systems of PDEs of the above form. In addition to this generic form above, we also provide support for specific problems that can be solved in a more efficient manner, namely:
+
+1. `DiffusionEquation`s: $\partial_tu = \div[D(\vb x)\grad u]$.
+2. `MeanExitTimeProblem`s: $\div[D(\vb x)\grad T(\vb x)] = -1$.
+3. `LinearReactionDiffusionEquation`s: $\partial_tu + \div[D(\vb x)\grad u] + f(\vb x)u$.
+4. `PoissonsEquation`: $\div[D(\vb x)\grad u]  f(\vb x)$.
+5. `LaplacesEquation`: $\div[D(\vb x)\grad u] = 0$.
+
+See the documentation for more information.
 
 If this package doesn't suit what you need, you may like to review some of the other PDE packages shown [here](https://github.com/JuliaPDE/SurveyofPDEPackages).
 
- As a very quick demonstration, here is how we could solve a diffusion equation with Dirichlet boundary conditions on a square domain; please see the docs for more information.
+ As a very quick demonstration, here is how we could solve a diffusion equation with Dirichlet boundary conditions on a square domain using the standard `FVMProblem` formulation; please see the docs for more information.
 
 ```julia
 using FiniteVolumeMethod, DelaunayTriangulation, CairoMakie, DifferentialEquations
@@ -39,4 +47,12 @@ record(fig, "anim.gif", eachindex(sol)) do i
 end
 ```
 
-![Animation of a solution](https://github.com/DanielVandH/FiniteVolumeMethod.jl/blob/imp_clean/anim.gif)
+![Animation of a solution](https://github.com/DanielVandH/FiniteVolumeMethod.jl/blob/main/anim.gif)
+
+We could have equivalently used the `DiffusionEquation` template, so that `prob` could have also been defined by 
+
+```julia
+prob = DiffusionEquation(mesh, BCs; diffusion_function=D, initial_condition, final_time)
+```
+
+and be solved much more efficiently. See the documentation for more information.

docs/Project.toml

@@ -8,11 +8,13 @@ Cubature = "667455a9-e2ce-5579-9412-b964f529a492"
 DataInterpolations = "82cc6244-b520-54b8-b5a6-8a565e85f1d0"
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
 DelaunayTriangulation = "927a84f5-c5f4-47a5-9785-b46e178433df"
+DiffEqDevTools = "f3b72e0c-5b89-59e1-b016-84e28bfd966d"
 DifferentialEquations = "0c46a032-eb83-5123-abaf-570d42b7fbaa"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 ElasticArrays = "fdbdab4c-e67f-52f5-8c3f-e7b388dad3d4"
 FastGaussQuadrature = "442a2c76-b920-505d-bb47-c5924d526838"
 FiniteVolumeMethod = "d4f04ab7-4f65-4d72-8a28-7087bc7f46f4"
+JET = "c3a54625-cd67-489e-a8e7-0a5a0ff4e31b"
 Krylov = "ba0b0d4f-ebba-5204-a429-3ac8c609bfb7"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 LinearSolve = "7ed4a6bd-45f5-4d41-b270-4a48e9bafcae"
@@ -21,14 +23,17 @@ LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589"
 NaturalNeighbours = "f16ad982-4edb-46b1-8125-78e5a8b5a9e6"
 NonlinearSolve = "8913a72c-1f9b-4ce2-8d82-65094dcecaec"
 OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
+PProf = "e4faabce-9ead-11e9-39d9-4379958e3056"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 ReferenceTests = "324d217c-45ce-50fc-942e-d289b448e8cf"
 Roots = "f2b01f46-fcfa-551c-844a-d8ac1e96c665"
+SciMLBase = "0bca4576-84f4-4d90-8ffe-ffa030f20462"
 SimpleGraphs = "55797a34-41de-5266-9ec1-32ac4eb504d3"
+SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
+Sparspak = "e56a9233-b9d6-4f03-8d0f-1825330902ac"
+SpecialFunctions = "276daf66-3868-5448-9aa4-cd146d93841b"
 StableRNGs = "860ef19b-820b-49d6-a774-d7a799459cd3"
 StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
 SteadyStateDiffEq = "9672c7b4-1e72-59bd-8a11-6ac3964bc41f"
+Sundials = "c3572dad-4567-51f8-b174-8c6c989267f4"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
-
-[compat]
-DelaunayTriangulation = "0.7.2"

docs/liveserver.jl

@@ -10,10 +10,12 @@ withenv("LIVESERVER_ACTIVE" => "true") do
         include_dirs=[joinpath(repo_root, "src")],
         skip_dirs=[
             joinpath(repo_root, "docs/src/tutorials"),
-            joinpath(repo_root, "docs/src/figures")
+            joinpath(repo_root, "docs/src/figures"),
+            joinpath(repo_root, "docs/src/wyos"),
         ],
-        include_files = [
-            joinpath(repo_root, "docs/src/tutorials/overview.md")
+        include_files=[
+            joinpath(repo_root, "docs/src/tutorials/overview.md"),
+            joinpath(repo_root, "docs/src/wyos/overview.md"),
         ]
     )
 end

docs/make.jl

@@ -17,12 +17,12 @@ const session_tmp = mktempdir()
 
 # When running docs locally, the EditURL is incorrect. For example, we might get 
 #   ```@meta
-#   EditURL = "<unknown>/docs/src/literate_tutorials/constrained.jl"
+#   EditURL = "<unknown>/docs/src/literate_tutorials/name.jl"
 #   ```
 # We need to replace this EditURL if we are running the docs locally. The last case is more complicated because, 
 # after changing to use temporary directories, it can now look like...
 #   ```@meta
-#   EditURL = "../../../../../../../AppData/Local/Temp/jl_8nsMGu/cs1_just_the_code.jl"
+#   EditURL = "../../../../../../../AppData/Local/Temp/jl_8nsMGu/name_just_the_code.jl"
 #   ```
 function update_edit_url(content, file, folder)
     content = replace(content, "<unknown>" => "https://github.com/DanielVandH/FiniteVolumeMethod.jl/tree/main")
@@ -53,33 +53,34 @@ end
 
 # Now process all the literate files
 ct() = Dates.format(now(), "HH:MM:SS")
-folder = "tutorials"
-dir = joinpath(@__DIR__, "src", "literate_" * folder)
-outputdir = joinpath(@__DIR__, "src", folder)
-!isdir(outputdir) && mkpath(outputdir)
-files = readdir(dir)
-filter!(file -> endswith(file, ".jl") && !occursin("just_the_code", file), files)
-for file in files
-    # See also https://github.com/Ferrite-FEM/Ferrite.jl/blob/d474caf357c696cdb80d7c5e1edcbc7b4c91af6b/docs/generate.jl for some of this
-    file_path = joinpath(dir, file)
-    new_file_path = add_just_the_code_section(dir, file)
-    script = Literate.script(file_path, session_tmp, name=splitext(file)[1] * "_just_the_code_cleaned")
-    code = strip(read(script, String))
-    @info "[$(ct())] Processing $file: Converting markdown script"
-    line_ending_symbol = occursin(code, "\r\n") ? "\r\n" : "\n"
-    code_clean = join(filter(x -> !endswith(x, "#hide"), split(code, r"\n|\r\n")), line_ending_symbol)
-    code_clean = replace(code_clean, r"^# This file was generated .*$"m => "")
-    code_clean = strip(code_clean)
-    post_strip = content -> replace(content, "@__CODE__" => code_clean)
-    editurl_update = content -> update_edit_url(content, file, folder)
-    Literate.markdown(
-        new_file_path,
-        outputdir;
-        documenter=true,
-        postprocess=editurl_update ∘ post_strip,
-        credit=true,
-        name=splitext(file)[1]
-    )
+for folder in ("tutorials", "wyos")
+    dir = joinpath(@__DIR__, "src", "literate_" * folder)
+    outputdir = joinpath(@__DIR__, "src", folder)
+    !isdir(outputdir) && mkpath(outputdir)
+    files = readdir(dir)
+    filter!(file -> endswith(file, ".jl") && !occursin("just_the_code", file), files)
+    for file in files
+        # See also https://github.com/Ferrite-FEM/Ferrite.jl/blob/d474caf357c696cdb80d7c5e1edcbc7b4c91af6b/docs/generate.jl for some of this
+        file_path = joinpath(dir, file)
+        new_file_path = add_just_the_code_section(dir, file)
+        script = Literate.script(file_path, session_tmp, name=splitext(file)[1] * "_just_the_code_cleaned")
+        code = strip(read(script, String))
+        @info "[$(ct())] Processing $file: Converting markdown script"
+        line_ending_symbol = occursin(code, "\r\n") ? "\r\n" : "\n"
+        code_clean = join(filter(x -> !endswith(x, "#hide"), split(code, r"\n|\r\n")), line_ending_symbol)
+        code_clean = replace(code_clean, r"^# This file was generated .*$"m => "")
+        code_clean = strip(code_clean)
+        post_strip = content -> replace(content, "@__CODE__" => code_clean)
+        editurl_update = content -> update_edit_url(content, file, folder)
+        Literate.markdown(
+            new_file_path,
+            outputdir;
+            documenter=true,
+            postprocess=editurl_update ∘ post_strip,
+            credit=true,
+            name=splitext(file)[1]
+        )
+    end
 end
 
 # All the pages to be included
@@ -102,7 +103,15 @@ const _PAGES = [
         "Diffusion Equation on an Annulus" => "tutorials/diffusion_equation_on_an_annulus.md",
         "Mean Exit Time" => "tutorials/mean_exit_time.md",
         "Solving Mazes with Laplace's Equation" => "tutorials/solving_mazes_with_laplaces_equation.md",
-        "Keller-Segel Model of Chemotaxis" => "tutorials/keller_segel_chemotaxis.md"
+        "Keller-Segel Model of Chemotaxis" => "tutorials/keller_segel_chemotaxis.md",
+    ],
+    "Solvers for Specific Problems, and Writing Your Own" => [
+        "Section Overview" => "wyos/overview.md",
+        "Diffusion Equations" => "wyos/diffusion_equations.md",
+        "Mean Exit Time Problems" => "wyos/mean_exit_time.md",
+        "Linear Reaction-Diffusion Equations" => "wyos/linear_reaction_diffusion_equations.md",
+        "Poisson's Equation" => "wyos/poissons_equation.md",
+        "Laplace's Equation" => "wyos/laplaces_equation.md",
     ],
     "Mathematical and Implementation Details" => "math.md"
 ]
@@ -134,7 +143,7 @@ for (root, dir, files) in walkdir(doc_dir)
         end
     end
 end
-# !isempty(missing_set) && error("Missing files: $missing_set")
+!isempty(missing_set) && error("Missing files: $missing_set")
 
 # Make and deploy
 makedocs(;
@@ -162,4 +171,5 @@ makedocs(;
 
 deploydocs(;
     repo="github.com/DanielVandH/FiniteVolumeMethod.jl",
-    devbranch="main")
+    devbranch="main",
+    push_preview=true)

docs/src/index.md

@@ -18,4 +18,12 @@ using the finite volume method, with additional support for steady-state problem
 \pdv{u(\vb x, t)}{t} = \div\left[D(\vb x, t, u)\grad u(\vb x, t)\right] + S(\vb x, t, u).
 ```
 
-The tutorials in the sidebar demonstrate the many possibilities of this package.
+The [tutorials](tutorials/overview.md) in the sidebar demonstrate the many possibilities of this package. In addition to these two generic forms, we also provide support for specific problems that can be solved in a more efficient manner, namely:
+
+1. `DiffusionEquation`s: $\partial_tu = \div[D(\vb x)\grad u]$.
+2. `MeanExitTimeProblem`s: $\div[D(\vb x)\grad T(\vb x)] = -1$.
+3. `LinearReactionDiffusionEquation`s: $\partial_tu + \div[D(\vb x)\grad u] + f(\vb x)u$.
+4. `PoissonsEquation`: $\div[D(\vb x)\grad u]  f(\vb x)$.
+5. `LaplacesEquation`: $\div[D(\vb x)\grad u] = 0$.
+
+See the [Solvers for Specific Problems, and Writing Your Own](wyos/overview.md) section for more information on these templates.

docs/src/interface.md

@@ -83,6 +83,12 @@ Additionally, `FVMProblem` merges the provided boundary conditions and internal
 Conditions
 ```
 
+Note that the functions in `Conditions` get wrapped into a `ParametrisedFunction` type, which is public API.
+
+```@docs
+ParametrisedFunction
+```
+
 # `SteadyFVMProblem`: Making the problem a steady-state problem
 
 To make an `FVMProblem` a steady-state problem, meaning that you are solving

docs/src/literate_tutorials/diffusion_equation_in_a_wedge_with_mixed_boundary_conditions.jl

@@ -53,6 +53,7 @@ refine!(tri; max_area=1e-4A)
 mesh = FVMGeometry(tri)
 
 # This is the mesh we've constructed.
+using CairoMakie
 fig, ax, sc = triplot(tri)
 fig
 

docs/src/literate_tutorials/diffusion_equation_on_a_square_plate.jl

@@ -56,7 +56,6 @@ using DifferentialEquations
 sol = solve(prob, saveat=0.05)
 
 # To visualise the solution, we can use `tricontourf!` from Makie.jl. 
-using CairoMakie
 fig = Figure(fontsize=38)
 for (i, j) in zip(1:3, (1, 6, 11))
     ax = Axis(fig[1, i], width=600, height=600,

docs/src/literate_tutorials/equilibrium_temperature_distribution_with_mixed_boundary_conditions_and_using_ensembleproblems.jl

@@ -109,11 +109,7 @@ ens_prob = EnsembleProblem(steady_prob,
     prob_func=(prob, i, repeat) -> let T∞_range = T∞_range, h = h, k = k
         _prob =
             @set prob.problem.conditions.functions[3].parameters =
-                (h=h, T∞=T∞_range[i], k=k) 
-        ## This way of accessing the parameters is using some internals (specifically,
-        ## the functions field of conditions is not public API). 
-        ## A better way could be to e.g. make T∞ mutable initially, e.g. Ref(20),
-        ## and then mutate it.
+                (h=h, T∞=T∞_range[i], k=k)
         return _prob
     end,
     safetycopy=false)

docs/src/literate_tutorials/helmholtz_equation_with_inhomogeneous_boundary_conditions.jl

@@ -40,7 +40,7 @@ BCs = BoundaryConditions(mesh, (x, y, t, u, p) -> -one(u), Neumann)
 # So, for this problem, $D = 1$ and $S = u$. 
 diffusion_function = (x, y, t, u, p) -> one(u)
 source_function = (x, y, t, u, p) -> u
-initial_condition = zeros(num_points(tri))
+initial_condition = zeros(DelaunayTriangulation.num_solid_vertices(tri))
 final_time = Inf
 prob = FVMProblem(mesh, BCs;
     diffusion_function,

docs/src/literate_tutorials/laplaces_equation_with_internal_dirichlet_conditions.jl

@@ -91,7 +91,7 @@ ICs = InternalConditions((x, y, t, u, p) -> zero(u),
 # one suitable guess is $u(x, y) = 100y$ with $u(1/2, y) = 0$ for $0 \leq y \leq 2/5$;
 # in fact, $u(x, y) = 100y$ is the solution of the problem without the internal condition. 
 # Let us now use this to define our initial condition. 
-initial_condition = zeros(num_points(tri))
+initial_condition = zeros(DelaunayTriangulation.num_solid_vertices(tri))
 for i in each_solid_vertex(tri)
     x, y = get_point(tri, i)
     initial_condition[i] = ifelse(x == 1 / 2 && 0 ≤ y ≤ 2 / 5, 0, 100y)