docs

Author: vpuri3

docs/make.jl

@@ -29,6 +29,7 @@ makedocs(
         ],
         "Advanced" => Any[
             "advanced/developing.md"
+            "advanced/custom.md"
         ]
     ]
 )

docs/src/advanced/custom.md

@@ -0,0 +1,55 @@
+# Passing in a Custom Linear Solver
+Julia users are constantly a wide variety of applications in the SciML ecosystem,
+often requiring custom handling. As existing solvers in `LinearSolve.jl` may not
+be optimally suited for novel applications, it is essential for the linear solve
+interface to be easily extendable by users. To that end, the linear solve algorithm
+`LinearSolveFunction()` accepts a user-defined function for handling the solve. A
+user can pass in their custom linear solve function, say `my_linsolve`, to
+`LinearSolveFunction()`. A contrived example of solving a linear system with a custom solver is below.
+```julia
+using LinearSolve, LinearAlgebra
+
+function my_linsolve(A,b,u,p,newA,Pl,Pr,solverdata;verbose=true, kwargs...)
+    if verbose == true
+        println("solving Ax=b")
+    end
+    u = A \ b
+    return u
+end
+
+prob = LinearProblem(Diagonal(rand(4)), rand(4))
+alg  = LinearSolveFunction(my_linsolve),
+sol  = solve(prob, alg)
+```
+The inputs to the function are as follows:
+- `A`, the linear operator
+- `b`, the right-hand-side
+- `u`, the solution initialized as `zero(b)`,
+- `p`, a set of parameters
+- `newA`, a `Bool` which is `true` if `A` has been modified since last solve
+- `Pl`, left-preconditioner
+- `Pr`, right-preconditioner
+- `solverdata`, solver cache set to `nothing` if solver hasn't been initialized
+- `kwargs`, standard SciML keyword arguments such as `verbose`, `maxiters`,
+`abstol`, `reltol`
+The function `my_linsolve` must accept the above specified arguments, and return
+the solution, `u`. As memory for `u` is already allocated, the user may choose
+to modify `u` in place as follows:
+```julia
+function my_linsolve!(A,b,u,p,newA,Pl,Pr,solverdata;verbose=true, kwargs...)
+    if verbose == true
+        println("solving Ax=b")
+    end
+    u .= A \ b # in place
+    return u
+end
+
+alg  = LinearSolveFunction(my_linsolve!)
+sol  = solve(prob, alg)
+```
+Finally, note that `LinearSolveFunction()` dispatches to the default linear solve
+algorithm handling if no arguments are passed in.
+```julia
+alg = LinearSolveFunction()
+sol = solve(prob, alg) # same as solve(prob, nothing)
+```

docs/src/solvers/solvers.md

@@ -21,9 +21,13 @@ As sparse matrices get larger, iterative solvers tend to get more efficient than
 factorization methods if a lower tolerance of the solution is required.
 IterativeSolvers.jl uses a low-rank Q update in its GMRES so it tends to be
 faster than Krylov.jl for CPU-based arrays, but it's only compatible with
-CPU-based arrays whilc Krylov.jl is more general and will support accelerators
+CPU-based arrays while Krylov.jl is more general and will support accelerators
 like CUDA.
 
+Finally, a user can pass a custom function ofr the linear solve using
+`LinearSolveFunction()` if existing solvers are not optimal for their application.
+The interface is detailed [here](#passing-in-a-custom-linear-solver)
+
 ## Full List of Methods
 
 ### RecursiveFactorization.jl