From f5533a5ede308a29f1c493c52e429cd918b4be87 Mon Sep 17 00:00:00 2001 From: Pieter Ghysels Date: Thu, 26 Oct 2023 14:57:55 -0700 Subject: [PATCH] Documentation in structured matrix --- src/structured/StructuredMatrix.hpp | 112 ++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) diff --git a/src/structured/StructuredMatrix.hpp b/src/structured/StructuredMatrix.hpp index 99be1150..81b39020 100644 --- a/src/structured/StructuredMatrix.hpp +++ b/src/structured/StructuredMatrix.hpp @@ -537,6 +537,9 @@ namespace strumpack { * \param adm optional admissibility info for BLR, should be of * size row_tree->leaf_sizes().size() x * col_tree->leaf_sizes().size() + * \param p coordinates of geometry. Should be a matrix of size + * rows x d, where d is the dimension of the geometry. This is + * used for HSS compression, not used for HODLR/HODBF/BLR. * * \return std::unique_ptr holding a pointer to a * StructuredMatrix of the requested StructuredMatrix::Type @@ -584,6 +587,9 @@ namespace strumpack { * \param adm optional admissibility info for BLR, should be of * size row_tree->leaf_sizes().size() x * col_tree->leaf_sizes().size() + * \param p coordinates of geometry. Should be a matrix of size + * rows x d, where d is the dimension of the geometry. This is + * used for HSS compression, not used for HODLR/HODBF/BLR. * * \return std::unique_ptr holding a pointer to a * StructuredMatrix of the requested StructuredMatrix::Type @@ -611,6 +617,40 @@ namespace strumpack { const admissibility_t* adm=nullptr, const DenseMatrix* p=nullptr); + /** + * Construct a StructuredMatrix and compute a factorization. For + * BLR, compression and factorization are combined and cannot be + * called separately. + * + * \tparam scalar_t precision of input matrix, and of + * constructed StructuredMatrix. Note that not all types support + * every all precisions. See StructuredMatrix::Type. + * + * \param A Input dense matrix, will not be modified + * \param opts Options object + * \param row_tree optional clustertree for the rows, see also + * strumpack::binary_tree_clustering + * \param col_tree optional clustertree for the columns. If the + * matrix is square, this does not need to be specified. + * \param adm optional admissibility info for BLR, should be of + * size row_tree->leaf_sizes().size() x + * col_tree->leaf_sizes().size() + * + * \return std::unique_ptr holding a pointer to a + * StructuredMatrix of the requested StructuredMatrix::Type + * + * \throw std::invalid_argument If the operatation is not + * supported for the type of structured::StructuredMatrix, if the + * type requires a square matrix and the input is not square, if + * the structured::StructuredMatrix type requires MPI. + * \throw std::logic_error If the operation is not implemented yet + * \throw std::runtime_error If the operation requires a third + * party library which was not enabled when configuring STRUMPACK. + * + * \see strumpack::binary_tree_clustering, construct_from_dense + * construct_from_elements, construct_matrix_free and + * construct_partially_matrix_free + */ template std::unique_ptr> construct_and_factor_from_dense(const DenseMatrix& A, const StructuredOptions& opts, @@ -618,6 +658,42 @@ namespace strumpack { const structured::ClusterTree* col_tree=nullptr, const admissibility_t* adm=nullptr); + /** + * Construct a StructuredMatrix and compute a factorization. For + * BLR, compression and factorization are combined and cannot be + * called separately. + * + * \tparam scalar_t precision of input matrix, and of + * constructed StructuredMatrix. Note that not all types support + * every all precisions. See StructuredMatrix::Type. + * + * \param rows Number of rows of matrix to be constructed. + * \param cols Number of columns of matrix to be constructed. + * \param A Matrix extraction routine. + * \param opts Options object + * \param row_tree optional clustertree for the rows, see also + * strumpack::binary_tree_clustering + * \param col_tree optional clustertree for the columns. If the + * matrix is square, this does not need to be specified. + * \param adm optional admissibility info for BLR, should be of + * size row_tree->leaf_sizes().size() x + * col_tree->leaf_sizes().size() + * + * \return std::unique_ptr holding a pointer to a + * StructuredMatrix of the requested StructuredMatrix::Type + * + * \throw std::invalid_argument If the operatation is not + * supported for the type of structured::StructuredMatrix, if the + * type requires a square matrix and the input is not square, if + * the structured::StructuredMatrix type requires MPI. + * \throw std::logic_error If the operation is not implemented yet + * \throw std::runtime_error If the operation requires a third + * party library which was not enabled when configuring STRUMPACK. + * + * \see strumpack::binary_tree_clustering, construct_from_dense + * construct_from_elements, construct_matrix_free and + * construct_partially_matrix_free + */ template std::unique_ptr> construct_and_factor_from_elements(int rows, int cols, const extract_t& A, @@ -625,6 +701,42 @@ namespace strumpack { const structured::ClusterTree* row_tree=nullptr, const structured::ClusterTree* col_tree=nullptr, const admissibility_t* adm=nullptr); + /** + * Construct a StructuredMatrix and compute a factorization. For + * BLR, compression and factorization are combined and cannot be + * called separately. + * + * \tparam scalar_t precision of input matrix, and of + * constructed StructuredMatrix. Note that not all types support + * every all precisions. See StructuredMatrix::Type. + * + * \param rows Number of rows of matrix to be constructed. + * \param cols Number of columns of matrix to be constructed. + * \param A Matrix block extraction routine. + * \param opts Options object + * \param row_tree optional clustertree for the rows, see also + * strumpack::binary_tree_clustering + * \param col_tree optional clustertree for the columns. If the + * matrix is square, this does not need to be specified. + * \param adm optional admissibility info for BLR, should be of + * size row_tree->leaf_sizes().size() x + * col_tree->leaf_sizes().size() + * + * \return std::unique_ptr holding a pointer to a + * StructuredMatrix of the requested StructuredMatrix::Type + * + * \throw std::invalid_argument If the operatation is not + * supported for the type of structured::StructuredMatrix, if the + * type requires a square matrix and the input is not square, if + * the structured::StructuredMatrix type requires MPI. + * \throw std::logic_error If the operation is not implemented yet + * \throw std::runtime_error If the operation requires a third + * party library which was not enabled when configuring STRUMPACK. + * + * \see strumpack::binary_tree_clustering, construct_from_dense + * construct_from_elements, construct_matrix_free and + * construct_partially_matrix_free + */ template std::unique_ptr> construct_and_factor_from_elements(int rows, int cols, const extract_block_t& A,