SplineBuilder doc

include/ddc/kernels/splines/spline_builder.hpp

@@ -10,10 +10,29 @@
 #include "deriv.hpp"
 
 namespace ddc {
+
+/**
+ * @brief An enum determining the backend solver of a SplineBuilder or SplineBuilder2d.
+ *
+ * An enum determining the backend solver of a SplineBuilder or SplineBuilder2d. Only GINKGO is available at the moment,
+ * other solvers will be implemented in the future.
+ */
 enum class SplineSolver {
-    GINKGO
-}; // Only GINKGO available atm, other solvers will be implemented in the futur
+    GINKGO ///< Enum member to identify the Ginkgo-based solver (iterative method)
+};
 
+/**
+ * @brief A helper giving the uniform/non_uniform status of a spline interpolation mesh according to its attributes.
+ *
+ * A helper giving the uniform/non_uniform status of a spline interpolation mesh according to its attributes.
+ *
+ * @param is_uniform A boolean giving the presumed status before considering boundary conditions.
+ * @param BcXmin The lower boundary condition.
+ * @param BcXmax The upper boundary condition.
+ * @param degree The degree of the spline.
+ *
+ * @return A boolean giving the uniform/non_uniform status.
+ */
 constexpr bool is_spline_interpolation_mesh_uniform(
         bool const is_uniform,
         ddc::BoundCond const BcXmin,
@@ -31,9 +50,17 @@ constexpr bool is_spline_interpolation_mesh_uniform(
  *
  * A class which contains an operator () which can be used to build a spline approximation
  * of a function. A spline approximation is represented by coefficients stored in a Chunk
- * of BSplines. The spline is constructed such that it respects the boundary conditions
+ * of B-splines. The spline is constructed such that it respects the boundary conditions
  * BcXmin and BcXmax, and it interpolates the function at the points on the interpolation_mesh
  * associated with interpolation_mesh_type.
+ * @tparam ExecSpace The Kokkos execution space on which the spline approximation is performed.
+ * @tparam MemorySpace The Kokkos memory space on which the data (interpolation function and splines coefficients) is stored.
+ * @tparam BSplines The discrete dimension representing the B-splines.
+ * @tparam InterpolationMesh The discrete dimension on which interpolation points are defined.
+ * @tparam BcXmin The lower boundary condition.
+ * @tparam BcXmax The upper boundary condition.
+ * @tparam Solver The SplineSolver giving the backend used to perform the spline approximation.
+ * @tparam IDimX A variadic template of all the discrete dimensions forming the full space (InterpolationMesh + batched dimensions).
  */
 template <
         class ExecSpace,
@@ -56,76 +83,92 @@ class SplineBuilder
     using tag_type = typename InterpolationMesh::continuous_dimension_type;
 
 public:
+    /// @brief The type of the Kokkos execution space used by this class.
     using exec_space = ExecSpace;
 
+    /// @brief The type of the Kokkos memory space used by this class.
     using memory_space = MemorySpace;
 
-    /**
-     * @brief The type of the interpolation mesh used by this class.
-     */
+    /// @brief The type of the interpolation discrete dimension (discrete dimension of interest) used by this class.
     using interpolation_mesh_type = InterpolationMesh;
 
-    /**
-     * @brief The type of the BSplines which are compatible with this class.
-     */
+    /// @brief The discrete dimension representing the B-splines.
     using bsplines_type = BSplines;
 
+    /// @brief The type of the Deriv dimension at the boundaries.
     using deriv_type = ddc::Deriv<tag_type>;
 
-    /**
-     * @brief The type of the domain for the interpolation mesh used by this class.
-     */
+    /// @brief The type of the domain for the 1D interpolation mesh used by this class.
     using interpolation_domain_type = ddc::DiscreteDomain<interpolation_mesh_type>;
 
+    /// @brief The type of the whole domain representing interpolation points.
     using batched_interpolation_domain_type = ddc::DiscreteDomain<IDimX...>;
 
+    /**
+	 * @brief The type of the batch domain (obtained by removing the dimension of interest
+	 * from the whole domain).
+	 *
+	 * Example: For batched_interpolation_domain_type = DiscreteDomain<X,Y,Z> and a dimension of interest Y,
+     * this is DiscreteDomain<X,Z>
+	 */
     using batch_domain_type =
             typename ddc::detail::convert_type_seq_to_discrete_domain<ddc::type_seq_remove_t<
                     ddc::detail::TypeSeq<IDimX...>,
                     ddc::detail::TypeSeq<interpolation_mesh_type>>>;
 
+    /**
+     * @brief The type of the whole spline domain (cartesian product of 1D spline domain
+     * and batch domain) preserving the underlying memory layout (order of dimensions).
+     *
+     * Example: For batched_interpolation_domain_type = DiscreteDomain<X,Y,Z> and a dimension of interest Y
+     * (associated to a B-splines tag BSplinesY), this is DiscreteDomain<X,BSplinesY,Z>.
+     */
     using batched_spline_domain_type =
             typename ddc::detail::convert_type_seq_to_discrete_domain<ddc::type_seq_replace_t<
                     ddc::detail::TypeSeq<IDimX...>,
                     ddc::detail::TypeSeq<interpolation_mesh_type>,
                     ddc::detail::TypeSeq<bsplines_type>>>;
 
+    /**
+     * @brief The type of the whole spline domain (cartesian product of the 1D spline domain
+     * and the batch domain) with 1D spline dimension being the leading dimension.
+     *
+     * Example: For batched_interpolation_domain_type = DiscreteDomain<X,Y,Z> and a dimension of interest Y
+     * (associated to a B-splines tag BSplinesY), this is DiscreteDomain<BSplinesY,X,Z>.
+     */
     using batched_spline_tr_domain_type =
             typename ddc::detail::convert_type_seq_to_discrete_domain<ddc::type_seq_merge_t<
                     ddc::detail::TypeSeq<bsplines_type>,
                     ddc::type_seq_remove_t<
                             ddc::detail::TypeSeq<IDimX...>,
                             ddc::detail::TypeSeq<interpolation_mesh_type>>>>;
 
+    /**
+     * @brief The type of the whole Deriv domain (cartesian product of 1D Deriv domain 
+     * and batch domain) preserving the underlying memory layout (order of dimensions).
+     *
+     * Example: For batched_interpolation_domain_type = DiscreteDomain<X,Y,Z> and a dimension of interest Y,
+     * this is DiscreteDomain<X,Deriv<Y>,Z>
+     */
     using batched_derivs_domain_type =
             typename ddc::detail::convert_type_seq_to_discrete_domain<ddc::type_seq_replace_t<
                     ddc::detail::TypeSeq<IDimX...>,
                     ddc::detail::TypeSeq<interpolation_mesh_type>,
                     ddc::detail::TypeSeq<deriv_type>>>;
 
-    /**
-     * @brief Indicates if the degree of the splines is odd or even.
-     */
+    /// @brief Indicates if the degree of the splines is odd or even.
     static constexpr bool s_odd = BSplines::degree() % 2;
 
-    /**
-     * @brief The number of equations which define the boundary conditions at the lower bound.
-     */
+    /// @brief The number of equations defining the boundary condition at the lower bound.
     static constexpr int s_nbc_xmin = n_boundary_equations(BcXmin, BSplines::degree());
 
-    /**
-     * @brief The number of equations which define the boundary conditions at the upper bound.
-     */
+    /// @brief The number of equations defining the boundary condition at the upper bound.
     static constexpr int s_nbc_xmax = n_boundary_equations(BcXmax, BSplines::degree());
 
-    /**
-     * @brief The boundary condition implemented at the lower bound.
-     */
+    /// @brief The boundary condition implemented at the lower bound.
     static constexpr ddc::BoundCond s_bc_xmin = BcXmin;
 
-    /**
-     * @brief The boundary condition implemented at the upper bound.
-     */
+    /// @brief The boundary condition implemented at the upper bound.
     static constexpr ddc::BoundCond s_bc_xmax = BcXmax;
 
 private:
@@ -142,6 +185,22 @@ class SplineBuilder
     int compute_offset(interpolation_domain_type const& interpolation_domain);
 
 public:
+    /**
+     * @brief Build a SplineBuilder acting on batched_interpolation_domain.
+     * 
+     * @param batched_interpolation_domain The domain on which the interpolation points are defined.
+     * @param cols_per_chunk A hyperparameter used by the slicer (internal to the solver) to define the size
+     * of a chunk of right-hand-sides of the linear problem to be computed in parallel (chunks are treated
+     * by the linear solver one-after-the-other).
+     *
+     * This value is optional. If no value is provided then the default value is chosen by the requested solver.
+     * @param preconditionner_max_block_size A hyperparameter used by the slicer (internal to the solver) to
+     * define the size of a block used by the Block-Jacobi preconditioner.
+     *
+     * This value is optional. If no value is provided then the default value is chosen by the requested solver.
+     *
+     * @see MatrixSparse
+     */
     explicit SplineBuilder(
             batched_interpolation_domain_type const& batched_interpolation_domain,
             std::optional<int> cols_per_chunk = std::nullopt,
@@ -169,62 +228,83 @@ class SplineBuilder
                 preconditionner_max_block_size);
     }
 
+    /// @brief Copy-constructor is deleted
     SplineBuilder(SplineBuilder const& x) = delete;
 
-    /**
-     * @brief Create a new SplineBuilder by copy
+    /** @brief Move-constructs
      *
-     * @param x The SplineBuilder being copied.
+     * @param x An rvalue to another SplineBuilder.
      */
     SplineBuilder(SplineBuilder&& x) = default;
 
+    /// @brief Destructs
     ~SplineBuilder() = default;
 
+    /// @brief Copy-assignment is deleted
     SplineBuilder& operator=(SplineBuilder const& x) = delete;
 
-    /**
-     * @brief Copy a SplineBuilder.
+    /** @brief Move-assigns
      *
-     * @param x The SplineBuilder being copied.
-     * @returns A reference to this object.
+     * @param x An rvalue to another SplineBuilder.
+     * @return A reference to the moved SplineBuilder
      */
     SplineBuilder& operator=(SplineBuilder&& x) = default;
 
-    batched_interpolation_domain_type batched_interpolation_domain() const noexcept
+    /**
+     * @brief Get the domain for the 1D interpolation mesh used by this class.
+     *
+     * This is 1D because it is defined along the dimension of interest.
+     *
+     * @return The 1D domain for the interpolation mesh.
+     */
+    interpolation_domain_type interpolation_domain() const noexcept
     {
-        return m_batched_interpolation_domain;
+        return interpolation_domain_type(m_batched_interpolation_domain);
     }
 
     /**
-     * @brief Get the domain from which the approximation is defined.
+     * @brief Get the whole domain representing interpolation points.
      *
-     * Get the domain on which values of the function must be provided in order
-     * to build a spline approximation of the function.
+     * Values of the function must be provided on this domain in order
+     * to build a spline representation of the function (cartesian product of 1D interpolation_domain and batch_domain).
      *
-     * @return The domain for the grid points.
+     * @return The domain for the interpolation mesh.
      */
-    interpolation_domain_type interpolation_domain() const noexcept
+    batched_interpolation_domain_type batched_interpolation_domain() const noexcept
     {
-        return interpolation_domain_type(batched_interpolation_domain());
+        return m_batched_interpolation_domain;
     }
 
+    /**
+     * @brief Get the batch domain.
+     *
+     * Obtained by removing the dimension of interest from the whole interpolation domain.
+     *
+     * @return The batch domain.
+     */
     batch_domain_type batch_domain() const noexcept
     {
         return ddc::remove_dims_of(batched_interpolation_domain(), interpolation_domain());
     }
 
+    /**
+     * @brief Get the 1D domain on which spline coefficients are defined.
+     *
+     * The 1D spline domain corresponding to the dimension of interest.
+     *
+     * @return The 1D domain for the spline coefficients.
+     */
     ddc::DiscreteDomain<bsplines_type> spline_domain() const noexcept
     {
         return ddc::discrete_space<bsplines_type>().full_domain();
     }
 
     /**
-     * @brief Get the domain on which the approximation is defined.
+     * @brief Get the whole domain on which spline coefficients are defined, preserving memory layout.
      *
-     * Get the domain of the basis-splines for which the coefficients of the spline
-     * approximation must be calculated.
+     * Spline approximations (spline-transformed functions) are computed on this domain.
      *
-     * @return The domain for the splines.
+     * @return The domain for the spline coefficients.
      */
     batched_spline_domain_type batched_spline_domain() const noexcept
     {
@@ -233,11 +313,25 @@ class SplineBuilder
                 bsplines_type>(batched_interpolation_domain(), spline_domain());
     }
 
+    /**
+     * @brief Get the whole domain on which spline coefficients are defined, with the dimension of interest being the leading dimension.
+     *
+     * This is used internally due to solver limitation and because it may be beneficial to computation performance.
+     *
+     * @return The (transposed) domain for the spline coefficients.
+     */
     batched_spline_tr_domain_type batched_spline_tr_domain() const noexcept
     {
         return batched_spline_tr_domain_type(spline_domain(), batch_domain());
     }
 
+    /**
+     * @brief Get the whole domain on which derivatives on lower boundary are defined.
+     *
+     * This is only used with BoundCond::HERMITE boundary conditions.
+     *
+     * @return The domain for the Derivs values.
+     */
     batched_derivs_domain_type batched_derivs_xmin_domain() const noexcept
     {
         return ddc::replace_dim_of<interpolation_mesh_type, deriv_type>(
@@ -247,6 +341,13 @@ class SplineBuilder
                         ddc::DiscreteVector<deriv_type>(s_nbc_xmin)));
     }
 
+    /**
+     * @brief Get the whole domain on which derivatives on upper boundary are defined.
+     *
+     * This is only used with BoundCond::HERMITE boundary conditions.
+     *
+     * @return The domain for the Derivs values.
+     */
     batched_derivs_domain_type batched_derivs_xmax_domain() const noexcept
     {
         return ddc::replace_dim_of<interpolation_mesh_type, deriv_type>(
@@ -259,9 +360,13 @@ class SplineBuilder
     /**
      * @brief Get the interpolation matrix.
      *
-     * Get the interpolation matrix. This can be useful for debugging (as it allows
+     * This can be useful for debugging (as it allows
      * one to print the matrix) or for more complex quadrature schemes.
      *
+     * Warning: the returned detail::Matrix class is not supposed to be exposed
+     * to user, which means its usage is not supported out of the scope of current class.
+     * Use at your own risk.
+     *
      * @return A reference to the interpolation matrix.
      */
     const ddc::detail::Matrix& get_interpolation_matrix() const noexcept
@@ -270,20 +375,23 @@ class SplineBuilder
     }
 
     /**
-     * @brief Build a spline approximation of a function.
+     * @brief Compute a spline approximation of a function.
      *
-     * Use the values of a function at known grid points (as specified by
-     * SplineBuilder::interpolation_domain) and the derivatives of the
-     * function at the boundaries (if necessary for the chosen boundary
-     * conditions) to calculate a spline approximation of a function.
+     * Use the values of a function (defined on
+     * SplineBuilder::batched_interpolation_domain) and the derivatives of the
+     * function at the boundaries (in the case of BoundCond::HERMITE only, defined 
+     * on SplineBuilder::batched_derivs_xmin_domain and SplineBuilder::batched_derivs_xmax_domain) 
+     * to calculate a spline approximation of this function.
      *
      * The spline approximation is stored as a ChunkSpan of coefficients
-     * associated with basis-splines.
+     * associated with B-splines.
      *
-     * @param[out] spline The coefficients of the spline calculated by the function.
-     * @param[in] vals The values of the function at the grid points.
-     * @param[in] derivs_xmin The values of the derivatives at the lower boundary.
-     * @param[in] derivs_xmax The values of the derivatives at the upper boundary.
+     * @param[out] spline The coefficients of the spline computed by this SplineBuilder.
+     * @param[in] vals The values of the function on the interpolation mesh.
+     * @param[in] derivs_xmin The values of the derivatives at the lower boundary
+     * (used only with BoundCond::HERMITE lower boundary condition).
+     * @param[in] derivs_xmax The values of the derivatives at the upper boundary
+     * (used only with BoundCond::HERMITE upper boundary condition).
      */
     template <class Layout>
     void operator()(