Add citations and a simple example

Author: vchuravy

docs/Project.toml

@@ -1,6 +1,7 @@
 [deps]
 CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 Krylov = "ba0b0d4f-ebba-5204-a429-3ac8c609bfb7"
 KrylovPreconditioners = "45d422c2-293f-44ce-8315-2cb988662dec"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"

docs/make.jl

@@ -4,6 +4,7 @@ using NewtonKrylov
 using Documenter
 import Documenter.Remotes: GitHub
 using Literate
+using DocumenterCitations
 
 DocMeta.setdocmeta!(NewtonKrylov, :DocTestSetup, :(using NewtonKrylov); recursive = true)
 
@@ -17,6 +18,8 @@ const OUTPUT_DIR = joinpath(@__DIR__, "src/generated")
 
 examples = [
     "Bratu 1D" => "bratu",
+    "Simple" => "simple",
+    "BVP" => "bvp",
 ]
 
 for (_, name) in examples
@@ -26,6 +29,8 @@ end
 
 examples = [title => joinpath("generated", string(name, ".md")) for (title, name) in examples]
 
+bib = CitationBibliography(joinpath(@__DIR__, "src", "refs.bib"))
+
 makedocs(;
     modules = [NewtonKrylov],
     authors = "Valentin Churavy",
@@ -40,6 +45,7 @@ makedocs(;
                 class = :js,
                 attributes = Dict(Symbol("data-domain") => "vchuravy.dev", :defer => "")
             ),
+            "assets/citations.css",
         ],
         mathengine = MathJax3(),
     ),
@@ -49,6 +55,7 @@ makedocs(;
     ],
     doctest = true,
     linkcheck = true,
+    plugins = [bib]
 )
 
 deploydocs(;

docs/src/assets/citations.css

@@ -0,0 +1,17 @@
+.citation dl {
+  display: grid;
+  grid-template-columns: max-content auto; }
+.citation dt {
+  grid-column-start: 1; }
+.citation dd {
+  grid-column-start: 2;
+  margin-bottom: 0.75em; }
+.citation ul {
+ padding: 0 0 2.25em 0;
+ margin: 0;
+ list-style: none !important;}
+.citation ul li {
+ text-indent: -2.25em;
+ margin: 0.33em 0.5em 0.5em 2.25em;}
+.citation ol li {
+ padding-left:0.75em;}

docs/src/index.md

@@ -1,6 +1,6 @@
 # NewtonKrylov.jl
 
-
+Newton Method using Krylov.jl (montoison-orban-2023)[@cite]
 
 ## API
 
@@ -21,4 +21,9 @@ NewtonKrylov.EisenstatWalker
 
 ```@docs
 NewtonKrylov.JacobianOperator
+```
+
+## Bibliography
+
+```@bibliography
 ```

docs/src/refs.bib

@@ -0,0 +1,53 @@
+@BOOK{Kelley2022
+  title     = {Solving nonlinear equations with iterative methods: Solvers and
+               examples in Julia},
+  author    = {Kelley, C T},
+  publisher = {Society for Industrial and Applied Mathematics},
+  location  = {Philadelphia, PA},
+  date      = {2022-01},
+  doi       = {10.1137/1.9781611977271},
+  isbn      = {9781611977264,9781611977271},
+  urldate   = {2024-11-15},
+  language  = {en}
+}
+
+@BOOK{Kelley2003,
+  title     = {Solving nonlinear equations with Newton's method},
+  author    = {Kelley, C T},
+  publisher = {Society for Industrial and Applied Mathematics},
+  location  = {Philadelphia, Pa.},
+  date      = {2003},
+  doi       = {10.1137/1.9780898718898},
+  isbn      = {9780898715460,9780898718898},
+  series    = {Fundamentals of algorithms},
+  urldate   = {2024-11-12},
+  language  = {en}
+}
+
+@article{montoison-orban-2023,
+  author  = {Montoison, Alexis and Orban, Dominique},
+  title   = {{Krylov.jl: A Julia basket of hand-picked Krylov methods}},
+  journal = {Journal of Open Source Software},
+  volume  = {8},
+  number  = {89},
+  pages   = {5187},
+  year    = {2023},
+  doi     = {10.21105/joss.05187}
+}
+
+@ARTICLE{Kan2022-ko,
+  title        = {Extension of complex step finite difference method to
+                  Jacobian-free {Newton–Krylov​} method},
+  author       = {Kan, Ziyun and Song, Ningning and Peng, Haijun and Chen,
+                  Biaosong},
+  journaltitle = {Journal of computational and applied mathematics},
+  publisher    = {Elsevier BV},
+  volume       = {399},
+  issue        = {113732},
+  pages        = {113732},
+  date         = {2022-01-01},
+  doi          = {10.1016/j.cam.2021.113732},
+  issn         = {0377-0427,1879-1778},
+  urldate      = {2024-10-21},
+  language     = {en}
+}

examples/bratu.jl

@@ -1,4 +1,4 @@
-# # 1D bratu equation
+# # 1D bratu equation from (Kan2022-ko)[@cite]
 
 # ## Necessary packages
 using NewtonKrylov, Krylov

examples/bvp.jl

@@ -1,4 +1,4 @@
-# BVP from Solving Nonlinear Equations with Iterative Methods:
+# BVP from (Kelley2022)[@cite]
 
 using NewtonKrylov, Krylov, LinearAlgebra
 

examples/simple.jl

@@ -0,0 +1,50 @@
+## Simple 2D example from (Kelley2003)[@cite]
+
+using NewtonKrylov, LinearAlgebra
+using CairoMakie
+
+function F!(res, x)
+    res[1] = x[1]^2 + x[2]^2 - 2
+    return res[2] = exp(x[1] - 1) + x[2]^2 - 2
+end
+
+function F(x)
+    res = similar(x)
+    F!(res, x)
+    return res
+end
+
+
+xs = LinRange(-3, 8, 1000)
+ys = LinRange(-15, 10, 1000)
+
+levels = [0.1, 0.25, 0.5:2:10..., 10.0:10:200..., 200:100:4000...]
+
+fig, ax = contour(xs, ys, (x, y) -> norm(F([x, y])); levels)
+
+trace_1 = let x₀ = [2.0, 0.5]
+    xs = Vector{Tuple{Float64, Float64}}(undef, 0)
+    hist(x, res, n_res) = (push!(xs, (x[1], x[2])); nothing)
+    x, stats = newton_krylov!(F!, x₀, callback = hist)
+    xs
+end
+lines!(ax, trace_1)
+
+trace_2 = let x₀ = [2.5, 3.0]
+    xs = Vector{Tuple{Float64, Float64}}(undef, 0)
+    hist(x, res, n_res) = (push!(xs, (x[1], x[2])); nothing)
+    x, stats = newton_krylov!(F!, x₀, callback = hist)
+    xs
+end
+lines!(ax, trace_2)
+
+trace_3 = let x₀ = [3.0, 4.0]
+    xs = Vector{Tuple{Float64, Float64}}(undef, 0)
+    hist(x, res, n_res) = (push!(xs, (x[1], x[2])); nothing)
+    x, stats = newton_krylov!(F!, x₀, callback = hist, forcing = NewtonKrylov.EisenstatWalker(η_max = 0.68949), verbose = 1)
+    @show stats.solved
+    xs
+end
+lines!(ax, trace_3)
+
+fig

src/NewtonKrylov.jl

@@ -121,12 +121,12 @@ function (F::EisenstatWalker)(η, tol, n_res, n_res_prior)
 end
 inital(F::EisenstatWalker) = F.η_max
 
-function newton_krylov(F, u₀, M::Int = length(u₀); kwargs...)
+function newton_krylov(F, u₀::AbstractArray, M::Int = length(u₀); kwargs...)
     F!(res, u) = (res .= F(u); nothing)
     return newton_krylov!(F!, u₀, M; kwargs...)
 end
 
-function newton_krylov!(F!, u₀, M::Int = length(u₀); kwargs...)
+function newton_krylov!(F!, u₀::AbstractArray, M::Int = length(u₀); kwargs...)
     res = similar(u₀, M)
     return newton_krylov!(F!, u₀, res; kwargs...)
 end
@@ -156,20 +156,23 @@ end
              If `nothing` an exact Newton method is used.   
 """
 function newton_krylov!(
-        F!, u, res;
+        F!, u::AbstractArray, res::AbstractArray;
         tol_rel = 1.0e-6,
         tol_abs = 1.0e-12,
         max_niter = 50,
         forcing::Union{Forcing, Nothing} = EisenstatWalker(),
         verbose = 0,
-        Solver = CgSolver,
+        Solver = GmresSolver,
         M = nothing,
         N = nothing,
-        krylov_kwargs = (;)
+        krylov_kwargs = (;),
+        callback = (args...) -> nothing,
     )
     t₀ = time_ns()
     F!(res, u) # res = F(u)
     n_res = norm(res)
+    callback(u, res, n_res)
+
     tol = tol_rel * n_res + tol_abs
 
     if forcing !== nothing
@@ -208,9 +211,11 @@ function newton_krylov!(
         u .+= s .* d
 
         # Update residual and norm
-        F!(res, u) # res = F(u)
         n_res_prior = n_res
+
+        F!(res, u) # res = F(u)
         n_res = norm(res)
+        callback(u, res, n_res)
 
         if isinf(n_res) || isnan(n_res)
             @error "Inner solver blew up" stats

test/runtests.jl

@@ -1,2 +1,17 @@
 using Test
 using NewtonKrylov
+
+function F!(res, x)
+    res[1] = x[1]^2 + x[2]^2 - 2
+    return res[2] = exp(x[1] - 1) + x[2]^2 - 2
+end
+
+let x₀ = [2.0, 0.5]
+    x, stats = newton_krylov!(F!, x₀)
+    @test stats.solved
+end
+
+let x₀ = [3.0, 5.0]
+    x, stats = newton_krylov!(F!, x₀)
+    @test stats.solved
+end