include/AIDA/IModelFunction.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_IMODELFUNCTION_H
0008 #define AIDA_IMODELFUNCTION_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 <vector>
0016
0017 #include "AIDA/IFunction.h"
0018
0019 namespace AIDA {
0020
0021 class IRangeSet;
0022
0023 /** @interface IModelFunction
0024  *
0025  * Interface of model function for fitting (for advanced users).
0026  *
0027  * OPEN QUESTIONS:
0028  *
0029  * How to treat normalization at user level? Two possibilities:
0030  * - we have "Gauss" and "NormalizedGauss", the first one user cannot
0031  *   use for ML fit
0032  * - we have only one "Gauss" function, but it's smart and when normalized,
0033  *   gets rid of one of its parameters
0034  *
0035  * Normalization range might be set directly on the function by the user?
0036  * Now we set it in the data pipe, Victor thinks that it is not very clear
0037  * and should be on the function ;)
0038  *
0039  * @author  The AIDA team (http://aida.freehep.org/)
0040  *
0041  */
0042
0043 class IModelFunction : virtual public IFunction {
0044
0045 public:
0046     /// Destructor.
0047     virtual ~IModelFunction() { /* nop */; }
0048
0049   /// Return false if function does not provide the normalization capability.
0050     virtual bool providesNormalization() const = 0;
0051
0052   /**
0053    * Normalize by internally adjusting some of the parameters.
0054    * When normalization is on then integral of the function in
0055    * the normalization range equals to 1.
0056    */
0057     virtual void normalize(bool on) = 0;
0058
0059   /**
0060    * Return true if normalization is currently switched on.
0061    */
0062     virtual bool isNormalized() const = 0;
0063
0064   /**
0065    * Compute gradient with respect to parameters.
0066    */
0067     virtual const std::vector<double>  & parameterGradient(const std::vector<double>  & x) const = 0;
0068
0069   /**
0070    * Return true if provides parameter gradient.
0071    */
0072     virtual bool providesParameterGradient() const = 0;
0073
0074   /**
0075    * Set the normalization range from -inf to +inf in the i-th
0076    * axis (dimension).
0077    *
0078    * Full range is the default if not set otherwise.
0079    * It is still possible to evaluate function outside of the
0080    * normalization range.
0081    *
0082    * PENDING: no methods to retrieve current range!
0083    */
0084     virtual IRangeSet & normalizationRange(int iAxis) = 0;
0085
0086   /**
0087    * Set full range in all axes.
0088    */
0089     virtual void includeNormalizationAll() = 0;
0090
0091   /**
0092    * Set empty range in all axes.
0093    */
0094     virtual void excludeNormalizationAll() = 0;
0095 }; // class
0096 } // namespace AIDA
0097 #endif /* ifndef AIDA_IMODELFUNCTION_H */