use doxygen math \f$, and some doc descriptions

Author: pratikvn

include/ginkgo/core/base/lin_op.hpp

@@ -69,22 +69,22 @@ class Diagonal;
  * and preconditioners is that the most common operation performed on all of
  * them can be expressed as an application of a linear operator to a vector:
  *
- * +   the sparse matrix-vector product with a matrix $A$ is a linear
- *     operator application $y = Ax$;
+ * +   the sparse matrix-vector product with a matrix \f$A\f$ is a linear
+ *     operator application \f$y = Ax\f$;
  * +   the application of a preconditioner is a linear operator application
- *     $y = M^{-1}x$, where $M$ is an approximation of the original
- *     system matrix $A$ (thus a preconditioner represents an "approximate
- *     inverse" operator $M^{-1}$).
- * +   the system solve $Ax = b$ can be viewed as linear operator
+ *     \f$y = M^{-1}x\f$, where \f$M\f$ is an approximation of the original
+ *     system matrix \f$A\f$ (thus a preconditioner represents an "approximate
+ *     inverse" operator \f$M^{-1}\f$).
+ * +   the system solve \f$Ax = b\f$ can be viewed as linear operator
  *     application
- *     $x = A^{-1}b$ (it goes without saying that the implementation of
+ *     \f$x = A^{-1}b\f$ (it goes without saying that the implementation of
  *     linear system solves does not follow this conceptual idea), so a linear
  *     system solver can be viewed as a representation of the operator
- *     $A^{-1}$.
+ *     \f$A^{-1}\f$.
  *
  * Finally, direct manipulation of LinOp objects is rarely required in
  * simple scenarios. As an illustrative example, one could construct a
- * fixed-point iteration routine $x_{k+1} = Lx_k + b$ as follows:
+ * fixed-point iteration routine \f$x_{k+1} = Lx_k + b\f$ as follows:
  *
  * ```cpp
  * std::unique_ptr<matrix::Dense<>> calculate_fixed_point(
@@ -103,9 +103,9 @@ class Diagonal;
  * }
  * ```
  *
- * Here, if $L$ is a matrix, LinOp::apply() refers to the matrix vector
- * product, and `L->apply(a, b)` computes $b = L \cdot a$.
- * `x->add_scaled(one, b)` is the `axpy` vector update $x:=x+b$.
+ * Here, if \f$L\f$ is a matrix, LinOp::apply() refers to the matrix vector
+ * product, and `L->apply(a, b)` computes \f$b = L \cdot a\f$.
+ * `x->add_scaled(one, b)` is the `axpy` vector update \f$x:=x+b\f$.
  *
  * The interesting part of this example is the apply() routine at line 4 of the
  * function body. Since this routine is part of the LinOp base class, the
@@ -291,34 +291,34 @@ class LinOp : public EnableAbstractPolymorphicObject<LinOp> {
  * linear operator into another.
  *
  * In Ginkgo, every linear solver is viewed as a mapping. For example,
- * given an s.p.d linear system $Ax = b$, the solution $x = A^{-1}b$
+ * given an s.p.d linear system \f$Ax = b\f$, the solution \f$x = A^{-1}b\f$
  * can be computed using the CG method. This algorithm can be represented in
  * terms of linear operators and mappings between them as follows:
  *
  * -   A Cg::Factory is a higher order mapping which, given an input operator
- *     $A$, returns a new linear operator $A^{-1}$ stored in "CG
+ *     \f$A\f$, returns a new linear operator \f$A^{-1}\f$ stored in "CG
  *     format"
- * -   Storing the operator $A^{-1}$ in "CG format" means that the data
+ * -   Storing the operator \f$A^{-1}\f$ in "CG format" means that the data
  *     structure used to store the operator is just a simple pointer to the
- *     original matrix $A$. The application $x = A^{-1}b$ of such an
+ *     original matrix \f$A\f$. The application \f$x = A^{-1}b\f$ of such an
  *     operator can then be implemented by solving the linear system
- *     $Ax = b$ using the CG method. This is achieved in code by having a
+ *     \f$Ax = b\f$ using the CG method. This is achieved in code by having a
  *     special class for each of those "formats" (e.g. the "Cg" class defines
  *     such a format for the CG solver).
  *
  * Another example of a LinOpFactory is a preconditioner. A preconditioner for
- * a linear operator $A$ is a linear operator $M^{-1}$, which
- * approximates $A^{-1}$. In addition, it is stored in a way such that
- * both the data of $M^{-1}$ is cheap to compute from $A$, and the
- * operation $x = M^{-1}b$ can be computed quickly. These operators are
+ * a linear operator \f$A\f$ is a linear operator \f$M^{-1}\f$, which
+ * approximates \f$A^{-1}\f$. In addition, it is stored in a way such that
+ * both the data of \f$M^{-1}\f$ is cheap to compute from \f$A\f$, and the
+ * operation \f$x = M^{-1}b\f$ can be computed quickly. These operators are
  * useful to accelerate the convergence of  Krylov solvers.
  * Thus, a preconditioner also fits into the LinOpFactory framework:
  *
- * -   The factory maps a linear operator $A$ into a preconditioner
- *     $M^{-1}$ which is stored in suitable format (e.g. as a product of
+ * -   The factory maps a linear operator \f$A\f$ into a preconditioner
+ *     \f$M^{-1}\f$ which is stored in suitable format (e.g. as a product of
  *     two factors in case of ILU preconditioners).
  * -   The resulting linear operator implements the application operation
- *     $x = M^{-1}b$ depending on the format the preconditioner is stored
+ *     \f$x = M^{-1}b\f$ depending on the format the preconditioner is stored
  *     in (e.g. as two triangular solves in case of ILU)
  *
  * Example: using CG in Ginkgo
@@ -372,7 +372,7 @@ class LinOpFactory
  * conjugate transpose.
  *
  * The normal transpose returns the transpose of the linear operator without
- * changing any of its elements representing the operation, $B = A^{T}$.
+ * changing any of its elements representing the operation, \f$B = A^{T}\f$.
  *
  * The conjugate transpose returns the conjugate of each of the elements and
  * additionally transposes the linear operator representing the operation, $B
@@ -451,7 +451,7 @@ class Permutable {
      * value `(perm[i],perm[j])`.
      *
      * From the linear algebra perspective, with $P_{ij} = \delta_{i
-     * \pi(i)}$, this represents the operation $P A P^T$.
+     * \pi(i)}$, this represents the operation \f$P A P^T\f$.
      *
      * @param permutation_indices  the array of indices containing the
      *                             permutation order.
@@ -472,7 +472,7 @@ class Permutable {
      * contains the input value `(i,j)`.
      *
      * From the linear algebra perspective, with $P_{ij} = \delta_{i
-     * \pi(i)}$, this represents the operation $P^{-1} A P^{-T}$.
+     * \pi(i)}$, this represents the operation \f$P^{-1} A P^{-T}\f$.
      *
      * @param permutation_indices  the array of indices containing the
      *                             permutation order.
@@ -492,7 +492,7 @@ class Permutable {
      * In the resulting LinOp, the row `i` contains the input row `perm[i]`.
      *
      * From the linear algebra perspective, with $P_{ij} = \delta_{i
-     * \pi(i)}$, this represents the operation $P A$.
+     * \pi(i)}$, this represents the operation \f$P A\f$.
      *
      * @param permutation_indices  the array of indices containing the
      *                             permutation order.
@@ -509,7 +509,7 @@ class Permutable {
      * `perm[i]`.
      *
      * From the linear algebra perspective, with $P_{ij} = \delta_{i
-     * \pi(i)}$, this represents the operation $A P^T$.
+     * \pi(i)}$, this represents the operation \f$A P^T\f$.
      *
      * @param permutation_indices  the array of indices containing the
      *                             permutation order `perm`.
@@ -525,7 +525,7 @@ class Permutable {
      * In the resulting LinOp, the row `perm[i]` contains the input row `i`.
      *
      * From the linear algebra perspective, with $P_{ij} = \delta_{i
-     * \pi(i)}$, this represents the operation $P^{-1} A$.
+     * \pi(i)}$, this represents the operation \f$P^{-1} A\f$.
      *
      * @param permutation_indices  the array of indices containing the
      *                             permutation order `perm`.
@@ -542,7 +542,7 @@ class Permutable {
      * `i`.
      *
      * From the linear algebra perspective, with $P_{ij} = \delta_{i
-     * \pi(i)}$, this represents the operation $A P^{-T}$.
+     * \pi(i)}$, this represents the operation \f$A P^{-T}\f$.
      *
      * @param permutation_indices  the array of indices containing the
      *                             permutation order `perm`.

include/ginkgo/core/distributed/index_map.hpp

@@ -30,13 +30,13 @@ enum class index_space {
 /**
  * \brief This class defines mappings between global and local indices.
  *
- * Given an index space $I = [0, \dots, N)$ that is partitioned into $P$
- * disjoint subsets $I_k, k = 1, \dots, P$, this class defines for each
- * subset an extended global index set $\hat{I}_k \supset I_K$. The extended
- * index set contains the global indices owned by part $k$, as well as
- * remote indices $R_k = \hat{I}_k \setminus I_k$, which are also accessed by
- * part $k$, but owned by parts $l \neq k$.
- * At the core, this class provides mappings from the global index space $I$
+ * Given an index space \f$I = [0, \dots, N)\f$ that is partitioned into \f$P\f$
+ * disjoint subsets \f$I_k, k = 1, \dots, P\f$, this class defines for each
+ * subset an extended global index set \f$\hat{I}_k \supset I_K\f$. The extended
+ * index set contains the global indices owned by part \f$k\f$, as well as
+ * remote indices \f$R_k = \hat{I}_k \setminus I_k\f$, which are also accessed by
+ * part \f$k\f$, but owned by parts \f$l \neq k\f$.
+ * At the core, this class provides mappings from the global index space \f$I\f$
  * into different local index spaces. The combined local index space
  * (index_space::combined) is then defined as
  * $[0, \dots, |\hat{I}_k|)$. Additionally, the combined index space can be
@@ -45,19 +45,19 @@ enum class index_space {
  * $[0, \dots, |I_k|)$, and the non-locally owned as $[0, \dots, |R_k|)$.
  * With these index sets, the following mappings are defined:
  *
- * - $c_k : \hat{I}_k \mapsto [0, \dots, |\hat{I}_k|)$ which maps global indices
+ * - \f$c_k : \hat{I}_k \mapsto [0, \dots, |\hat{I}_k|)\f$ which maps global indices
  *   into the combined/full local index space (denoted as
  *   index_space::combined),
- * - $l_k: I_k \mapsto [0, \dots, |I_k|)$ which maps global indices into the
+ * - \f$l_k: I_k \mapsto [0, \dots, |I_k|)\f$ which maps global indices into the
  *   locally owned index space (denoted as index_space::local),
- * - $r_k: R_k \mapsto [0, \dots, |R_k|)$ which maps global indices into the
+ * - \f$r_k: R_k \mapsto [0, \dots, |R_k|)\f$ which maps global indices into the
  *   non-locally owned index space (denoted as index_space::non_local).
  *
  * The required map can be selected by passing the appropriate type of an
  * index_space.
  *
- * The index map for $I_k$ has no knowledge about any other index maps for
- * $I_l, l \neq k$. In particular, any global index passed to the `map_to_local`
+ * The index map for \f$I_k\f$ has no knowledge about any other index maps for
+ * \f$I_l, l \neq k\f$. In particular, any global index passed to the `map_to_local`
  * map that is not part of the specified index space, will be mapped to an
  * invalid_index.
  *
@@ -135,25 +135,25 @@ class index_map {
     index_map(std::shared_ptr<const Executor> exec);
 
     /**
-     * \brief get the index set $R_k$ for this rank.
+     * \brief get the index set \f$R_k\f$ for this rank.
      *
      * The indices are ordered by their owning rank and global index.
      */
     const segmented_array<GlobalIndexType>& get_remote_global_idxs() const;
 
     /**
-     * \brief get the index set $R_k$, but mapped to their respective local
+     * \brief get the index set \f$R_k\f$, but mapped to their respective local
      *        index space.
      *
      * The indices are grouped by their owning rank and sorted according to
      * their global index within each group.
      *
-     * The set $R_k = \hat{I}_k \setminus I_k$ can also be written as the union
-     * of the intersection of $\hat{I}_k$ with other disjoint sets
-     * $I_l, l \neq k$, i.e.
+     * The set \f$R_k = \hat{I}_k \setminus I_k\f$ can also be written as the union
+     * of the intersection of \f$\hat{I}_k\f$ with other disjoint sets
+     * \f$I_l, l \neq k\f$, i.e.
      * $R_k = \bigcup_{j \neq k} \hat{I}_k \cap I_j = \bigcup_{j \neq k}
-     * R_{k,j}$. The set $R_{k,j}$ can then be mapped by $l_j$ to get the local
-     * indices wrt. part $j$. The indices here are mapped by $l_j$.
+     * R_{k,j}$. The set \f$R_{k,j}\f$ can then be mapped by \f$l_j\f$ to get the local
+     * indices wrt. part \f$j\f$. The indices here are mapped by \f$l_j\f$.
      */
     const segmented_array<LocalIndexType>& get_remote_local_idxs() const;
 

include/ginkgo/core/distributed/vector.hpp

@@ -345,7 +345,7 @@ class Vector
                           array<char>& tmp) const;
 
     /**
-     * Computes the square of the column-wise Euclidean ($L^2$) norm of this
+     * Computes the square of the column-wise Euclidean (\f$L^2\f$) norm of this
      * (multi-)vector using a global reduction.
      *
      * @param result  a Dense row vector, used to store the norm
@@ -355,7 +355,7 @@ class Vector
     void compute_squared_norm2(ptr_param<LinOp> result) const;
 
     /**
-     * Computes the square of the column-wise Euclidean ($L^2$) norm of this
+     * Computes the square of the column-wise Euclidean (\f$L^2\f$) norm of this
      * (multi-)vector using a global reduction.
      *
      * @param result  a Dense row vector, used to store the norm

include/ginkgo/core/factorization/ic.hpp

@@ -29,10 +29,10 @@ namespace factorization {
 /**
  * Represents an incomplete Cholesky factorization (IC(0)) of a sparse matrix.
  *
- * More specifically, it consists of a lower triangular factor $L$ and
- * its conjugate transpose $L^H$ with sparsity pattern
- * $\mathcal S(L + L^H)$ = $\mathcal S(A)$
- * fulfilling $LL^H = A$ at every non-zero location of $A$.
+ * More specifically, it consists of a lower triangular factor \f$L\f$ and
+ * its conjugate transpose \f$L^H\f$ with sparsity pattern
+ * \f$\mathcal S(L + L^H)\f$ = \f$\mathcal S(A)\f$
+ * fulfilling \f$LL^H = A\f$ at every non-zero location of \f$A\f$.
  *
  * @tparam ValueType  Type of the values of all matrices used in this class
  * @tparam IndexType  Type of the indices of all matrices used in this class

include/ginkgo/core/factorization/ilu.hpp

@@ -29,10 +29,10 @@ namespace factorization {
 /**
  * Represents an incomplete LU factorization -- ILU(0) -- of a sparse matrix.
  *
- * More specifically, it consists of a lower unitriangular factor $L$ and
- * an upper triangular factor $U$ with sparsity pattern
- * $\mathcal S(L + U)$ = $\mathcal S(A)$
- * fulfilling $LU = A$ at every non-zero location of $A$.
+ * More specifically, it consists of a lower unitriangular factor \f$L\f$ and
+ * an upper triangular factor \f$U\f$ with sparsity pattern
+ * \f$\mathcal S(L + U)\f$ = \f$\mathcal S(A)\f$
+ * fulfilling \f$LU = A\f$ at every non-zero location of \f$A\f$.
  *
  * @tparam ValueType  Type of the values of all matrices used in this class
  * @tparam IndexType  Type of the indices of all matrices used in this class

include/ginkgo/core/factorization/par_ic.hpp

@@ -28,8 +28,8 @@ namespace factorization {
 /**
  * ParIC is an incomplete Cholesky factorization which is computed in parallel.
  *
- * $L$ is a lower triangular matrix, which approximates a given matrix $A$ with
- * $A \approx LL^H$. Here, $L + L^H$ has the same sparsity pattern as $A$, which
+ * \f$L\f$ is a lower triangular matrix, which approximates a given matrix \f$A\f$ with
+ * \f$A \approx LL^H\f$. Here, \f$L + L^H\f$ has the same sparsity pattern as \f$A\f$, which
  * is also called IC(0).
  *
  * The ParIC algorithm generates the incomplete factors iteratively, using a
@@ -43,12 +43,12 @@ namespace factorization {
  * \end{cases}
  * $
  *
- * In general, the entries of $L$ can be iterated in parallel and in
+ * In general, the entries of \f$L\f$ can be iterated in parallel and in
  * asynchronous fashion, the algorithm asymptotically converges to the
- * incomplete factors $L$ and $L^H$ fulfilling $\left(R = A - L \cdot
- * L^H\right)\vert_\mathcal{S} = 0\vert_\mathcal{S}$ where $\mathcal{S}$ is the
+ * incomplete factors \f$L\f$ and \f$L^H\f$ fulfilling $\left(R = A - L \cdot
+ * L^H\right)\vert_\mathcal{S} = 0\vert_\mathcal{S}$ where \f$\mathcal{S}\f$ is the
  * pre-defined sparsity pattern (in case of IC(0) the sparsity pattern of the
- * system matrix $A$). The number of ParIC sweeps needed for convergence
+ * system matrix \f$A\f$). The number of ParIC sweeps needed for convergence
  * depends on the parallelism level: For sequential execution, a single sweep
  * is sufficient, for fine-grained parallelism, the number of sweeps necessary
  * to get a good approximation of the incomplete factors depends heavily on the

include/ginkgo/core/factorization/par_ict.hpp

@@ -29,18 +29,18 @@ namespace factorization {
  * ParICT is an incomplete threshold-based Cholesky factorization which is
  * computed in parallel.
  *
- * $L$ is a lower triangular matrix which approximates a given symmetric
- * positive definite matrix $A$ with $A \approx LL^T$. Here, $L$ has a sparsity
+ * \f$L\f$ is a lower triangular matrix which approximates a given symmetric
+ * positive definite matrix \f$A\f$ with \f$A \approx LL^T\f$. Here, \f$L\f$ has a sparsity
  * pattern that is improved iteratively based on its element-wise magnitude.
- * The initial sparsity pattern is chosen based on the lower triangle of $A$.
+ * The initial sparsity pattern is chosen based on the lower triangle of \f$A\f$.
  *
  * One iteration of the ParICT algorithm consists of the following steps:
  *
- * 1. Calculating the residual $R = A - LL^T$
- * 2. Adding new non-zero locations from $R$ to $L$.
+ * 1. Calculating the residual \f$R = A - LL^T\f$
+ * 2. Adding new non-zero locations from \f$R\f$ to \f$L\f$.
  *    The new non-zero locations are initialized based on the corresponding
  *    residual value.
- * 3. Executing a fixed-point iteration on $L$ according to
+ * 3. Executing a fixed-point iteration on \f$L\f$ according to
  * $
  * F(L) =
  * \begin{cases}
@@ -49,11 +49,11 @@ namespace factorization {
  *     \sqrt{a_{ij}-\sum_{k=1}^{j-1}l_{ik}l_{jk}}, \quad & i = j \\
  * \end{cases}
  * $
- * 4. Removing the smallest entries (by magnitude) from $L$
- * 5. Executing a fixed-point iteration on the (now sparser) $L$
+ * 4. Removing the smallest entries (by magnitude) from \f$L\f$
+ * 5. Executing a fixed-point iteration on the (now sparser) \f$L\f$
  *
  * This ParICT algorithm thus improves the sparsity pattern and the
- * approximation of $L$ simultaneously.
+ * approximation of \f$L\f$ simultaneously.
  *
  * The implementation follows the design of H. Anzt et al.,
  * ParILUT - A Parallel Threshold ILU for GPUs, 2019 IEEE International

include/ginkgo/core/factorization/par_ilu.hpp

@@ -28,9 +28,9 @@ namespace factorization {
 /**
  * ParILU is an incomplete LU factorization which is computed in parallel.
  *
- * $L$ is a lower unitriangular, while $U$ is an upper triangular matrix, which
- * approximate a given matrix $A$ with $A \approx LU$. Here, $L$ and $U$ have
- * the same sparsity pattern as $A$, which is also called ILU(0).
+ * \f$L\f$ is a lower unitriangular, while \f$U\f$ is an upper triangular matrix, which
+ * approximate a given matrix \f$A\f$ with \f$A \approx LU\f$. Here, \f$L\f$ and \f$U\f$ have
+ * the same sparsity pattern as \f$A\f$, which is also called ILU(0).
  *
  * The ParILU algorithm generates the incomplete factors iteratively, using a
  * fixed-point iteration of the form
@@ -44,12 +44,12 @@ namespace factorization {
  * \end{cases}
  * $
  *
- * In general, the entries of $L$ and $U$ can be iterated in parallel and in
+ * In general, the entries of \f$L\f$ and \f$U\f$ can be iterated in parallel and in
  * asynchronous fashion, the algorithm asymptotically converges to the
- * incomplete factors $L$ and $U$ fulfilling $\left(R = A - L \cdot
- * U\right)\vert_\mathcal{S} = 0\vert_\mathcal{S}$ where $\mathcal{S}$ is the
+ * incomplete factors \f$L\f$ and \f$U\f$ fulfilling $\left(R = A - L \cdot
+ * U\right)\vert_\mathcal{S} = 0\vert_\mathcal{S}$ where \f$\mathcal{S}\f$ is the
  * pre-defined sparsity pattern (in case of ILU(0) the sparsity pattern of the
- * system matrix $A$). The number of ParILU sweeps needed for convergence
+ * system matrix \f$A\f$). The number of ParILU sweeps needed for convergence
  * depends on the parallelism level: For sequential execution, a single sweep
  * is sufficient, for fine-grained parallelism, the number of sweeps necessary
  * to get a good approximation of the incomplete factors depends heavily on the