From e6d560ef95990df76780975c142857ec2e68f619 Mon Sep 17 00:00:00 2001 From: vdubos Date: Thu, 21 Sep 2023 10:05:48 +0200 Subject: [PATCH 1/3] add doc to lrmatgenerator --- .../interfaces/virtual_lrmat_generator.hpp | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/include/htool/hmatrix/interfaces/virtual_lrmat_generator.hpp b/include/htool/hmatrix/interfaces/virtual_lrmat_generator.hpp index d25f1a48..0a7c8936 100644 --- a/include/htool/hmatrix/interfaces/virtual_lrmat_generator.hpp +++ b/include/htool/hmatrix/interfaces/virtual_lrmat_generator.hpp @@ -9,14 +9,39 @@ namespace htool { +/** + * @brief + * + * @tparam CoefficientPrecision + * @tparam CoordinatesPrecision + */ template class VirtualLowRankGenerator { public: VirtualLowRankGenerator() {} // C style + /** + * @brief Build a low rank approximation of the block defined by \p t , \p s and \p A . The block has a size \f$ (M \times N)\f$ where \f$ M \f$ is the size of \p t , and \f$ N \f$ is the size of \p s . + * + * The low rank approximation is defined as \f$ \mathbf{U} \mathbf{V}\f$, where \f$\mathbf{U}\f$ has a size \f$ (M \times r)\f$ and \f$\mathbf{V}\f$ has a size \f$ (r \times N)\f$, \f$ r\f$ being the resulting \p rank . The resulting \f$\mathbf{U}\f$ and \f$\mathbf{V}\f$ are stored on output in \p U and \p V. + * + * @param A VirtualGenerator given to generator coefficient of the approximated kernel. + * @param t target Cluster that defines the rows of the approximated block + * @param s source Cluster that defines the columns of the approximated block + * @param epsilon input tolerance + * @param rank On input, given tolerance or if \p rank <0, the approximation is expected to continue up to an epsilon tolerance. On output, it is the obtained rank at the end of the low rank approximation. + * @param U \f$ \mathbf{U} \f$-part of the low-rank approximation on output + * @param V \f$ \mathbf{V} \f$-part of the low-rank approximation on output + */ virtual void copy_low_rank_approximation(const VirtualGenerator &A, const Cluster &t, const Cluster &s, underlying_type epsilon, int &rank, Matrix &U, Matrix &V) const = 0; + /** + * @brief Check if htool needs to desallocate or not the data stored in \p U and \p V . + * + * @return true + * @return false + */ virtual bool is_htool_owning_data() const { return true; } virtual ~VirtualLowRankGenerator() {} }; From 96f2f87805f25806f3d8e7969362a54c921985b7 Mon Sep 17 00:00:00 2001 From: vdubos Date: Thu, 21 Sep 2023 10:20:03 +0200 Subject: [PATCH 2/3] add documentation for VirtualGenerator --- .../hmatrix/interfaces/virtual_generator.hpp | 23 +++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/include/htool/hmatrix/interfaces/virtual_generator.hpp b/include/htool/hmatrix/interfaces/virtual_generator.hpp index 5803c900..4c723df5 100644 --- a/include/htool/hmatrix/interfaces/virtual_generator.hpp +++ b/include/htool/hmatrix/interfaces/virtual_generator.hpp @@ -6,10 +6,24 @@ namespace htool { +/** + * @brief Define the interface for the user to give Htool a function generating dense sub-blocks of the global matrix the user wants to compress. This is done by the user implementing VirtualGenerator::copy_submatrix. + * + * @tparam T Precision of the coefficients (float, double,...). + */ template class VirtualGenerator { public: + /** + * @brief Generate a dense sub-block of the global matrix the user wants to compress. Note that sub-blocks queried by Htool are potentially non-contiguous in the user's numbering. + * + * @param[in] M specifies the number of columns of the queried block + * @param[in] N specifies the number of rows of the queried block + * @param[in] row_offset specifies the offset of the queried block. + * @param[in] col_offset specifies the offset of the queried block. + * @param[out] ptr is a \p T precision array of size \f$ M\times N\f$. Htool already allocates and desallocates it internally, so it should **not** be allocated by the user. + */ virtual void copy_submatrix(int M, int N, int row_offset, int col_offset, CoefficientPrecision *ptr) const = 0; // virtual void copy_submatrix(int M, int N, const int *rows, const int *cols, CoefficientPrecision *ptr) const = 0; @@ -36,6 +50,15 @@ class VirtualGeneratorWithPermutation : public VirtualGenerator Date: Fri, 22 Sep 2023 11:48:52 +0200 Subject: [PATCH 3/3] add param in/out --- .../hmatrix/interfaces/virtual_lrmat_generator.hpp | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/include/htool/hmatrix/interfaces/virtual_lrmat_generator.hpp b/include/htool/hmatrix/interfaces/virtual_lrmat_generator.hpp index 0a7c8936..5c619109 100644 --- a/include/htool/hmatrix/interfaces/virtual_lrmat_generator.hpp +++ b/include/htool/hmatrix/interfaces/virtual_lrmat_generator.hpp @@ -26,13 +26,13 @@ class VirtualLowRankGenerator { * * The low rank approximation is defined as \f$ \mathbf{U} \mathbf{V}\f$, where \f$\mathbf{U}\f$ has a size \f$ (M \times r)\f$ and \f$\mathbf{V}\f$ has a size \f$ (r \times N)\f$, \f$ r\f$ being the resulting \p rank . The resulting \f$\mathbf{U}\f$ and \f$\mathbf{V}\f$ are stored on output in \p U and \p V. * - * @param A VirtualGenerator given to generator coefficient of the approximated kernel. - * @param t target Cluster that defines the rows of the approximated block - * @param s source Cluster that defines the columns of the approximated block - * @param epsilon input tolerance - * @param rank On input, given tolerance or if \p rank <0, the approximation is expected to continue up to an epsilon tolerance. On output, it is the obtained rank at the end of the low rank approximation. - * @param U \f$ \mathbf{U} \f$-part of the low-rank approximation on output - * @param V \f$ \mathbf{V} \f$-part of the low-rank approximation on output + * @param[in] A VirtualGenerator given to generator coefficient of the approximated kernel. + * @param[in] t target Cluster that defines the rows of the approximated block + * @param[in] s source Cluster that defines the columns of the approximated block + * @param[in] epsilon input tolerance + * @param[inout] rank On input, given tolerance or if \p rank <0, the approximation is expected to continue up to an epsilon tolerance. On output, it is the obtained rank at the end of the low rank approximation. + * @param[out] U \f$ \mathbf{U} \f$-part of the low-rank approximation on output + * @param[out] V \f$ \mathbf{V} \f$-part of the low-rank approximation on output */ virtual void copy_low_rank_approximation(const VirtualGenerator &A, const Cluster &t, const Cluster &s, underlying_type epsilon, int &rank, Matrix &U, Matrix &V) const = 0;