Documentation

src/core/CrossCorrelation.h

@@ -34,29 +34,88 @@
 
 namespace mrcpp {
 
+/**
+ * @class CrossCorrelation
+ * @brief Container and loader for the left and right cross-correlation coefficient matrices
+ *        of a multiwavelet filter family
+ *
+ * @details
+ * Holds two dense matrices associated with the chosen polynomial order \f$ k \f$ (\f$ K = k+1 \f$) and
+ * filter family #type (Interpol or Legendre):
+ * \f[
+ *   \mathrm{Left},\,\mathrm{Right} \in \mathbb{R}^{K^2 \times 2K}.
+ * \f]
+ * Each row corresponds to a flattened index pair \f$ (i,j) \f$ with \f$ i,j \in \{0,\ldots,K-1\} \f$
+ * and each row stores a \f$ 2K \f$-wide correlation stencil. Objects are constructed either by loading
+ * binary coefficient files from disk or by adopting in-memory matrices. There are no mutating public
+ * methods; the class is a thread-safe value holder once constructed.
+ *
+ * @see CrossCorrelationCache for the process-wide singleton that caches these objects by order
+ */
 class CrossCorrelation final {
 public:
+    /**
+     * @brief Construct by loading coefficient tables from the MRCPP filter library
+     * @param k Polynomial order (\f$ k \geq 1 \f$; \f$ K = k+1 \f$)
+     * @param t Filter family/type code (Interpol or Legendre)
+     *
+     * @details Discovers the library path via details::find_filters(), selects files by @p t and @p k,
+     * and reads them into #Left and #Right
+     *
+     * @note Aborts via MSG_ABORT if @p k or @p t is invalid or the files cannot be opened
+     */
     CrossCorrelation(int k, int t);
+
+    /**
+     * @brief Construct from in-memory matrices without file I/O
+     * @param t     Filter family/type code
+     * @param[in] ldata Left matrix of size \f$ K^2 \times 2K \f$
+     * @param[in] rdata Right matrix of size \f$ K^2 \times 2K \f$ (must match dimensions of @p ldata)
+     *
+     * @details The polynomial order is inferred as \f$ k = \text{ldata.cols()}/2 - 1 \f$
+     *
+     * @note Aborts if dimensions are inconsistent or the type is invalid
+     */
     CrossCorrelation(int t, const Eigen::MatrixXd &ldata, const Eigen::MatrixXd &rdata);
 
+    /** @return The filter family/type code associated with this object */
     int getType() const { return this->type; }
+
+    /** @return The polynomial order k (so K = k + 1) */
     int getOrder() const { return this->order; }
+
+    /** @return Const reference to the left cross-correlation matrix */
     const Eigen::MatrixXd &getLMatrix() const { return this->Left; }
+
+    /** @return Const reference to the right cross-correlation matrix */
     const Eigen::MatrixXd &getRMatrix() const { return this->Right; }
 
 protected:
-    int type;
-    int order;
+    int type;  ///< Filter family/type code (Interpol or Legendre; see constants.h)
+    int order; ///< Polynomial order \f$ k \f$ (\f$ K = k+1 \f$; controls matrix dimensions \f$ K^2 \times 2K \f$)
 
-    Eigen::MatrixXd Left;
-    Eigen::MatrixXd Right;
+    Eigen::MatrixXd Left;  ///< Left cross-correlation matrix of size \f$ K^2 \times 2K \f$
+    Eigen::MatrixXd Right; ///< Right cross-correlation matrix of size \f$ K^2 \times 2K \f$
 
 private:
+    /**
+     * @brief Compose the on-disk paths to the left and right binary tables
+     * @param[in] lib Root directory of the MRCPP filter library
+     *
+     * @details Sets #L_path and #R_path using family-specific naming conventions based on #type and #order
+     */
     void setCCCPaths(const std::string &lib);
+
+    /**
+     * @brief Read the binary coefficient tables from disk into #Left and #Right
+     *
+     * @details Reads two files whose paths are stored in #L_path and #R_path. Each file contains
+     * \f$ K^2 \f$ rows of \f$ 2K \f$ doubles. Values smaller than MachinePrec are zeroed.
+     */
     void readCCCBin();
 
-    std::string L_path;
-    std::string R_path;
+    std::string L_path; ///< Full path to the left coefficient binary file (resolved at construction)
+    std::string R_path; ///< Full path to the right coefficient binary file (resolved at construction)
 };
 
-} // namespace mrcpp
+} // namespace mrcpp

src/core/CrossCorrelationCache.cpp

@@ -76,71 +76,6 @@ template <int T> const Eigen::MatrixXd &CrossCorrelationCache<T>::getLMatrix(int
 }
 
 
-/** @brief Fetches the cross correlation coefficients.
- *
- * @param[in] order: Dimension of \f$ V_0 \subset L^2(\mathbb R) \f$ minus one,
- * that is the maximum degree \f$ k \f$ of polynomials in \f$ V_0 \subset L^2(0, 1) \f$.
- * @returns The right matrix of cross correlation coefficients.
- *
- * @details The cross correlation coefficients
- * \f[
- *   C^{(+)}_{ijp}
- *   =
- *   \int_0^1 dz
- *   \int_0^1 dx
- *   \phi_i(x)
- *   \phi_j(x - z)
- *   \phi_p(z)
- * \f]
- * with \f$ i, j = 0, \ldots, k \f$ and \f$ p = 0, \ldots, 2k + 1 \f$.
- * They are grouped in the so called right matrix
- * \f[
- *   \begin{pmatrix}
- *       C^{(+)}_{000}
- *       &
- *       C^{(+)}_{001}
- *       &
- *       \ldots
- *       &
- *       C^{(+)}_{00,2k+1}
- *       \\
- *       C^{(+)}_{010}
- *       &
- *       C^{(+)}_{011}
- *       &
- *       \ldots
- *       &
- *       C^{(+)}_{01,2k+1}
- *       \\
- *       \ldots
- *       &
- *       \ldots
- *       &
- *       \ldots
- *       &
- *       \ldots
- *       \\
- *       C^{(+)}_{k, k - 1, 0}
- *       &
- *       C^{(+)}_{k, k - 1, 1}
- *       &
- *       \ldots
- *       &
- *       C^{(+)}_{k, k - 1, 2k+1}
- *       \\
- *       C^{(+)}_{kk0}
- *       &
- *       C^{(+)}_{kk1}
- *       &
- *       \ldots
- *       &
- *       C^{(+)}_{kk,2k+1}
- *   \end{pmatrix}
- * \f]
- * that is returned by the method.
- * 
- *
- */
 template <int T> const Eigen::MatrixXd &CrossCorrelationCache<T>::getRMatrix(int order) {
     if (not hasId(order)) { load(order); }
     return ObjectCache<CrossCorrelation>::get(order).getRMatrix();

src/core/CrossCorrelationCache.h

@@ -33,29 +33,103 @@
 
 namespace mrcpp {
 
+/**
+ * @def getCrossCorrelationCache(T, X)
+ * @brief Bind a local reference @p X to the singleton CrossCorrelationCache<T>
+ *
+ * @details Expands to <tt>CrossCorrelationCache<T> &X = CrossCorrelationCache<T>::getInstance()</tt>
+ * Example: <tt>getCrossCorrelationCache(Interpol, ccc); const auto& L = ccc.getLMatrix(order);</tt>
+ */
 #define getCrossCorrelationCache(T, X) CrossCorrelationCache<T> &X = CrossCorrelationCache<T>::getInstance()
 
+/**
+ * @class CrossCorrelationCache
+ * @brief Thread-safe cache for @ref CrossCorrelation objects, keyed by order
+ *
+ * This cache avoids repeatedly loading the (potentially large) left/right
+ * cross-correlation matrices from disk. One cache instance exists per filter
+ * family, realized as a template parameter @p T (e.g., Interpol or Legendre).
+ *
+ * Design notes:
+ *  - Singleton pattern (Meyers singleton) per @p T via getInstance().
+ *  - Inherits from @ref ObjectCache<CrossCorrelation>, which provides the
+ *    generic cache interface (load/get/hasId etc.).
+ *  - Actual loading and synchronization details are implemented in the
+ *    corresponding .cpp; OpenMP locks guard first-time insertions.
+ *
+ * @tparam T Filter family tag (int constant), e.g. Interpol or Legendre
+ */
 template <int T> class CrossCorrelationCache final : public ObjectCache<CrossCorrelation> {
 public:
+    /**
+     * @brief Access the unique cache instance for the template family @p T
+     *
+     * Uses a function-local static (Meyers singleton). Thread-safe in C++11+.
+     */
     static CrossCorrelationCache<T> &getInstance() {
         static CrossCorrelationCache<T> theCrossCorrelationCache;
         return theCrossCorrelationCache;
     }
+
+    /**
+     * @brief Ensure that the entry for @p order is present in the cache
+     *
+     * If absent, constructs a new @ref CrossCorrelation(order, type) and
+     * inserts it. See .cpp for locking and memory accounting.
+     */
     void load(int order) override;
+
+    /**
+     * @brief Retrieve the cached @ref CrossCorrelation for @p order
+     *
+     * Loads on demand if missing. Returns a reference owned by the cache.
+     */
     CrossCorrelation &get(int order) override;
 
+    /**
+     * @brief Convenience accessor returning the Left cross-correlation matrix for a given order
+     * @param order Polynomial order k
+     * @return Const reference to the left matrix (lazy-loads the entry if absent)
+     */
     const Eigen::MatrixXd &getLMatrix(int order);
+
+    /**
+     * @brief Convenience accessor returning the Right cross-correlation matrix for a given order
+     * @param order Polynomial order \f$ k \f$
+     * @return Const reference to the right cross-correlation coefficient matrix (lazy-loads if absent)
+     *
+     * @details The right matrix collects the cross-correlation coefficients
+     * \f[
+     *   C^{(+)}_{ijp} = \int_0^1 dz \int_0^1 dx\, \phi_i(x)\, \phi_j(x-z)\, \phi_p(z)
+     * \f]
+     * with \f$ i,j = 0,\ldots,k \f$ and \f$ p = 0,\ldots,2k+1 \f$, arranged row-wise with the
+     * flattened \f$(i,j)\f$ index as the row and \f$ p \f$ as the column index
+     */
     const Eigen::MatrixXd &getRMatrix(int order);
 
+    /**
+     * @brief Filter family/type code associated with this cache
+     *
+     * Set in the private constructor based on the template parameter @p T.
+     * (E.g., Interpol or Legendre.)
+     */
     int getType() const { return this->type; }
 
 protected:
-    int type;
-    std::string libPath; ///< Base path to filter library
+    int type;           ///< Filter family/type code matching template parameter @p T (e.g., Interpol or Legendre)
+    std::string libPath; ///< Reserved base path for the filter library (path resolution is currently delegated to CrossCorrelation)
+
 private:
+    /**
+     * @brief Private constructor enforces the singleton pattern
+     *
+     * Initializes @ref type based on T; see .cpp for validation.
+     */
     CrossCorrelationCache();
+
+    // Non-copyable / non-assignable — keeps the singleton unique.
     CrossCorrelationCache(CrossCorrelationCache<T> const &ccc) = delete;
     CrossCorrelationCache<T> &operator=(CrossCorrelationCache<T> const &ccc) = delete;
 };
 
-} // namespace mrcpp
+} // namespace mrcpp

src/core/FilterCache.h

@@ -23,18 +23,6 @@
  * <https://mrcpp.readthedocs.io/>
  */
 
-/*
- *
- * \breif FilterCache is a static class taking care of loading and
- * unloading MultiWavelet filters, and their tensor counter parts.
- *
- * All data in FilterCache is static, and thus shared amongst all
- * instance objects. The type of filter, Legendre or Interpolating is
- * determined by a template variable so that both types of filters can
- * co-exist.
- *
- */
-
 #pragma once
 
 #include "MWFilter.h"
@@ -45,38 +33,93 @@
 
 namespace mrcpp {
 
+/**
+ * @def getFilterCache(T, X)
+ * @brief Bind a local reference @p X to the singleton FilterCache<T>
+ *
+ * @details Expands to <tt>FilterCache<T> &X = FilterCache<T>::getInstance()</tt>
+ */
+
+/**
+ * @def getLegendreFilterCache(X)
+ * @brief Convenience shorthand for @ref getFilterCache with the Legendre family
+ */
+
+/**
+ * @def getInterpolatingFilterCache(X)
+ * @brief Convenience shorthand for @ref getFilterCache with the Interpol family
+ */
 #define getFilterCache(T, X) FilterCache<T> &X = FilterCache<T>::getInstance()
 #define getLegendreFilterCache(X) FilterCache<Legendre> &X = FilterCache<Legendre>::getInstance()
 #define getInterpolatingFilterCache(X) FilterCache<Interpol> &X = FilterCache<Interpol>::getInstance()
 
-/** This class is an abstract base class for the various filter caches.
- * It's needed in order to be able to use the actual filter caches
- * without reference to the actual filter types */
+/**
+ * @class BaseFilterCache
+ * @brief Non-templated abstract interface over the filter cache hierarchy
+ *
+ * @details Callers that do not know the filter family at compile time can interact with any FilterCache<T>
+ * through this base class. Inherits from ObjectCache<MWFilter> for generic index-addressed storage,
+ * and declares pure virtual load(), get(), and getFilterMatrix() for family-specific implementations.
+ */
 class BaseFilterCache : public ObjectCache<MWFilter> {
 public:
+    /// Ensure the filter for @p order exists in the cache (lazy load if needed)
     void load(int order) override = 0;
+
+    /// Retrieve the cached MWFilter for @p order (loads it on demand)
     MWFilter &get(int order) override = 0;
+
+    /// Convenience accessor: return the filter matrix (const) for @p order
     virtual const Eigen::MatrixXd &getFilterMatrix(int order) = 0;
 };
 
+/**
+ * @class FilterCache
+ * @tparam T Integer tag selecting the filter family (Interpol or Legendre)
+ * @brief Process-wide singleton cache for MWFilter objects keyed by polynomial order
+ *
+ * @details One instance exists per family @p T (Meyers singleton via getInstance()). First-time loads
+ * construct MWFilter(order, type) under an OpenMP lock; subsequent reads are lock-free. Copy and
+ * assignment are deleted to enforce singleton semantics.
+ *
+ * @see MWFilter for the cached object type
+ * @see BaseFilterCache for the non-templated interface
+ */
 template <int T> class FilterCache final : public BaseFilterCache {
 public:
+    /**
+     * @brief Access the singleton cache for the template family T
+     *
+     * The instance is created on first use and lives until program exit
+     */
     static FilterCache &getInstance() {
         static FilterCache theFilterCache;
         return theFilterCache;
     }
 
+    /// Ensure entry for @p order exists; loads it if missing (see .cpp)
     void load(int order) override;
+
+    /// Retrieve the MWFilter for @p order; loads it if missing
     MWFilter &get(int order) override;
+
+    /// Convenience accessor returning a const reference to the filter matrix
     const Eigen::MatrixXd &getFilterMatrix(int order) override;
 
 protected:
-    int type;
+    int type; ///< Runtime family/type code derived from template parameter @p T; passed to MWFilter(order, type)
 
 private:
+    /**
+     * @brief Private constructor enforces the singleton pattern
+     *
+     * @details Sets #type from @p T and performs minimal family-specific validation (see .cpp)
+     */
     FilterCache();
+
+    // Non-copyable and non-assignable to maintain single instance semantics.
     FilterCache(FilterCache<T> const &fc) = delete;
     FilterCache &operator=(FilterCache<T> const &fc) = delete;
 };
 
-} // namespace mrcpp
+} // namespace mrcpp