Add more descriptions to keywords

SciML · Aug 25, 2024 · a94970a · a94970a
1 parent 0cd03e0
commit a94970a
Show file tree

Hide file tree

Showing 8 changed files with 295 additions and 71 deletions.
diff --git a/docs/make.jl b/docs/make.jl
@@ -38,7 +38,8 @@ makedocs(sitename = "OrdinaryDiffEq.jl",
     warnonly = [:docs_block, :missing_docs, :eval_block],
     format = Documenter.HTML(analytics = "UA-90474609-3",
         assets = ["assets/favicon.ico"],
-        canonical = "https://ordinarydiffeq.sciml.ai/stable/"),
+        canonical = "https://ordinarydiffeq.sciml.ai/stable/",
+        size_threshold_ignore = ["implicit\\Rosenbrock.md"]),
     pages = [
         "OrdinaryDiffEq.jl: ODE solvers and utilities" => "index.md",
         "Usage" => "usage.md",

diff --git a/lib/OrdinaryDiffEqBDF/src/algorithms.jl b/lib/OrdinaryDiffEqBDF/src/algorithms.jl
@@ -11,19 +11,64 @@ function BDF_docstring(description::String,
         diff_type = Val{:forward},
         linsolve = nothing,
         precs = DEFAULT_PRECS,
-        """ * extra_keyword_default
+        """ * "\n" * extra_keyword_default
 
     keyword_default_description = """
-        - `chunk_size`: TBD
-        - `autodiff`: TBD
-        - `standardtag`: TBD
-        - `concrete_jac`: TBD
-        - `diff_type`: TBD
-        - `linsolve`: TBD
-        - `precs`: TBD
-        - `precs`: TBD
-        """ * extra_keyword_description
-
+    - `chunk_size`: The chunk size used with ForwardDiff.jl. Defaults to `Val{0}()`
+        and thus uses the internal ForwardDiff.jl algorithm for the choice.
+    - `autodiff`: Specifies whether to use automatic differentiation via
+        [ForwardDiff.jl](https://github.com/JuliaDiff/ForwardDiff.jl) or finite
+        differencing via [FiniteDiff.jl](https://github.com/JuliaDiff/FiniteDiff.jl).
+        Defaults to `Val{true}()` for automatic differentiation.
+    - `standardtag`: Specifies whether to use package-specific tags instead of the
+        ForwardDiff default function-specific tags. For more information, see
+        [this blog post](https://www.stochasticlifestyle.com/improved-forwarddiff-jl-stacktraces-with-package-tags/).
+        Defaults to `Val{true}()`.
+    - `concrete_jac`: Specifies whether a Jacobian should be constructed. Defaults to
+        `nothing`, which means it will be chosen true/false depending on circumstances
+        of the solver, such as whether a Krylov subspace method is used for `linsolve`.
+    - `diff_type`: The type of differentiation used in FiniteDiff.jl if `autodiff=false`.
+        Defaults to `Val{:forward}`, with alternatives of `Val{:central}` and
+        `Val{:complex}`.
+    - `linsolve`: Any [LinearSolve.jl](https://github.com/SciML/LinearSolve.jl) compatible linear solver.
+      For example, to use [KLU.jl](https://github.com/JuliaSparse/KLU.jl), specify
+      `$name(linsolve = KLUFactorization()`).
+       When `nothing` is passed, uses `DefaultLinearSolver`.
+    - `precs`: Any [LinearSolve.jl-compatible preconditioner](https://docs.sciml.ai/LinearSolve/stable/basics/Preconditioners/)
+      can be used as a left or right preconditioner.
+      Preconditioners are specified by the `Pl,Pr = precs(W,du,u,p,t,newW,Plprev,Prprev,solverdata)`
+      function where the arguments are defined as:
+        - `W`: the current Jacobian of the nonlinear system. Specified as either
+            ``I - \\gamma J`` or ``I/\\gamma - J`` depending on the algorithm. This will
+            commonly be a `WOperator` type defined by OrdinaryDiffEq.jl. It is a lazy
+            representation of the operator. Users can construct the W-matrix on demand
+            by calling `convert(AbstractMatrix,W)` to receive an `AbstractMatrix` matching
+            the `jac_prototype`.
+        - `du`: the current ODE derivative
+        - `u`: the current ODE state
+        - `p`: the ODE parameters
+        - `t`: the current ODE time
+        - `newW`: a `Bool` which specifies whether the `W` matrix has been updated since
+            the last call to `precs`. It is recommended that this is checked to only
+            update the preconditioner when `newW == true`.
+        - `Plprev`: the previous `Pl`.
+        - `Prprev`: the previous `Pr`.
+        - `solverdata`: Optional extra data the solvers can give to the `precs` function.
+            Solver-dependent and subject to change.
+      The return is a tuple `(Pl,Pr)` of the LinearSolve.jl-compatible preconditioners.
+      To specify one-sided preconditioning, simply return `nothing` for the preconditioner
+      which is not used. Additionally, `precs` must supply the dispatch:
+      ```julia
+      Pl, Pr = precs(W, du, u, p, t, ::Nothing, ::Nothing, ::Nothing, solverdata)
+      ```
+      which is used in the solver setup phase to construct the integrator
+      type with the preconditioners `(Pl,Pr)`.
+      The default is `precs=DEFAULT_PRECS` where the default preconditioner function
+      is defined as:
+      ```julia
+      DEFAULT_PRECS(W, du, u, p, t, newW, Plprev, Prprev, solverdata) = nothing, nothing
+      ```
+        """ * "/n" * extra_keyword_description
     generic_solver_docstring(
         description, name, "Multistep Method.", references,
         keyword_default_description, keyword_default
@@ -45,7 +90,7 @@ end
     - `smooth_est`: TBD
     - `extrapolant`: TBD
     - `controller`: TBD
-    - `step_limiter!`: TBD
+    - `step_limiter!`: function of the form `limiter!(u, integrator, p, t)`
     """,
     extra_keyword_default = """
     κ = nothing,
@@ -224,7 +269,7 @@ Optional parameter kappa defaults to Shampine's accuracy-optimal -0.1850.",
     - `extrapolant`: TBD
     - `kappa`: TBD
     - `controller`: TBD
-    - `step_limiter!`: TBD
+    - `step_limiter!`: function of the form `limiter!(u, integrator, p, t)`
     """,
     extra_keyword_default = """
     nlsolve = NLNewton(),
@@ -279,7 +324,7 @@ end
     - `extrapolant`: TBD
     - `kappa`: TBD
     - `controller`: TBD
-    - `step_limiter!`: TBD
+    - `step_limiter!`: function of the form `limiter!(u, integrator, p, t)`
     """,
     extra_keyword_default = """
     nlsolve = NLNewton(),
@@ -337,7 +382,7 @@ Utilizes Shampine's accuracy-optimal kappa values as defaults (has a keyword arg
     - `extrapolant`: TBD
     - `kappa`: TBD
     - `controller`: TBD
-    - `step_limiter!`: TBD
+    - `step_limiter!`: function of the form `limiter!(u, integrator, p, t)`
     """,
     extra_keyword_default = """
     κ = nothing,
@@ -436,7 +481,7 @@ Utilizes Shampine's accuracy-optimal kappa values as defaults (has a keyword arg
     - `nlsolve`: TBD
     - `extrapolant`: TBD
     - `controller`: TBD
-    - `step_limiter!`: TBD
+    - `step_limiter!`: function of the form `limiter!(u, integrator, p, t)`
     - `max_order`: TBD
     """,
     extra_keyword_default = """

diff --git a/lib/OrdinaryDiffEqCore/src/doc_utils.jl b/lib/OrdinaryDiffEqCore/src/doc_utils.jl
@@ -91,13 +91,60 @@ function differentiation_rk_docstring(description::String,
     """ * extra_keyword_default
 
     keyword_default_description = """
-    - `chunk_size`: TBD
-    - `autodiff`: TBD
-    - `standardtag`: TBD
-    - `concrete_jac`: TBD
-    - `diff_type`: TBD
-    - `linsolve`: TBD
-    - `precs`: TBD
+    - `chunk_size`: The chunk size used with ForwardDiff.jl. Defaults to `Val{0}()`
+        and thus uses the internal ForwardDiff.jl algorithm for the choice.
+    - `autodiff`: Specifies whether to use automatic differentiation via
+        [ForwardDiff.jl](https://github.com/JuliaDiff/ForwardDiff.jl) or finite
+        differencing via [FiniteDiff.jl](https://github.com/JuliaDiff/FiniteDiff.jl).
+        Defaults to `Val{true}()` for automatic differentiation.
+    - `standardtag`: Specifies whether to use package-specific tags instead of the
+        ForwardDiff default function-specific tags. For more information, see
+        [this blog post](https://www.stochasticlifestyle.com/improved-forwarddiff-jl-stacktraces-with-package-tags/).
+        Defaults to `Val{true}()`.
+    - `concrete_jac`: Specifies whether a Jacobian should be constructed. Defaults to
+        `nothing`, which means it will be chosen true/false depending on circumstances
+        of the solver, such as whether a Krylov subspace method is used for `linsolve`.
+    - `diff_type`: The type of differentiation used in FiniteDiff.jl if `autodiff=false`.
+        Defaults to `Val{:forward}`, with alternatives of `Val{:central}` and
+        `Val{:complex}`.
+    - `linsolve`: Any [LinearSolve.jl](https://github.com/SciML/LinearSolve.jl) compatible linear solver.
+      For example, to use [KLU.jl](https://github.com/JuliaSparse/KLU.jl), specify
+      `$name(linsolve = KLUFactorization()`).
+       When `nothing` is passed, uses `DefaultLinearSolver`.
+    - `precs`: Any [LinearSolve.jl-compatible preconditioner](https://docs.sciml.ai/LinearSolve/stable/basics/Preconditioners/)
+      can be used as a left or right preconditioner.
+      Preconditioners are specified by the `Pl,Pr = precs(W,du,u,p,t,newW,Plprev,Prprev,solverdata)`
+      function where the arguments are defined as:
+        - `W`: the current Jacobian of the nonlinear system. Specified as either
+            ``I - \\gamma J`` or ``I/\\gamma - J`` depending on the algorithm. This will
+            commonly be a `WOperator` type defined by OrdinaryDiffEq.jl. It is a lazy
+            representation of the operator. Users can construct the W-matrix on demand
+            by calling `convert(AbstractMatrix,W)` to receive an `AbstractMatrix` matching
+            the `jac_prototype`.
+        - `du`: the current ODE derivative
+        - `u`: the current ODE state
+        - `p`: the ODE parameters
+        - `t`: the current ODE time
+        - `newW`: a `Bool` which specifies whether the `W` matrix has been updated since
+            the last call to `precs`. It is recommended that this is checked to only
+            update the preconditioner when `newW == true`.
+        - `Plprev`: the previous `Pl`.
+        - `Prprev`: the previous `Pr`.
+        - `solverdata`: Optional extra data the solvers can give to the `precs` function.
+            Solver-dependent and subject to change.
+      The return is a tuple `(Pl,Pr)` of the LinearSolve.jl-compatible preconditioners.
+      To specify one-sided preconditioning, simply return `nothing` for the preconditioner
+      which is not used. Additionally, `precs` must supply the dispatch:
+      ```julia
+      Pl, Pr = precs(W, du, u, p, t, ::Nothing, ::Nothing, ::Nothing, solverdata)
+      ```
+      which is used in the solver setup phase to construct the integrator
+      type with the preconditioners `(Pl,Pr)`.
+      The default is `precs=DEFAULT_PRECS` where the default preconditioner function
+      is defined as:
+      ```julia
+      DEFAULT_PRECS(W, du, u, p, t, newW, Plprev, Prprev, solverdata) = nothing, nothing
+      ```
     """ * extra_keyword_description
 
     generic_solver_docstring(

diff --git a/lib/OrdinaryDiffEqFIRK/src/algorithms.jl b/lib/OrdinaryDiffEqFIRK/src/algorithms.jl
@@ -11,20 +11,10 @@ hairer1999stiff = """@article{hairer1999stiff,
 
 extra_keyword_description = """
     - `extrapolant`: TBD
-    - `fast_convergence_cutoff`: TBD
-    - `new_W_γdt_cutoff`: TBD
-    - `controller`: TBD
-    - `κ`: TBD
-    - `maxiters`: TBD
     - `smooth_est`: TBD
-    - `step_limiter!`: TBD"""
+    - `step_limiter!`: function of the form `limiter!(u, integrator, p, t)`"""
 extra_keyword_default = """
     extrapolant = :dense,
-    fast_convergence_cutoff = 1 // 5,
-    new_W_γdt_cutoff = 1 // 5,
-    controller = :Predictive,
-    κ = nothing,
-    maxiters = 10,
     smooth_est = true,
     step_limiter! = trivial_limiter!"""
 

diff --git a/lib/OrdinaryDiffEqPDIRK/src/algorithms.jl b/lib/OrdinaryDiffEqPDIRK/src/algorithms.jl
@@ -14,12 +14,12 @@
     extra_keyword_description = """
     - `nlsolve`: TBD,
     - `extrapolant`: TBD,
-    - `threading`: TBD,
+    - `thread`: determines whether internal broadcasting on appropriate CPU arrays should be serial (`thread = OrdinaryDiffEq.False()`) or use multiple threads (`thread = OrdinaryDiffEq.True()`) when Julia is started with multiple threads.
     """,
     extra_keyword_default = """
     nlsolve = NLNewton(),
     extrapolant = :constant,
-    threading = true,
+    thread = OrdinaryDiffEq.True(),
     """)
 struct PDIRK44{CS, AD, F, F2, P, FDT, ST, CJ, TO} <:
        OrdinaryDiffEqNewtonAlgorithm{CS, AD, FDT, ST, CJ}

diff --git a/lib/OrdinaryDiffEqRosenbrock/src/OrdinaryDiffEqRosenbrock.jl b/lib/OrdinaryDiffEqRosenbrock/src/OrdinaryDiffEqRosenbrock.jl
@@ -58,13 +58,60 @@ function rosenbrock_wanner_docstring(description::String,
     """ * extra_keyword_default
 
     keyword_default_description = """
-    - `chunk_size`: TBD
-    - `standardtag`: TBD
-    - `autodiff`: boolean to control if the Jacobian should be computed via AD or not
-    - `concrete_jac`: function of the form `jac!(J, u, p, t)`
-    - `diff_type`: TBD
-    - `linsolve`: custom solver for the inner linear systems
-    - `precs`: custom preconditioner for the inner linear solver
+    - `chunk_size`: The chunk size used with ForwardDiff.jl. Defaults to `Val{0}()`
+        and thus uses the internal ForwardDiff.jl algorithm for the choice.
+    - `standardtag`: Specifies whether to use package-specific tags instead of the
+        ForwardDiff default function-specific tags. For more information, see
+        [this blog post](https://www.stochasticlifestyle.com/improved-forwarddiff-jl-stacktraces-with-package-tags/).
+        Defaults to `Val{true}()`.
+    - `autodiff`: Specifies whether to use automatic differentiation via
+        [ForwardDiff.jl](https://github.com/JuliaDiff/ForwardDiff.jl) or finite
+        differencing via [FiniteDiff.jl](https://github.com/JuliaDiff/FiniteDiff.jl).
+        Defaults to `Val{true}()` for automatic differentiation.
+    - `concrete_jac`: Specifies whether a Jacobian should be constructed. Defaults to
+        `nothing`, which means it will be chosen true/false depending on circumstances
+        of the solver, such as whether a Krylov subspace method is used for `linsolve`.
+    - `diff_type`: The type of differentiation used in FiniteDiff.jl if `autodiff=false`.
+        Defaults to `Val{:forward}`, with alternatives of `Val{:central}` and
+        `Val{:complex}`.
+    - `linsolve`: Any [LinearSolve.jl](https://github.com/SciML/LinearSolve.jl) compatible linear solver.
+      For example, to use [KLU.jl](https://github.com/JuliaSparse/KLU.jl), specify
+      `$name(linsolve = KLUFactorization()`).
+       When `nothing` is passed, uses `DefaultLinearSolver`.
+    - `precs`: Any [LinearSolve.jl-compatible preconditioner](https://docs.sciml.ai/LinearSolve/stable/basics/Preconditioners/)
+      can be used as a left or right preconditioner.
+      Preconditioners are specified by the `Pl,Pr = precs(W,du,u,p,t,newW,Plprev,Prprev,solverdata)`
+      function where the arguments are defined as:
+        - `W`: the current Jacobian of the nonlinear system. Specified as either
+            ``I - \\gamma J`` or ``I/\\gamma - J`` depending on the algorithm. This will
+            commonly be a `WOperator` type defined by OrdinaryDiffEq.jl. It is a lazy
+            representation of the operator. Users can construct the W-matrix on demand
+            by calling `convert(AbstractMatrix,W)` to receive an `AbstractMatrix` matching
+            the `jac_prototype`.
+        - `du`: the current ODE derivative
+        - `u`: the current ODE state
+        - `p`: the ODE parameters
+        - `t`: the current ODE time
+        - `newW`: a `Bool` which specifies whether the `W` matrix has been updated since
+            the last call to `precs`. It is recommended that this is checked to only
+            update the preconditioner when `newW == true`.
+        - `Plprev`: the previous `Pl`.
+        - `Prprev`: the previous `Pr`.
+        - `solverdata`: Optional extra data the solvers can give to the `precs` function.
+            Solver-dependent and subject to change.
+      The return is a tuple `(Pl,Pr)` of the LinearSolve.jl-compatible preconditioners.
+      To specify one-sided preconditioning, simply return `nothing` for the preconditioner
+      which is not used. Additionally, `precs` must supply the dispatch:
+      ```julia
+      Pl, Pr = precs(W, du, u, p, t, ::Nothing, ::Nothing, ::Nothing, solverdata)
+      ```
+      which is used in the solver setup phase to construct the integrator
+      type with the preconditioners `(Pl,Pr)`.
+      The default is `precs=DEFAULT_PRECS` where the default preconditioner function
+      is defined as:
+      ```julia
+      DEFAULT_PRECS(W, du, u, p, t, newW, Plprev, Prprev, solverdata) = nothing, nothing
+      ```
     """ * extra_keyword_description
 
     if with_step_limiter
@@ -85,13 +132,60 @@ function rosenbrock_docstring(description::String,
         extra_keyword_default = "",
         with_step_limiter = false)
     keyword_default = """
-    chunk_size = Val{0}(),
-    standardtag = Val{true}(),
-    autodiff = Val{true}(),
-    concrete_jac = nothing,
-    diff_type = Val{:central},
-    linsolve = nothing,
-    precs = DEFAULT_PRECS,
+    - `chunk_size`: The chunk size used with ForwardDiff.jl. Defaults to `Val{0}()`
+        and thus uses the internal ForwardDiff.jl algorithm for the choice.
+    - `standardtag`: Specifies whether to use package-specific tags instead of the
+        ForwardDiff default function-specific tags. For more information, see
+        [this blog post](https://www.stochasticlifestyle.com/improved-forwarddiff-jl-stacktraces-with-package-tags/).
+        Defaults to `Val{true}()`.
+    - `autodiff`: Specifies whether to use automatic differentiation via
+        [ForwardDiff.jl](https://github.com/JuliaDiff/ForwardDiff.jl) or finite
+        differencing via [FiniteDiff.jl](https://github.com/JuliaDiff/FiniteDiff.jl).
+        Defaults to `Val{true}()` for automatic differentiation.
+    - `concrete_jac`: Specifies whether a Jacobian should be constructed. Defaults to
+        `nothing`, which means it will be chosen true/false depending on circumstances
+        of the solver, such as whether a Krylov subspace method is used for `linsolve`.
+    - `diff_type`: The type of differentiation used in FiniteDiff.jl if `autodiff=false`.
+        Defaults to `Val{:forward}`, with alternatives of `Val{:central}` and
+        `Val{:complex}`.
+    - `linsolve`: Any [LinearSolve.jl](https://github.com/SciML/LinearSolve.jl) compatible linear solver.
+      For example, to use [KLU.jl](https://github.com/JuliaSparse/KLU.jl), specify
+      `$name(linsolve = KLUFactorization()`).
+       When `nothing` is passed, uses `DefaultLinearSolver`.
+    - `precs`: Any [LinearSolve.jl-compatible preconditioner](https://docs.sciml.ai/LinearSolve/stable/basics/Preconditioners/)
+      can be used as a left or right preconditioner.
+      Preconditioners are specified by the `Pl,Pr = precs(W,du,u,p,t,newW,Plprev,Prprev,solverdata)`
+      function where the arguments are defined as:
+        - `W`: the current Jacobian of the nonlinear system. Specified as either
+            ``I - \\gamma J`` or ``I/\\gamma - J`` depending on the algorithm. This will
+            commonly be a `WOperator` type defined by OrdinaryDiffEq.jl. It is a lazy
+            representation of the operator. Users can construct the W-matrix on demand
+            by calling `convert(AbstractMatrix,W)` to receive an `AbstractMatrix` matching
+            the `jac_prototype`.
+        - `du`: the current ODE derivative
+        - `u`: the current ODE state
+        - `p`: the ODE parameters
+        - `t`: the current ODE time
+        - `newW`: a `Bool` which specifies whether the `W` matrix has been updated since
+            the last call to `precs`. It is recommended that this is checked to only
+            update the preconditioner when `newW == true`.
+        - `Plprev`: the previous `Pl`.
+        - `Prprev`: the previous `Pr`.
+        - `solverdata`: Optional extra data the solvers can give to the `precs` function.
+            Solver-dependent and subject to change.
+      The return is a tuple `(Pl,Pr)` of the LinearSolve.jl-compatible preconditioners.
+      To specify one-sided preconditioning, simply return `nothing` for the preconditioner
+      which is not used. Additionally, `precs` must supply the dispatch:
+      ```julia
+      Pl, Pr = precs(W, du, u, p, t, ::Nothing, ::Nothing, ::Nothing, solverdata)
+      ```
+      which is used in the solver setup phase to construct the integrator
+      type with the preconditioners `(Pl,Pr)`.
+      The default is `precs=DEFAULT_PRECS` where the default preconditioner function
+      is defined as:
+      ```julia
+      DEFAULT_PRECS(W, du, u, p, t, newW, Plprev, Prprev, solverdata) = nothing, nothing
+      ```
     """ * extra_keyword_default
 
     keyword_default_description = """