Interfacing fitters ------------------- @ 1/ General contraints and needs @ 2/ Naming and organisation @ 3/ fitter itself @ 4/ Display of results @ 5/ Communication with modeler, available functions @ 6/ Open points @ 7/ Modifications of this document 1/ General contraints and needs ------------------------------- - The interface is essentially: -> get the values of the parameters from the modeler (start) -> get the residuals (and chi2) from the modeler. <- send back the values of the parameters. Various tools (functions) are available, for instance to get informations on the parameters (see later). - The computation of residuals lasts from a fraction of a second to many minutes. As much as possible, we must save the number of computations of the residuals... - A fitter must be allowed to call another fitter. For instance: o A fitter is looking for the global minimum by using a fitter that only dives in local minima. o A fitter can find a minimum, but relies on another fitter to determine errors on the parameters, correlation matrix, statistics, etc. - Parameters can be vectorial. This is handled internally by the software. The fitter only sees one set that gathers all the parameters to be fitted. 2/ Naming and organisation -------------------------- - A fitter has a unique name (preferably short), "". o Now defined: - "standard" = "trfit" - "trfit" - "nlfit" - "Nelder_Mead" (airi) - Corresponding software can be loaded by including file "LITpro_fitter_.i" In production, this file is included only when necessary, when the corresponding fitter is actually used. - Two functions must be defined: o lpf__go(world, keywords=, ...) o lpf__show(world) These functions will be called by user functions lp_go_fit and lp_show_fit. - To authorize a new fitter just add it to the list: h_set, LPF_FITTER_NAMES, = "60 chars of description"; The GUI may use lpf_go_fit_list() to get the list of the fitters and associated description. 3/ fitter itself ---------------- lpf__go(world, keywords=keywords, ... key=val, ...) - inputs o world is the opaque object where everything is stored. o keywords that must be accepted: verbose - gives some information during the fit. Generally not used during production. Essentially for experts. No output is allowed if verbose=0. itmax - max number of iterations. One iteration corresponds to a successful step, with a chi2 improvement. plot - (naming should change...). A reference on a user function to be called between two iterations (see after). o Other specific keywords can be defined. When useful for the user, the keywords can be made available to the user in lp_go_fit. o Specific keywords for "trfit" (that could be used by other fitters if approximately the same meaning). tol_step= - Tolerance on the smallest step. Each parameter is normalized by its scale (see lp_set_parameter). The fit is stopped if the norm of the vector of fitter parameters is less than TOL_STEP. Default is 1e-8. tol_gradient= - Tolerance on null gradient. Fit is stopped if the norm of the vector of derivatives of chi2 versus each parameter is lower than TOL_GRADIENT. Default is 1e-8. tol_degen= - Tolerance on the detection on degenerencies. Default is 1e-8. o Keywords can also be given through a hash table named "keywords": keywords |- verbose |- itmax |- plot |- tol_step |- tol_gradient `- tol_degen This way is the standard way. Function lpf_parse_keyword is useful for handling the default values of the keywords (see later). o Default values of the keywords must be defined by each fitter. - They may be optimized differently for each fitter (itmax) - This does not prevent to set defaults at the level of lp_go_fit. o Precedence of the keywords: - 1 - the value given with the keyword; if void, - 2 - the value found in keywords; if void, - 3 - the default value defined in the fitter function. This parsing can be easily done by using lpf_parse_keyword: itmax = lpf_parse_keyword("itmax", keywords, 200); (1) (2) (3) - Outputs o Returns a hash table (can be the fitter workspace). o Mandatory entries in this workspace : chi2 - final chi2. iter - number of iterations done. itmax - maximum number of iterations. - Specific behaviors and limitations o The fitter is requested to ask for the residuals in the current state of the parameters, before to change them. This is usually done to start the fit anyway. This will allow the user to know the change of chi2 before and after the fit. o "plot" user function must be called with argument world between two iterations. if (!is_void(plot) && is_func(plot)) { plot, world; } o A fitter can call another fitter directly, but must use functions lpf_fitter_go() and lpf_fitter_show() (see after). - Informations from the other fitter can be obtained by reading the returned hash table. o control-C The fitter can be interrupted with control-C. The signal must be catched (yorick function catch()) to save the current results like a normal exit with a limited number of iterations. The last obtained best parameters are loaded in world using lpf_set_fitted_parameter_values() (see [@5]). 4/ Display of results --------------------- s = lpf__show(world) This function is called by lp_show_fit. The output is a single string (several lines) to be displayed to the user either by the CLI of by the GUI. For now, the information to be displayed is: values of the parameters, standard deviations, correlation matrices. Sample from trfit: Stopping alibi: no significant change in parameter values (tol_step) Final values and standard deviation for fitted parameters: d1 = 2.0039 +/- 0.0164 d2 = 2.2654 +/- 0.0588 i1 = 0.77707 +/- 0.0523 i2 = 0.22293 +/- 0.0152 x2 = -16.389 +/- 0.0104 y2 = -8.9162 +/- 0.0155 --- Covariance matrix --- d1 d2 i1 i2 x2 y2 d1 2.7e-04 -4.3e-04 3.1e-05 -3.1e-05 -1.9e-05 5.1e-05 d2 -4.3e-04 3.5e-03 -9.2e-05 9.2e-05 9.9e-05 -1.2e-04 i1 3.1e-05 -9.2e-05 2.7e-03 7.8e-04 -5.8e-06 8.3e-06 i2 -3.1e-05 9.2e-05 7.8e-04 2.3e-04 5.8e-06 -8.3e-06 x2 -1.9e-05 9.9e-05 -5.8e-06 5.8e-06 1.1e-04 -4.4e-05 y2 5.1e-05 -1.2e-04 8.3e-06 -8.3e-06 -4.4e-05 2.4e-04 --- Correlation matrix --- d1 d2 i1 i2 x2 y2 d1 1 -0.44 0.036 -0.13 -0.11 0.2 d2 -0.44 1 -0.03 0.1 0.16 -0.13 i1 0.036 -0.03 1 0.98 -0.011 0.01 i2 -0.13 0.1 0.98 1 0.037 -0.035 x2 -0.11 0.16 -0.011 0.037 1 -0.27 y2 0.2 -0.13 0.01 -0.035 -0.27 1 5/ Communication with modeler, available functions -------------------------------------------------- The actions are mainly: - get/set the values of the parameters to be fitted, - get the weighted residuals, chi2. - parsing the keywords: itmax = lpf_parse_keyword("itmax", keywords, 200); We have see this in [@3]. - workspace ws = lpw_get_workspace(world, ""); // get new workspace This gives an independent workspace that can be obtained again at next call. If useful, keyword "clean" allows the workspace to be empty (cleaned). If not cleaned a new call of the same fitter will get again the previous workspace. - get/set values of the parameters a = lpf_get_fitted_parameter_values(world); lpf_set_fitted_parameter_values, world, a; Only the values to be fitted are all stacked in the same vector. The fitting interface knows the correspondence with the actual parameters. Vectorial parameters are possible. --------------------------------------------------------------------- WARNING: setting a parameter out of the bound is not allowed => crash --------------------------------------------------------------------- The fitter must be sure to update the last (i.e. best) values of the parameters by using lpf_set_fitted_parameter_values(). - Vector of weighted residuals and chi2 res = lpf_compute_residuals(world); chi2 = lpf_compute_chi2(res); If necessary, getting the size of the array of the residuals is possible before to compute residuals, this way: nres = lpw_get_global(world, "number_of_data"); - Getting informations on the parameters. names = lpf_get_fitted_parameter_names(world) val = lpw_get_parameter(world, names(i)). In names, there is a one-to-one correspondence with vector of parameter values. In case of a vectorial parameter, the name of the parameter is repeated as many times as the number of elements in the vectorial parameter. Properties: descr - (string) description of the parameter. flags - (long) flags. Autorized flags are: LPW_FLAGS_FIXED, LPW_FLAGS_VMIN, LPW_FLAGS_VMAX, LPW_FLAGS_AUTOSCALE. (flags & LPW_FLAGS_AUTOSCALE) => autoscale (scale not defined) (flags & LPW_FLAGS_VMIN) => has vmin defined (flags & LPW_FLAGS_VMAX) => has vmax defined (flags & LPW_FLAGS_FIXED) => not fitted parameter (*) (*) Since the parameters are fitted parameters here, this test is always FALSE. scale - (double) Typical magnitude of the parameter value if it is known. If void, an automatic scaling is used by the fitting algorithm for this parameter. units - (string) name of units (only informative). vmax - (double) upper bound for the value of the parameter. If void, no upper bound is defined for the parameter. vmin - (double) lower bound for the value of the parameter. If void, no lower bound is defined for the parameter. A property can be void if not defined. --------------------------------------------------------------------- WARNING: setting a parameter out of the bound is not allowed => crash --------------------------------------------------------------------- - Calling other fitters (equested in [@1]). fct = lpf_fitter_go(fitter_name) ws = fct(world, itmax=3) The first function returns a reference on the fitter function. If fitter_name is not given (or void), the standard fitter is used. lpf_fitter_go checks the availability of the fitter function and includes corresponding files if necessary. As any fitter, the hash table allows some information to be returned. The function can be called more directly this way, if used only once: ws = lpf_fitter_go(fitter_name)(world, itmax=3) The summary of the fit can also be obtained this way, for instance for appending the returned lines to the ones of the calling fitter. To be added in the function lpf__show(world). summary = lpf_fitter_show(fitter_name) 6/ Open points -------------- - Need for errors on the parameters, correlation matrix, etc. as shown in [@4]. Probably need to implement algorithms for this task. o trfit: use jacobian from the gradient computed from finite differences, with rescaling of error bars. o need for resampling methods ? - Control-C not yet implemented in trfit. If a satisfactory solution is yet to be validated. - If all the parameters are fixed, the GUI should ask the user to release at least one parameter when clicking on "run fit". 7/ Modifications of this document --------------------------------- $Log: interface_with_fitters.txt,v $ Revision 1.3 2012-01-23 13:00:42 michel - Full rereading. - Added informations on lpf_parse_keyword(). - Removed recursive calling of lp_go_fit. - Introduce recursive calling with lpf_fitter_go() and lpf_fitter_show(). Revision 1.2 2012-01-22 23:29:23 isa some small corrections Revision 1.1 2012-01-22 15:57:09 michel - Description of the interface between LITpro code and fitters, for the implementation of new fitters.