root/Math/Derivator.h

0001 // @(#)root/mathmore:$Id$
0002 // Authors: L. Moneta, A. Zsenei   08/2005
0003
0004  /**********************************************************************
0005   *                                                                    *
0006   * Copyright (c) 2004 ROOT Foundation,  CERN/PH-SFT                   *
0007   *                                                                    *
0008   * This library is free software; you can redistribute it and/or      *
0009   * modify it under the terms of the GNU General Public License        *
0010   * as published by the Free Software Foundation; either version 2     *
0011   * of the License, or (at your option) any later version.             *
0012   *                                                                    *
0013   * This library is distributed in the hope that it will be useful,    *
0014   * but WITHOUT ANY WARRANTY; without even the implied warranty of     *
0015   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU   *
0016   * General Public License for more details.                           *
0017   *                                                                    *
0018   * You should have received a copy of the GNU General Public License  *
0019   * along with this library (see file COPYING); if not, write          *
0020   * to the Free Software Foundation, Inc., 59 Temple Place, Suite      *
0021   * 330, Boston, MA 02111-1307 USA, or contact the author.             *
0022   *                                                                    *
0023   **********************************************************************/
0024
0025 // Header file for class Derivator
0026 //
0027 // class for calculating Derivative of functions
0028 //
0029 // Created by: moneta  at Sat Nov 13 14:46:00 2004
0030 //
0031 // Last update: Sat Nov 13 14:46:00 2004
0032 //
0033 #ifndef ROOT_Math_Derivator
0034 #define ROOT_Math_Derivator
0035
0036
0037 #include "Math/IFunctionfwd.h"
0038
0039 #include "Math/IParamFunctionfwd.h"
0040
0041
0042 namespace ROOT {
0043 namespace Math {
0044
0045
0046
0047 class GSLDerivator;
0048
0049 //_______________________________________________________________________
0050 /**
0051     Class for computing numerical derivative of a function.
0052     Presently this class is implemented only using the numerical derivatives
0053     algorithms provided by GSL
0054     using the implementation class ROOT::Math::GSLDerivator
0055
0056     This class does not support copying
0057
0058     @ingroup Deriv
0059 */
0060
0061 class Derivator {
0062
0063 public:
0064
0065    /**
0066       signature for function pointers used by GSL
0067    */
0068    typedef double ( * GSLFuncPointer ) ( double, void * );
0069
0070    /**
0071       Empty Construct for a Derivator class
0072       Need to set the function afterwards with Derivator::SetFunction
0073    */
0074    Derivator();
0075    /**
0076       Construct using a ROOT::Math::IGenFunction interface
0077     */
0078    explicit Derivator(const IGenFunction &f);
0079    /**
0080       Construct using a GSL function pointer type
0081        @param f :  free function pointer of the GSL required type
0082        @param p :  pointer to the object carrying the function state
0083                     (for example the function object itself)
0084     */
0085    explicit Derivator(const GSLFuncPointer &f, void * p = nullptr);
0086
0087    /// destructor
0088    virtual ~Derivator();
0089
0090    // disable copying
0091 private:
0092
0093    Derivator(const Derivator &);
0094    Derivator & operator = (const Derivator &);
0095
0096 public:
0097
0098
0099 #ifdef LATER
0100    /**
0101        Template methods for generic functions
0102        Set the function f for evaluating the derivative.
0103        The function type must implement the assignment operator,
0104        <em>  double  operator() (  double  x ) </em>
0105    */
0106    template <class UserFunc>
0107    inline void SetFunction(const UserFunc &f) {
0108       const void * p = &f;
0109       SetFunction(  &GSLFunctionAdapter<UserFunc>::F, const_cast<void *>(p) );
0110    }
0111 #endif
0112
0113    /**
0114       Set the function for calculating the derivatives.
0115       The function must implement the ROOT::Math::IGenFunction signature
0116    */
0117    void SetFunction(const IGenFunction &f);
0118
0119
0120    /**
0121        Set the function f for evaluating the derivative using a GSL function pointer type
0122        @param f :  free function pointer of the GSL required type
0123        @param p :  pointer to the object carrying the function state
0124                     (for example the function object itself)
0125    */
0126    void SetFunction( const GSLFuncPointer &f, void * p = nullptr);
0127
0128
0129
0130    /**
0131        Computes the numerical derivative of a function f at a point x.
0132        It uses Derivator::EvalCentral to compute the derivative using an
0133        adaptive central difference algorithm with a step size h
0134    */
0135
0136    double Eval(double x, double h = 1E-8) const;
0137
0138
0139
0140    /**
0141        Computes the numerical derivative at a point x using an adaptive central
0142        difference algorithm with a step size h.
0143    */
0144    double EvalCentral( double x, double h = 1E-8) const;
0145
0146    /**
0147        Computes the numerical derivative at a point x using an adaptive forward
0148        difference algorithm with a step size h.
0149        The function is evaluated only at points greater than x and at x itself.
0150    */
0151    double EvalForward( double x, double h = 1E-8) const;
0152
0153    /**
0154        Computes the numerical derivative at a point x using an adaptive backward
0155        difference algorithm with a step size h.
0156        The function is evaluated only at points less than x and at x itself.
0157    */
0158    double EvalBackward( double x, double h = 1E-8) const;
0159
0160    /** @name --- Static methods ---
0161        This methods don't require to use a Derivator object, and are designed to be used in
0162        fast calculation. Error and status code cannot be retrieved in this case
0163     */
0164
0165    /**
0166        Computes the numerical derivative of a function f at a point x.
0167        It uses Derivator::EvalCentral to compute the derivative using an
0168        adaptive central difference algorithm with a step size h
0169    */
0170    static double Eval(const IGenFunction & f, double x, double h = 1E-8);
0171
0172    /**
0173        Computes the numerical derivative of a function f at a point x using an adaptive central
0174        difference algorithm with a step size h
0175    */
0176    static double EvalCentral(const IGenFunction & f, double x, double h = 1E-8);
0177
0178
0179    /**
0180        Computes the numerical derivative of a function f at a point x using an adaptive forward
0181        difference algorithm with a step size h.
0182        The function is evaluated only at points greater than x and at x itself
0183    */
0184    static double EvalForward(const IGenFunction & f, double x, double h = 1E-8);
0185
0186    /**
0187        Computes the numerical derivative of a function f at a point x using an adaptive backward
0188        difference algorithm with a step size h.
0189        The function is evaluated only at points less than x and at x itself
0190    */
0191    static double EvalBackward(const IGenFunction & f, double x, double h = 1E-8);
0192
0193    // Derivatives for multi-dimension functions
0194    /**
0195       Evaluate the partial derivative of a multi-dim function
0196       with respect coordinate x_icoord at the point x[]
0197     */
0198    static double Eval(const IMultiGenFunction & f, const double * x, unsigned int icoord = 0, double h = 1E-8);
0199
0200    /**
0201       Evaluate the derivative with respect a parameter for one-dim parameteric function
0202       at the point ( x,p[]) with respect the parameter p_ipar
0203     */
0204    static double Eval(IParamFunction & f, double x, const double * p, unsigned int ipar = 0, double h = 1E-8);
0205
0206    /**
0207       Evaluate the derivative with respect a parameter for a multi-dim parameteric function
0208       at the point ( x[],p[]) with respect the parameter p_ipar
0209     */
0210    static double Eval(IParamMultiFunction & f, const double * x, const double * p, unsigned int ipar = 0, double h = 1E-8);
0211
0212
0213    /**
0214       return the error status of the last derivative calculation
0215    */
0216    int Status() const;
0217
0218    /**
0219       return  the result of the last derivative calculation
0220    */
0221    double Result() const;
0222
0223    /**
0224       return the estimate of the absolute error of the last derivative calculation
0225    */
0226    double Error() const;
0227
0228
0229 private:
0230
0231
0232    mutable GSLDerivator * fDerivator;
0233
0234 };
0235
0236
0237
0238
0239 } // namespace Math
0240 } // namespace ROOT
0241
0242
0243 #endif /* ROOT_Math_Derivator */