Documentation

src/core/CrossCorrelation.h

@@ -34,29 +34,134 @@
 
 namespace mrcpp {
 
+/**
+ * @class CrossCorrelation
+ * @brief Container/loader for multiwavelet cross-correlation coefficient tables.
+ *
+ * This class encapsulates the left/right cross-correlation matrices associated
+ * with a chosen multiwavelet filter family and polynomial order.
+ *
+ *  • The filter "family" is identified by an integer @c type
+ *    (e.g., Interpolatory or Legendre; concrete codes are defined elsewhere
+ *    and validated in the implementation).
+ *
+ *  • The polynomial @c order is k ≥ 1. We use K = k + 1 for dimensions.
+ *
+ *  • Two dense matrices are held:
+ *        Left  ∈ ℝ^{(K·K) × (2K)},
+ *        Right ∈ ℝ^{(K·K) × (2K)}.
+ *    Each row corresponds to a flattened (i,j) pair with i,j∈{0..K−1};
+ *    each row stores a 2K-wide correlation stencil.
+ *
+ * Objects can be constructed by loading the binary coefficient files from disk
+ * (constructor #1) or by adopting matrices already residing in memory
+ * (constructor #2). Accessors expose the type/order and const references to
+ * the matrices; there are no mutating public methods by design.
+ *
+ * Invariants (enforced in the implementation):
+ *  - 1 ≤ order ≤ MaxOrder
+ *  - Left.cols() == Right.cols() == 2K where K = order + 1
+ *  - Left.rows() == Right.rows() == K*K
+ *
+ * Thread-safety: the class is a simple value holder once constructed.
+ * Concurrent reads are safe; concurrent writes are not supported.
+ */
 class CrossCorrelation final {
 public:
+    /**
+     * @brief Construct by loading coefficient tables from the filter library.
+     *
+     * The library path is discovered internally (see details::find_filters()).
+     * Files are chosen based on @p type and @p k and read into #Left/#Right.
+     *
+     * @param k     Polynomial order (k ≥ 1). Sets K = k + 1 for dimensions.
+     * @param t     Filter family/type code (e.g., Interpol, Legendre).
+     *
+     * @throws abort/error (via MRCPP messaging) on invalid @p k/@p t or if the
+     *         required binary files cannot be opened.
+     */
     CrossCorrelation(int k, int t);
+
+    /**
+     * @brief Construct from in-memory matrices (no file I/O).
+     *
+     * The order is inferred from the column count: 2K columns ⇒ order = K−1.
+     * The two matrices must be shape-compatible (same size).
+     *
+     * @param t      Filter family/type code.
+     * @param ldata  Left  matrix, size (K*K) × (2K).
+     * @param rdata  Right matrix, size (K*K) × (2K).
+     *
+     * @throws abort/error 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:
+    /**
+     * @brief Filter family/type code.
+     *
+     * The meaning of this integer is validated against known families
+     * (e.g., Interpolatory / Legendre) in the implementation. Kept as @c int
+     * here to avoid header dependencies on the specific enum.
+     */
     int type;
+
+    /**
+     * @brief Polynomial order k (k ≥ 1; K = k + 1).
+     *
+     * Controls the matrix dimensions:
+     *   rows = K*K, cols = 2K.
+     */
     int order;
 
+    /**
+     * @brief Left cross-correlation coefficient matrix.
+     * Size: (K*K) × (2K), where K = order + 1.
+     */
     Eigen::MatrixXd Left;
+
+    /**
+     * @brief Right cross-correlation coefficient matrix.
+     * Size: (K*K) × (2K), where K = order + 1.
+     */
     Eigen::MatrixXd Right;
 
 private:
+    /**
+     * @brief Compose on-disk file paths for the left/right tables.
+     *
+     * Uses the discovered filter library root @p lib and the current
+     * @c type / @c order to set #L_path and #R_path to the expected filenames.
+     * (Naming convention is family-specific; see implementation.)
+     */
     void setCCCPaths(const std::string &lib);
+
+    /**
+     * @brief Read the binary coefficient tables into #Left/#Right.
+     *
+     * Expects two files (left/right). Populates matrices with dimensions
+     * (K*K) × (2K). Very small magnitudes may be zeroed for numerical
+     * cleanliness (implementation detail).
+     */
     void readCCCBin();
 
+    /** @brief Full path to the left coefficient file (resolved at runtime). */
     std::string L_path;
+
+    /** @brief Full path to the right coefficient file (resolved at runtime). */
     std::string R_path;
 };
 
-} // namespace mrcpp
+} // namespace mrcpp

src/core/CrossCorrelationCache.h

@@ -33,29 +33,110 @@
 
 namespace mrcpp {
 
+/**
+ * @def getCrossCorrelationCache(T, X)
+ * @brief Convenience macro to obtain a named reference to the singleton cache.
+ *
+ * Expands to:
+ *   CrossCorrelationCache<T> &X = CrossCorrelationCache<T>::getInstance()
+ *
+ * Example:
+ *   getCrossCorrelationCache(Interpol, ccc);
+ *   const auto& L = ccc.getLMatrix(order);
+ */
 #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 for the Left matrix of a given order.
+     *
+     * Triggers lazy load if needed, then returns a const reference.
+     */
     const Eigen::MatrixXd &getLMatrix(int order);
+
+    /**
+     * @brief Convenience accessor for the Right matrix of a given order.
+     *
+     * Triggers lazy load if needed, then returns a const reference.
+     */
     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:
+    /**
+     * @brief Filter family/type code (matches template parameter @p T).
+     */
     int type;
+
+    /**
+     * @brief Base path to filter/correlation library on disk.
+     *
+     * Reserved for potential use by loaders. Actual path resolution is
+     * currently handled inside CrossCorrelation (see details::find_filters()).
+     */
     std::string libPath; ///< Base path to filter library
+
 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

@@ -24,15 +24,30 @@
  */
 
 /*
+ * Overview
+ * --------
+ * FilterCache provides a process-wide cache for multiwavelet filter banks
+ * (MWFilter) so that the same filter for a given polynomial order is created
+ * and loaded exactly once and then reused. This avoids repeated I/O and setup.
  *
- * \breif FilterCache is a static class taking care of loading and
- * unloading MultiWavelet filters, and their tensor counter parts.
+ * Design highlights:
+ *  - There are different *families* of filters (e.g. Legendre vs Interpolating).
+ *    We want caches for both, alive simultaneously. To achieve this, the
+ *    concrete cache is a class template FilterCache<T>, where T encodes the
+ *    family. Each T gets its own singleton instance.
  *
- * 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.
+ *  - The cache is keyed by the *order* (polynomial order k). Loading an entry
+ *    constructs MWFilter(order, type) and stores it internally for reuse.
  *
+ *  - Thread-safety and the actual load/get logic are implemented in the .cpp
+ *    using OpenMP locks (MRCPP_SET_OMP_LOCK / MRCPP_UNSET_OMP_LOCK).
+ *
+ * About this header:
+ *  - Declares a tiny abstract façade (BaseFilterCache) to allow use via a
+ *    non-templated base pointer/reference when the family is not known at
+ *    compile time.
+ *  - Declares the templated FilterCache<T> singleton with the minimal API:
+ *      load(order), get(order), and getFilterMatrix(order).
  */
 
 #pragma once
@@ -45,38 +60,106 @@
 
 namespace mrcpp {
 
+/**
+ * @def getFilterCache(T, X)
+ * @brief Create a named reference @p X bound to the singleton FilterCache<T>.
+ *
+ * Usage:
+ *   getFilterCache(Interpol, cache);
+ *   const auto& H = cache.getFilterMatrix(order);
+ *
+ * @def getLegendreFilterCache(X)
+ * @brief Convenience macro for FilterCache<Legendre>.
+ *
+ * @def getInterpolatingFilterCache(X)
+ * @brief Convenience macro for FilterCache<Interpol>.
+ */
 #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 Abstract façade over the templated filter cache.
+ *
+ * Rationale:
+ *   Callers that do not know the filter family T at compile time can still
+ *   interact with a cache through this non-templated interface. Concrete
+ *   implementations are provided by FilterCache<T>.
+ *
+ * Notes:
+ *   - Inherits from ObjectCache<MWFilter> to reuse generic cache plumbing.
+ *   - Pure virtual methods delegate to the concrete implementation in
+ *     FilterCache<T>.
+ */
 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 (e.g., Interpol, Legendre).
+ * @brief Singleton cache of MWFilter objects for a specific filter family.
+ *
+ * Key properties:
+ *  - One singleton instance per family T (Meyers singleton via getInstance()).
+ *  - API mirrors BaseFilterCache and ObjectCache<MWFilter>.
+ *  - The constructor is private to enforce the singleton pattern.
+ *  - Copy/assignment are deleted to prevent accidental duplication.
+ *
+ * Thread-safety:
+ *  - The .cpp guards first-time loads with OpenMP locks.
+ *  - Reads after an entry exists are lock-free through the base cache API.
+ */
 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:
+    /**
+     * @brief Runtime family/type code corresponding to template parameter T.
+     *
+     * Initialized in the private constructor; used to construct MWFilter(order, type).
+     */
     int type;
 
 private:
+    /**
+     * @brief Private constructor enforces the singleton pattern.
+     *
+     * Sets #type based on T and performs any minimal family-specific setup.
+     * (Validation happens in the .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