include/AIDA/IFitter.h

0001 // -*- C++ -*-
0002 // AID-GENERATED
0003 // =========================================================================
0004 // This class was generated by AID - Abstract Interface Definition
0005 // DO NOT MODIFY, but use the org.freehep.aid.Aid utility to regenerate it.
0006 // =========================================================================
0007 #ifndef AIDA_IFITTER_H
0008 #define AIDA_IFITTER_H 1
0009
0010 //  This file is part of the AIDA library
0011 //  Copyright (C) 2002 by the AIDA team.  All rights reserved.
0012 //  This library is free software and under the terms of the
0013 //  GNU Library General Public License described in the LGPL.txt
0014
0015 #include <string>
0016 #include <vector>
0017
0018 namespace AIDA {
0019
0020 class IBaseHistogram;
0021 class IDataPointSet;
0022 class IFitData;
0023 class IFitParameterSettings;
0024 class IFitResult;
0025 class IFunction;
0026
0027 /** @interface IFitter
0028  *
0029  * Fitter performs fits, scans and computes contours.
0030  *
0031  * Fitter never stores association to the data and functions which are
0032  * used for fitting. Results of the fit are availabe in the IFitResult
0033  * object, which also remebers the initial fit configuration.
0034  *
0035  * @author The AIDA team (http://aida.freehep.org/)
0036  *
0037  */
0038
0039 class IFitter {
0040
0041 public:
0042     /// Destructor.
0043     virtual ~IFitter() { /* nop */; }
0044
0045     /**
0046      * Fit an IFunction to an IFitData.
0047      * The result of the fit is an IFitResult.
0048      * @param fitData The IFitData to be fitted.
0049      * @param func    The IFunction to fit on the data.
0050      * @return        The IFitResult containing the results of the fit.
0051      *
0052      */
0053     virtual IFitResult * fit(IFitData & fitData, IFunction & func) = 0;
0054
0055     /**
0056      * Shortcut to fit an IBaseHistogram directly with an IFunction.
0057      * The dimension of the IBaseHistogram must match the dimension of the IFunction.
0058      * IHistograms and IProfiles are for binned fits only, IClouds only for unbinned fits.
0059      * @param hist The IBaseHistogram to be fitted.
0060      * @param func The IFunction to fit on the data.
0061      * @return     The IFitResult containing the result of the fit.
0062      *
0063      */
0064     virtual IFitResult * fit(IBaseHistogram & hist, IFunction & func) = 0;
0065
0066     /**
0067      * Shortcut to fit an IBaseHistogram directly with an IFunction.
0068      * The dimension of the IBaseHistogram must match the dimension of the IFunction.
0069      * IHistograms and IProfiles are for binned fits only, IClouds only for unbinned fits.
0070      * @param hist  The IBaseHistogram to be fitted.
0071      * @param model The string defining the function to be used.
0072      * @return      The IFitResult containing the result of the fit.
0073      *
0074      */
0075     virtual IFitResult * fit(IBaseHistogram & hist, const std::string & model) = 0;
0076
0077     /**
0078      * Shortcut to fit an IBaseHistogram directly with an IFunction.
0079      * The dimension of the IBaseHistogram must match the dimension of the IFunction.
0080      * IHistograms and IProfiles are for binned fits only, IClouds only for unbinned fits.
0081      * @param hist              The IBaseHistogram to be fitted.
0082      * @param model             The string defining the function to be used.
0083      * @param initialParameters The array of the initial parameter values; its size must match the number of
0084      *                          parameters in the function.
0085      * @return                  The IFitResult containing the result of the fit.
0086      *
0087      */
0088     virtual IFitResult * fit(IBaseHistogram & hist, const std::string & model, const std::vector<double>  & initialParameters) = 0;
0089
0090     /**
0091      * Shortcut to fit an IDataPointSet directly with an IFunction.
0092      * The dimension of the IDataPointSet must be equal the dimension of the IFunction + 1.
0093      * This are binned fits only; the last coordinate of the IDataPointSet is used as
0094      * the "height" in a fit to an IBaseHistogram.
0095      * @param dataPointSet The IDataPointSet to be fitted.
0096      * @param func         The IFunction to fit on the data.
0097      * @return             The IFitResult containing the result of the fit.
0098      *
0099      */
0100     virtual IFitResult * fit(IDataPointSet & dataPointSet, IFunction & f) = 0;
0101
0102     /**
0103      * Shortcut to fit an IDataPointSet directly with an IFunction.
0104      * The dimension of the IDataPointSet must be equal the dimension of the IFunction + 1.
0105      * This are binned fits only; the last coordinate of the IDataPointSet is used as
0106      * the "height" in a fit to an IBaseHistogram.
0107      * @param dataPointSet The IDataPointSet to be fitted.
0108      * @param model        The string defining the function to be used.
0109      * @return             The IFitResult containing the result of the fit.
0110      *
0111      */
0112     virtual IFitResult * fit(IDataPointSet & dataPointSet, const std::string & model) = 0;
0113
0114     /**
0115      * Shortcut to fit an IDataPointSet directly with an IFunction.
0116      * The dimension of the IDataPointSet must be equal the dimension of the IFunction + 1.
0117      * This are binned fits only; the last coordinate of the IDataPointSet is used as
0118      * the "height" in a fit to an IBaseHistogram.
0119      * @param dataPointSet      The IDataPointSet to be fitted.
0120      * @param model             The string defining the function to be used.
0121      * @param initialParameters The array of the initial parameter values; its size must match the number of
0122      *                          parameters in the function.
0123      * @return                  The IFitResult containing the result of the fit.
0124      *
0125      */
0126     virtual IFitResult * fit(IDataPointSet & dataPointSet, const std::string & model, const std::vector<double>  & initialParameters) = 0;
0127
0128     /// Shortcut for the predefined models.
0129     virtual IFitResult * fit(IFitData & d, const std::string & model) = 0;
0130
0131     virtual IFitResult * fit(IFitData & d, const std::string & model, const std::vector<double>  & initialParameters) = 0;
0132
0133     /**
0134      * Set the optimization engine which is used internally for fitting.
0135      * @param name The name of the optimizer engine.
0136      *             Examples of predefined engines: "minuit". The engine name is case-insensitive.
0137      *             Different engines are provided by different implementations.
0138      * @return false If the name does not correspond to a valid engine.
0139      *
0140      */
0141     virtual bool setEngine(const std::string & name) = 0;
0142
0143     /**
0144      * Get the name of the engine currently in use.
0145      * @return The name of the optimizer engine used by the IFitter.
0146      *
0147      */
0148     virtual std::string engineName() = 0;
0149
0150     /**
0151      * Access to fit parameter settings. FitParameterSettings object belongs to
0152      * and is managed by the fitter. Fitter implementation takes care that the
0153      * returned reference is valid thru the lifetime of fitter.
0154      * User can set the settings of the parameters independently of the
0155      * parameters of the fitted function.
0156      * Setting for parameters unknown in the function and set in the
0157      * fitter are ignored in the fit.
0158      * If settings are not explicitly set in the fitter, their default
0159      * values are attached to function parameters during the fit.
0160      */
0161     virtual IFitParameterSettings & fitParameterSettings(const std::string & name) = 0;
0162
0163     /**
0164      * Get a vector of names of all parameter settings defined in the fitter.
0165      */
0166     virtual std::vector<std::string>  listParameterSettings() = 0;
0167
0168     /**
0169      * Reset all parameter settings which fitter remebers.
0170      */
0171     virtual void resetParameterSettings() = 0;
0172
0173     /**
0174      * Set a general constraint in the parameter space. The constraint
0175      * is a parsed expression. PENDING: The syntax to be fixed.
0176      */
0177     virtual bool setConstraint(const std::string & expr) = 0;
0178
0179     /// Get the list of all constraints.
0180     virtual std::vector<std::string>  constraints() = 0;
0181
0182     /**
0183      * Reset all the constraints.
0184      */
0185     virtual void resetConstraints() = 0;
0186
0187     /**
0188      * Set the fit method type. Examples of pre-defined methods: "chi2", "ml".
0189      * The method names are case-insensitive.
0190      * @param name The name of the fit method.
0191      * @return false If the name does not correspond to a valid fit method.
0192      *
0193      */
0194     virtual bool setFitMethod(const std::string & name) = 0;
0195
0196     /**
0197      * Get the name of the fit method currently in use.
0198      * @return The name of the fit method.
0199      *
0200      */
0201     virtual std::string fitMethodName() = 0;
0202
0203     /// Create a 1D scan of the fit quality for given parameter 'par' of
0204     /// the function.
0205     /// User must make sure that the returned vector is properly deleted
0206     /// after use.
0207     /// The vector containes 'npts' points which are evenly sampled in the
0208     /// interval ('pmin','pmax').
0209     virtual IDataPointSet * createScan1D(IFitData & d, IFunction & f, const std::string & par, int npts, double pmin, double pmax) = 0;
0210
0211     /// Create a 2D contour spanned on 'par1' and 'par2',
0212     /// with given number of npts points. Contour is create using previously
0213     /// obtained fit results. Argument 'up' tells the vertical distance of
0214     /// the contour plane above the minimal fit quality value.
0215     virtual IDataPointSet * createContour(IFitData & d, IFitResult & r, const std::string & par1, const std::string & par2, int npts, double up) = 0;
0216
0217     /**
0218      * Choose between using or not using the
0219      * analytical derivatives if provided by the function.
0220      * @param useGrad If <code>true</code> the IFitter will use the
0221      *                analytical derivatives if provided by the IFunction.
0222      *
0223      */
0224     virtual void setUseFunctionGradient(bool useGrad) = 0;
0225
0226     /**
0227      * Check if the IFitter is set to use the analytical derivatives provided
0228      * by the IFunction.
0229      * @return <code>true</code> if the IFitter uses the analytical derivatives.
0230      *
0231      */
0232     virtual bool useFunctionGradient() = 0;
0233
0234     /**
0235      * @link association
0236      * @directed
0237      * @label <<create>>
0238      */
0239     /*#  IFitResult lnkIFitResult; */
0240
0241     /** @link dependency */
0242     /*#  IFitData lnkIFitData; */
0243
0244     /** @link aggregation
0245      * @supplierRole <<internal copy>>*/
0246     /*#  IFitParameterSettings lnkIFitParameter; */
0247
0248     /** @link dependency
0249      * @label fitter uses function for fitting*/
0250     /*#  IFunction lnkIFunction; */
0251 }; // class
0252 } // namespace AIDA
0253 #endif /* ifndef AIDA_IFITTER_H */