Commit 2d9aa63b authored by PRUVOST Florent's avatar PRUVOST Florent Committed by Mathieu Faverge

update doxygen api user

parent e0381aff
......@@ -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
......@@ -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
......
......@@ -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,
......
......@@ -28,6 +28,7 @@
#include "coreblas.h"
/**
*******************************************************************************
*
* @ingroup CORE_CHAMELEON_Complex64_t
*
......
......@@ -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,
......
......@@ -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,
......
......@@ -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,
......
......@@ -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,
......
......@@ -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,
......
......@@ -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)
{
......
......@@ -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)
......
......@@ -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,
......
......@@ -26,9 +26,73 @@
#include "coreblas.h"
/**
*******************************************************************************
*
* @ingroup CORE_CHAMELEON_Complex64_t
*
* Performs one of the symmetric rank 2k operations
*
* \f[ C = \alpha A \times B^T + \alpha B \times A^T + \beta C, \f]
* or
* \f[ C = \alpha A^T \times B + \alpha B^T \times A + \beta C, \f]
*
* where alpha and beta are scalars,
* C is an n-by-n symmetric 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^T + \alpha B \times A^T + \beta C; \f]
* - ChamTrans:
* \f[ C = \alpha A^T \times B + \alpha B^T \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 = ChamTrans, 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 = ChamTrans, ka = n.
*
* @param[in] LDA
* The leading dimension of the array A.
* If trans = ChamNoTrans, lda >= max(1, n);
* if trans = ChamTrans, lda >= max(1, k).
*
* @param[in] B
* An ldb-by-kb matrix.
* If trans = ChamNoTrans, kb = k;
* if trans = ChamTrans, kb = n.
*
* @param[in] LDB
* The leading dimension of the array B.
* If trans = ChamNoTrans, ldb >= max(1, n);
* if trans = ChamTrans, 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_zsyr2k(cham_uplo_t uplo, cham_trans_t trans,
int N, int K,
......
......@@ -26,9 +26,61 @@
#include "coreblas.h"
/**
*******************************************************************************
*
* @ingroup CORE_CHAMELEON_Complex64_t
*
* Performs one of the symmetric rank k operations
*
* \f[ C = \alpha A \times A^T + \beta C, \f]
* or
* \f[ C = \alpha A^T \times A + \beta C, \f]
*
* where alpha and beta are scalars, C is an n-by-n symmetric
* 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