From d8b003703d292d4bfbeb7a83c70bbf970b63107d Mon Sep 17 00:00:00 2001
From: Fredrik Ekre <ekrefredrik@gmail.com>
Date: Wed, 27 Jul 2022 13:48:28 +0200
Subject: [PATCH] Document single-process usage with SparseMatrixCS(C|R) as the
 matrix.

---
 docs/Manifest.toml              |  8 +++---
 docs/src/hypre-matrix-vector.md | 43 +++++++++++++++++++++++++++++----
 2 files changed, 42 insertions(+), 9 deletions(-)

diff --git a/docs/Manifest.toml b/docs/Manifest.toml
index 8c63045..70933a5 100644
--- a/docs/Manifest.toml
+++ b/docs/Manifest.toml
@@ -49,8 +49,8 @@ version = "0.8.6"
 
 [[deps.Documenter]]
 deps = ["ANSIColoredPrinters", "Base64", "Dates", "DocStringExtensions", "IOCapture", "InteractiveUtils", "JSON", "LibGit2", "Logging", "Markdown", "REPL", "Test", "Unicode"]
-git-tree-sha1 = "7c98cab82668f33299b195c1940690b2ec3a0ac2"
-repo-rev = "master"
+git-tree-sha1 = "c2cc31489a9ed6c602810c5ca298a3c3002510c5"
+repo-rev = "fe/mindepth"
 repo-url = "https://github.com/JuliaDocs/Documenter.jl.git"
 uuid = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 version = "0.28.0-DEV"
@@ -67,9 +67,9 @@ version = "1.0.0"
 
 [[deps.HYPRE_jll]]
 deps = ["Artifacts", "JLLWrappers", "LAPACK_jll", "LazyArtifacts", "Libdl", "MPICH_jll", "MPIPreferences", "MPItrampoline_jll", "MicrosoftMPI_jll", "OpenBLAS_jll", "OpenMPI_jll", "Pkg", "TOML"]
-git-tree-sha1 = "ed07e4165a837e4606bc5dfbb6536ab0ec798ab8"
+git-tree-sha1 = "b77d3eca75f8442e034ccf415c87405a49e77985"
 uuid = "0a602bbd-b08b-5d75-8d32-0de6eef44785"
-version = "2.23.0+1"
+version = "2.23.1+1"
 
 [[deps.IOCapture]]
 deps = ["Logging", "Random"]
diff --git a/docs/src/hypre-matrix-vector.md b/docs/src/hypre-matrix-vector.md
index 651fa37..0bc30a1 100644
--- a/docs/src/hypre-matrix-vector.md
+++ b/docs/src/hypre-matrix-vector.md
@@ -6,7 +6,12 @@ Interface](https://hypre.readthedocs.io/en/latest/api-int-ij.html) which can be
 general sparse matrices.
 
 HYPRE.jl defines conversion methods from standard Julia datastructures to `HYPREMatrix` and
-`HYPREVector`, respectively.
+`HYPREVector`, respectively. See the following sections for details:
+
+```@contents
+Pages = ["hypre-matrix-vector.md"]
+MinDepth = 2
+```
 
 ## PartitionedArrays.jl (multi-process)
 
@@ -15,11 +20,11 @@ HYPRE.jl integrates seemlessly with `PSparseMatrix` and `PVector` from the
 be passed directly to `solve` and `solve!`. Internally this will construct a `HYPREMatrix`
 and `HYPREVector`s and then convert the solution back to a `PVector`.
 
-The `HYPREMatrix` constructor supports both `SparseMatrixCSC` and `SparseMatrixCSR` as
+The `HYPREMatrix` constructor support both `SparseMatrixCSC` and `SparseMatrixCSR` as
 storage backends for the `PSparseMatrix`. However, since HYPREs internal storage is also CSR
 based it can be *slightly* more resource efficient to use `SparseMatrixCSR`.
 
-The constructors also supports both PartitionedArrays.jl backends: When using the `MPI`
+The constructors also support both PartitionedArrays.jl backends: When using the `MPI`
 backend the communicator of the `PSparseMatrix`/`PVector` is used also for the
 `HYPREMatrix`/`HYPREVector`, and when using the `Sequential` backend it is assumed to be a
 single-process setup, and the global communicator `MPI.COMM_WORLD` is used.
@@ -68,9 +73,37 @@ copy!(x, x_h)
 
 ## `SparseMatrixCSC` / `SparseMatrixCSR` (single-process)
 
+HYPRE.jl also support working directly with `SparseMatrixCSC` (from the
+[SparseArrays.jl](https://github.com/JuliaSparse/SparseArrays.jl) standard library) and
+`SparseMatrixCSR` (from the
+[SparseMatricesCSR.jl](https://github.com/gridap/SparseMatricesCSR.jl) package). This makes
+it possible to use solvers and preconditioners even for single-process problems. When using
+these type of spars matrices it is assumed that the right hand side and solution vectors are
+regular Julia `Vector`s.
+
+Just like when using the PartitionedArrays.jl package, it is possible to pass sparse
+matrices directly to `solve` and `solve!`, but it is also possible to create `HYPREMatrix`
+and `HYPREVector` explicitly, possibly saving some resources when doing multiple consecutive
+linear solves (see previous section).
+
+**Example pseudocode**
+
+```julia
+A = SparseMatrixCSC(...)
+x = Vector(...)
+b = Vector(...)
+
+# Solve with zero initial guess
+x = solve(solver, A, b)
+
+# Inplace solve with x as initial guess
+x = zeros(length(b))
+solve!(solver, x, A, b)
+```
+
 
 ## `SparseMatrixCSC` / `SparseMatrixCSR` (multi-process)
 
 !!! warning
-    This interface isn't finalized yet and is subject to change.
-
+    This interface isn't finalized yet and is therefore not documented since it
+    is subject to change.