User`s & Reference Guide
Contents
1. UP is the 1 o quantile of the chi squared distribution with r degrees of freedom The scale factor of F is essential Additive terms which do not depend on 6 can be dropped however With r 1 and UP 1 the coverage probability corresponds to that of a one sigma error bar for a single parameter In Gaussian models 2 log likelihood equals up to a constant additive term the chi squared fit criterion and the whole analysis applies In many other cases the equality holds asymptotically thus validating the Minos analysis with F being the chi squared fit criterion For example using the Taylor expansion of log s around n the 2 log likelihood for the standard Poisson model for histogram cells counts can be written as 2 logL 27 n log f 8 f 8 logn 2 8 n f 8 n DOS t ii Ni ena f 8 ton 4 i f 8 n ni 2 gt a e C where C does not depend on 8 and each lies between n and f 8 Strong law of large numbers implies that n f 6 tends to 1 with probability one as the sample size increases f also increases in this case We thus have 2 f 9 n 5 lt 2 logL C 1 AE which shows that indeed the chi squared criterion is asymtotically equivalent to 2 log likelihood and that Minos analysis is asymptotically valid for the Poisson histogram cells counts model Gemini User s amp Reference Guide Hessian based error analysis 3 5 Hessian based2. bound upper bound and step can be given Consequtive values are assigned to consequtive parameters in the given order Parameters which are not explicitly defined are treated as unbounded with initial value zero void printSetup const Print the current problem setup to standard output including title minimization method initial parameters values parameters bounds and steps int setLinConstraint int cid const double cf double Ib double ub Add linear constraint with identifier cid nop vector of coefficients c lower bound Ib and upper bound ub Return 0 1 if success failure The function fails if the identifier is already in use nop stands for the number of objective function arguments Pre defined constants MINF minus infinity and INF infinity can be used in case a bound is not imposed int setNlinConstraint int cid NLCF funptr double Ib double ub Add non linear constraint with identifier cid constraint function pointer funptr lower bound Ib and upper bound ub Return 0 1 if success failure The function fails if the identifier is already in use Pre defined constants MINF minus infinity and INF infinity can be used in case a bound is not imposed int removeConstraint int cid Remove constraint number cid Return 0 1 if success failure The function fails if there is no constraint with the identifier cid int getResult int no double amp estimate double amp error double amp fval const If call
3. given error parameter UP the uncertainty set US of the solution 6 6 6 is defined as 1 US 0 F 0 F 6 lt UP For any sub vector of 6 the uncertainty set is constructed as the orthogonal projection of US onto the corresponding plane spanned by the selected components This purely geometrical concept is meaningful in qualitative sense for arbitrary objective functions Errors or uncertainties are related to the shape of the objective function in a neighbourhood of the minimum Well defined quantitative meaning in probabilistic terms can be assigned to such defined errors or uncertainties in statistical problems when the objective function is a fit criterion for example a chi squared log likelihood or least squares loss function Error analysis based on the plain difference F 6 F 8 is called Minos analysis as in Minuit In this context we also use terms like Minos error and Minos confidence region Minos analysis can be computationally very costly however as it requires multiple function minimization to find points on the boundary of US or of its projection It will be seen below how Minos analysis can formally be justified in statistical terms For maximum likelihood estimators and standard minimum chi squared estimators for example it can be done via the asymptotic chi squared distribution of a suitably transformed likelihood ratio A standard way to overcome the computational
4. merging and can be used for overlaying the contours If the marks used in the two contours to be added are non conflicting they will be preserved Otherwise new marks will be created in such a way that the points from the two added contours can still be distinguished when the sum is plotted For example GEminiContour cl c2 fill the contours plot overlayed contours cl c2 plot The title and center are inherited by the sum from the left most term 16 Gemini User s amp Reference Guide Chapter 2 Common public methods Gemini s functionality is implemented in a set of non virtual virtual and pure virtual methods in the abstract base class GEmini Some virtual methods are overriden in the derived classes CMinuit and NAGmin Suitable versions are then called according to the actual object type All pure virtual functions are implemented in the derived classes 2 1 Non virtual methods 18 22 Virtual methods 20 2 3 Pure virtual methods 22 Gemini User s amp Reference Guide 17 Common public methods 2 1 18 Non virtual methods int initParms const char file Read parameters setup from a text file Return 0 1 in case od success failure Lines starting with are ignored as comment lines A line defining a parameter consists of blank separated tokens and must contain the parameter number and name Optionally the initial value lower
5. the sample size the difference between inverses of those two Hessians becomes asymptotically insignificant As a result with H denoting the Hessian of the Lagrangian at 6 one can approximate the covariance matrix of 6 as follows 6 VQ H HT A A H A ATH As a by product of the minimization process the NAG C minimizer nag_opt_nlp used in Gemini to solve constrained problems provides the upper triangular Choleski factor R such that H R R A convenient way of computing V is then to solve the equation R B A with respect to B and compute Vg RU B B B BNR or alternatively to find the OR decomposition B QU of B form a matrix O consisting of the last p k columns of Q and compute 2 F Va R QIR Q The latter method is used in Gemini It is instructive to see how this formalism works for simple bound constraints In this case we can permute the parameters so that the last k of them are effectively fixed and z H Po and He Pe Oe QD Qx D with D and D of size k k Obviously Let us write 1 ASH AS D and using 6 one obtains after some elementary algebra T 1 Vo p 0 p 0 0 0 0 The block matrix inversion formula 3 applied to H then immediately gives Va P o 0 0 Gemini User s amp Reference Guide 37 Error analysis in Gemini which means that the covariance matrix of the free parameters can be obtained by removing those rows and columns of the Hes
6. we drop here the rows and columns of zeros which correspond to parameters which are either fixed or on the boundary The function returns 0 1 in case of success failure cov is a nin array stored row wise Note that the returned matrix is the genuine covariance matrix only if the error parameter up has been set correctly i e such that the usual one sigma errors are computed c f the description of setError above virtual int getCov int n int m double amp cov const Set cov to the covariance of the parameters n and m Return 0 1 in case of success failure In the NAGmin implementation the covariance matrix is re calculated from its Choleski factor whenever this function is called Thus if many covariances are to be obtained it will be much more efficient to call getCovMatrix and pick up suitable elements rather than to call getCov many times As above Cov is the genuine covariance only if the error parameter up has been set correctly i e such that the usual one sigma errors are computed virtual int minosErrors int n double amp neg double amp pos Find Minos errors for parameter n store internally and return them in neg and pos Return values 0 success 1 errors out of limits 2 new minimum found 3 no of function calls exceded its limit 4 other failure virtual int minosContour int n int m GEminiContour amp p Try to find p np points along a contour on the plane spanned by parameters n and m The contour is def
7. Gemini minimization and error analysis package in C Version 1 0 User s amp Reference Guide August 1999 Zbigniew Szkutnik Copyright CERN Geneva 1997 Copyright and any other appropriate legal protection of this documentation and associated computer program reserved in all countries of the world Organisations collaborating with CERN may receive this program and documentation freely and without charge CERN undertakes no obligation for the maintenance of this program nor responsibility for its correctness and accepts no liability whatsoever resulting from its use Program and documentation are provided solely for the use of the organisation to which they are distributed This program may not be copied or otherwise distributed without permission This message must be retained on this and any other authorised copies The material cannot be sold CERN should be given credit in all references This document has been prepared with Release 5 5 of the Adobe FrameMaker Technical Publishing System using the User s Guide template prepared by Mario Ruggier of the Information and Programming Techniques Group at CERN Only widely available fonts have been used with the principal ones being Running text Palatino 10 5 pt on 13 5 pt line spacing Chapter numbers and titles AvantGarde DemiBold 36 and 24 pt Section headings AvantGarde DemiBold 20 pt Subsection and subsubsection headings Helvetica Bold 12 and 10 pt Capt
8. Index 42 initParms 18 L linear constraints 4 18 27 M MIGRAD 4 MINE 18 20 minimization object 12 minimize 20 22 Minos 3 15 19 20 22 minosContour 22 minosErrors 22 Minuit 26 MNEXCM 26 MNINTR 26 N nag_opt_nlp 4 NAGmin 3 12 13 17 27 NLCF 14 O objective function 4 10 objective function object 11 12 OBJfun 4 OBJfun counter 11 OBJfun resetCounter 11 overlaying contours 16 P parmDef 20 printResults 19 printSetup 18 problem title 12 R removeConstraint 18 resetStartPoint 20 S selection of minimizer 12 13 setError 15 20 22 setLinConstraint 18 setNlinConstraint 14 18 setObjFun 20 setPrecision 21 setPrintLevel 22 setTitle 20 setTolerance 21 Gemini User s amp Reference Guide Index U UP value 20 W warningsOFF 21 warningsON 21 Gemini User s amp Reference Guide 43 Index 44 Gemini User s amp Reference Guide
9. and can be used if minimization objects are dynamically allocated on the heap This allows the user to select the minimizer at run time rather than at compilation time For example capture the objective function OBJfun f myObjectiveFunction GEmini mcptr int nop 4 number of function argument if something use Minuit mcptr new CMinuit Minuit test nop amp f else use NAG C mcptr new NAGmin NAG C test nop amp f mcptr gt minimize mcptr gt printResults delete mcptr Gemini User s amp Reference Guide 13 Functions and objects 1 5 General constraints functions By default the minimization problem is considered unconstrained i e each argument can take any real value The user can however restrict the objective function domain by imposing bound constraints setting lower and or upper bounds for any argument linear constraints setting lower and or upper bounds for linear combinations of arguments and general non linear constraints setting lower and or upper bounds for the values of arbitrary functions of the arguments In the latter case for each non linear constraint the user must provide a C C function which computes for a given vector of arguments the constraint function value and optionally its gradient Computing as many gradient components as possible will generally improve both performance and reliability The constraint can then actually be imposed
10. can only be solved be means of the NAGmin class Internally the NAG minimizer nag opt nlp is used for such problems Although the objective function and the constraint functions are assumed to be smooth at least twice continuously differentiable the method of nag_opt_nlp will usually solve the problem if there are only isolated discontinuities away from the solution The only currently used minimizers are MIGRAD for CMinuit and nag_opt_nlp for NAGmin Note however that the CMinuit specific method command allows for execution of any Minuit command thus providing an indirect way of using other Minuit minimization methods like SIMPLEX or MINIMIZE The objective function to be minimized is encapsulated in an OBJfun class It can be used simply to capture the usual user s function e g OBJfun f chi2f or a user can derive his own function class from it add all the functionality needed in his her specific problem and override the virtual member function objfun with the actual objective function Contours are implemented as an abstract data type GEminiContour with overloaded assignment and addition operators Its usage is described in detail in section 1 6 Gemini internally maintains two set of parameters the initial setup used as a starting point for the first minimization process and the result of the last minimization If another minimization process is started after the previous one is completed and if no intermediate parameter re
11. d degree polynomial of one variable may look as follows void fun int n double g double f const double x int code const double a 1 0 b 2 0 c 1 0 compute function value af 2 xe O ex 0 SAR OT ce if code 2 compute gradient g 0 2 a x 0 b The objective function may have any name unless the user overrides the objfun member of the objective function object as described in the next section Although the objective function is assumed to be smooth at least twice continuously differentiable the minimizers will usually solve the problem if there are only isolated discontinuites away from the solution 10 Gemini User s amp Reference Guide The objective function object 1 2 The objective function object The objective function object encapsulates the objective function a function calls counter and possibly some user defined functionality like initialization The objective function object OBJfun can simply capture a usual user function say chi2f OBJfun f chi2f or the user can derive his her own class from OBJfun with overriden virtual member function objfun and possibly some problem specific functionality added e g class alephRb public OBJfun public user added functionality initialization e t c override virtual objective function from OBJfun void objfun int n double grad double fval const double x int code private A
12. definition has been done then the result of the previous minimization is used as the starting point for the next one Whenever a user re defines a parameter both sets of parameters get updated At any stage of the analysis the original starting point can be set by calling the function resetStartPoint Thus the same starting point can be re used with another minimizer but the results of the current minimization overwrite the previous ones The covariance matrix is computed but not stored in its final form Only the parameters errors are stored In NAGmin the covariance matrix is re computed from its Choleski factor and stored in a user s matrix if explicitly requested by a call to getCovMatrix as described below In CMinuit the covariance matrix is retrieved from the Minuit s memory if requested The application code must include gemini h the Gemini header file NAG C header files are not needed when the application code is being compiled Some examples are provided with the installation kit At CERN they can be accessed at LHCXXTOP share GEMINI pro examples Installation details are described in a HTML document accessible at CERN at LHCXXTOP share GEMINI pro doc geminilib html The package has been tested on HP CC and aCC IBM xlC DEC cxx Sun CC Linux egcs and Windows NT MS VC 5 4 Gemini User s amp Reference Guide Preface For details related to the minimization algorithms the user is ref
13. difficulty of Minos analysis is to approximate F 0 F with 0 5 0 6 H 6 with H being the Hessian of F at 8 One obtains this approximation via the standard Taylor expansion of F around 6 and using the fact that the gradient of F at the minimum is zero With this approximation approximate versions of both US and its projections can be found analytically so that multiple function minimization can be avoided This leads to the standard Hessian based error analysis and is related to asymptotically normal distributions of estimators In the following sections those two approaches are described in more detail and their links to standard statistics exposed Unconstrained minimization problems are discussed first Error analysis for problems with constraints is the subject of the last section It is always assumed that the problem is regular enough for the underlying mathematical theory to be applicable The aim of this description is to expose main ideas rather than to present technical details Relevant mathematical results can be found for example in the books by Silvey 4 Bard 5 and Serfling 3 The book by Eadie at al 6 is a standard statistical reference for HEP physicists It contains in particular a discussion of the Minos idea in less formal terms of an implicit transformation to linearity and back which provides further insight into the idea of Minos Gemini User s amp Reference Guide Minos error analysi
14. e form 4 US 0 0 5 0 lt UP Gemini User s amp Reference Guide 33 Error analysis in Gemini 34 In order to set this in relation with statistics recall that if F is 2 log likelihood then the maximum likelihood estimator 8 is in regular cases asymptotically normally distributed 6 AN 6 J where 7 1 2 E H is the Fisher information matrix for the whole data set Again in regular cases one can reasonably assume that EH H 6 and use the inverse of 1 2 H as an estimate S of the covariance matrix of 8 This is clearly related to 2 and means that since 4 0 s 0 6 is asymptotically chi squared distributed with p degrees of freedom in order to have the asymptotic 1 a coverage probability for US one should set UP to the 1 a quantile of the chi squared distribution with p degrees of freedom Further S in 4 can clearly be interpreted as the covariance matrix of the marginal distribution of 6 8 and in view of its asymptotic normality setting UP in 4 to the 1 a quantile of the chi squared distribution with r degrees of freedom we get the asymptotic coverage probability 1 a for US More generally the above argument can be extended to any M estimator in which case the asymptotic covariance matrix needs not to be the inverse of the Fisher information matrix but continues to be the properly normalized inversed Hessian For the chi squared fit criterion the app
15. e file is read and options are initialized when an object of the type NAGmin is created One very useful option which can be set via e04ucc opt is verify_grad which has the effect that the minimizer verifies user provided gradient components This is very useful while debugging a newly written application See section E04 in the NAG C library manual 2 for more details If the user objective function computes ALL the gradient elements then setting options obj_deriv to TRUE will improve both performance and reliability NAGmin solves problems with general constraints and performs the related error analysis Note that Minuit is not able to solve such problems even if general constraints can be set in the CMinuit class minimize will fail in that case Gemini User s amp Reference Guide 27 Minimizer specific extensions 28 Gemini User s amp Reference Guide Appendix A Error analysis in Gemini General concept of errors den oe BS 30 Minos error analysis 2 9 gets lt p eX Ge Men st 31 Hessian based error analysis 33 Practical summary lt 2 4 a He Bod dos 35 Error analysis in constrained minimization 36 Gemini User s amp Reference Guide 29 Error analysis in Gemini 3 3 General concept of errors 30 The general concept of errors or uncertainties in Gemini is the same as in Minuit For a given objective function F 8 to be minimized with 6 6 6 nr and for a
16. e without any intermediate action the current solution is taken as the starting point However if this routine is called before the second minimize the original starting point will be used rather than the current solution Note that in any case the current Hessian approximation gets forgotten which may be useful if the Hessian is extremely ill conditioned c f NAG C documentation 2 virtual void setTitle const char title Set problem title virtual void setError double up Define the error parameter same as Minuit s UP value The scale factor for the inverted Hessian is then 2 up thus leading to usual one sigma errors if Up 1 for chi 2 or up 0 5 for negative log likelihood The default value for up is 1 It is the user s responsibility to correctly set this parameter and correctly interprete the errors obtained Negative values of up are ignored Whenever setError is called the parameters errors if any are recalculated and Minos errors get forgotten so that the current stored solution is always consistent with the current value of the up parameter Gemini User s amp Reference Guide Virtual methods virtual int fixParm int no Fix the parameter number no at the current value obtained in the minimization process and return 0 If minimization has not been done yet the function returns 1 with no change in the parameter setup virtual void warningsON void Switch the warnings printout on default v
17. ed before minimization or after unsuccessful minimization the function returns 1 Otherwise 0 is returned and for parameter number no estimate is set to the optimal parameter value error to the error estimate and fval to the minimum function value If error was not successfully computed error is set to 1 Gemini User s amp Reference Guide Non virtual methods int getMinosErrors int no double amp negative double amp positive const Retrieve Minos errors for parameter no Zeros are returned in negative positive if the respective error has not been computed The function fails if no is out of range or minimization has not been performed yet Return values 0 1 success failure int ellipticalContour int n int m GEminiContour amp p const Find p np points along a contour on the plane spanned by parameters n and m The contour is defined as the set of points in which the local parabolic approximation to the objective function based on the Hessian takes the value min UP where min is the current minimum and UP is the value defined in setError Thus it just constructs standard confidence regions based on the marginal distributions of the estimates Note that elliptical contours can only be constructed after both a minimum and the Hessian at the minimum have been found Return values 0 1 success failure void printResults const Print the results to standard output including title minimization method number o
18. eneral constraints The standard approach to constrained minimization is via the Lagrange functional Only active constraints influence the error analysis Assume that F log likelihood Let A 0 6 8 denote the vector of constraints active at the solution and Ay A be the vector of Lagrange coefficients The solution 6 is then obtained by setting to zero the gradient of the Lagrangian G 0 F 8 A7h 6 and solving the equation with respect to 8 and Denote by A the p k matrix of gradients of h 6 and write Ig Ag _ Ve ia kdl where 1 is the Fisher information matrix for the whole data set It can be shown that in regular models 6 AN 6 Vo and AN O V and and are asymptotically independent More explicitly one can show that 5 6 AN 8 Ig Iq AA IS AS AT a l AN O A iz Ag Gemini User s amp Reference Guide Error analysis in constrained minimization Recall that 7 equals the expectation of the Hessian of F log likelihood and that it is usually approximated by the Hessian at the minimum In the process of a constrained minimization however the Hessian of the Lagrangian at the minimum is easily obtainable and not that of F Those two Hessians differ by terms of the form 3 A a hC gt 96 08 which according to 5 may increase at the rate of the square root of the sample size Since the Hessian of F increases at the rate of
19. ered to the corresponding manuals for Minuit 1 and NAG C 2 Gemini User s amp Reference Guide 5 Preface 6 Gemini User s amp Reference Guide Contents Preface Chapter 1 Functions and objects 1 1 The objective function 1 2 The objective function object 13 Minimization objects and their constructors 14 Generic pointer to a minimization object 1 5 General constraints functions 1 6 Contour objects Chapter 2 Common public methods 2 1 Non virtual methods 2 2 Virtual methods 2 3 Pure virtual methods Chapter 3 Minimizer specific extensions 3 1 Minuit specific extensions 3 2 NAG specific extensions Appendix A Error analysis in Gemini 3 3 General concept of errors 34 Minos error analysis 3 5 Hessian based error analysis 3 6 Practical summary 3 7 Error analysis in constrained minimization Bibliography Index Gemini User s amp Reference Guide 10 11 12 13 14 15 17 18 20 22 525 26 27 29 30 231 33 35 36 39 41 Contents 8 Gemini User s amp Reference Guide Chapter Functions and objects This chapter describes the functions and objects used in Gemini 1 1 1 2 1 3 1 4 1 5 1 6 The objective function e le e 10 The objective function object 11 Minimization objects and their constructors 12 Generic pointer to a minimization object 13 Ge
20. error analysis In the Hessian based error analysis F 8 F 6 is approximated with 0 5 0 8 H 6 6 with H being the Hessian of F at 6 The approximate version US of the uncertainty set US corresponding to a given value of the UP parameter takes then the form 2 US fe 30 0 00 5 lt ur The orthogonal projection US of US onto the plane spanned by say the first r components of 8 consists of all points 6 6 such that the minimum of 8 6 H 8 6 with respect to 8 p 8 is not greater than 2 UP Let us split 6 6 into two sub vectors 6 consisting of the first r components and consisting of the remaining p r components Correspondingly we can write H H He 12 H H with H of size r r and H of size p r p r Looking for a minimum with respect to 6 and with 6 fixed we have then 0 0 H 0 6 0 H 0 20 H 0 0 H28 GO and grad G 8 2H16 2H0y The equation grad G 6 0 gives the minimum point 6 H H1 6 The minimum value is x T 1 7 G 871 0 H Hp HA H 8 which gives US fo 507 H H iy Hia Ur On the other hand using the symmetric block matrix inversion formula we have 1 a Hy Hp O H H pH Hi x i Ho H xe Hy I H1 X z l ay x with X H H H H H H _ This means that with S 0 5H we can write US 0 0 6 5 6 6 lt UP and denoting by S the upper left r r portion of S the projection US takes th
21. f function calls parameters errors and function value at the minimum Gemini User s amp Reference Guide 19 Common public methods 2 2 Virtual methods 20 virtual int parmDef int no const char name double value double step double IBound double uBound Define parameter number no by setting its name value step lower bound IBound and upper bound uBound and return 0 1 in case of success failure Pre defined constants MINF minus infinity and INF infinity can be used in case a bound is not imposed Setting value IBound uBound results in fixing the parameter at that common value Parameters which are not explicitly defined are treated as unbounded with initial value zero name can be set to NULL in which case a default name is assigned to the parameter virtual void setObjFun int nofparms OBJfun fptr Assign a new objective function object pointed to by fptr and set the number of parameters to nofparms For NAGmin the current parametrs definitions for parameters 1 to nofparms and the current options setup are preserved For CMinuit however any new function assignement forces Minuit s re initialization in order to avoid any interference with the previous analysis As a side effect the previous parameters definitions and the minimization options previously set get lost and have to be re set virtual int resetStartPoint void Reset start point to the original one If a second call to minimize is mad
22. f points c the point mark A suitable copy constructor is provided so that contours can safely be passed by value The contour title is normally set by the contour filling routine Once o contour is filled its title can be redefined by the user through the GEminiContour public method void setTitle const char str The title length is limited to 70 If str points to a longer string it will be truncated Similarly the contour centre is normally set by the contour filling routine to the current minimum point but can also be set explicitly through the public method void setOrigin double xo double yo The contour can be plotted in the text mode for preliminary inspection through the public method void plot void Gemini User s amp Reference Guide 15 Functions and objects The x and y coordinates of the points are stored in public arrays x and y and the coordinates of the i th contour points can be accessed as x i and y i with i 0 n 1 The pointers to the double arrays of x s and y s are returned by public member functions xp and yp Whenever a declared contour is being filled a public member n should be set to the actual number of points filled In Gemini it is done automatically and n is equal to nop if the requested number of points has successfully been found Contours are implemented in Gemini as an abstract data type with overloaded assignment and addition operators Addition means in this case
23. freedom a fact used for the construction of the so called asymptotic likelihood ratio test A test It follows immediately that for any true 8 with the given values of the first two components F 0 0 F 8 is asymptotically chi squared distributed with two degrees of freedom we impose two constraints by fixing the values of and 6 and for any true 9 with the given value of the first component 0 F 8 is asymptotically chi squared distributed with one degree of freedom we fix the value of 6 only A standard Neyman asymptotic 1 o confidence region for 6 6 can then be constructed as 8 8 F 85 F 5 lt cy with c being the 1 guantile of the chi squared distribution with two degrees of freedom This is exactly the projection of US with UP c onto the plane spanned by the first two components a Similarly an asymptotic Neyman 1 o confidence region for 9 is 0 F 8 F 8 lt c with c being the 1 a quantile of the chi squared distribution with one degree of freedom Again this is the projection of US with UP c onto the first axis With obvious modifications the same argument applies of course to any subset of the components of 8 Gemini User s amp Reference Guide 31 Error analysis in Gemini 32 To summarize If F is 2 log likelihood then Minos confidence regions for r components of 8 have the asymptotic coverage probability 1 a if
24. function object can either be assigned to a minimization object via its constructor or alternatively via a public method setObjFun At any time only one OBJfun object can be assigned to the fitting object Any new assignment with setObjFun replaces the previous one For CMinuit any new function assignement forces Minuit s re initialization in order to avoid any interference with the previous analysis As a side effect the minimization options like e g the output level previously set get lost and have to be re set Internally a function calls counter is implemented Two public methods give access to this counter although there is normally no need to do anything with the counter long counter void Return the current value of the counter void resetCounter void Reset the counter to zero Gemini User s amp Reference Guide 11 Functions and objects 1 3 Minimization objects and their constructors The minimization object is the main object which contains the complete problem definition It also provides methods for assigning an objective function object defining the objective function arguments and their admissible regions setting minimization options running a minimizer obtaining the current status of the minimization process obtaining results and error analysis If the minimization object is of type CMinuit then Minuit is used as the minimization engine Similarly if it is of type NAGmin then NAG C minim
25. ined as the set of points in which the minimum of the objective function w r t all the remaining parameters equals min UP where min is the Gemini User s amp Reference Guide Pure virtual methods current minimum and UP is the value defined in setError p n is set to the number of points actually found Return values number of points found if successful O less than 4 points found 1 other failure Gemini User s amp Reference Guide 23 Common public methods 24 Gemini User s amp Reference Guide Chapter 3 Minimizer specific extensions Some useful minimizer specific features are implemented as extensions so that they are not part of the GEmini class 3 1 Minuit specific extensions 26 3 2 o NAG specificextensions 4 4 27 Gemini User s amp Reference Guide 25 Minimizer specific extensions 3 1 Minuit specific extensions int command const char cmd const double argsf int argsno const Execute Minuit command cmd with argsno arguments given in the array args Return 0 1 in case of success failure This corresponds to the Minuit s subroutine MNEXCM void commandMode void const Switch to the command mode with commands read from standard input This is an analog of the Minuit s subroutine MNINTR 26 Gemini User s amp Reference Guide NAG specific extensions 3 2 NAG specific extensions Optional parameters can be set via a file e04ucc opt Th
26. ions Helvetica 9 pt Listings Courier Bold 9 pt Use of any trademark in this document is not intended in any way to infringe on the rights of the trademark holder Preface Gemini is a GEneral MINImization and error analysis package implemented as a C class library Minuit s functionality is provided in a Minuit style even if internally another minimizer may actually do the work and new functionality offered by NAG C minimizers is added Gemini thus provides a unified C API both to standard Minuit and to NAG C family of minimizers For the common subset of functionality it is up to the user which minimization engine does the work Minuit or NAG C The user can easily switch between various minimizers without essential changes in the application code The currently supported set of minimizers Minuit and NAG C can be extended without essential changes in the API The abstract base class GEmini defines an interface to the common functionality The CMinuit class is derived from GEmini and provides a Minuit based implementation of the GEmini functionality plus Minuit specific extensions Similarly the NAGmin class is derived from GEmini as well and provides a NAG based implementation of the GEmini functionality plus NAG specific extensions If the user s minimization object is declared as being of type CMinuit then Minuit will be used as the minimization engine Correspondingly if the user declares the object as being of ty
27. irtual void warningSOFF void Switch the warnings printout off virtual void setPrecision double prec Precision corresponds to the Minuit s parameter EPS or Nag options f_prec It defines the precision to which the objective function can be computed See corresponding manuals for details virtual void setTolerance double tol Tolerance is Nag options optim_tol and corresponds to Minuit s tolerance parameter The algorithm stops if the estimated vertical distance to the minimum is smaller than tol NOTE The last statement is precisely true for MIGRAD but only approximately true for nag_opt_nlp where the convergence criteria are slightly more complicated See 2 for more details Gemini User s amp Reference Guide 21 Common public methods 2 3 22 Pure virtual methods virtual void setPrintLevel int level Set printout level level 1 0 1 2 3 virtual int minimize void Solve the current minimization problem by means of the currently selected method Return 0 1 in case of success failure virtual int getCovMatrix int n double cov const Let nofp stand for the number of currently free parameters If n lt nofp the function fills the n n cov matrix with the n by n portion of the covariance matrix If n gt nofp the upper left corner of the cov matrix is filled with nofp nofp elements of the covariance matrix and the remaining elements of cov are not modified Thus following Minuit s tradition
28. izers are used Current minimization object constructors are CMinuit CMinuit int n OBJfun fptr CMinuit const char ptitle int n OBJfun fptr and NAGmin NAGmin int n OBJfun fptr NAGmin const char ptitle int n OBJfun fptr where n number of arguments of the objective function ptitle optional problem title fptr pointer to the objective function object The length of the title is limited to 80 characters as defined in gemini h If ptitle points to a longer string only the first 80 characters are stored as the problem s title CMinuit is equivalent to CMinuit 0 NULL and NAGmin is equivalent to NAGmin 0 NULL They create an empty minimization object An objective function object can then be assigned to such an empty fitting object by executing setObjFun as described below At any time only one OBJfun object can be assigned to the fitting object Any new assignment with setObjFun replaces the previous one For CMinuit any new function assignement forces Minuit s re initialization in order to avoid any interference with the previous analysis As a side effect the minimization options like e g the output level previously set get lost and have to be re set 12 Gemini User s amp Reference Guide Generic pointer to a minimization object 1 4 Generic pointer to a minimization object A generic pointer of the type GEmini can point both to CMinuit and NAGmin type objects
29. neral constraints functions 14 Contour objects EE ky De PS NS 15 Gemini User s amp Reference Guide 9 Functions and objects 1 1 The objective function The objective function is the function to be minimized The user must supply a C C function which computes the objective function value and optionally its gradient for a given vector of function arguments Computing as many gradient components as possible will generally improve both performance and reliability The objective function has the prototype void int n double gi double objf const double x int code where n Input the number of function arguments g n Output the function must not change the elements of g if no gradient is computed If the gradient is computed its computed components should be filled in g if on input code 2 objf Output the value of the objective function at the current point given in x x n Input the point x at which the function value and possibly gradient is required code Input if code 0 only function value must be computed If code 2 both the function value and available gradient components should be computed For Minuit code 1 is allowed as well in which case initialization tasks can be performed Note however that the initialization tasks can better be encapsulated in the constructor of the user s function class derived from OBJfun A simple example function which implements a secon
30. onstraint function is typedef ined as NLCF and is passed as argument to the function setNlinConstraint 14 Gemini User s amp Reference Guide Contour objects 1 6 Contour objects A contour is a set of points from the boundary of a bounded set in a two dimensional subspace In Gemini it typically represents either an elliptical boundary of a Hessian based confidence region for a selected pair of parameters or a Minos contour i e the curve on which the minimum of the objective function with respect to all the remaining parameters equals the current minimum plus the current value of the UP parameter as set via the setError function Contours are implemented in Gemini as a GEminiContour class Along with the contour points stored in counter clock order GEminiContour also stores the coordinates of the contour centre the title assigned to the contour and the point marks which are used for contour plotting in the text mode Two public members np and n contain correspondingly the number of data points to be filled and the number of data points actually stored Thus np will typically be set before the contour is filled while n is set by the routine which actually fills the contour The default value of np is 20 and the default point mark is The following contour constructors are available GEminiContour GEminiContour int nop GEminiContour char c GEminiContour int nop char c where nop the required number o
31. pe NAGmin then NAG C minimizers will be used There is no single class which contains references both to Minuit and to NAG C This is done on purpose so that orthodox Minuit or NAG C users are not forced to link the other library only if the Gemini library is created as a static library Gemini finds a minimum of an objective function possibly subject to general constraints and performs an error analysis The concept of errors is that of Minuit so that it is the user s responsibility to properly scale the inversed Hessian or equivalently define the UP parameter and to properly interpret the results Both Hessian based errors and Minos errors are implemented Correspondingly two types of function contours or confidence regions in statistical problems are available elliptical and Minos ones Minos error analysis is however possible only for unconstrained and bound constraint problems General constraints cover in addition to the usual bound constraints two additional types of constraints Gemini User s amp Reference Guide 3 Preface linear constraints of the form lb lt c x lt ub where c is a column vector of coefficients x is a column vector of objective function arguments and b and ub are lower and upper bounds general non linear constraints of the form b lt h x lt up where h stands for any function of the objective function arguments Problems with linear and or non linear constraints
32. roximation argument from the previous section applies Gemini User s amp Reference Guide Practical summary 3 6 Practical summary The covariance matrix in Gemini is computed for unrestricted minimization problems as 2 UP H and the Hessian based error of 6 is calculated as Jsu The following table summarizes the rules for proper setting of UP for single parameter s errors one sigma error two sigma error three sigma error log L UP 0 5 UP 2 UP 45 2 log L UP 1 UP 4 UP 9 chi squared UP 1 UP 4 UP 9 For a standard least squares fit the values of UP should be taken from the last row and multiplied by the standard estimate 6 of the residual variance Since the variance estimate can only be computed after the fit the value of UP can be set before minimization as for a chi squared fit and the computed errors multiplied by 6 afterwards For simultaneous 1 a confidence regions for r parameters UP should be set to the 1 a quantile of the chi squared distribution with r degrees of freedom for 2log L or chi squared fit criteria and to half of that value for log L For a least squares fit the values of UP should be computed as for the chi squared fit and multiplied by the standard estimate 6 of the residual variance Gemini User s amp Reference Guide 35 Error analysis in Gemini 3 7 36 Error analysis in constrained minimization A special case of cons
33. s 3 4 Minos error analysis The Minos uncertainty set US for the whole vector 9 is defined above in 1 In order to obtain an uncertainty set for two components only say 8 and 6 we have to project US onto the plane spanned by those components This projection is a set of points 0 0 such that for some 8 0 F lt F 6 UP Equivalently it is the set of points 0 such that the minimum of F 8 with respect to 6 9 and with 9 and 6 fixed is not greater than F 6 UP The boundary of this set is thus the contour of the function F 8 85 ming e F 8 which corresponds to F 6 05 F 8 UP For a single parameter say 6 we define a function F 9 ming and construct the uncertainty set or the projection of US as 0 lt F 6 UP For a regular function F genuine local minimum 9 and small UP this will be an interval 6 say The positive and negative Minos errors are then defined as correspondingly 6 and 6 8 In order to give Minos errors a quantitative statistical meaning let us assume first that F is 2 log likelihood for a regular statistical model The unrestricted minimum 6 of F is then a maximum likelihood estimator of 8 Let further 6 be the minimum of F subject to r independent restrictions h h h 8 0 It is well known that for any true 6 which satisfies the restrictions F 6 F is asymptotically chi squared distributed with r degrees of
34. sian which correspond to the fixed parameters and inverting the resulting sub Hessian 38 Gemini User s amp Reference Guide Bibliography Minuit Function Minimization and Error Analysis Reference Manual FJames CERN Program Library Long Writeup D506 1994 NAG C Library Manual Mark 5 Vol 2 The Numerical Algorithms Group Limited 1998 Approximation Theorems of Mathematical Statistics R J Serfling Wiley 1980 Statistical Inference S D Silvey Chapman and Hall 1975 Nonlinear Parameter Estimation Y Bard Academic Press 1974 Statistical Methods in Experimental Physics W T Eadie D Drijard FJames M Roos and B Sadoulet North Holland 1971 Gemini User s amp Reference Guide 39 Bibliography 40 Gemini User s amp Reference Guide C CMinuit 3 12 13 17 27 CMinuit command 26 CMinuit commandMode 26 constraint identifier 18 contour 4 15 19 22 covariance matrix 4 22 E ellipticalContour 19 F fixParm 21 function calls counter 11 G GEmini 3 17 GEminiContour 4 15 GEminiContour plot 15 GEminiContour setOrigin 15 GEminiContour setTitle 15 general constraint function 14 general constraints 4 18 27 generic pointer 13 getCov 22 getCovMatrix 4 22 getMinosErrors 19 getResult 18 gradient 10 14 27 H Hessian 3 15 19 20 I include files 4 INF 18 20 index Gemini User s amp Reference Guide 41
35. traints are bound constraints Both Minos and Hessian based error analysis apply to problems with bound constraints If a bound constraint is active i e a variable is on its boundary it is considered fixed at that value and correspondingly its error is set to zero For non active constraints Minos confidence regions are forced to be contained in the admissible regions and are cropped if necessary Hessian based error analysis is not affected by non active bound constraints For general constraints the situation is different Even if Minos analysis is potentially applicable to problems with general constraints it is likely that the uncertainty sets are rather irregular or even degenerate due to the restrictions imposed In effect it is rather difficult to construct a general algorithm able to handle those rather arbitrary sets The Minos algorithm has been imported to Gemini from Minuit with only minor modifications It has been designed and works effectively however only if the uncertainty sets are rather regular especially if they are convex and non degenerate as it is typically the case in fitting applications with no general constraints imposed Although it seems feasible to use the Minos algorithm for single parameter s errors in general constrained problems it has not been sufficiently tested yet and remains to be done In Gemini only Hessian based error analysis as described below has been implemented for problems with g
36. with setNlinConstraint A general constraint function has the prototype void int n double gil double val const double xf int code where n Input the number of function arguments g n Output the function must not change the elements of g if no gradient is computed If the gradient is computed its computed components should be filled in g if on input code 2 val Output the value of the constraint function at the current point given in x x n Input the point x at which the function value and possibly gradient is required code Input if code 0 only function value must be computed If code 2 both the function value and available gradient components should be computed For example if the objective function is a function of four arguments and if one wants to impose a constraint on the sum of squares of the last two arguments the corresponding general constraint function might look as follows void cfun int n double g double f const double x int code compute constraint function value f x 2 x 2 x 3 x 3 if code 2 compute gradient components g 0 gli 0 GLA 28x 1274 g 3 2 x 3 The constraint function can have any name Although the constraint function is assumed to be smooth at least twice continuously differentiable the minimizers will usually solve the problem if there are only isolated discontinuites away from the solution A pointer to a c
Download Pdf Manuals
Related Search