Documentation

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 <typename CoefficientPrecision>
 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<CoefficientPreci
         copy_submatrix_from_user_numbering(M, N, m_target_permutation + row_offset, m_source_permutation + col_offset, ptr);
     }
 
+    /**
+     * @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] rows is an integer array of size \f$M\f$. It specifies the queried columns in the user's numbering
+     * @param[in] cols is an integer array of size \f$N\f$. It specifies the queried rows in the user's numbering
+     * @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_from_user_numbering(int M, int N, const int *rows, const int *cols, CoefficientPrecision *ptr) const = 0;
 };
 

include/htool/hmatrix/interfaces/virtual_lrmat_generator.hpp

@@ -9,14 +9,39 @@
 
 namespace htool {
 
+/**
+ * @brief
+ *
+ * @tparam CoefficientPrecision
+ * @tparam CoordinatesPrecision
+ */
 template <typename CoefficientPrecision, typename CoordinatesPrecision>
 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[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<CoefficientPrecision> &A, const Cluster<CoordinatesPrecision> &t, const Cluster<CoordinatesPrecision> &s, underlying_type<CoefficientPrecision> epsilon, int &rank, Matrix<CoefficientPrecision> &U, Matrix<CoefficientPrecision> &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() {}
 };