LegendrePolynomial.hpp

Go to the documentation of this file.

/** \file LegendrePolynomial.hpp
\brief Implementation of Legendre polynomials
 
This file provides functions and classes for calculating Legendre polynomial
basis functions and their derivatives for use in finite element approximations.
 
*/
 
 
 
#ifndef __LEGENDREPOLYNOMIALS_HPP__
#define __LEGENDREPOLYNOMIALS_HPP__
 
namespace MoFEM {
 
/**
\brief Calculate Legendre approximation basis
 
\ingroup mofem_base_functions
 
This function computes Legendre polynomials and their derivatives for use in
finite element approximations. Legendre polynomials form a complete orthogonal
system on the interval [-1,1] and are widely used in high-order finite element
methods due to their excellent numerical properties.
 
The Legendre polynomials are defined by the recurrence relation:
\f[
P_0(s)=1;\quad P_1(s) = s
\f]
and the following terms are generated inductively using Bonnet's recursion formula:
\f[
P_{n+1}(s)=\frac{2n+1}{n+1}sP_n(s)-\frac{n}{n+1}P_{n-1}(s)
\f]
 
The parameter \f$s\f$ is the normalized coordinate:
\f[
s\in[-1,1] \quad \textrm{and}\; s=s(\xi_0,\xi_1,\xi_2)
\f]
where \f$\xi_i\f$ are barycentric coordinates of the element.
 
For more information on Legendre polynomials, see:
https://en.wikipedia.org/wiki/Legendre_polynomials
 
\param p approximation order (degree of highest polynomial)
\param s position parameter \f$s\in[-1,1]\f$ at which to evaluate polynomials
\param diff_s derivatives of coordinate transformation, i.e. \f$\frac{\partial s}{\partial \xi_i}\f$
\param L [out] array of Legendre polynomial values \f$P_0(s), P_1(s), \ldots, P_p(s)\f$
\param diffL [out] array of polynomial derivatives, i.e. \f$\frac{\partial P_k}{\partial \xi_i}\f$
\param dim spatial dimension for derivative calculations
\return PetscErrorCode indicating success or failure
 
\note The output arrays L and diffL must be pre-allocated with sufficient size
\note For complex-valued evaluations, use the overloaded version with complex arguments
 
*/
PetscErrorCode Legendre_polynomials(int p, double s,
                                    double *diff_s, double *L,
                                    double *diffL, int dim);
 
 
/** 
 * \brief Complex-valued Legendre polynomial evaluation
 * 
 * This overloaded version computes Legendre polynomials for complex arguments,
 * which is useful for analytical continuation and complex finite element methods.
 * The recurrence relations and mathematical properties are identical to the 
 * real-valued version.
 * 
 * \param p approximation order (degree of highest polynomial)
 * \param s complex position parameter at which to evaluate polynomials
 * \param diff_s derivatives of coordinate transformation (real-valued)
 * \param L [out] array of complex Legendre polynomial values
 * \param diffL [out] array of complex polynomial derivatives
 * \param dim spatial dimension for derivative calculations
 * \return PetscErrorCode indicating success or failure
 * 
 * \see Legendre_polynomials(int, double, double*, double*, double*, int) for real version
 */
PetscErrorCode Legendre_polynomials(
    int p, std::complex<double> s, std::complex<double>* diff_s,
    std::complex<double>* L, std::complex<double>* diffL, int dim);
 
/**
 * \brief Context class for Legendre basis function arguments
 * \ingroup mofem_base_functions
 * 
 * This class stores parameters and data required for evaluating Legendre
 * polynomial basis functions and their derivatives.
 */
struct LegendrePolynomialCtx : public BaseFunctionCtx {
 
  MoFEMErrorCode query_interface(boost::typeindex::type_index type_index,
                                 UnknownInterface **iface) const;
 
  int P;                                           ///< Approximation order
  double *diffS;                                   ///< Derivatives of s parameter
  int dIm;                                         ///< Dimension
  boost::shared_ptr<MatrixDouble> baseFunPtr;      ///< Pointer to base function matrix
  boost::shared_ptr<MatrixDouble> baseDiffFunPtr;  ///< Pointer to base function derivatives matrix
 
  /// Function pointer for polynomial evaluation
  PetscErrorCode (*basePolynomialsType0)(int p, double s, double *diff_s,
                                         double *L, double *diffL,
                                         const int dim);
 
  /**
   * \brief Constructor
   * \param p approximation order
   * \param diff_s derivatives of s parameter
   * \param dim dimension
   * \param base_fun_ptr pointer to base function matrix
   * \param base_diff_fun_ptr pointer to base function derivatives matrix
   */
  LegendrePolynomialCtx(int p, double *diff_s, int dim,
                        boost::shared_ptr<MatrixDouble> base_fun_ptr,
                        boost::shared_ptr<MatrixDouble> base_diff_fun_ptr)
      : P(p), diffS(diff_s), dIm(dim), baseFunPtr(base_fun_ptr),
        baseDiffFunPtr(base_diff_fun_ptr),
        basePolynomialsType0(Legendre_polynomials) {}
  ~LegendrePolynomialCtx() {}
};
 
/**
 * \brief Class for calculating Legendre basis functions
 * \ingroup mofem_base_functions
 * 
 * This class implements the BaseFunction interface to provide Legendre
 * polynomial evaluation capabilities for finite element approximations.
 */
struct LegendrePolynomial : public BaseFunction {
 
  MoFEMErrorCode query_interface(boost::typeindex::type_index type_index,
                                 UnknownInterface **iface) const;
 
  LegendrePolynomial() {}
  ~LegendrePolynomial() {}
 
  /**
   * \brief Evaluate Legendre basis functions at given points
   * \param pts matrix of evaluation points
   * \param ctx_ptr context containing evaluation parameters
   * \return error code
   */
  MoFEMErrorCode getValue(MatrixDouble &pts,
                          boost::shared_ptr<BaseFunctionCtx> ctx_ptr);
};
 
 
 
} // namespace MoFEM
 
#endif //__LEGENDREPOLYNOMIALS_HPP__