From e4a112908b6e4e463ac8e7ac78b0f1059e96f74f Mon Sep 17 00:00:00 2001
From: pengyu <6712304+FantasyVR@users.noreply.github.com>
Date: Wed, 30 Nov 2022 16:37:27 +0800
Subject: [PATCH] [doc] Cherrypicks sparse matrix doc changes into v1.3.0
 release branch (#6770)

### Brief Summary
Cherrypicks https://github.com/taichi-dev/taichi/pull/6719 into v1.3.0
release branch

Co-authored-by: Olinaaaloompa <106292061+Olinaaaloompa@users.noreply.github.com>
Co-authored-by: Yi Xu <xy_xuyi@foxmail.com>
---
 docs/lang/articles/math/sparse_matrix.md | 27 ++++++++++++------------
 1 file changed, 14 insertions(+), 13 deletions(-)

diff --git a/docs/lang/articles/math/sparse_matrix.md b/docs/lang/articles/math/sparse_matrix.md
index 49f86cfe62d54..2d4df0a61c73d 100644
--- a/docs/lang/articles/math/sparse_matrix.md
+++ b/docs/lang/articles/math/sparse_matrix.md
@@ -4,25 +4,25 @@ sidebar_position: 2
 
 # Sparse Matrix
 
-Sparse matrices are frequently used when solving linear systems in science and engineering. Taichi provides programmers with useful APIs for sparse matrices.
+Sparse matrices are frequently involved in solving linear systems in science and engineering. Taichi provides useful APIs for sparse matrices on the CPU and CUDA backends.
 
-To use the sparse matrix in taichi programs, you should follow these three steps:
+To use sparse matrices in Taichi programs, follow these three steps:
 
 1. Create a `builder` using `ti.linalg.SparseMatrixBuilder()`.
-2. Fill the `builder` with your matrices' data.
-3. Create sparse matrices from the `builder`.
+2. Call `ti.kernel` to fill the `builder` with your matrices' data.
+3. Build sparse matrices from the `builder`.
 
 :::caution WARNING
-The sparse matrix is still under implementation. There are some limitations:
+The sparse matrix feature is still under development. There are some limitations:
+- The sparse matrix data type on the CPU backend only supports `f32` and `f64`.
+- The sparse matrix data type on the CUDA backend only supports `f32`.
 
-- Only the CPU backend is supported.
-- The data type of sparse matrix is float32.
-- The storage format is column-major
 :::
 Here's an example:
 ```python
 import taichi as ti
-ti.init(arch=ti.x64) # only CPU backend is supported for now
+arch = ti.cpu # or ti.cuda
+ti.init(arch=arch)
 
 n = 4
 # step 1: create sparse matrix builder
@@ -135,9 +135,9 @@ print(f">>>> Element Access: A[0,0] = {A[0,0]}")
 ## Sparse linear solver
 You may want to solve some linear equations using sparse matrices.
 Then, the following steps could help:
-1. Create a `solver` using `ti.linalg.SparseSolver(solver_type, ordering)`. Currently, the sparse solver supports `LLT`, `LDLT` and `LU` factorization types, and orderings including `AMD`, `COLAMD`.
+1. Create a `solver` using `ti.linalg.SparseSolver(solver_type, ordering)`. Currently, the factorization types supported on CPU backends are `LLT`, `LDLT`, and `LU`, and supported orderings include `AMD` and `COLAMD`. The sparse solver on CUDA supports the `LLT` factorization type only.
 2. Analyze and factorize the sparse matrix you want to solve using `solver.analyze_pattern(sparse_matrix)` and `solver.factorize(sparse_matrix)`
-3. Call `solver.solve(b)` to get your solutions, where `b` is a numpy array or taichi filed representing the right-hand side of the linear system.
+3. Call `x = solver.solve(b)`, where `x` is the solution and `b` is the right-hand side of the linear system. On CPU backends, `x` and `b` can be NumPy arrays, Taichi Ndarrays, or Taichi fields. On the CUDA backend, `x` and `b` *must* be Taichi Ndarrays.
 4. Call `solver.info()` to check if the solving process succeeds.
 
 Here's a full example.
@@ -145,12 +145,13 @@ Here's a full example.
 ```python
 import taichi as ti
 
-ti.init(arch=ti.x64)
+arch = ti.cpu # or ti.cuda
+ti.init(arch=arch)
 
 n = 4
 
 K = ti.linalg.SparseMatrixBuilder(n, n, max_num_triplets=100)
-b = ti.field(ti.f32, shape=n)
+b = ti.ndarray(ti.f32, shape=n)
 
 @ti.kernel
 def fill(A: ti.types.sparse_matrix_builder(), b: ti.template(), interval: ti.i32):