update the documentation and format

Co-authored-by: Marcel Koch <marcel.koch@kit.edu>
Co-authored-by: Pratik Nayak <pratikvn@protonmail.com>

common/unified/preconditioner/jacobi_kernels.cpp

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: 2017 - 2024 The Ginkgo authors
+// SPDX-FileCopyrightText: 2017 - 2025 The Ginkgo authors
 //
 // SPDX-License-Identifier: BSD-3-Clause
 
@@ -140,6 +140,9 @@ void scalar_l1(std::shared_ptr<const DefaultExecutor> exec,
                 }
                 off_diag += abs(vals[i]);
             }
+            // TODO: It is unclear effect when this applies to negative diagonal
+            // value. The reference paper only discusses the positive diagonal
+            // value.
             diag[row] += off_diag;
         },
         csr->get_size()[0], csr->get_const_row_ptrs(),
@@ -179,6 +182,9 @@ void block_l1(std::shared_ptr<const DefaultExecutor> exec, size_type num_blocks,
                     }
                     off_diag += abs(vals[i]);
                 }
+                // TODO: It is unclear effect when this applies to negative
+                // diagonal value. The reference paper only discusses the
+                // positive diagonal value.
                 vals[diag_idx] += off_diag;
             }
         },

core/preconditioner/jacobi.cpp

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: 2017 - 2024 The Ginkgo authors
+// SPDX-FileCopyrightText: 2017 - 2025 The Ginkgo authors
 //
 // SPDX-License-Identifier: BSD-3-Clause
 

core/preconditioner/jacobi_kernels.hpp

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: 2017 - 2024 The Ginkgo authors
+// SPDX-FileCopyrightText: 2017 - 2025 The Ginkgo authors
 //
 // SPDX-License-Identifier: BSD-3-Clause
 

core/test/config/preconditioner.cpp

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: 2017 - 2024 The Ginkgo authors
+// SPDX-FileCopyrightText: 2017 - 2025 The Ginkgo authors
 //
 // SPDX-License-Identifier: BSD-3-Clause
 

core/test/preconditioner/jacobi.cpp

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: 2017 - 2024 The Ginkgo authors
+// SPDX-FileCopyrightText: 2017 - 2025 The Ginkgo authors
 //
 // SPDX-License-Identifier: BSD-3-Clause
 

include/ginkgo/core/preconditioner/jacobi.hpp

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: 2017 - 2024 The Ginkgo authors
+// SPDX-FileCopyrightText: 2017 - 2025 The Ginkgo authors
 //
 // SPDX-License-Identifier: BSD-3-Clause
 
@@ -373,9 +373,14 @@ class Jacobi : public EnableLinOp<Jacobi<ValueType, IndexType>>,
 
         /**
          * Use L1 Jacboi, which is introduced in the paper A. H. Baker et al.
-         * "Multigrid smoothers for ultraparallel computing."
-         * If it is true, it generates the preconditioner on A + Diag(sum_{k in
-         * off diagonal block of i} A_ik) not A.
+         * "Multigrid smoothers for ultraparallel computing." This paper
+         * discusses this type of smoother with the following matrix property.
+         * $ A_{ii} \geq \theta \sum_{j \in \text{off diagonal block}} |A_{ij}|,
+         * \theta \geq 0 $
+         * If it is true, it generates the preconditioner on A +
+         * Diag(sum_{k in off-diagonal block of i} |A_ik|) instead of A. We
+         * aggregate the absolute value of the entries with the same row in the
+         * off-diagonal block into the diagonal value.
          */
         bool GKO_FACTORY_PARAMETER_SCALAR(aggregate_l1, false);
 

reference/preconditioner/jacobi_kernels.cpp

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: 2017 - 2024 The Ginkgo authors
+// SPDX-FileCopyrightText: 2017 - 2025 The Ginkgo authors
 //
 // SPDX-License-Identifier: BSD-3-Clause
 
@@ -738,6 +738,9 @@ void scalar_l1(std::shared_ptr<const DefaultExecutor> exec,
             }
             off_diag += abs(csr->get_const_values()[i]);
         }
+        // TODO: It is unclear effect when this applies to negative diagonal
+        // value. The reference paper only discusses the positive diagonal
+        // value.
         diag->get_values()[row] += off_diag;
     }
 }
@@ -768,6 +771,9 @@ void block_l1(std::shared_ptr<const DefaultExecutor> exec, size_type num_blocks,
                 }
                 off_diag += abs(csr->get_const_values()[i]);
             }
+            // TODO: It is unclear effect when this applies to negative diagonal
+            // value. The reference paper only discusses the positive diagonal
+            // value.
             csr->get_values()[diag_idx] += off_diag;
         }
     }

reference/test/preconditioner/jacobi_kernels.cpp

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: 2017 - 2024 The Ginkgo authors
+// SPDX-FileCopyrightText: 2017 - 2025 The Ginkgo authors
 //
 // SPDX-License-Identifier: BSD-3-Clause
 
@@ -138,7 +138,7 @@ TYPED_TEST(Jacobi, FindsNaturalBlocks)
     using Mtx = typename TestFixture::Mtx;
     using index_type = typename TestFixture::index_type;
     using value_type = typename TestFixture::value_type;
-    auto mtx = Mtx::create(this->exec, gko::dim<2>{4}, 8);
+    auto mtx = Mtx::create(this->exec, gko::dim<2>{4, 4}, 8);
     this->template init_array<index_type>(mtx->get_row_ptrs(), {0, 2, 4, 6, 8});
     this->template init_array<index_type>(mtx->get_col_idxs(),
                                           {0, 1, 0, 1, 0, 2, 0, 2});
@@ -1119,15 +1119,15 @@ TYPED_TEST(Jacobi, ConvertsEmptyToDense)
 TYPED_TEST(Jacobi, ScalarL1Diag)
 {
     /* example matrix:
-        1   1
-        2   2
-       -5       1
-        1      -1
+        1   1   0   0
+        2   2   0   0
+       -5   0   1   0
+        1   0  -1   0
      */
     using Mtx = typename TestFixture::Mtx;
     using index_type = typename TestFixture::index_type;
     using value_type = typename TestFixture::value_type;
-    auto mtx = Mtx::create(this->exec, gko::dim<2>{4}, 8);
+    auto mtx = Mtx::create(this->exec, gko::dim<2>{4, 4}, 8);
     this->template init_array<index_type>(mtx->get_row_ptrs(), {0, 2, 4, 6, 8});
     this->template init_array<index_type>(mtx->get_col_idxs(),
                                           {0, 1, 0, 1, 0, 2, 0, 2});
@@ -1149,15 +1149,17 @@ TYPED_TEST(Jacobi, ScalarL1Diag)
 TYPED_TEST(Jacobi, BlockL1)
 {
     /* example matrix:
-        1   1
-        2   2
-       -5       1
-        1      -1   1
+        1 | 1
+       ---+---+
+        2 | 2 |
+          +---+--------
+       -5     |  1
+        1     | -1   1
      */
     using Mtx = typename TestFixture::Mtx;
     using index_type = typename TestFixture::index_type;
     using value_type = typename TestFixture::value_type;
-    auto mtx = Mtx::create(this->exec, gko::dim<2>{4}, 9);
+    auto mtx = Mtx::create(this->exec, gko::dim<2>{4, 4}, 9);
     this->template init_array<index_type>(mtx->get_row_ptrs(), {0, 2, 4, 6, 9});
     this->template init_array<index_type>(mtx->get_col_idxs(),
                                           {0, 1, 0, 1, 0, 2, 0, 2, 3});

test/preconditioner/jacobi_kernels.cpp

@@ -1,4 +1,4 @@
-// SPDX-FileCopyrightText: 2017 - 2024 The Ginkgo authors
+// SPDX-FileCopyrightText: 2017 - 2025 The Ginkgo authors
 //
 // SPDX-License-Identifier: BSD-3-Clause
 
@@ -257,7 +257,7 @@ TEST_F(Jacobi,
 }
 
 
-TEST_F(Jacobi, ScalarInLargeMatrixEquivalentToRef)
+TEST_F(Jacobi, ScalarL1InLargeMatrixEquivalentToRef)
 {
     /* example matrix:
         1   1
@@ -287,11 +287,11 @@ TEST_F(Jacobi, ScalarInLargeMatrixEquivalentToRef)
 TEST_F(Jacobi, BlockL1InLargeMatrixEquivalentToRef)
 {
     /* example matrix duplicated 50 times:
-        1   1       1
-        1   1       1
-        1       1   1
-        1       1   1
-        1       1
+        1   1   0   1   0
+        1   1   0   1   0
+        1   0   1   1   0
+        1   0   1   1   0
+        1   0   1   0   0
      */
     using data = gko::matrix_data<double, int>;
     auto mtx = share(Mtx::create(ref));