FML

LCG Project | LCG Applications Area

SEAL Project | Project Portal

 

$Date: 2005/01/11 11:21:03 $

FML: Fitting and Minimization Library

FML is a generic library for solving fitting and minimization problems. It defines abstract interfaces for minimization and it contains a default implementation of the Minimizer interface based on the SEAL C++ Minuit library. However, it can be also used with other minimization libraries and examples of implementations of the FML minimizer based on NagC (code) or the old Fortran Minuit (code) exist.

FML provides support for performing fitting based on the Chi2, binned and unbinned likelihood methods. In addition predefined model functions such as gaussian, exponential or polynomial are provided, together with functionality of adding them. The library defines also a generic function interface, which can be easily implemented by the user to define a customize user model function for fitting problems or a user objective function for minimization problems. Interfaces for configuring and controlling the fitting and minimization processes are as well provided

Examples of Usage

Perfom a Chi2 fit to a given data set

Suppose we have a data set, for example from an histogram. The data sets consists of three std::vector<double> : x , representing in case of an histogram bin center data, y , for bin heights and ey for bin errors.

Before fitting the user needs to copy the data in the fml::DataVector container and to create a model function.

// create and fill DataVector

fml::DataVector  v;
v.reserve( x.size() ); std::vector<std::vector<double> > xcor(x.size); for (unsigned int i = 0; i < x.size(); ++i) { // DataVector needs a vector of a vector for coordinates xcor[i].push_back( x[i]); v.push_back( xcor[i], y[i], ey[i] ); } // create fit model function (Gaussian) with mean = 0, sigma = 1, and amplitude = 100 fml::GaussModelFunction f(0,1,100);

In this case it is created from one of the function (a Gaussian) present in the library. An FML function can be also created from a free function as in the following examples:

//Power Low function :  1 dimension with 2 parameters

double myFunc(const std::vector<double> & x, const std::vector<double> & p) { 
return p[1]*exp( log(x[0])*p[0]);
}
// create an FML function using myFunc passing dimension (1) and number of params (2)  
fml::UserModelFunction f(myFunction,1,2); 

To perform the fit the user then need to create an instance of the Fitter class and then calling the method fit passing as argument a reference to the DataVector and the function. The fit method returns a pointer to the FitResult class, which contains all information resulting from the fit (fitted parameters, errors, covariance matrix, chi2, etc..).

/// create fitter with default engine
fml::Fitter fitter;
/// perform fit
std::auto_ptr<fml::FitResult> result = fitter.fit(*v,*f); 
if(result->isValid() )
{
    std::cout << "fitting successful!\n";
    result->printOn(std::cout);
}
else
   std::cout << "fitting failed!\n";
   return; 
}

This fit is performed using the default minimizer engine present in the library (lcg_minuit) and the default fitting method (Chi2). Through the class FitConfig the user can change engine, methods, setting minimizer control parameters and change parameter settings. Here is an example:

/// change fit engine and method
fml::Fitter fitter;
fitter.fitConfig().setEngine("simplex");
fitter.fitConfig().setMethod("PoissonML");
// For likelihood fits error UP needs to be set to 0.5
fitter.fitConfig().setErrorUP(0.5); 
// change parameter settings for param 1 
fml::FitParameterSettings & ps1 = fitter.fitConfig().fitParameterSettings(f->parameterNames()[0])
ps1.setStepSize(0.1);
// change setting for parameters 2 (set fixed) 
fml::FitParameterSettings & ps2 = fitter.fitConfig().fitParameterSettings(f->parameterNames()[1])
ps2.bound().setFixed(f->parameters()[1]);

More examples on the usage of FML can be found looking at the tests present in the repository.


Contact: Lorenzo Moneta