Finish diagnostics API tutorial

Author: avik-pal

docs/pages.jl

@@ -26,7 +26,7 @@ pages = ["index.md",
         "native/steadystatediffeq.md",
         "native/descent.md",
         "native/globalization.md",
-        "native/diagnostics.md",],
+        "native/diagnostics.md"],
     "Wrapped Solver APIs" => Any["api/fastlevenbergmarquardt.md",
         "api/fixedpointacceleration.md",
         "api/leastsquaresoptim.md",

docs/src/basics/diagnostics_api.md

@@ -1,9 +1,9 @@
 # [Diagnostics API](@id diagnostics_api)
 
 Detailed API Documentation is provided at
-[Diagonstics API Reference](@ref diagnostics_api_reference).
+[Diagnostics API Reference](@ref diagnostics_api_reference).
 
-# Logging the Solve Process
+## Logging the Solve Process
 
 All NonlinearSolve.jl native solvers allow storing and displaying the trace of the nonlinear
 solve process. This is controlled by 3 keyword arguments to `solve`:
@@ -16,9 +16,17 @@ solve process. This is controlled by 3 keyword arguments to `solve`:
  3. `store_trace`: Must be `Val(true)` or `Val(false)`. This controls whether the trace is
     stored in the solution object. (Defaults to `Val(false)`)
 
+## Detailed Internal Timings
+
+All the native NonlinearSolve.jl algorithms come with in-built
+[TimerOutputs.jl](https://github.com/KristofferC/TimerOutputs.jl) support. However, this
+is disabled by default and can be enabled via [`NonlinearSolve.enable_timer_outputs`](@ref).
+
+Note that you will have to restart Julia to disable the timer outputs once enabled.
+
 ## Example Usage
 
-```@example tracing
+```@example diagnostics_example
 using ModelingToolkit, NonlinearSolve
 
 @variables x y z
@@ -42,19 +50,37 @@ solve(prob)
 This produced the output, but it is hard to diagnose what is going on. We can turn on
 the trace to see what is happening:
 
-```@example tracing
+```@example diagnostics_example
 solve(prob; show_trace = Val(true), trace_level = TraceAll(10))
 nothing; # hide
 ```
 
 You can also store the trace in the solution object:
 
-```@example tracing
+```@example diagnostics_example
 sol = solve(prob; trace_level = TraceAll(), store_trace = Val(true));
 
 sol.trace
 ```
 
+Now, let's try to investigate the time it took for individual internal steps. We will have
+to use the `init` and `solve!` API for this. The `TimerOutput` will be present in
+`cache.timer`. However, note that for poly-algorithms this is currently not implemented.
+
+```@example diagnostics_example
+cache = init(prob, NewtonRaphson(); show_trace = Val(true));
+solve!(cache)
+cache.timer
+```
+
+Let's try for some other solver:
+
+```@example diagnostics_example
+cache = init(prob, DFSane(); show_trace = Val(true), trace_level = TraceMinimal(50));
+solve!(cache)
+cache.timer
+```
+
 !!! note
 
     For `iteration == 0` only the `norm(fu, Inf)` is guaranteed to be meaningful. The other

docs/src/basics/faq.md

@@ -77,8 +77,8 @@ sol = solve(prob_oop, LevenbergMarquardt(; autodiff = AutoFiniteDiff()); maxiter
 
 This worked but, Finite Differencing is not the recommended approach in any scenario.
 
-  2. Rewrite the function to use
-[PreallocationTools.jl](https://github.com/SciML/PreallocationTools.jl) or write it as
+ 2. Rewrite the function to use
+    [PreallocationTools.jl](https://github.com/SciML/PreallocationTools.jl) or write it as
 
 ```@example dual_error_faq
 function fff_correct(var, p)
@@ -144,8 +144,8 @@ nothing # hide
 
 And boom! Type stable again. For selecting the chunksize the method is:
 
-  1. For small inputs `≤ 12` use `chunksize = <length of input>`
-  2. For larger inputs, use `chunksize = 12`
+ 1. For small inputs `≤ 12` use `chunksize = <length of input>`
+ 2. For larger inputs, use `chunksize = 12`
 
 In general, the chunksize should be `≤ length of input`. However, a very large chunksize
 can lead to excessive compilation times and slowdown.

docs/src/native/simplenonlinearsolve.md

@@ -26,25 +26,18 @@ These methods are suited for any general nonlinear root-finding problem, i.e.
 `NonlinearProblem`.
 
 | Solver                               | In-place | Out of Place | Non-Allocating (Scalars) | Non-Allocating (`SArray`) |
-| ------------------------------------ | -------- | ------------ | ------------------------ | ------------------------- |
-| [`SimpleNewtonRaphson`](@ref)        | ✔️        | ✔️            | ✔️                        | ✔️                         |
-| [`SimpleBroyden`](@ref)              | ✔️        | ✔️            | ✔️                        | ✔️                         |
-| [`SimpleHalley`](@ref)               | ❌        | ✔️            | ✔️                        | ❌                         |
-| [`SimpleKlement`](@ref)              | ✔️        | ✔️            | ✔️                        | ✔️                         |
-| [`SimpleTrustRegion`](@ref)          | ✔️        | ✔️            | ✔️                        | ✔️                         |
-| [`SimpleDFSane`](@ref)               | ✔️        | ✔️            | ✔️[^1]                    | ✔️                         |
-| [`SimpleLimitedMemoryBroyden`](@ref) | ✔️        | ✔️            | ✔️                        | ✔️[^2]                     |
+|:------------------------------------ |:-------- |:------------ |:------------------------ |:------------------------- |
+| [`SimpleNewtonRaphson`](@ref)        | ✔️       | ✔️           | ✔️                       | ✔️                        |
+| [`SimpleBroyden`](@ref)              | ✔️       | ✔️           | ✔️                       | ✔️                        |
+| [`SimpleHalley`](@ref)               | ❌        | ✔️           | ✔️                       | ❌                         |
+| [`SimpleKlement`](@ref)              | ✔️       | ✔️           | ✔️                       | ✔️                        |
+| [`SimpleTrustRegion`](@ref)          | ✔️       | ✔️           | ✔️                       | ✔️                        |
+| [`SimpleDFSane`](@ref)               | ✔️       | ✔️           | ✔️[^1]                   | ✔️                        |
+| [`SimpleLimitedMemoryBroyden`](@ref) | ✔️       | ✔️           | ✔️                       | ✔️[^2]                    |
 
 The algorithms which are non-allocating can be used directly inside GPU Kernels[^3].
 See [PSOGPU.jl](https://github.com/SciML/PSOGPU.jl) for more details.
 
-[^1]: Needs [`StaticArrays.jl`](https://github.com/JuliaArrays/StaticArrays.jl) to be
-      installed and loaded for the non-allocating version.
-[^2]: This method is non-allocating if the termination condition is set to either `nothing`
-      (default) or [`AbsNormTerminationMode`](@ref).
-[^3]: Only the defaults are guaranteed to work inside kernels. We try to provide warnings
-      if the used version is not non-allocating.
-
 ```@docs
 SimpleNewtonRaphson
 SimpleBroyden
@@ -57,3 +50,10 @@ SimpleLimitedMemoryBroyden
 
 `SimpleGaussNewton` is aliased to [`SimpleNewtonRaphson`](@ref) for solving Nonlinear Least
 Squares problems.
+
+[^1]: Needs [`StaticArrays.jl`](https://github.com/JuliaArrays/StaticArrays.jl) to be
+    installed and loaded for the non-allocating version.
+[^2]: This method is non-allocating if the termination condition is set to either `nothing`
+    (default) or [`AbsNormTerminationMode`](@ref).
+[^3]: Only the defaults are guaranteed to work inside kernels. We try to provide warnings
+    if the used version is not non-allocating.

src/algorithms/levenberg_marquardt.jl

@@ -24,7 +24,7 @@ nonlinear systems.
     a minimum value of the elements in `DᵀD` to prevent the damping from being too small.
     Defaults to `1e-8`.
   - `disable_geodesic`: Disables Geodesic Acceleration if set to `Val(true)`. It provides
-    a way to trade-off robustness for speed, though in most sitations Geodesic Acceleration
+    a way to trade-off robustness for speed, though in most situations Geodesic Acceleration
     should not be disabled.
 
 For the remaining arguments, see [`GeodesicAcceleration`](@ref) and

src/utils.jl

@@ -120,6 +120,7 @@ end
 Statistics from the nonlinear equation solver about the solution process.
 
 ## Fields
+
   - nf: Number of function evaluations.
   - njacs: Number of Jacobians created during the solve.
   - nfactors: Number of factorzations of the jacobian required for the solve.