From 43a71bf3b1d6ea2bdc0c6a59bf1ab4ee02ac4634 Mon Sep 17 00:00:00 2001
From: Mathieu Faverge <mathieu.faverge@inria.fr>
Date: Mon, 26 Apr 2021 11:36:21 +0200
Subject: [PATCH] Add comments
---
coreblas/compute/hmat_z.c | 178 +++++++++++++++++++++++++++++++++++++-
1 file changed, 176 insertions(+), 2 deletions(-)
diff --git a/coreblas/compute/hmat_z.c b/coreblas/compute/hmat_z.c
index b232bf71b..aa7f0d219 100644
--- a/coreblas/compute/hmat_z.c
+++ b/coreblas/compute/hmat_z.c
@@ -1,12 +1,12 @@
/**
*
- * @file core_zhmat.c
+ * @file hmat_z.c
*
* @copyright 2019-2019 Bordeaux INP, CNRS (LaBRI UMR 5800), Inria,
* Univ. Bordeaux. All rights reserved.
* @copyright 2019-2019 Universidad Jaume I. All rights reserved.
*
- * @brief Chameleon CPU kernel interface from CHAM_tile_t layout to the real one.
+ * @brief Chameleon interface for H-Mat kernels
*
* @version 1.0.0
* @author Rocio Carratala-Saez
@@ -22,16 +22,31 @@
*/
hmat_interface_t hmat_zinterface;
+/**
+ * @brief Constructor of the C++ interface
+ */
void __hmat_zinit() __attribute__(( constructor ));
void __hmat_zinit() {
hmat_init_default_interface( &hmat_zinterface, HMAT_DOUBLE_COMPLEX );
}
+/**
+ * @brief Destructor of the C++ interface
+ */
void __hmat_zfini() __attribute__(( destructor ));
void __hmat_zfini() {
hmat_zinterface.finalize();
}
+/**
+ * @brief Cholesky factorization of an H-Matrix
+ *
+ * @param[in,out] A
+ * On entry, the input matrix A.
+ * On exit, the factorized matrix A.
+ *
+ * @return 0 (Return an integer to match prototype of LAPACK)
+ */
int hmat_zpotrf( hmat_matrix_t *A ) {
hmat_factorization_context_t ctx_facto;
hmat_factorization_context_init( &ctx_facto );
@@ -40,6 +55,15 @@ int hmat_zpotrf( hmat_matrix_t *A ) {
return 0;
}
+/**
+ * @brief LU factorization of an H-Matrix
+ *
+ * @param[in,out] A
+ * On entry, the input matrix A.
+ * On exit, the factorized matrix A.
+ *
+ * @return 0 (Return an integer to match prototype of LAPACK)
+ */
int hmat_zgetrf( hmat_matrix_t *A ) {
hmat_factorization_context_t ctx_facto;
hmat_factorization_context_init( &ctx_facto );
@@ -48,21 +72,147 @@ int hmat_zgetrf( hmat_matrix_t *A ) {
return 0;
}
+/**
+ * @brief Matrix-Matrix product of H-Matrices
+ *
+ * Computes \f[ C = \alpha op(A) op(B) + \beta C \f]
+ *
+ * where op(A) = A, A^t or conj(A^t)
+ *
+ * @param[in] transA
+ * 'N' : op(A) = A
+ * 'T' : op(A) = A^t
+ * 'C' : op(A) = conj(A^t)
+ *
+ * @param[in] transB
+ * 'N' : op(B) = B
+ * 'T' : op(B) = B'
+ * 'C' : op(B) = conj(B')
+ *
+ * @param[in] alpha
+ * The scalar alpha.
+ *
+ * @param[in] alpha
+ * The scalar alpha.
+ *
+ * @param[in] A
+ * On entry, the input matrix A.
+ *
+ * @param[in] B
+ * On entry, the input matrix B.
+ *
+ * @param[in] beta
+ * The scalar beta.
+ *
+ * @param[in,out] C
+ * On entry, the input matrix C.
+ * On exit, the updated matrix C.
+ *
+ * @return 0 (Return an integer to match prototype of LAPACK)
+ */
int hmat_zgemm( char transA, char transB, void* alpha, hmat_matrix_t* A,
hmat_matrix_t* B, void* beta, hmat_matrix_t* C ) {
return hmat_zinterface.gemm( transA, transB, alpha, A, B, beta, C );
}
+/**
+ * @brief Matrix-Matrix product of an H-Matrix with a full-rank matrix.
+ *
+ * Computes \f[ C = \alpha op(A) B + \beta C \f]
+ *
+ * where op(A) = A, A^t or conj(A^t), and A is an H-Matrix, and B and C are
+ * full-rank matrices.
+ *
+ * @param[in] transA
+ * 'N' : op(A) = A
+ * 'T' : op(A) = A^t
+ * 'C' : op(A) = conj(A^t)
+ *
+ * @param[in] alpha
+ * The scalar alpha.
+ *
+ * @param[in] alpha
+ * The scalar alpha.
+ *
+ * @param[in] A
+ * On entry, the input H-Matrix A.
+ *
+ * @param[in] B
+ * On entry, the full-rank matrix B.
+ *
+ * @param[in] beta
+ * The scalar beta.
+ *
+ * @param[in,out] C
+ * On entry, the full-rank matrix C.
+ * On exit, the updated full-rank matrix C.
+ *
+ * @return 0 on success, -1 otherwise
+ */
int hmat_zgemv( char transA, void* alpha, hmat_matrix_t* A,
void* B, void* beta, void* C, int nrhs ) {
return hmat_zinterface.gemm_scalar( transA, alpha, A, B, beta, C, nrhs );
}
+/**
+ * @brief Solve a triangular system \f[ A x = b \f] with A being an H-Matrix
+ *
+ * Solves \f[ \alpha op(A) X = B \f] or \f[ \alpha X op(A) = B \f]
+ *
+ * where op(A) = A, A^t or conj(A^t), and A is an H-Matrix, and B and C are
+ * full-rank matrices.
+ *
+ * @param[in] side
+ * 'L' : Solves \alpha A X = B
+ * 'R' : Solves \alpha X A = B
+ *
+ * @param[in] uplo
+ * 'L' : A is lower triangular, upper part is not referenced
+ * 'U' : A is upper triangular, lower part is not referenced
+ *
+ * @param[in] trans
+ * 'N' : op(A) = A
+ * 'T' : op(A) = A^t
+ * 'C' : op(A) = conj(A^t)
+ *
+ * @param[in] uplo
+ * 'U' : A has a unitary diagonal which is ot referenced
+ * 'N' : A has a non unitary diagonal
+ *
+ * @param[in] m
+ * The number of rows of B
+ *
+ * @param[in] n
+ * The number of columns of B
+ *
+ * @param[in] alpha
+ * The scalar alpha.
+ *
+ * @param[in] A
+ * On entry, the input H-Matrix A.
+ *
+ * @param[in] is_b_hmat
+ * if true, B is an H-Matrix, otherwise B is full-rank and stored in lapack layout
+ *
+ * @param[in] B
+ * On entry, the H-Mat of full-rank matrix B.
+ * On entry, the solution of the trinagular system.
+ *
+ * @return 0 on success, -1 otherwise
+ */
int hmat_ztrsm( char side, char uplo, char trans, char diag, int m, int n,
void* alpha, hmat_matrix_t* A, int is_b_hmat, void* B ) {
return hmat_zinterface.trsm( side, uplo, trans, diag, m, n, alpha, A, is_b_hmat, B );
}
+/**
+ * @brief Read/Unpack an H-Matrix from a packed format into a contiguous buffer
+ *
+ * @param[in] buffer
+ * The buffer that contains the packed H-Matrix.
+ *
+ * @return The unpack H-Matrix
+ */
hmat_matrix_t *hmat_zread( void *buffer ) {
hmat_buffer_comm_t buffer_struct = { 0, (char*)buffer };
hmat_matrix_t *hmat = hmat_zinterface.read_struct( (hmat_iostream)(&buffer_comm_read),
@@ -71,6 +221,14 @@ hmat_matrix_t *hmat_zread( void *buffer ) {
return hmat;
}
+/**
+ * @brief Compute the size required to store the H-Matrix in a packed format
+ *
+ * @param[in] hmat
+ * The H-Matrix for which the size must be computed
+ *
+ * @return The size of the H-Matrix (structure+data)
+ */
size_t hmat_zsize( hmat_matrix_t *hmat ) {
size_t size = 0;
hmat_zinterface.write_struct( hmat, (hmat_iostream)(&buffer_comm_size), (void *)(&size) );
@@ -78,12 +236,28 @@ size_t hmat_zsize( hmat_matrix_t *hmat ) {
return size;
}
+/**
+ * @brief Write/pack an H-Matrix in a packed format in a given buffer
+ *
+ * @param[in] hmat
+ * The H-Matrix to pack
+ *
+ * @param[in,out] ptr
+ * On entry the allocated buffer with sufficent space to store the H-Matrix.
+ * On exit, contains the packed H-Matrix.
+ */
void hmat_zwrite( hmat_matrix_t *hmat, char *ptr ) {
hmat_buffer_comm_t buffer_struct = { 0, ptr };
hmat_zinterface.write_struct( hmat, (hmat_iostream)(&buffer_comm_write), (void *)(&buffer_struct) );
hmat_zinterface.write_data( hmat, (hmat_iostream)(&buffer_comm_write), (void *)(&buffer_struct) );
}
+/**
+ * @brief Free the data structure (structure+data) associated to an H-Matrix
+ *
+ * @param[in] hmat
+ * The H-Matrix to destroy
+ */
void hmat_zdestroy( hmat_matrix_t *hmat ) {
hmat_zinterface.destroy( hmat );
}
--
GitLab