From 118352a04d2fc33691a78b4b949a1f752489353a Mon Sep 17 00:00:00 2001 From: houkensjtu Date: Thu, 4 May 2023 20:38:54 +0800 Subject: [PATCH 1/5] Split linear solver article from sparse_matrix.md. --- docs/lang/articles/math/linear_solver.md | 73 ++++++++++++++++++++++++ docs/lang/articles/math/sparse_matrix.md | 63 -------------------- 2 files changed, 73 insertions(+), 63 deletions(-) create mode 100644 docs/lang/articles/math/linear_solver.md diff --git a/docs/lang/articles/math/linear_solver.md b/docs/lang/articles/math/linear_solver.md new file mode 100644 index 0000000000000..c5cd8abdb3ddb --- /dev/null +++ b/docs/lang/articles/math/linear_solver.md @@ -0,0 +1,73 @@ +--- +sidebar_position: 3 +--- + +# Linear Solver + +Solving linear equations is a common task in scientific computing. Taichi provides basic direct and iterative linear solvers for +various simulation scenarios. Currently, there are two categories of linear solvers available: +1. Solvers built for `SparseMatrix` +2. Solvers built for `ti.field` + +## 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 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 `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. + +```python +import taichi as ti + +arch = ti.cpu # or ti.cuda +ti.init(arch=arch) + +n = 4 + +K = ti.linalg.SparseMatrixBuilder(n, n, max_num_triplets=100) +b = ti.ndarray(ti.f32, shape=n) + +@ti.kernel +def fill(A: ti.types.sparse_matrix_builder(), b: ti.template(), interval: ti.i32): + for i in range(n): + A[i, i] += 2.0 + + if i % interval == 0: + b[i] += 1.0 + +fill(K, b, 3) + +A = K.build() +print(">>>> Matrix A:") +print(A) +print(">>>> Vector b:") +print(b) +# outputs: +# >>>> Matrix A: +# [2, 0, 0, 0] +# [0, 2, 0, 0] +# [0, 0, 2, 0] +# [0, 0, 0, 2] +# >>>> Vector b: +# [1. 0. 0. 1.] +solver = ti.linalg.SparseSolver(solver_type="LLT") +solver.analyze_pattern(A) +solver.factorize(A) +x = solver.solve(b) +isSuccess = solver.info() +print(">>>> Solve sparse linear systems Ax = b with the solution x:") +print(x) +print(f">>>> Computation was successful?: {isSuccess}") +# outputs: +# >>>> Solve sparse linear systems Ax = b with the solution x: +# [0.5 0. 0. 0.5] +# >>>> Computation was successful?: True +``` +## Examples + +Please have a look at our two demos for more information: ++ [Stable fluid](https://github.com/taichi-dev/taichi/blob/master/python/taichi/examples/simulation/stable_fluid.py): A 2D fluid simulation using a sparse Laplacian matrix to solve Poisson's pressure equation. ++ [Implicit mass spring](https://github.com/taichi-dev/taichi/blob/master/python/taichi/examples/simulation/implicit_mass_spring.py): A 2D cloth simulation demo using sparse matrices to solve the linear systems. diff --git a/docs/lang/articles/math/sparse_matrix.md b/docs/lang/articles/math/sparse_matrix.md index 2d4df0a61c73d..c26398eb4f375 100644 --- a/docs/lang/articles/math/sparse_matrix.md +++ b/docs/lang/articles/math/sparse_matrix.md @@ -131,66 +131,3 @@ print(f">>>> Element Access: A[0,0] = {A[0,0]}") # outputs: # >>>> Element Access: A[0,0] = 1.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 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 `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. - -```python -import taichi as ti - -arch = ti.cpu # or ti.cuda -ti.init(arch=arch) - -n = 4 - -K = ti.linalg.SparseMatrixBuilder(n, n, max_num_triplets=100) -b = ti.ndarray(ti.f32, shape=n) - -@ti.kernel -def fill(A: ti.types.sparse_matrix_builder(), b: ti.template(), interval: ti.i32): - for i in range(n): - A[i, i] += 2.0 - - if i % interval == 0: - b[i] += 1.0 - -fill(K, b, 3) - -A = K.build() -print(">>>> Matrix A:") -print(A) -print(">>>> Vector b:") -print(b) -# outputs: -# >>>> Matrix A: -# [2, 0, 0, 0] -# [0, 2, 0, 0] -# [0, 0, 2, 0] -# [0, 0, 0, 2] -# >>>> Vector b: -# [1. 0. 0. 1.] -solver = ti.linalg.SparseSolver(solver_type="LLT") -solver.analyze_pattern(A) -solver.factorize(A) -x = solver.solve(b) -isSuccess = solver.info() -print(">>>> Solve sparse linear systems Ax = b with the solution x:") -print(x) -print(f">>>> Computation was successful?: {isSuccess}") -# outputs: -# >>>> Solve sparse linear systems Ax = b with the solution x: -# [0.5 0. 0. 0.5] -# >>>> Computation was successful?: True -``` -## Examples - -Please have a look at our two demos for more information: -+ [Stable fluid](https://github.com/taichi-dev/taichi/blob/master/python/taichi/examples/simulation/stable_fluid.py): A 2D fluid simulation using a sparse Laplacian matrix to solve Poisson's pressure equation. -+ [Implicit mass spring](https://github.com/taichi-dev/taichi/blob/master/python/taichi/examples/simulation/implicit_mass_spring.py): A 2D cloth simulation demo using sparse matrices to solve the linear systems. From 696739549f0b80e2af3920500c8b69a28978ee0e Mon Sep 17 00:00:00 2001 From: Qian Bao Date: Sat, 6 May 2023 10:06:36 +0800 Subject: [PATCH 2/5] Update docs/lang/articles/math/linear_solver.md Co-authored-by: Zhao Liang --- docs/lang/articles/math/linear_solver.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/lang/articles/math/linear_solver.md b/docs/lang/articles/math/linear_solver.md index c5cd8abdb3ddb..3b585def9bc05 100644 --- a/docs/lang/articles/math/linear_solver.md +++ b/docs/lang/articles/math/linear_solver.md @@ -57,10 +57,10 @@ solver = ti.linalg.SparseSolver(solver_type="LLT") solver.analyze_pattern(A) solver.factorize(A) x = solver.solve(b) -isSuccess = solver.info() +success = solver.info() print(">>>> Solve sparse linear systems Ax = b with the solution x:") print(x) -print(f">>>> Computation was successful?: {isSuccess}") +print(f">>>> Computation succeed: {success}") # outputs: # >>>> Solve sparse linear systems Ax = b with the solution x: # [0.5 0. 0. 0.5] From ea5b8c90e501d973dc77fa19218419d586ae38f3 Mon Sep 17 00:00:00 2001 From: Qian Bao Date: Mon, 8 May 2023 16:49:01 +0800 Subject: [PATCH 3/5] Add udpated sparse docs to cover-in-ci.lst. --- docs/cover-in-ci.lst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/cover-in-ci.lst b/docs/cover-in-ci.lst index 420ae0ee214c6..9f25e55ce9d68 100644 --- a/docs/cover-in-ci.lst +++ b/docs/cover-in-ci.lst @@ -31,3 +31,5 @@ docs/lang/articles/visualization/ggui.md docs/lang/articles/visualization/gui_system.md docs/rfcs/20220410-rfc-process.md docs/rfcs/yyyymmdd-rfc-template.md +docs/lang/articles/math/linear_solver.md +docs/lang/articles/math/sparse_matrix.md \ No newline at end of file From 2e5155dc64fbf4ee7ce8f57fb4be3511a4d751db Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Mon, 8 May 2023 08:50:09 +0000 Subject: [PATCH 4/5] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/cover-in-ci.lst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/cover-in-ci.lst b/docs/cover-in-ci.lst index 9f25e55ce9d68..723b95147504a 100644 --- a/docs/cover-in-ci.lst +++ b/docs/cover-in-ci.lst @@ -32,4 +32,4 @@ docs/lang/articles/visualization/gui_system.md docs/rfcs/20220410-rfc-process.md docs/rfcs/yyyymmdd-rfc-template.md docs/lang/articles/math/linear_solver.md -docs/lang/articles/math/sparse_matrix.md \ No newline at end of file +docs/lang/articles/math/sparse_matrix.md From 1bc1435342180d747c5d18cc8b804d4e39b9d161 Mon Sep 17 00:00:00 2001 From: Qian Bao Date: Mon, 8 May 2023 17:59:10 +0800 Subject: [PATCH 5/5] Fix CI test failures in sparse docs. --- docs/lang/articles/math/linear_solver.md | 2 +- docs/lang/articles/math/sparse_matrix.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/lang/articles/math/linear_solver.md b/docs/lang/articles/math/linear_solver.md index 3b585def9bc05..cd852e4d48a93 100644 --- a/docs/lang/articles/math/linear_solver.md +++ b/docs/lang/articles/math/linear_solver.md @@ -31,7 +31,7 @@ K = ti.linalg.SparseMatrixBuilder(n, n, max_num_triplets=100) b = ti.ndarray(ti.f32, shape=n) @ti.kernel -def fill(A: ti.types.sparse_matrix_builder(), b: ti.template(), interval: ti.i32): +def fill(A: ti.types.sparse_matrix_builder(), b: ti.types.ndarray(), interval: ti.i32): for i in range(n): A[i, i] += 2.0 diff --git a/docs/lang/articles/math/sparse_matrix.md b/docs/lang/articles/math/sparse_matrix.md index c26398eb4f375..780ae4c08d390 100644 --- a/docs/lang/articles/math/sparse_matrix.md +++ b/docs/lang/articles/math/sparse_matrix.md @@ -56,7 +56,7 @@ print(A) The basic operations like `+`, `-`, `*`, `@` and transpose of sparse matrices are supported now. -```python +```python cont print(">>>> Summation: C = A + A") C = A + A print(C)