diff --git a/include/ddc/kernels/splines/null_extrapolation_rule.hpp b/include/ddc/kernels/splines/null_extrapolation_rule.hpp index baa5bc6ab..c26c3039d 100644 --- a/include/ddc/kernels/splines/null_extrapolation_rule.hpp +++ b/include/ddc/kernels/splines/null_extrapolation_rule.hpp @@ -8,8 +8,16 @@ namespace ddc { +/** + * @brief A functor describing a null extrapolation boundary value for 1D spline evaluator. + */ struct NullExtrapolationRule { + /** + * @brief Evaluates the spline at a coordinate outside of the domain. + * + * @return A double with the value of the function outside the domain (here, 0.). + */ template KOKKOS_FUNCTION double operator()(CoordType, ChunkSpan) const { diff --git a/include/ddc/kernels/splines/spline_evaluator.hpp b/include/ddc/kernels/splines/spline_evaluator.hpp index d85d64b1b..444116498 100644 --- a/include/ddc/kernels/splines/spline_evaluator.hpp +++ b/include/ddc/kernels/splines/spline_evaluator.hpp @@ -15,10 +15,23 @@ namespace ddc { +/** + * @brief A class to evaluate, differentiate or integrate a spline function. + * + * A class which contains an operator () which can be used to evaluate, differentiate or integrate a spline function. + * + * @tparam ExecSpace The Kokkos execution space on which the spline evaluation is performed. + * @tparam MemorySpace The Kokkos memory space on which the data (spline coefficients and evaluation) is stored. + * @tparam BSplines The discrete dimension representing the B-splines. + * @tparam EvaluationMesh The discrete dimension on which evaluation points are defined. + * @tparam LeftExtrapolationRule The lower extrapolation rule type. + * @tparam RightExtrapolationRule The upper extrapolation rule type. + * @tparam IDimX A variadic template of all the discrete dimensions forming the full space (EvaluationMesh + batched dimensions). + */ template < class ExecSpace, class MemorySpace, - class BSplinesType, + class BSplines, class EvaluationMesh, class LeftExtrapolationRule, class RightExtrapolationRule, @@ -26,46 +39,69 @@ template < class SplineEvaluator { private: - // Tags to determine what to evaluate + /** + * @brief Tag to indicate that the value of the spline should be evaluated. + */ struct eval_type { }; + /** + * @brief Tag to indicate that derivative of the spline should be evaluated. + */ struct eval_deriv_type { }; - using tag_type = typename BSplinesType::tag_type; + using tag_type = typename BSplines::tag_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; - using bsplines_type = BSplinesType; - - using left_extrapolation_rule_type = LeftExtrapolationRule; - using right_extrapolation_rule_type = RightExtrapolationRule; - + /// @brief The type of the evaluation discrete dimension (discrete dimension of interest) used by this class. using evaluation_mesh_type = EvaluationMesh; + /// @brief The discrete dimension representing the B-splines. + using bsplines_type = BSplines; + + /// @brief The type of the domain for the 1D evaluation mesh used by this class. using evaluation_domain_type = ddc::DiscreteDomain; + /// @brief The type of the whole domain representing evaluation points. using batched_evaluation_domain_type = ddc::DiscreteDomain; + /// @brief The type of the 1D spline domain corresponding to the dimension of interest. using spline_domain_type = ddc::DiscreteDomain; + /** + * @brief The type of the batch domain (obtained by removing the dimension of interest + * from the whole domain). + */ using batch_domain_type = typename ddc::detail::convert_type_seq_to_discrete_domain, ddc::detail::TypeSeq>>; + /** + * @brief The type of the whole spline domain (cartesian product of 1D spline domain + * and batch domain) preserving the order of dimensions. + */ using batched_spline_domain_type = typename ddc::detail::convert_type_seq_to_discrete_domain, ddc::detail::TypeSeq, ddc::detail::TypeSeq>>; + /// @brief The type of the extrapolation rule at the lower boundary. + using left_extrapolation_rule_type = LeftExtrapolationRule; + + /// @brief The type of the extrapolation rule at the upper boundary. + using right_extrapolation_rule_type = RightExtrapolationRule; + private: LeftExtrapolationRule m_left_extrap_rule; @@ -105,6 +141,14 @@ class SplineEvaluator memory_space>>, "RightExtrapolationRule::operator() has to be callable with usual arguments."); + /** + * @brief Build a SplineEvaluator acting on batched_spline_domain. + * + * @param left_extrap_rule The extrapolation rule at the lower boundary. + * @param right_extrap_rule The extrapolation rule at the upper boundary. + * + * @see NullExtrapolationRule ConstantExtrapolationRule PeriodicExtrapolationRule + */ explicit SplineEvaluator( LeftExtrapolationRule const& left_extrap_rule, RightExtrapolationRule const& right_extrap_rule) @@ -113,26 +157,79 @@ class SplineEvaluator { } + /** + * @brief Copy-constructs. + * + * @param x A reference to another SplineEvaluator. + */ SplineEvaluator(SplineEvaluator const& x) = default; + /** + * @brief Move-constructs. + * + * @param x An rvalue to another SplineEvaluator. + */ SplineEvaluator(SplineEvaluator&& x) = default; + /// @brief Destructs ~SplineEvaluator() = default; + /** + * @brief Copy-assigns. + * + * @param x A reference to another SplineEvaluator. + * @return A reference to this object. + */ SplineEvaluator& operator=(SplineEvaluator const& x) = default; + /** + * @brief Move-assigns. + * + * @param x An rvalue to another SplineEvaluator. + * @return A reference to this object. + */ SplineEvaluator& operator=(SplineEvaluator&& x) = default; + /** + * @brief Get the lower extrapolation rule. + * + * Extrapolation rules are functors used to define the behavior of the SplineEvaluator out of the domain where the break points of the B-splines are defined. + * + * @return The lower extrapolation rule. + * + * @see NullExtrapolationRule ConstantExtrapolationRule PeriodicExtrapolationRule + */ left_extrapolation_rule_type left_extrapolation_rule() const { return m_left_extrap_rule; } + /** + * @brief Get the upper extrapolation rule. + * + * Extrapolation rules are functors used to define the behavior of the SplineEvaluator out of the domain where the break points of the B-splines are defined. + * + * @return The upper extrapolation rule. + * + * @see NullExtrapolationRule ConstantExtrapolationRule PeriodicExtrapolationRule + */ right_extrapolation_rule_type right_extrapolation_rule() const { return m_right_extrap_rule; } + /** + * @brief Evaluate 1D spline function (described by its spline coefficients) at a given coordinate. + * + * The spline coefficients represent a 1D spline function defined on a B-splines (basis splines). They can be obtained via various methods, such as using a SplineBuilder. + * + * Remark: calling SplineBuilder then SplineEvaluator corresponds to a spline interpolation. + * + * @param coord_eval The coordinate where the spline is evaluated. Note that only the component along the dimension of interest is used. + * @param spline_coef A ChunkSpan storing the 1D spline coefficients. + * + * @return The value of the spline function at the desired coordinate. + */ template KOKKOS_FUNCTION double operator()( ddc::Coordinate const& coord_eval, @@ -142,6 +239,26 @@ class SplineEvaluator return eval(coord_eval, spline_coef); } + /** + * @brief Evaluate spline function (described by its spline coefficients) on a mesh. + * + * The spline coefficients represent a spline function defined on a cartesian product of batch_domain and B-splines + * (basis splines). They can be obtained via various methods, such as using a SplineBuilder. + * + * This is not a multidimensional evaluation. This is a batched 1D evaluation. This means that for each slice of coordinates + * identified by a batch_domain_type::discrete_element_type, the evaluation is performed with the 1D set of + * spline coefficients identified by the same batch_domain_type::discrete_element_type. + * + * Remark: calling SplineBuilder then SplineEvaluator corresponds to a spline interpolation. + * + * @param[out] spline_eval The values of the spline function at the desired coordinates. For practical reasons those are + * stored in a ChunkSpan defined on a batched_evaluation_domain_type. + * @param[in] coords_eval The coordinates where the spline is evaluated. Those are + * stored in a ChunkSpan defined on a batched_evaluation_domain_type. Note that the coordinates of the + * points represented by this domain are unused and irrelevant (but the points themselves (DiscreteElement) are used to select + * the set of 1D spline coefficients retained to perform the evaluation). + * @param[in] spline_coef A ChunkSpan storing the spline coefficients. + */ template void operator()( ddc::ChunkSpan const @@ -170,6 +287,17 @@ class SplineEvaluator }); } + /** + * @brief Differentiate 1D spline function (described by its spline coefficients) at a given coordinate. + * + * The spline coefficients represent a 1D spline function defined on a B-splines (basis splines). They can be + * obtained via various methods, such as using a SplineBuilder. + * + * @param coord_eval The coordinate where the spline is differentiated. Note that only the component along the dimension of interest is used. + * @param spline_coef A ChunkSpan storing the 1D spline coefficients. + * + * @return The derivative of the spline function at the desired coordinate. + */ template KOKKOS_FUNCTION double deriv( ddc::Coordinate const& coord_eval, @@ -179,6 +307,24 @@ class SplineEvaluator return eval_no_bc(coord_eval, spline_coef); } + /** + * @brief Differentiate spline function (described by its spline coefficients) on a mesh. + * + * The spline coefficients represent a spline function defined on a cartesian product of batch_domain and B-splines + * (basis splines). They can be obtained via various methods, such as using a SplineBuilder. + * + * The derivation is not performed in a multidimensional way (in any sense). This is a batched 1D derivation. + * This means that for each slice of coordinates identified by a batch_domain_type::discrete_element_type, + * the derivation is performed with the 1D set of spline coefficients identified by the same batch_domain_type::discrete_element_type. + * + * @param[out] spline_eval The derivatives of the spline function at the desired coordinates. For practical reasons those are + * stored in a ChunkSpan defined on a batched_evaluation_domain_type. + * @param[in] coords_eval The coordinates where the spline is differentiated. Those are + * stored in a ChunkSpan defined on a batched_evaluation_domain_type. Note that the coordinates of the + * points represented by this domain are unused and irrelevant (but the points themselves (DiscreteElement) are used to select + * the set of 1D spline coefficients retained to perform the evaluation). + * @param[in] spline_coef A ChunkSpan storing the spline coefficients. + */ template void deriv( ddc::ChunkSpan const @@ -208,6 +354,19 @@ class SplineEvaluator }); } + /** @brief Perform batched 1D integrations of a spline function (described by its spline coefficients) along the dimension of interest and store results on a subdomain of batch_domain. + * + * The spline coefficients represent a spline function defined on a B-splines (basis splines). They can be obtained via the SplineBuilder. + * + * The integration is not performed in a multidimensional way (in any sense). This is a batched 1D integration. + * This means that for each element of integrals, the integration is performed with the 1D set of + * spline coefficients identified by the same DiscreteElement. + * + * @param[out] integrals The integrals of the spline function on the subdomain of batch_domain. For practical reasons those are + * stored in a ChunkSpan defined on a batch_domain_type. Note that the coordinates of the + * points represented by this domain are unused and irrelevant. + * @param[in] spline_coef A ChunkSpan storing the spline coefficients. + */ template void integrate( ddc::ChunkSpan const integrals, diff --git a/include/ddc/kernels/splines/spline_evaluator_2d.hpp b/include/ddc/kernels/splines/spline_evaluator_2d.hpp index fa77349a2..57701ead2 100644 --- a/include/ddc/kernels/splines/spline_evaluator_2d.hpp +++ b/include/ddc/kernels/splines/spline_evaluator_2d.hpp @@ -16,15 +16,29 @@ namespace ddc { /** - * @brief Define an evaluator 2D on B-splines. + * @brief A class to evaluate, differentiate or integrate a 2D spline function. + * + * A class which contains an operator () which can be used to evaluate, differentiate or integrate a 2D spline function. + * + * @tparam ExecSpace The Kokkos execution space on which the spline evaluation is performed. + * @tparam MemorySpace The Kokkos memory space on which the data (spline coefficients and evaluation) is stored. + * @tparam BSplines1 The discrete dimension representing the B-splines along the first dimension of interest. + * @tparam BSplines2 The discrete dimension representing the B-splines along the second dimension of interest. + * @tparam EvaluationMesh1 The first discrete dimension on which evaluation points are defined. + * @tparam EvaluationMesh2 The second discrete dimension on which evaluation points are defined. + * @tparam LeftExtrapolationRule1 The lower extrapolation rule type along first dimension of interest. + * @tparam RightExtrapolationRule1 The upper extrapolation rule type along first dimension of interest. + * @tparam LeftExtrapolationRule2 The lower extrapolation rule type along second dimension of interest. + * @tparam RightExtrapolationRule2 The upper extrapolation rule type along second dimension of interest. + * @tparam IDimX A variadic template of all the discrete dimensions forming the full space (EvaluationMesh1 + EvaluationMesh2 + batched dimensions). */ template < class ExecSpace, class MemorySpace, - class BSplinesType1, - class BSplinesType2, - class evaluation_mesh_type1, - class evaluation_mesh_type2, + class BSplines1, + class BSplines2, + class EvaluationMesh1, + class EvaluationMesh2, class LeftExtrapolationRule1, class RightExtrapolationRule1, class LeftExtrapolationRule2, @@ -47,44 +61,80 @@ class SplineEvaluator2D { }; - using tag_type1 = typename BSplinesType1::tag_type; - using tag_type2 = typename BSplinesType2::tag_type; + using tag_type1 = typename BSplines1::tag_type; + using tag_type2 = typename BSplines2::tag_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; - using bsplines_type1 = BSplinesType1; - using bsplines_type2 = BSplinesType2; + /// @brief The type of the first discrete dimension of interest used by this class. + using evaluation_mesh_type1 = EvaluationMesh1; - using left_extrapolation_rule_1_type = LeftExtrapolationRule1; - using right_extrapolation_rule_1_type = RightExtrapolationRule1; - using left_extrapolation_rule_2_type = LeftExtrapolationRule2; - using right_extrapolation_rule_2_type = RightExtrapolationRule2; + /// @brief The type of the second discrete dimension of interest used by this class. + using evaluation_mesh_type2 = EvaluationMesh2; + /// @brief The discrete dimension representing the B-splines along first dimension. + using bsplines_type1 = BSplines1; + + /// @brief The discrete dimension representing the B-splines along second dimension. + using bsplines_type2 = BSplines2; + + /// @brief The type of the domain for the 1D evaluation mesh along first dimension used by this class. using evaluation_domain_type1 = ddc::DiscreteDomain; + + /// @brief The type of the domain for the 1D evaluation mesh along second dimension used by this class. using evaluation_domain_type2 = ddc::DiscreteDomain; + + /// @brief The type of the domain for the 2D evaluation mesh used by this class. using evaluation_domain_type = ddc::DiscreteDomain; + /// @brief The type of the whole domain representing evaluation points. using batched_evaluation_domain_type = ddc::DiscreteDomain; + /// @brief The type of the 1D spline domain corresponding to the first dimension of interest. using spline_domain_type1 = ddc::DiscreteDomain; + + /// @brief The type of the 1D spline domain corresponding to the second dimension of interest. using spline_domain_type2 = ddc::DiscreteDomain; + + /// @brief The type of the 2D spline domain corresponding to the dimensions of interest. using spline_domain_type = ddc::DiscreteDomain; + /** + * @brief The type of the batch domain (obtained by removing the dimensions of interest + * from the whole domain). + */ using batch_domain_type = typename ddc::detail::convert_type_seq_to_discrete_domain, ddc::detail::TypeSeq>>; + /** + * @brief The type of the whole spline domain (cartesian product of 2D spline domain + * and batch domain) preserving the underlying memory layout (order of dimensions). + */ using batched_spline_domain_type = typename ddc::detail::convert_type_seq_to_discrete_domain, ddc::detail::TypeSeq, ddc::detail::TypeSeq>>; + /// @brief The type of the extrapolation rule at the lower boundary along the first dimension. + using left_extrapolation_rule_1_type = LeftExtrapolationRule1; + + /// @brief The type of the extrapolation rule at the upper boundary along the first dimension. + using right_extrapolation_rule_1_type = RightExtrapolationRule1; + + /// @brief The type of the extrapolation rule at the lower boundary along the second dimension. + using left_extrapolation_rule_2_type = LeftExtrapolationRule2; + + /// @brief The type of the extrapolation rule at the upper boundary along the second dimension. + using right_extrapolation_rule_2_type = RightExtrapolationRule2; private: LeftExtrapolationRule1 m_left_extrap_rule_1; @@ -163,22 +213,14 @@ class SplineEvaluator2D "with usual arguments."); /** - * @brief Instantiate an evaluator operator. - * - * @param[in] left_extrap_rule1 - * A SplineBoundaryValue2D object giving the value on the "left side" of the domain - * in the first dimension. - * @param[in] right_extrap_rule1 - * A SplineBoundaryValue2D object giving the value on the "right side" of the domain - * in the first dimension. - * @param[in] left_extrap_rule2 - * A SplineBoundaryValue2D object giving the value on the "left side" of the domain - * in the second dimension. - * @param[in] right_extrap_rule2 - * A SplineBoundaryValue2D object giving the value on the "right side" of the domain - * in the second dimension. - * - * @see SplineBoundaryValue2D + * @brief Build a SplineEvaluator2D acting on batched_spline_domain. + * + * @param left_extrap_rule1 The extrapolation rule at the lower boundary along the first dimension. + * @param right_extrap_rule1 The extrapolation rule at the upper boundary along the first dimension. + * @param left_extrap_rule2 The extrapolation rule at the lower boundary along the second dimension. + * @param right_extrap_rule2 The extrapolation rule at the upper boundary along the second dimension. + * + * @see NullExtrapolationRule ConstantExtrapolationRule PeriodicExtrapolationRule */ explicit SplineEvaluator2D( LeftExtrapolationRule1 const& left_extrap_rule1, @@ -193,76 +235,105 @@ class SplineEvaluator2D } /** - * @brief Instantiate a SplineEvaluator2D from another - * SplineEvaluator2D (lvalue). + * @brief Copy-constructs. * - * @param[in] x - * SplineEvaluator2D evaluator used to instantiate the new one. + * @param x A reference to another SplineEvaluator. */ SplineEvaluator2D(SplineEvaluator2D const& x) = default; /** - * @brief Instantiate a SplineEvaluator2D from another temporary - * SplineEvaluator2D (rvalue). + * @brief Move-constructs. * - * @param[in] x - * SplineEvaluator2D evaluator used to instantiate the new one. + * @param x An rvalue to another SplineEvaluator. */ SplineEvaluator2D(SplineEvaluator2D&& x) = default; + /// @brief Destructs. ~SplineEvaluator2D() = default; /** - * @brief Assign a SplineEvaluator2D from another SplineEvaluator2D (lvalue). - * - * @param[in] x - * SplineEvaluator2D mapping used to assign. + * @brief Copy-assigns. * - * @return The SplineEvaluator2D assigned. + * @param x A reference to another SplineEvaluator. + * @return A reference to this object. */ SplineEvaluator2D& operator=(SplineEvaluator2D const& x) = default; /** - * @brief Assign a SplineEvaluator2D from another temporary SplineEvaluator2D (rvalue). + * @brief Move-assigns. * - * @param[in] x - * SplineEvaluator2D mapping used to assign. - * - * @return The SplineEvaluator2D assigned. + * @param x An rvalue to another SplineEvaluator. + * @return A reference to this object. */ SplineEvaluator2D& operator=(SplineEvaluator2D&& x) = default; - - + /** + * @brief Get the lower extrapolation rule along the first dimension. + * + * Extrapolation rules are functors used to define the behavior of the SplineEvaluator out of the domain where the break points of the B-splines are defined. + * + * @return The lower extrapolation rule along the first dimension. + * + * @see NullExtrapolationRule ConstantExtrapolationRule PeriodicExtrapolationRule + */ left_extrapolation_rule_1_type left_extrapolation_rule_dim_1() const { return m_left_extrap_rule_1; } + /** + * @brief Get the upper extrapolation rule along the first dimension. + * + * Extrapolation rules are functors used to define the behavior of the SplineEvaluator out of the domain where the break points of the B-splines are defined. + * + * @return The upper extrapolation rule along the first dimension. + * + * @see NullExtrapolationRule ConstantExtrapolationRule PeriodicExtrapolationRule + */ right_extrapolation_rule_1_type right_extrapolation_rule_dim_1() const { return m_right_extrap_rule_1; } + /** + * @brief Get the lower extrapolation rule along the second dimension. + * + * Extrapolation rules are functors used to define the behavior of the SplineEvaluator out of the domain where the break points of the B-splines are defined. + * + * @return The lower extrapolation rule along the second dimension. + * + * @see NullExtrapolationRule ConstantExtrapolationRule PeriodicExtrapolationRule + */ left_extrapolation_rule_2_type left_extrapolation_rule_dim_2() const { return m_left_extrap_rule_2; } + /** + * @brief Get the upper extrapolation rule along the second dimension. + * + * Extrapolation rules are functors used to define the behavior of the SplineEvaluator out of the domain where the break points of the B-splines are defined. + * + * @return The upper extrapolation rule along the second dimension. + * + * @see NullExtrapolationRule ConstantExtrapolationRule PeriodicExtrapolationRule + */ right_extrapolation_rule_2_type right_extrapolation_rule_dim_2() const { return m_right_extrap_rule_2; } /** - * @brief Get the value of the function on B-splines at the coordinate given. + * @brief Evaluate 2D spline function (described by its spline coefficients) at a given coordinate. * - * @param[in] coord_eval - * The 2D coordinate where we want to evaluate the function. - * @param[in] spline_coef - * The B-splines coefficients of the function we want to evaluate. + * The spline coefficients represent a 2D spline function defined on a B-splines (basis splines). They can be obtained via various methods, such as using a SplineBuilder2D. * - * @return A double containing the value of the function at the coordinate given. + * Remark: calling SplineBuilder2D then SplineEvaluator2D corresponds to a 2D spline interpolation. + * + * @param coord_eval The coordinate where the spline is evaluated. Note that only the components along the dimensions of interest are used. + * @param spline_coef A ChunkSpan storing the 2D spline coefficients. + * + * @return The value of the spline function at the desired coordinate. */ template KOKKOS_FUNCTION double operator()( @@ -273,6 +344,26 @@ class SplineEvaluator2D return eval(coord_eval, spline_coef); } + /** + * @brief Evaluate 2D spline function (described by its spline coefficients) on a mesh. + * + * The spline coefficients represent a 2D spline function defined on a cartesian product of batch_domain and B-splines + * (basis splines). They can be obtained via various methods, such as using a SplineBuilder2D. + * + * This is not a nD evaluation. This is a batched 2D evaluation. This means that for each slice of coordinates + * identified by a batch_domain_type::discrete_element_type, the evaluation is performed with the 2D set of + * spline coefficients identified by the same batch_domain_type::discrete_element_type. + * + * Remark: calling SplineBuilder2D then SplineEvaluator2D corresponds to a 2D spline interpolation. + * + * @param[out] spline_eval The values of the 2D spline function at the desired coordinates. For practical reasons those are + * stored in a ChunkSpan defined on a batched_evaluation_domain_type. + * @param[in] coords_eval The coordinates where the spline is evaluated. Those are + * stored in a ChunkSpan defined on a batched_evaluation_domain_type. Note that the coordinates of the + * points represented by this domain are unused and irrelevant (but the points themselves (DiscreteElement) are used to select + * the set of 2D spline coefficients retained to perform the evaluation). + * @param[in] spline_coef A ChunkSpan storing the 2D spline coefficients. + */ template void operator()( ddc::ChunkSpan const @@ -304,14 +395,15 @@ class SplineEvaluator2D } /** - * @brief Get the value of the derivative of the first dimension of the function on B-splines at the coordinate given. + * @brief Differentiate 2D spline function (described by its spline coefficients) at a given coordinate along first dimension of interest. * - * @param[in] coord_eval - * The 2D coordinate where we want to evaluate the derivative of the first dimension of the function. - * @param[in] spline_coef - * The B-splines coefficients of the function we want to evaluate. + * The spline coefficients represent a 2D spline function defined on a B-splines (basis splines). They can be + * obtained via various methods, such as using a SplineBuilder2D. * - * @return A double containing the value of the derivative of the first dimension of the function at the coordinate given. + * @param coord_eval The coordinate where the spline is differentiated. Note that only the components along the dimensions of interest are used. + * @param spline_coef A ChunkSpan storing the 2D spline coefficients. + * + * @return The derivative of the spline function at the desired coordinate. */ template KOKKOS_FUNCTION double deriv_dim_1( @@ -323,14 +415,15 @@ class SplineEvaluator2D } /** - * @brief Get the value of the derivative of the second dimension of the function on B-splines at the coordinate given. + * @brief Differentiate 2D spline function (described by its spline coefficients) at a given coordinate along second dimension of interest. * - * @param[in] coord_eval - * The 2D coordinate where we want to evaluate the derivative of the second dimension of the function. - * @param[in] spline_coef - * The B-splines coefficients of the function we want to evaluate. + * The spline coefficients represent a 2D spline function defined on a B-splines (basis splines). They can be + * obtained via various methods, such as using a SplineBuilder2D. + * + * @param coord_eval The coordinate where the spline is differentiated. Note that only the components along the dimensions of interest are used. + * @param spline_coef A ChunkSpan storing the 2D spline coefficients. * - * @return A double containing the value of the derivative of the second dimension of the function at the coordinate given. + * @return The derivative of the spline function at the desired coordinate. */ template KOKKOS_FUNCTION double deriv_dim_2( @@ -342,14 +435,15 @@ class SplineEvaluator2D } /** - * @brief Get the value of the cross derivative of the function on B-splines at the coordinate given. + * @brief Cross-differentiate 2D spline function (described by its spline coefficients) at a given coordinate. * - * @param[in] coord_eval - * The 2D coordinate where we want to evaluate the cross derivative of the function. - * @param[in] spline_coef - * The B-splines coefficients of the function we want to evaluate. + * The spline coefficients represent a 2D spline function defined on a B-splines (basis splines). They can be + * obtained via various methods, such as using a SplineBuilder2D. + * + * @param coord_eval The coordinate where the spline is differentiated. Note that only the components along the dimensions of interest are used. + * @param spline_coef A ChunkSpan storing the 2D spline coefficients. * - * @return A double containing the value of the cross derivative of the function at the coordinate given. + * @return The derivative of the spline function at the desired coordinate. */ template KOKKOS_FUNCTION double deriv_1_and_2( @@ -360,6 +454,19 @@ class SplineEvaluator2D return eval_no_bc(coord_eval, spline_coef); } + /** + * @brief Differentiate 2D spline function (described by its spline coefficients) at a given coordinate along a specified dimension of interest. + * + * The spline coefficients represent a 2D spline function defined on a B-splines (basis splines). They can be + * obtained via various methods, such as using a SplineBuilder2D. + * + * @tparam InterestDim Dimension along which differentiation is performed. + * + * @param coord_eval The coordinate where the spline is differentiated. Note that only the components along the dimensions of interest are used. + * @param spline_coef A ChunkSpan storing the 2D spline coefficients. + * + * @return The derivative of the spline function at the desired coordinate. + */ template KOKKOS_FUNCTION double deriv( ddc::Coordinate const& coord_eval, @@ -382,6 +489,22 @@ class SplineEvaluator2D } } + /** + * @brief Double-differentiate 2D spline function (described by its spline coefficients) at a given coordinate along specified dimensions of interest. + * + * The spline coefficients represent a 2D spline function defined on a B-splines (basis splines). They can be + * obtained via various methods, such as using a SplineBuilder2D. + * + * Note: double-differentiation other than cross-differentiation is not supported atm. See #440 + * + * @tparam InterestDim1 First dimension along which differentiation is performed. + * @tparam InterestDim2 Second dimension along which differentiation is performed. + * + * @param coord_eval The coordinate where the spline is double-differentiated. Note that only the components along the dimensions of interest are used. + * @param spline_coef A ChunkSpan storing the 2D spline coefficients. + * + * @return The derivative of the spline function at the desired coordinate. + */ template KOKKOS_FUNCTION double deriv2( ddc::Coordinate const& coord_eval, @@ -401,14 +524,24 @@ class SplineEvaluator2D } /** - * @brief Get the values of the derivative of the first dimension of the function on B-splines at the coordinates given. + * @brief Differentiate 2D spline function (described by its spline coefficients) on a mesh along first dimension of interest. * - * @param[out] spline_eval - * A ChunkSpan with the values of the derivative of the first dimension of the function at the coordinates given. - * @param[in] coords_eval - * A ChunkSpan with the 2D coordinates where we want to evaluate the derivative of the first dimension of the function. - * @param[in] spline_coef - * The B-splines coefficients of the function we want to evaluate. + * The spline coefficients represent a 2D spline function defined on a cartesian product of batch_domain and B-splines + * (basis splines). They can be obtained via various methods, such as using a SplineBuilder2D. + * + * This is not a nD evaluation. This is a batched 2D differentiation. + * This means that for each slice of coordinates identified by a batch_domain_type::discrete_element_type, + * the differentiation is performed with the 2D set of spline coefficients identified by the same batch_domain_type::discrete_element_type. + * + * @param[out] spline_eval The derivatives of the 2D spline function at the desired coordinates. For practical reasons those are + * stored in a ChunkSpan defined on a batched_evaluation_domain_type. Note that the coordinates of the + * points represented by this domain are unused and irrelevant (but the points themselves (DiscreteElement) are used to select + * the set of 2D spline coefficients retained to perform the evaluation). + * @param[in] coords_eval The coordinates where the spline is differentiated. Those are + * stored in a ChunkSpan defined on a batched_evaluation_domain_type. Note that the coordinates of the + * points represented by this domain are unused and irrelevant (but the points themselves (DiscreteElement) are used to select + * the set of 2D spline coefficients retained to perform the evaluation). + * @param[in] spline_coef A ChunkSpan storing the 2D spline coefficients. */ template void deriv_dim_1( @@ -443,14 +576,22 @@ class SplineEvaluator2D } /** - * @brief Get the values of the derivative of the second dimension of the function on B-splines at the coordinates given. + * @brief Differentiate 2D spline function (described by its spline coefficients) on a mesh along second dimension of interest. * - * @param[out] spline_eval - * A ChunkSpan with the values of the derivative of the second dimension of the function at the coordinates given. - * @param[in] coords_eval - * A ChunkSpan with the 2D coordinates where we want to evaluate the derivative of the second dimension of the function. - * @param[in] spline_coef - * The B-splines coefficients of the function we want to evaluate. + * The spline coefficients represent a 2D spline function defined on a cartesian product of batch_domain and B-splines + * (basis splines). They can be obtained via various methods, such as using a SplineBuilder2D. + * + * This is not a nD differentiation. This is a batched 2D differentiation. + * This means that for each slice of coordinates identified by a batch_domain_type::discrete_element_type, + * the differentiation is performed with the 2D set of spline coefficients identified by the same batch_domain_type::discrete_element_type. + * + * @param[out] spline_eval The derivatives of the 2D spline function at the desired coordinates. For practical reasons those are + * stored in a ChunkSpan defined on a batched_evaluation_domain_type. + * @param[in] coords_eval The coordinates where the spline is differentiated. Those are + * stored in a ChunkSpan defined on a batched_evaluation_domain_type. Note that the coordinates of the + * points represented by this domain are unused and irrelevant (but the points themselves (DiscreteElement) are used to select + * the set of 2D spline coefficients retained to perform the evaluation). + * @param[in] spline_coef A ChunkSpan storing the 2D spline coefficients. */ template void deriv_dim_2( @@ -485,14 +626,22 @@ class SplineEvaluator2D } /** - * @brief Get the values of the cross derivative of the function on B-splines at the coordinates given. + * @brief Cross-differentiate 2D spline function (described by its spline coefficients) on a mesh along dimensions of interest. * - * @param[out] spline_eval - * A ChunkSpan with the values of the cross derivative of the function at the coordinates given. - * @param[in] coords_eval - * A ChunkSpan with the 2D coordinates where we want to evaluate the cross derivative of the function. - * @param[in] spline_coef - * The B-splines coefficients of the function we want to evaluate. + * The spline coefficients represent a 2D spline function defined on a cartesian product of batch_domain and B-splines + * (basis splines). They can be obtained via various methods, such as using a SplineBuilder2D. + * + * This is not a nD cross-differentiation. This is a batched 2D cross-differentiation. + * This means that for each slice of coordinates identified by a batch_domain_type::discrete_element_type, + * the cross-differentiation is performed with the 2D set of spline coefficients identified by the same batch_domain_type::discrete_element_type. + * + * @param[out] spline_eval The cross-derivatives of the 2D spline function at the desired coordinates. For practical reasons those are + * stored in a ChunkSpan defined on a batched_evaluation_domain_type. + * @param[in] coords_eval The coordinates where the spline is differentiated. Those are + * stored in a ChunkSpan defined on a batched_evaluation_domain_type. Note that the coordinates of the + * points represented by this domain are unused and irrelevant (but the points themselves (DiscreteElement) are used to select + * the set of 2D spline coefficients retained to perform the evaluation). + * @param[in] spline_coef A ChunkSpan storing the 2D spline coefficients. */ template void deriv_1_and_2( @@ -526,6 +675,25 @@ class SplineEvaluator2D }); } + /** + * @brief Differentiate spline function (described by its spline coefficients) on a mesh along a specified dimension of interest. + * + * The spline coefficients represent a 2D spline function defined on a cartesian product of batch_domain and B-splines + * (basis splines). They can be obtained via various methods, such as using a SplineBuilder2D. + * + * This is not a nD evaluation. This is a batched 2D differentiation. + * This means that for each slice of coordinates identified by a batch_domain_type::discrete_element_type, + * the differentiation is performed with the 2D set of spline coefficients identified by the same batch_domain_type::discrete_element_type. + * + * @tparam InterestDim Dimension along which differentiation is performed. + * @param[out] spline_eval The derivatives of the 2D spline function at the desired coordinates. For practical reasons those are + * stored in a ChunkSpan defined on a batched_evaluation_domain_type. + * @param[in] coords_eval The coordinates where the spline is differentiated. Those are + * stored in a ChunkSpan defined on a batched_evaluation_domain_type. Note that the coordinates of the + * points represented by this domain are unused and irrelevant (but the points themselves (DiscreteElement) are used to select + * the set of 2D spline coefficients retained to perform the evaluation). + * @param[in] spline_coef A ChunkSpan storing the 2D spline coefficients. + */ template void deriv( ddc::ChunkSpan const @@ -554,6 +722,29 @@ class SplineEvaluator2D } } + /** + * @brief Double-differentiate 2D spline function (described by its spline coefficients) on a mesh along specified dimensions of interest. + * + * The spline coefficients represent a 2D spline function defined on a cartesian product of batch_domain and B-splines + * (basis splines). They can be obtained via various methods, such as using a SplineBuilder2D. + * + * This is not a nD evaluation. This is a batched 2D differentiation. + * This means that for each slice of coordinates identified by a batch_domain_type::discrete_element_type, + * the differentiation is performed with the 2D set of spline coefficients identified by the same batch_domain_type::discrete_element_type. + * + * Note: double-differentiation other than cross-differentiation is not supported atm. See #440 + * + * @tparam InterestDim1 First dimension along which differentiation is performed. + * @tparam InterestDim2 Second dimension along which differentiation is performed. + * + * @param[out] spline_eval The derivatives of the 2D spline function at the desired coordinates. For practical reasons those are + * stored in a ChunkSpan defined on a batched_evaluation_domain_type. + * @param[in] coords_eval The coordinates where the spline is differentiated. Those are + * stored in a ChunkSpan defined on a batched_evaluation_domain_type. Note that the coordinates of the + * points represented by this domain are unused and irrelevant (but the points themselves (DiscreteElement) are used to select + * the set of 2D spline coefficients retained to perform the evaluation). + * @param[in] spline_coef A ChunkSpan storing the 2D spline coefficients. + */ template < class InterestDim1, class InterestDim2, @@ -584,12 +775,18 @@ class SplineEvaluator2D return deriv_1_and_2(spline_eval, coords_eval, spline_coef); } - /** - * @brief Get the the integral of the function on B-splines on the domain. - * @param[out] integrals - * The integrals of the function - * @param[in] spline_coef - * The B-splines coefficients of the function we want to integrate. + /** @brief Perform batched 2D integrations of a spline function (described by its spline coefficients) along the dimensions of interest and store results on a subdomain of batch_domain. + * + * The spline coefficients represent a 2D spline function defined on a B-splines (basis splines). They can be obtained via various methods, such as using a SplineBuilder2D. + * + * This is not a nD integration. This is a batched 2D integration. + * This means that for each element of integrals, the integration is performed with the 2D set of + * spline coefficients identified by the same DiscreteElement. + * + * @param[out] integrals The integrals of the 2D spline function on the subdomain of batch_domain. For practical reasons those are + * stored in a ChunkSpan defined on a batch_domain_type. Note that the coordinates of the + * points represented by this domain are unused and irrelevant. + * @param[in] spline_coef A ChunkSpan storing the 2D spline coefficients. */ template void integrate(