Commit f341ee72 authored by Nabil Chouika's avatar Nabil Chouika
Browse files

Documentation of integration routines partons/core/partons#4

parent d1b5a266
......@@ -18,7 +18,9 @@ namespace NumA {
/**
* @class ChebyshevAIntegrator1D
*
* @brief Chebyshev quadrature for computing the integral \int_{-1}^1 dx f(x)sqrt(1-x^2).
* @brief Chebyshev quadrature for computing the integral \f$ \int_{-1}^1 \mathrm{dx} f(x) \sqrt{1-x^2} \f$.
*
* See Integrator1D documentation for an example.
*/
class ChebyshevAIntegrator1D: public QuadratureIntegrator1D {
......
......@@ -18,7 +18,9 @@ namespace NumA {
/**
* @class ChebyshevBIntegrator1D
*
* @brief Chebyshev quadrature for computing the integral \int_{-1}^1 dx f(x)/sqrt(1-x^2).
* @brief Chebyshev quadrature for computing the integral \f$ \int_{-1}^1 \mathrm{dx} \frac{f(x)}{\sqrt{1-x^2}} \f$.
*
* See Integrator1D documentation for an example.
*/
class ChebyshevBIntegrator1D: public QuadratureIntegrator1D {
......
......@@ -51,41 +51,31 @@ namespace NumA {
*
* As we assume that values at the ends of the interval hardly matter due to the rapid decay of the integrand
* we don't treat the end points differently.
*
* See Integrator1D documentation for an example.
*/
class DExpIntegrator1D: public Integrator1D {
public:
/**
* Default constructor
* Default constructor.
*/
DExpIntegrator1D();
/**
* Destructor
* Default destructor.
*/
virtual ~DExpIntegrator1D();
/**
*
* @return
*/
DExpIntegrator1D* clone() const;
/**
*
* @param pFunction
* @param a
* @param b
* @param parameters
* @return
*/
virtual double integrate(FunctionType1D* pFunction, double a, double b,
std::vector<double> &parameters);
protected:
/**
* Copy constructor
*
* @param other
* Copy constructor.
* Called by clone().
* @param other DExpIntegrator1D object to copy.
*/
DExpIntegrator1D(const DExpIntegrator1D &other);
......@@ -94,10 +84,10 @@ private:
////////////////////////////////////////////////////////////
// Member data
////////////////////////////////////////////////////////////
double m_errorEstimate;
int m_numFunctionEvaluations;
std::vector<double> m_nodes; ///< Nodes of the quadrature
std::vector<double> m_weights; ///< Weights of the quadrature
double m_errorEstimate; ///< Absolute error estimate.
int m_numFunctionEvaluations; ///< Number of evaluations.
std::vector<double> m_nodes; ///< Nodes of the quadrature.
std::vector<double> m_weights; ///< Weights of the quadrature.
std::vector<int> m_offsets;
};
......
......@@ -20,11 +20,20 @@ namespace NumA {
* @class GaussLegendreIntegrator1D
*
* @brief Gauss-Legendre quadrature.
*
* See Integrator1D documentation for an example.
*/
class GaussLegendreIntegrator1D: public QuadratureIntegrator1D {
public:
/**
* Constructor.
* @param N Order of the quadrature (number of nodes).
*/
GaussLegendreIntegrator1D(unsigned int N = 50); // TODO how many steps by default ?
/**
* Default destructor.
*/
virtual ~GaussLegendreIntegrator1D();
virtual void setN(unsigned int n);
......@@ -32,8 +41,13 @@ public:
virtual GaussLegendreIntegrator1D* clone() const;
protected:
/**
* Copy constructor.
* Called by clone().
* @param other GaussLegendreIntegrator1D object to copy.
*/
GaussLegendreIntegrator1D(const GaussLegendreIntegrator1D &other);
void setNodesAndWeights();
void setNodesAndWeights(); ///< Computes the nodes and weights of the Gauss-Legendre quadrature. Called when N is set.
};
} /* namespace NumA */
......
......@@ -17,11 +17,20 @@ namespace NumA {
* @class GaussLegendreSestIntegrator1D
*
* @brief Gauss-Legendre quadrature.
*
* See Integrator1D documentation for an example.
*/
class GaussLegendreSeStIntegrator1D: public QuadratureIntegrator1D {
public:
/**
* Constructor.
* @param N Order of the quadrature (number of nodes).
*/
GaussLegendreSeStIntegrator1D(unsigned int N = 50); // TODO how many steps by default ?
/**
* Default destructor.
*/
virtual ~GaussLegendreSeStIntegrator1D();
virtual void setN(unsigned int n);
......@@ -29,8 +38,13 @@ public:
virtual GaussLegendreSeStIntegrator1D* clone() const;
protected:
/**
* Copy constructor.
* Called by clone().
* @param other GaussLegendreSeStIntegrator1D object to copy.
*/
GaussLegendreSeStIntegrator1D(const GaussLegendreSeStIntegrator1D &other);
void setNodesAndWeights();
void setNodesAndWeights(); ///< Computes the nodes and weights of the Gauss-Legendre quadrature. Called when N is set.
};
} /* namespace NumA */
......
......@@ -26,45 +26,104 @@ namespace NumA {
* @class Integrator1D
*
* @brief Abstract class for all integration routines.
*
* Example:
* ```cpp
* NumA::Integrator1D* integrator = NumA::Integrator1D::newIntegrator(NumA::IntegratorType1D::GaussLegendre); // Using Gauss-Legendre quadrature.
* NumA::FunctionType1D* functor = NumA::FunctorUtils::newFunctor1D(this, &MyClass::myFunction); // See FunctionType1D documentation.
* double integral = integrator.integrate(functor, -1., 1.); // We integrate a function on [-1,1].
* ```
*/
class Integrator1D {
public:
static const std::string PARAM_NAME_ABSOLUTE_TOLERANCE;
static const std::string PARAM_NAME_RELATIVE_TOLERANCE;
static const std::string PARAM_NAME_ABSOLUTE_TOLERANCE; ///< Parameter used in the configure() to set the absolute tolerance.
static const std::string PARAM_NAME_RELATIVE_TOLERANCE; ///< Parameter used in the configure() to set the relative tolerance.
/**
* Default constructor.
*/
Integrator1D();
/**
* Default destructor.
*/
virtual ~Integrator1D();
virtual Integrator1D* clone() const = 0;
/**
* Integration routine.
* @param pFunction Functor representing the one-dimensional function to integrate.
* @param a Lower bound.
* @param b Upper bound.
* @param parameters Parameters that can be passed to the function.
* @return Integral.
*/
virtual double integrate(FunctionType1D* pFunction, double a, double b,
std::vector<double> &parameters) = 0;
/**
* Provides a generic method to configure all types of integrations by passing a Parameters object.
* Parameters class represents a list of couples key/value (see Parameters class documentation for more info).
*
* @param parameters ElemUtils::Parameters object.
*/
virtual void configure(const ElemUtils::Parameters &parameters);
//TODO moved to FunctorUtils ; remove this definition
/**
* Use FunctorUtils::newFunctor1D instead.
*
* TODO: Remove this method.
*/
template<typename PointerToObj, typename PointerToMemFn>
static Functor1D<PointerToObj, PointerToMemFn>* newIntegrationFunctor(
PointerToObj* object, PointerToMemFn function) {
return new Functor1D<PointerToObj, PointerToMemFn>(object, function);
}
/**
* Instantiates an Integrator object.
* Will be replaced by a Factory/Registry system in the future.
* @param oneDimIntegratorType Type of integrator.
* @return Integrator1D pointer.
*/
static Integrator1D* newIntegrator(
const IntegratorType1D::Type &oneDimIntegratorType);
// ##### GETTERS & SETTERS #####
/**
*
* @return Absolute and relative tolerances.
*/
const Tolerances& getTolerances() const;
/**
*
* @param tolerances Absolute and relative tolerances.
*/
void setTolerances(const Tolerances& tolerances);
/**
*
* @return Absolute and relative errors estimations.
*/
const Errors& getErrors() const;
/**
*
* @param errors Absolute and relative errors estimations.
*/
void setErrors(const Errors& errors);
protected:
Tolerances m_tolerances;
Errors m_errors;
Tolerances m_tolerances; ///< Absolute and relative tolerances.
Errors m_errors; ///< Absolute and relative errors estimations.
/**
* Copy constructor.
* Called by clone().
* @param other Integrator1D object to copy.
*/
Integrator1D(const Integrator1D &other);
};
......
......@@ -15,33 +15,59 @@ namespace NumA {
/**
* @class IntegratorType1D
*
* @brief
* @brief Type of one-dimensional integrations (wrapper for enum).
*
* See Integrator1D documentation for an example.
*/
class IntegratorType1D {
public:
/**
* Type of integration.
*/
enum Type {
UNDEFINED = 0, TRAPEZOIDAL, GaussLegendre, DEXP, GK21_ADAPTIVE
};
/**
* Default constructor.
*/
IntegratorType1D();
IntegratorType1D(Type type);
/**
* Default destructor.
*/
virtual ~IntegratorType1D();
/**
* Operator that casts back into an enum.
*/
operator Type() const;
/**
* Returns a formatted string displaying the type.
* @return std::string
*/
std::string toString();
/**
* Returns a short name for the type.
* @return std::string
*/
std::string getShortName();
/**
* Returns the wrapped enum.
* @return IntegratorType1D::Type
*/
IntegratorType1D::Type getType() const;
void setType(Type type);
private:
IntegratorType1D::Type m_type;
IntegratorType1D::Type m_type; ///< Type of integration (enum).
};
} /* namespace NumA */
......
......@@ -21,13 +21,26 @@ namespace NumA {
* @class QuadratureIntegrator1D
*
* @brief Abstract quadrature class (for fixed quadrature rules).
*
* Child classes must define a way to compute the nodes \f$ x_i \f$ and weights \f$ w_i \f$.\n
* The integration itself is done by this abstract class:
* \f$ \displaystyle \int_a^b f\left(x\right) \mathrm{d}x = \sum_{i=0}^{N-1} w_i f\left(x_i\right) \f$, through the integrate() routine.
*
* See Integrator1D documentation for an example.
*/
class QuadratureIntegrator1D: public Integrator1D {
public:
static const std::string PARAM_NAME_N;
static const std::string PARAM_NAME_N; ///< Parameter used in the configure() to set the order of the quadrature.
/**
* Constructor.
* @param N Order of the quadrature (number of nodes).
*/
QuadratureIntegrator1D(unsigned int N = 0);
/**
* Default destructor.
*/
virtual ~QuadratureIntegrator1D();
virtual QuadratureIntegrator1D* clone() const = 0;
......@@ -37,16 +50,37 @@ public:
virtual void configure(const ElemUtils::Parameters &parameters);
/**
*
* @return Order of the quadrature (number of nodes).
*/
unsigned int getN() const;
/**
*
* @param n Order of the quadrature (number of nodes).
*/
virtual void setN(unsigned int n) = 0;
/**
*
* @return Nodes of the quadrature.
*/
const std::vector<double>& getNodes() const;
/**
*
* @return Weights of the quadrature.
*/
const std::vector<double>& getWeights() const;
protected:
unsigned int m_N; ///< Order of the quadrature (number of nodes)
std::vector<double> m_nodes; ///< Nodes of the quadrature
std::vector<double> m_weights; ///< Weights of the quadrature
unsigned int m_N; ///< Order of the quadrature (number of nodes).
std::vector<double> m_nodes; ///< Nodes of the quadrature.
std::vector<double> m_weights; ///< Weights of the quadrature.
/**
* Copy constructor.
* Called by clone().
* @param other QuadratureIntegrator1D object to copy.
*/
QuadratureIntegrator1D(const QuadratureIntegrator1D &other);
};
......
......@@ -20,11 +20,20 @@ namespace NumA {
* @class TrapezoidalIntegrator1D
*
* @brief Trapezoidal integration.
*
* See Integrator1D documentation for an example.
*/
class TrapezoidalIntegrator1D: public QuadratureIntegrator1D {
public:
/**
* Constructor.
* @param N Order of the quadrature (number of nodes).
*/
TrapezoidalIntegrator1D(unsigned int N = 50);
/**
* Default destructor.
*/
virtual ~TrapezoidalIntegrator1D();
virtual TrapezoidalIntegrator1D* clone() const;
......@@ -36,8 +45,13 @@ public:
// std::vector<double>& parameters);
protected:
/**
* Copy constructor.
* Called by clone().
* @param other TrapezoidalIntegrator1D object to copy.
*/
TrapezoidalIntegrator1D(const TrapezoidalIntegrator1D &other);
void setNodesAndWeights();
void setNodesAndWeights(); ///< Computes the nodes and weights of the Gauss-Legendre quadrature. Called when N is set.
};
} /* namespace NumA */
......
......@@ -27,9 +27,12 @@ class Chebyshev {
public:
/**
* Default Constructor with the order N of the expansion.
* @param N Order of the expansion
* @param N Order of the expansion.
*/
Chebyshev(unsigned int N = 50);
/**
* Default destructor.
*/
virtual ~Chebyshev();
/**
......@@ -45,18 +48,52 @@ public:
const NumA::VectorD& getRoots() const;
const NumA::MatrixD& getValuesToCoeffsMatrix() const; ///< Transformation matrix from the values on nodes to the coefficients of the expansion.
const NumA::MatrixD& getCoeffsToValuesMatrix() const; ///< Transformation matrix from the coefficients of the expansion to the values on nodes.
/**
* Interpolation matrix.
* @return Matrix which gives a vector of the coefficients for the expansion when applied to a vector of values on Chebyshev nodes.
*/
const NumA::MatrixD& getValuesToCoeffsMatrix() const;
/**
*
* @return Matrix which gives a vector of the values on Chebyshev nodes when applied to a vector of coefficients for the expansion.
*/
const NumA::MatrixD& getCoeffsToValuesMatrix() const;
NumA::MatrixD getCoeffsToValuesMatrix(const NumA::VectorD& points) const; ///< Transformation matrix from the coefficients of the expansion to values on given points.
NumA::VectorD getCoeffsToValueVector(double x) const; ///< Transformation vector from the coefficients of the expansion to a value on a given point.
/**
*
* @param points Points where to evaluate the expansion.
* @return Matrix which gives a vector of the values on given points when applied to a vector of coefficients for the expansion.
*/
NumA::MatrixD getCoeffsToValuesMatrix(const NumA::VectorD& points) const;
/**
*
* @param x Point where the expansion is evaluated.
* @return Vector which gives the Chebyshev expansion on x when a scalar product is taken with a vector of coefficients for the expansion.
*/
NumA::VectorD getCoeffsToValueVector(double x) const;
NumA::MatrixD getValuesToValuesMatrix(const NumA::VectorD& points) const; ///< Transformation matrix from the values on nodes to values on given points.
NumA::VectorD getValuesToValueVector(double x) const; ///< Transformation vector from the the values on nodes to a value on a given point.
/**
* Interpolation matrix.
* @param points Points where to evaluate the expansion.
* @return Matrix which gives a vector of values on given points when applied to a vector of values on Chebyshev nodes.
*/
NumA::MatrixD getValuesToValuesMatrix(const NumA::VectorD& points) const;
/**
*
* @param x Point where the expansion is evaluated.
* @return Vector which gives the Chebyshev expansion on x when a scalar product is taken with a vector of values on Chebyshev nodes.
*/
NumA::VectorD getValuesToValueVector(double x) const;
/**
* Evaluate the Chebyshev expansion.
* @param coeffs Coefficients \f$ c_i \f$ of the expansion.
* @param x Point where the expansion is evaluated.
* @return Chebyshev expansion: \sum_{i=0}^{N-1} c_i T_i \left( x \right) \f$.
*/
double evaluateExpansion(const NumA::VectorD& coeffs, double x) const;
static double T(unsigned int i, double x); ///< \f$ T_i \left( x \right) = \cos \left( i \arccos \left( x \right) \right) \f$
static double T(unsigned int i, double x); ///< \f$ T_i \left( x \right) = \cos \left( i \arccos \left( x \right) \right) \f$.
private:
unsigned int m_N; ///< Order of the expansion.
......@@ -64,8 +101,8 @@ private:
NumA::MatrixD m_valuesToCoeffsMatrix; ///< Transformation matrix from the values on nodes to the coefficients of the expansion.
NumA::MatrixD m_coeffsToValuesMatrix; ///< Transformation matrix from the coefficients of the expansion to the values on nodes.
void initRoots();
void initValuesToCoeffsMatrix();
void initRoots(); ///< Initialize the roots.
void initValuesToCoeffsMatrix(); ///< Initialize the interpolation matrix.
};
} /* namespace NumA */
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment