Merge branch 'doxygen_api_user' into 'master'

update doxygen api user

See merge request solverstack/chameleon!126

.gitlab-ci.yml

@@ -312,7 +312,7 @@ pages:
     - cd build
     - cmake .. -DCHAMELEON_ENABLE_DOC=ON
     - make doc -j5
-    - mv doc/doxygen/out-dev/html/ ../public/
+    - mv doc/doxygen/out/html/ ../public/
     - cp -r doc/orgmode/* ../public/
   only:
     - master@solverstack/chameleon

README.org

@@ -50,7 +50,11 @@ dedicated to dense linear algebra.
 
 * Documentation
 ** User guide
-   The user guide is available directly in the sources as emacs
+
+   Please refer to the [[https://solverstack.gitlabpages.inria.fr/chameleon/users_guide.html][User guide]] to learn how to install and use
+   Chameleon.
+
+   The user guide is also available directly in the sources as emacs
    orgmode files, see :
    1) [[file:doc/orgmode/chapters/introduction.org][Introduction]] : description of the scientific context
    2) [[file:doc/orgmode/chapters/installing.org][Installing]] :
@@ -69,11 +73,15 @@ dedicated to dense linear algebra.
    cmake .. -DCHAMELEON_ENABLE_DOC=ON
    make doc
    #+end_src
+   see the ~doc/orgmode~ directory.
 
 ** Source code documentation (doxygen)
-   There is no up-to-date documentation of Chameleon.  We would like to
-   provide a doxygen documentation hosted on [[https://about.gitlab.com/2016/04/07/gitlab-pages-setup/][gitlab]] in the
-   future. Please refer to the section 2.1 of [[file:READMEDEV.org][READMEDEV]] to get
+
+   Please refer to the [[https://solverstack.gitlabpages.inria.fr/chameleon/index.html][doxygen documentation]] to get more precise
+   information about the API, the public and internal functions
+   prototypes and the data structures.
+
+   Please refer to the section 2.1 of [[file:READMEDEV.org][READMEDEV]] to get
    information about the documentation generation.
 
 ** For developers

coreblas/compute/core_zgemm.c

@@ -26,9 +26,77 @@
 #include "coreblas.h"
 
 /**
+ *******************************************************************************
  *
  * @ingroup CORE_CHAMELEON_Complex64_t
  *
+ *  Performs one of the matrix-matrix operations
+ *
+ *    \f[ C = \alpha [op( A )\times op( B )] + \beta C, \f]
+ *
+ *  where op( X ) is one of:
+ *    \f[ op( X ) = X,   \f]
+ *    \f[ op( X ) = X^T, \f]
+ *    \f[ op( X ) = X^H, \f]
+ *
+ *  alpha and beta are scalars, and A, B and C  are matrices, with op( A )
+ *  an m-by-k matrix, op( B ) a k-by-n matrix and C an m-by-n matrix.
+ *
+ *******************************************************************************
+ *
+ * @param[in] transA
+ *          - ChamNoTrans:   A is not transposed,
+ *          - ChamTrans:     A is transposed,
+ *          - ChamConjTrans: A is conjugate transposed.
+ *
+ * @param[in] transB
+ *          - ChamNoTrans:   B is not transposed,
+ *          - ChamTrans:     B is transposed,
+ *          - ChamConjTrans: B is conjugate transposed.
+ *
+ * @param[in] M
+ *          The number of rows of the matrix op( A ) and of the matrix C.
+ *          m >= 0.
+ *
+ * @param[in] N
+ *          The number of columns of the matrix op( B ) and of the matrix C.
+ *          n >= 0.
+ *
+ * @param[in] K
+ *          The number of columns of the matrix op( A ) and the number of rows
+ *          of the matrix op( B ). k >= 0.
+ *
+ * @param[in] alpha
+ *          The scalar alpha.
+ *
+ * @param[in] A
+ *          An lda-by-ka matrix, where ka is k when transa = ChamNoTrans,
+ *          and is m otherwise.
+ *
+ * @param[in] LDA
+ *          The leading dimension of the array A.
+ *          When transa = ChamNoTrans, lda >= max(1,m),
+ *          otherwise, lda >= max(1,k).
+ *
+ * @param[in] B
+ *          An ldb-by-kb matrix, where kb is n when transb = ChamNoTrans,
+ *          and is k otherwise.
+ *
+ * @param[in] LDB
+ *          The leading dimension of the array B.
+ *          When transb = ChamNoTrans, ldb >= max(1,k),
+ *          otherwise, ldb >= max(1,n).
+ *
+ * @param[in] beta
+ *          The scalar beta.
+ *
+ * @param[in,out] C
+ *          An ldc-by-n matrix. On exit, the array is overwritten by the m-by-n
+ *          matrix ( alpha*op( A )*op( B ) + beta*C ).
+ *
+ * @param[in] LDC
+ *          The leading dimension of the array C. ldc >= max(1,m).
+ *
  */
 void CORE_zgemm(cham_trans_t transA, cham_trans_t transB,
                 int M, int N, int K,

coreblas/compute/core_zgessm.c

@@ -28,6 +28,7 @@
 #include "coreblas.h"
 
 /**
+ *******************************************************************************
  *
  * @ingroup CORE_CHAMELEON_Complex64_t
  *

coreblas/compute/core_zhemm.c

@@ -26,8 +26,67 @@
 #include "coreblas.h"
 
 /**
+ *******************************************************************************
  *
  * @ingroup CORE_CHAMELEON_Complex64_t
+ *
+  *  Performs one of the matrix-matrix operations
+ *
+ *     \f[ C = \alpha \times A \times B + \beta \times C \f]
+ *  or
+ *     \f[ C = \alpha \times B \times A + \beta \times C \f]
+ *
+ *  where alpha and beta are scalars, A is a Hermitian matrix and B and
+ *  C are m-by-n matrices.
+ *
+ *******************************************************************************
+ *
+ * @param[in] side
+ *          Specifies whether the Hermitian matrix A appears on the
+ *          left or right in the operation as follows:
+ *          - ChamLeft:  \f[ C = \alpha \times A \times B + \beta \times C \f]
+ *          - ChamRight: \f[ C = \alpha \times B \times A + \beta \times C \f]
+ *
+ * @param[in] uplo
+ *          Specifies whether the upper or lower triangular part of
+ *          the Hermitian matrix A is to be referenced as follows:
+ *          - ChamLower:     Only the lower triangular part of the
+ *                             Hermitian matrix A is to be referenced.
+ *          - ChamUpper:     Only the upper triangular part of the
+ *                             Hermitian matrix A is to be referenced.
+ *
+ * @param[in] M
+ *          The number of rows of the matrix C. m >= 0.
+ *
+ * @param[in] N
+ *          The number of columns of the matrix C. n >= 0.
+ *
+ * @param[in] alpha
+ *          The scalar alpha.
+ *
+ * @param[in] A
+ *          A is an lda-by-ka matrix, where ka is m when side = ChamLeft,
+ *          and is n otherwise. Only the uplo triangular part is referenced.
+ *
+ * @param[in] LDA
+ *          The leading dimension of the array A. lda >= max(1,ka).
+ *
+ * @param[in] B
+ *          B is an ldb-by-n matrix, where the leading m-by-n part of
+ *          the array B must contain the matrix B.
+ *
+ * @param[in] LDB
+ *          The leading dimension of the array B. ldb >= max(1,m).
+ *
+ * @param[in] beta
+ *          The scalar beta.
+ *
+ * @param[in,out] C
+ *          C is an ldc-by-n matrix.
+ *          On exit, the array is overwritten by the m-by-n updated matrix.
+ *
+ * @param[in] LDC
+ *          The leading dimension of the array C. ldc >= max(1,m).
  *
  */
 void CORE_zhemm(cham_side_t side, cham_uplo_t uplo,

coreblas/compute/core_zher2k.c

@@ -26,9 +26,75 @@
 #include "coreblas.h"
 
 /**
+ *******************************************************************************
  *
  * @ingroup CORE_CHAMELEON_Complex64_t
  *
+ *  Performs one of the Hermitian rank 2k operations
+ *
+ *    \f[ C = \alpha A \times B^H + conjg( \alpha ) B \times A^H + \beta C, \f]
+ *    or
+ *    \f[ C = \alpha A^H \times B + conjg( \alpha ) B^H \times A + \beta C, \f]
+ *
+ *  where alpha is a complex scalar, beta is a real scalar,
+ *  C is an n-by-n Hermitian matrix, and A and B are n-by-k matrices
+ *  in the first case and k-by-n matrices in the second case.
+ *
+ *******************************************************************************
+ *
+ * @param[in] uplo
+ *          - ChamUpper: Upper triangle of C is stored;
+ *          - ChamLower: Lower triangle of C is stored.
+ *
+ * @param[in] trans
+ *          - ChamNoTrans:
+ *            \f[ C = \alpha A \times B^H
+ *                  + conjg( \alpha ) B \times A^H + \beta C; \f]
+ *          - ChamConjTrans:
+ *            \f[ C = \alpha A^H \times B
+ *                  + conjg( \alpha ) B^H \times A + \beta C. \f]
+ *
+ * @param[in] N
+ *          The order of the matrix C. n >= zero.
+ *
+ * @param[in] K
+ *          If trans = ChamNoTrans, number of columns of the A and B matrices;
+ *          if trans = ChamConjTrans, number of rows of the A and B matrices.
+ *
+ * @param[in] alpha
+ *          The scalar alpha.
+ *
+ * @param[in] A
+ *          An lda-by-ka matrix.
+ *          If trans = ChamNoTrans,   ka = k;
+ *          if trans = ChamConjTrans, ka = n.
+ *
+ * @param[in] LDA
+ *          The leading dimension of the array A.
+ *          If trans = ChamNoTrans,   lda >= max(1, n);
+ *          if trans = ChamConjTrans, lda >= max(1, k).
+ *
+ * @param[in] B
+ *          An ldb-by-kb matrix.
+ *          If trans = ChamNoTrans,   kb = k;
+ *          if trans = ChamConjTrans, kb = n.
+ *
+ * @param[in] LDB
+ *          The leading dimension of the array B.
+ *          If trans = ChamNoTrans,   ldb >= max(1, n);
+ *          if trans = ChamConjTrans, ldb >= max(1, k).
+ *
+ * @param[in] beta
+ *          The scalar beta.
+ *
+ * @param[in,out] C
+ *          An ldc-by-n matrix.
+ *          On exit, the uplo part of the matrix is overwritten
+ *          by the uplo part of the updated matrix.
+ *
+ * @param[in] LDC
+ *          The leading dimension of the array C. ldc >= max(1, n).
+ *
  */
 void CORE_zher2k(cham_uplo_t uplo, cham_trans_t trans,
                  int N, int K,

coreblas/compute/core_zherk.c

@@ -26,9 +26,61 @@
 #include "coreblas.h"
 
 /**
+ *******************************************************************************
  *
  * @ingroup CORE_CHAMELEON_Complex64_t
  *
+ *  Performs one of the Hermitian rank k operations
+ *
+ *    \f[ C = \alpha A \times A^H + \beta C, \f]
+ *    or
+ *    \f[ C = \alpha A^H \times A + \beta C, \f]
+ *
+ *  where alpha and beta are real scalars, C is an n-by-n Hermitian
+ *  matrix, and A is an n-by-k matrix in the first case and a k-by-n
+ *  matrix in the second case.
+ *
+ *******************************************************************************
+ *
+ * @param[in] uplo
+ *          - ChamUpper: Upper triangle of C is stored;
+ *          - ChamLower: Lower triangle of C is stored.
+ *
+ * @param[in] trans
+ *          - ChamNoTrans:   \f[ C = \alpha A \times A^H + \beta C; \f]
+ *          - ChamConjTrans: \f[ C = \alpha A^H \times A + \beta C. \f]
+ *
+ * @param[in] N
+ *          The order of the matrix C. n >= 0.
+ *
+ * @param[in] K
+ *          If trans = ChamNoTrans, number of columns of the A matrix;
+ *          if trans = ChamConjTrans, number of rows of the A matrix.
+ *
+ * @param[in] alpha
+ *          The scalar alpha.
+ *
+ * @param[in] A
+ *          A is an lda-by-ka matrix.
+ *          If trans = ChamNoTrans,   ka = k;
+ *          if trans = ChamConjTrans, ka = n.
+ *
+ * @param[in] LDA
+ *          The leading dimension of the array A.
+ *          If trans = ChamNoTrans,   lda >= max(1, n);
+ *          if trans = ChamConjTrans, lda >= max(1, k).
+ *
+ * @param[in] beta
+ *          The scalar beta.
+ *
+ * @param[in,out] C
+ *          C is an ldc-by-n matrix.
+ *          On exit, the uplo part of the matrix is overwritten
+ *          by the uplo part of the updated matrix.
+ *
+ * @param[in] LDC
+ *          The leading dimension of the array C. ldc >= max(1, n).
+ *
  */
 void CORE_zherk(cham_uplo_t uplo, cham_trans_t trans,
                 int N, int K,

coreblas/compute/core_zlacpy.c

@@ -27,9 +27,42 @@
 #include "coreblas.h"
 
 /**
+ *******************************************************************************
  *
  * @ingroup CORE_CHAMELEON_Complex64_t
  *
+ *  Copies all or part of a two-dimensional matrix A to another matrix B.
+ *
+ *******************************************************************************
+ *
+ * @param[in] uplo
+ *          - ChamGeneral: entire A,
+ *          - ChamUpper:   upper triangle,
+ *          - ChamLower:   lower triangle.
+ *
+ * @param[in] M
+ *          The number of rows of the matrices A and B.
+ *          m >= 0.
+ *
+ * @param[in] N
+ *          The number of columns of the matrices A and B.
+ *          n >= 0.
+ *
+ * @param[in] A
+ *          The m-by-n matrix to copy.
+ *
+ * @param[in] LDA
+ *          The leading dimension of the array A.
+ *          lda >= max(1,m).
+ *
+ * @param[out] B
+ *          The m-by-n copy of the matrix A.
+ *          On exit, B = A ONLY in the locations specified by uplo.
+ *
+ * @param[in] LDB
+ *          The leading dimension of the array B.
+ *          ldb >= max(1,m).
+ *
  */
 void CORE_zlacpy(cham_uplo_t uplo, int M, int N,
                  const CHAMELEON_Complex64_t *A, int LDA,

coreblas/compute/core_zlag2c.c

@@ -25,9 +25,36 @@
 #include "coreblas.h"
 
 /**
+ *******************************************************************************
  *
  * @ingroup CORE_CHAMELEON_Complex64_t
  *
+ *  Converts m-by-n matrix A from double complex to single complex precision.
+ *
+ *******************************************************************************
+ *
+ * @param[in] M
+ *          The number of rows of the matrix A.
+ *          m >= 0.
+ *
+ * @param[in] N
+ *          The number of columns of the matrix A.
+ *          n >= 0.
+ *
+ * @param[in] A
+ *          The lda-by-n matrix in double complex precision to convert.
+ *
+ * @param[in] LDA
+ *          The leading dimension of the matrix A.
+ *          lda >= max(1,m).
+ *
+ * @param[out] B
+ *          On exit, the converted LDB-by-n matrix in single complex precision.
+ *
+ * @param[in] LDB
+ *          The leading dimension of the matrix As.
+ *          ldas >= max(1,m).
+ *
  */
 void CORE_zlag2c(int m, int n,
                  const CHAMELEON_Complex64_t *A, int lda,
@@ -40,9 +67,36 @@ void CORE_zlag2c(int m, int n,
 /**/
 
 /**
+ *******************************************************************************
  *
  * @ingroup CORE_CHAMELEON_Complex64_t
  *
+ *  Converts m-by-n matrix A from single complex to double complex precision.
+ *
+ *******************************************************************************
+ *
+ * @param[in] m
+ *          The number of rows of the matrix As.
+ *          m >= 0.
+ *
+ * @param[in] n
+ *          The number of columns of the matrix As.
+ *          n >= 0.
+ *
+ * @param[in] As
+ *          The ldas-by-n matrix in single complex precision to convert.
+ *
+ * @param[in] ldas
+ *          The leading dimension of the matrix As.
+ *          ldas >= max(1,m).
+ *
+ * @param[out] A
+ *          On exit, the converted lda-by-n matrix in double complex precision.
+ *
+ * @param[in] lda
+ *          The leading dimension of the matrix A.
+ *          lda >= max(1,m).
+ *
  */
 void CORE_clag2z(int m, int n,
                  const CHAMELEON_Complex32_t *A, int lda,

coreblas/compute/core_zlauum.c

@@ -27,9 +27,45 @@
 #include "coreblas.h"
 
 /**
+ *******************************************************************************
  *
  * @ingroup CORE_CHAMELEON_Complex64_t
  *
+ *  Computes the product U * U^H or L^H * L, where the triangular
+ *  factor U or L is stored in the upper or lower triangular part of
+ *  the array A.
+ *
+ *  If uplo = 'U' or 'u' then the upper triangle of the result is stored,
+ *  overwriting the factor U in A.
+ *  If uplo = 'L' or 'l' then the lower triangle of the result is stored,
+ *  overwriting the factor L in A.
+
+ *
+ *******************************************************************************
+ *
+ * @param[in] uplo
+ *          = ChamUpper: Upper triangle of A is stored;
+ *          = ChamLower: Lower triangle of A is stored.
+ *
+ *
+ * @param[in] N
+ *          The order of the matrix A. n >= 0.
+ *
+ * @param[in,out] A
+ *          On entry, the triangular factor U or L.
+ *          On exit, if uplo = 'U', the upper triangle of A is
+ *          overwritten with the upper triangle of the product U * U^H;
+ *          if uplo = 'L', the lower triangle of A is overwritten with
+ *          the lower triangle of the product L^H * L.
+
+ *
+ * @param[in] LDA
+ *          The leading dimension of the array A. lda >= max(1,n).
+ *
+ * @param[out] info
+ *          - 0 on successful exit
+ *          - < 0 if -i, the i-th argument had an illegal value
+ *
  */
 void CORE_zlauum(cham_uplo_t uplo, int N, CHAMELEON_Complex64_t *A, int LDA)
 {

coreblas/compute/core_zpotrf.c

@@ -27,8 +27,48 @@
 #include "coreblas.h"
 
 /**
+ *******************************************************************************
  *
  * @ingroup CORE_CHAMELEON_Complex64_t
+ * 
+ *  Performs the Cholesky factorization of a Hermitian positive definite
+ *  matrix A. The factorization has the form
+ *
+ *    \f[ A = L \times L^H, \f]
+ *    or
+ *    \f[ A = U^H \times U, \f]
+ *
+ *  where U is an upper triangular matrix and L is a lower triangular matrix.
+ *
+ *******************************************************************************
+ *
+ * @param[in] uplo
+ *          - ChamUpper: Upper triangle of A is stored;
+ *          - ChamLower: Lower triangle of A is stored.
+ *
+ * @param[in] N
+ *          The order of the matrix A. n >= 0.
+ *
+ * @param[in,out] A
+ *          On entry, the Hermitian positive definite matrix A.
+ *          If uplo = ChamUpper, the leading N-by-N upper triangular part of A
+ *          contains the upper triangular part of the matrix A, and the strictly
+ *          lower triangular part of A is not referenced.
+ *          If uplo = ChamLower, the leading N-by-N lower triangular part of A
+ *          contains the lower triangular part of the matrix A, and the strictly
+ *          upper triangular part of A is not referenced.
+ *          On exit, if return value = 0, the factor U or L from the Cholesky
+ *          factorization A = U^H*U or A = L*L^H.
+ *
+ * @param[in] LDA
+ *          The leading dimension of the array A. lda >= max(1,n).
+ *
+ * @param[in] INFO
+              = 0:  successful exit
+              < 0:  if INFO = -i, the i-th argument had an illegal value
+              > 0:  if INFO = i, the leading minor of order i is not
+                    positive definite, and the factorization could not be
+                    completed.
  *
  */
 void CORE_zpotrf(cham_uplo_t uplo, int N, CHAMELEON_Complex64_t *A, int LDA, int *INFO)

coreblas/compute/core_zsymm.c

@@ -26,9 +26,68 @@
 #include "coreblas.h"
 
 /**
+ *******************************************************************************
  *
  * @ingroup CORE_CHAMELEON_Complex64_t
  *
+ *  Performs one of the matrix-matrix operations
+ *
+ *     \f[ C = \alpha \times A \times B + \beta \times C \f]
+ *  or
+ *     \f[ C = \alpha \times B \times A + \beta \times C \f]
+ *
+ *  where alpha and beta are scalars, A is a symmetric matrix and B and
+ *  C are m-by-n matrices.
+ *
+ *******************************************************************************
+ *
+ * @param[in] side
+ *          Specifies whether the symmetric matrix A appears on the
+ *          left or right in the operation as follows:
+ *          - ChamLeft:  \f[ C = \alpha \times A \times B + \beta \times C \f]
+ *          - ChamRight: \f[ C = \alpha \times B \times A + \beta \times C \f]
+ *
+ * @param[in] uplo
+ *          Specifies whether the upper or lower triangular part of
+ *          the symmetric matrix A is to be referenced as follows:
+ *          - ChamLower:     Only the lower triangular part of the
+ *                             symmetric matrix A is to be referenced.
+ *          - ChamUpper:     Only the upper triangular part of the
+ *                             symmetric matrix A is to be referenced.
+ *
+ * @param[in] M
+ *          The number of rows of the matrix C. m >= 0.
+ *
+ * @param[in] N
+ *          The number of columns of the matrix C. n >= 0.
+ *
+ * @param[in] alpha
+ *          The scalar alpha.
+ *
+ * @param[in] A
+ *          A is an lda-by-ka matrix, where ka is m when side = ChamLeft,
+ *          and is n otherwise. Only the uplo triangular part is referenced.
+ *
+ * @param[in] LDA
+ *          The leading dimension of the array A. lda >= max(1,ka).
+ *
+ * @param[in] B
+ *          B is an ldb-by-n matrix, where the leading m-by-n part of
+ *          the array B must contain the matrix B.
+ *
+ * @param[in] LDB
+ *          The leading dimension of the array B. ldb >= max(1,m).
+ *
+ * @param[in] beta
+ *          The scalar beta.
+ *
+ * @param[in,out] C
+ *          C is an ldc-by-n matrix.
+ *          On exit, the array is overwritten by the m-by-n updated matrix.
+ *
+ * @param[in] LDC
+ *          The leading dimension of the array C. ldc >= max(1,m).
+ * 
  */
 void CORE_zsymm(cham_side_t side, cham_uplo_t uplo,
                 int M, int N,

coreblas/compute/core_zsyr2k.c

@@ -26,9 +26,73 @@
 #include "coreblas.h"
 
 /**