User manual ()
Contents
1. n l 1 Ao 2 Fm M 1 e Fot m X Bom pa m 1 e variable s parameter s properties same as multi_alt_exp_model 13 1 8 multi_alt_exp_Asqr_expE_ model e function s N 1 f t 12 e t fs B n pipe M 1 1 40 le Bom Ha m 1 e variable s parameter s properties same as multi alt exp model 18 13 2 Vector two point models All the scalar two point models listed in section are also available as vector two point models called e multi exp vec model e multi exp expE vec model e multi exp Asqr vec model e multi exp Asqr expE vec model multi alt exp vec model e multi alt exp expE vec model multi alt exp Asqr vec model e multi alt exp Asgr expE vec model These models require one further key in addition to the keys of the corresponding scalar models the dimension of the vector Key content type dim 1 dim integer gt 1 A vector model has then dim functions f t i 1 dim of the same form as the underlying scalar model These functions have individual amplitude parameters but share all the energy parameters For example the functions for multi exp vec model are N 1 filt A ile Et y Bn i e EtdE1 dEn t n l for i 1 dim 13 3 Two point models with periodic B C All the scalar and vector two point models listed in and are also available with periodic boundary conditions Th2. lt plot_domain gt lt variable_name gt t lt variable_name gt lt plot_order gt 1 lt plot_order gt lt range gt lt min gt 0 lt min gt lt max gt 64 lt max gt lt range gt lt step gt 0 01 lt step gt lt plot_domain gt lt data_file gt lt file_type gt ASCII lt file_type gt file name re_v_1s_xyz_mom_0_0_0 dat lt file_name gt lt datan fiie lt multi_alt_exp_Asqr_expE_BC_model gt lt threept_multi_alt_exp_expE_model gt lt B to Kstar 3 point fn lt multi_exp_Asqr_expE_BC_model gt lt n_exp_initial gt 8 lt n_exp_initial gt lt n_o_exp_initial gt 8 lt n_o_exp_initial gt lt n_exp_final gt 8 lt n_exp_final gt lt n_o_exp_final gt 8 lt n_o_exp_final gt lt A_name gt A lt A_name gt lt B_name gt B lt B_name gt lt E_initial_name gt Ei lt E_initial_name gt lt dE_initial_name gt dEi lt dE_initial_name gt lt E_final_name gt Ef lt E_final_name gt lt dE_final_name gt dEf lt dE_final_name gt lt t_name gt t lt t_name gt lt T_name gt T lt T_name gt lt fit_domain gt lt variable_name gt t lt variable_name gt lt range gt lt min gt 1 lt min gt lt max gt T 2 lt max gt lt range gt lt fit_domain gt lt fit_domain gt lt variable_name gt T lt variable_name gt lt range gt lt min gt 14 lt min gt lt max gt 16 lt max gt lt range gt lt fit_domain gt lt plot_domain gt lt variable_name gt t lt variable
3. B name B string E name E string dE_name dE string t name t string dim 1 i dim 1 integer gt 2 dim 2 J l dim 2 integer gt 1 27 13 8 4 multi alt exp expE nonsym mat model e function s for i 2 dim 1 j 1 dim 2 N 1 filt Ax d Ay j e ty No Bx n i Byn j ee n 1 M 1 1 Aox Aoy j e Ta 27 Box m i Boy_m__j pisse m 1 for i 1 j 1 dim 2 n 1 N 1 filt Ay j je Bynj sma M 1 pen Aoy j ag t de y Boy mj m 1 e variable s parameter s properties same as multi alt exp nonsym mat model 13 9 Scalar three point models 13 9 1 threept multi exp model e function s f t T Alle te E T t ES y Bn n e F dF1 dF n t E E dE_1 dE_n T t n 0 N 1 n 0 N 1 n n 0 0 e variable s t T e parameter s A B nn E dE n F dF_n e properties 28 Key content type n_exp_initial N integer gt 1 n_exp_final N integer gt 1 A_name A string B_name B string E initial name E string dE initial name dE string E final name F string dE final name dF string t name t string T name T string 13 9 2 threept multi exp expE model e function s f t T e te 77 T 5 ET y Bnin e E HeT ein e He p pet T n 0 N 1 n 0 N 1 n n 4 0 0 e variable s parameter s properties same as threept_multi_exp_model 13 9 3 threept multi alt
4. dFo m eE dE e n eF dr mn e n E e O dE e Om er ET gdFo m e variable s parameter s properties same as threept multi alt exp model 13 10 Vector three point models The scalar three point models listed in section are also available as vector three point models called e threept_multi_exp_vec_model e threept_multi_exp_expE_vec_model e threept multi alt exp vec model e threept multi alt exp expE vec model These models require one further key in addition to the keys of the corresponding scalar models the dimension of the vector Key content type dim 4 1 dim integer gt 1 31 A vector model has then dim functions f t i 1 dim of the same form as the underlying scalar model These functions have individual amplitude parameters but share all the energy parameters For example the functions for threept_multi_exp_vec_model are filt T i ale t E T t y Bn ni e E aF 1 dF_n t E dE_1 dE_n T t n 0 N 1 n 20 N 1 n n 0 0 for 7 1 dim 13 11 Degenerate three point models 13 11 1 threept constant model e function s f t T C e variable s t T note both t and T are a dummy variables e parameter s C e properties Key content type C name C string t name t string T name T string 13 11 2 threept constant sqr model e fun
5. generated by the user For example lt fit_domain gt lt variable_name gt t lt variable_name gt lt range gt lt min gt 8 lt min gt lt max gt T 12 lt max gt lt range_bootstrap_file gt BK3pt brf lt range_bootstrap_file gt lt range gt lt fit_domain gt lt fit_domain gt lt variable name gt T lt variable name lt range gt lt min gt 0 lt min gt lt max gt 26 lt max gt lt range gt fit domain In this case the explicit range specified for the variable t via min and max 8 to T 12 are only used for the initial fit when XMBF starts but not for the bootstrap During the bootstrap the values for min and max for each bootstrap sample are instead read from the file specified in range bootstrap file in this case BK3pt brf This number of lines in this file must be equal to bootstrap samples and every line must have two entries the min and max As discussed in Sec these entries may also contain functions of constants and other variables but the functions must not contain whitespaces The first few lines of the file BK3pt brf in the example could for example be 15 5 112 10 T 14 d T12 de vene As discussed in Sec 10 1 in XMBF every fit domain can have multiple range nodes and the actual fit range is the union of the ranges It is allowed that some range nodes do not have a range bootstrap file while others do An optional step value Sec inside a range node is r
6. variable gt lt variables gt lt functions gt lt function gt lt number gt 1 lt number gt definition A_1 exp E t exp E T t lt definition gt lt function gt lt function gt lt number gt 2 lt number gt definition A 2 exp E t exp E T t lt definition gt lt function gt lt functions gt lt constants gt lt name gt T lt name gt lt constants gt lt parameters gt lt name gt A_2 lt name gt lt name gt E lt name gt lt name gt 1 lt name gt lt parameters gt lt derivatives gt lt derivative gt lt function_number gt 1 lt function_number gt lt parameter_name gt A 1 lt parameter name definition exp E t texp E T t lt definition gt lt derivative gt lt derivative gt lt function_number gt 1 lt function_number gt lt parameter_name gt A_2 lt parameter_name gt definition 0 lt definition gt lt derivative gt lt derivative gt lt function_number gt 1 lt function_number gt lt parameter_name gt E lt parameter name gt definition A 1 t exp E t T t exp E T t lt definition gt lt derivative gt lt derivative gt lt function_number gt 2 lt function_number gt lt parameter_name gt A 1 lt parameter name definition 0 lt definition gt lt derivative gt lt derivative gt lt function_number gt 2 lt function_number gt lt parameter_name gt A_2 lt param
7. Axi y ey y Bx n i By_n__j La n l for i 1 j 1 dim 2 N 1 fij t Ay_j e ty 5 By_n__j ae n 1 e variable s t e parameter s Ax i Bx n i for i 2 dim 1 Ay j By n__j for j 1 dim 2 E dE_n e properties Key content type n exp N integer gt 1 A name A string B name B string E name E string dE name dE string t name t string dim 1 i dim 1 integer gt 2 dim 2 j l dim 2 integer gt 1 13 8 2 multi exp expE nonsym mat model e function s for i 2 dim 1 j 1 dim 2 N 1 f t Axi Ay 3 gt gt Bx n i By n j e Are ten n 1 26 for i 1 j 1 dim 2 N 1 fij t Ay aoe t di gt By n_j glee e n 1 e variable s parameter s properties same as multi exp nonsym mat model 13 8 3 multi alt exp nonsym mat model e function s for i 2 dim 1 j 1 dim 2 n 1 N 1 fatu Ax d Ay j e t gt Bxn i By n j prote M 1 pr Aox Aoy j x ty y Box m_i Boy m j ase m 1 for i 1 j 1 dim 2 N 1 filt Ay_j era y By_n__j su nml M 1 De Aoy__j e t y Boy_m__j m 1 e variable s t e parameter s Ax i Bx_n_i for i 2 dim_1 Ay__j By n__j for j 1 dim 2 E dE_n Aox_i Box m_i for i 2 dim 1 Aoy__j Boy m j for j 1 dim 2 Eo dEo_n e properties Key content type n exp N integer gt 1 n_o_exp M integer gt 1 A_name A string
8. dim 2 E dE_n Ao_i Bo m_i for 1 max dim_1 dim 2 Eo dEo_m e properties Key content type n exp N integer 7 1 n o exp M integer gt 1 A_name A string B_name B string E name E string dE_name dE string t name t string dim 1 t dim 1 integer gt 1 dim 2 J l dim 2 integer gt 1 13 5 4 multi alt exp expE mat model e function s for i 1 dim 1 j 1 dim 2 N 1 fij t A d Aj e t gt Bm i B n j Lusi n 1 M 1 EA Ao__j pe n p Bo m i Bo mj pre m 1 e variable s parameter s properties same as multi alt exp mat model 13 6 Matrix two point models type II In type II matrix models the ground state is not special All amplitudes including the ground state amplitude are written as a product A_i B n i i e n now starts from 0 This means that max dim 1 dim 2 of the parameters B n i are redundant and Bayesian constraints must be acti vated The typical usage is to constrain the parameters B_ i 1 _ to 1 with a very small prior width e which effectively eliminates these parameters from the functions 23 13 6 1 multi exp mat II model e function s for i 1 dim 1 j 1 dim 2 N 1 Pk gt Bni Bng e Pret n 0 e variable s t parameter s A_i B n 3 for i 1 max dim 1 dim 2 E dE_n e properties Key content type n exp N integer gt 1 A name A string B
9. ed Rs 28 E RR ES SEKR oe He ROW deal Swe do 28 13 9 2 threept_multi_exp_expE_model 29 13 9 3 threept multi alt exp model 29 13 9 4 threept multi alt exp expE model 31 Da ER R EO He EE ee TA ae oe RA Nue 31 13 11 Degenerate three point models 2 2 a rn aa 32 13 ll lthreept constant model 32 13 11 2threept_constant_sqr_modell 32 13 11 3multi_exp_2var_modell 32 13 11 4multi_exp_expE_2var_model 33 A a a E a G E a a a E R i i e a 33 TERETERE oe Oe eS Bey ee CN ty es 33 14 User defined model 34 1 Introduction XMBF is used to perform fits that can combine multiple QMBF type fit models each with its own data file to a simultaneous fully correlated fit See the documentation of QMBF for the meaning of QMBF type fit model and the data file format More information on the method of combining multiple models to a simultaneous correlated fit can be found in Appendix C 2 of the PhD thesis Heavy quark physics on the lattice with improved nonrelativistic actions available at http www dspace cam ac uk handle 1810 225126 In XMBF fit parameters with the same name across different models will be shared The param eter names for each model are defined using input from the user so that the user can decide which parameters wi
10. E mat model SI ABE pon ten gt n exp 8 lt n exp n o exp 8 lt n_o_exp gt lt A name Ai lt A name lt B name Bi B name XE name Ei E name dE name dEi dE name t name t t name dim 1 2 dim 1 dim 2 1 dim 2 lt fit_domain gt lt variable_name gt t lt variable_name gt lt range gt lt min gt 2 lt min gt lt max gt 32 lt max gt lt range gt lt fit_domain gt lt plot_domain gt lt variable_name gt t lt variable_name gt lt plot_order gt 1 lt plot_order gt lt range gt min 0 lt min gt lt max gt 32 lt max gt lt range gt lt step gt 1 lt step gt lt plot_domain gt lt data_file gt lt file_type gt ASCII lt file_type gt lt file_name gt re B 2x1 matrix mom 0 0 0 dat lt file_name gt c data tile lt multi alt exp expE mat model multi alt exp Asgr expE BC model SEN Kstiarn 25 point fn gt lt n_exp gt 8 lt n_exp gt lt n_o_exp gt 8 lt n_o_exp gt lt A_name gt Af lt A_name gt lt B_name gt Bf lt B_name gt lt E_name gt Ef lt E_name gt lt dE_name gt dEf lt dE_name gt lt t_name gt t lt t_name gt lt T_name gt L4 lt T_name gt lt fit_domain gt lt variable name gt t lt variable name lt range gt lt min gt 1 lt min gt lt max gt 20 lt max gt lt range gt lt range gt lt min gt 44 lt min gt lt max gt 63 lt max gt lt range gt lt fit_domain gt
11. Fea nata e T 2 n 1 e variable s t e constant s T e parameter s Z P A Pp B_P_n Ep dE_n 33 e properties Key content type n exp N integer gt 1 n part P integer gt 1 A name A string B name B string Z name Z string E name E string dE name dE string t name t string T name T string 14 User defined model In addition to the built in models listed in Sec there is a model called parse model which allows the user to completely define new models using only the XML input file When using parse model the functions and if necessary their first order derivatives are entered as strings and parsed by XMBF A parse model of XMBF offers the same functionality as a user defined model of QMBF allowing the definition of models with an arbitrary number of functions variables parame ters and constants The functions and derivatives can be constructed using the same elementary operations as in QMBF the reader is referred to the QMBF manual for the details exp log sin cos tan sinh cosh tanh arcsin arccos arctan sqr sqrt alt 34 An example usage of parse_model is shown below parse model lt n variables 1 lt n variables n functions gt 2 lt n_functions gt lt variables gt lt variable gt lt number gt 1 lt number gt lt name gt t lt name gt lt
12. Sec 13 6 e function s for i 1 dim j i dim total number of functions dim dim 1 2 N 1 filt Ai Aj D BniBn je Ent n 0 e variable s t e parameter s A i Bni for i 1 max dim_1 dim 2 E dE n e properties Key content type n exp N integer 7 1 A name A string B name B string E name E string dE name dE string t name t string dim i 1 dim j dim integer gt I 13 7 4 multi exp expE mat II upper model Note some parameters are redundant see Sec 13 6 e function s for i 1 dim j i dim total number of functions dim dim 1 2 N 1 fij t Ai Aj y Bn_iBn je n 0 25 e variable s parameter s properties same as multi exp mat II upper model 13 8 Non symmetric matrix two point models Here the amplitudes are factorized into an outer product of two different vectors rather than the outer product of a vector with itself as in the models of Sec 13 5 Because of a reparametrization invariance some amplitude parameters need to be eliminated to get unique results This has already been done in the following models so that the fit functions are different for i 1 vs i gt 1 see below As in Sec the required storage order in the data files is such that the first index i runs slow and the second index 7 runs fast 13 8 1 multi exp nonsym mat model e function s for i 2 dim 1 j 1 dim 2 N 1 ja
13. XMBF 2 40 Stefan Meinel June 7 2013 Contents 1 Introduction Compiling XMBF 21 Standard Double Precision Build Rn 2 2 Build with Quad Double Inverter 2 3 Build for parallel bootstrap with MPI 2 4 Additional programs Using XMBF 3 1 Using XMBF mpack dd oe an ee He R3 EUR de eub er ae eu 3 2 Using XMBF mpi ea sa woe RR ea ae E Wy de de UR RO aies dela UR die e Basic structure of the input file The macros node The combined models node The chi sqr extra term node The fit settings node The parameter values and constant values nodes 0 More details on fit ranges 10 1 Lower and upper bounds 10 2 Step SIZES 1 Verb eG Roe mde OR RCR e A eB EE OW Teo KE dd x 11 More details on bootstrap 11 1 Resampling the data aaa 11 2 Resampling both the data and the fit ranges 12 Multifit 10 11 12 14 14 14 14 14 15 16 13 Built in Models 16 13 1 Scalar two point models 16 13 1 1 multi exp model satt saue mag eR a DU Ras 16 13 1 2 multi exp expE model 32 saus are eal a aem opo and ae Daan 17 13 1 8 multi exp Asgr modell 17 13 1 4 multi exp Asqr expE modell 17 13 1 5 multi alt exp mo
14. _Asqr_expE_BC_model gt lt threept_multi_alt_exp_expE_model gt MBE O MES polntefne lt n_exp_initial gt 1 lt n_exp_initial gt lt n_o_exp_initial gt 1 lt n_o_exp_initial gt lt n_exp_final gt 1 lt n_exp_final gt lt n_o_exp_final gt 0 lt n_o_exp_final gt lt A_name gt KA lt A_name gt lt B_name gt KB lt B_name gt lt E_initial_name gt Ei lt E_initial_name gt lt dE_initial_name gt dEi lt dE_initial_name gt lt E_final_name gt KEf lt E_final_name gt lt dE_final_name gt KdEf lt dE_final_name gt lt t_name gt t lt t_name gt lt T_name gt T lt T_name gt lt fit_domain gt lt variable_name gt t lt variable_name gt lt range gt lt min gt 6 lt min gt lt max gt T 12 lt max gt lt range gt lt fit_domain gt lt fit_domain gt lt variable_name gt T lt variable_name gt lt range gt min 0 lt min gt lt max gt 26 lt max gt lt range gt lt fit_domain gt lt plot_domain gt lt variable_name gt t lt variable_name gt lt plot_order gt 2 lt plot_order gt lt range gt min 0 lt min gt lt max gt T lt max gt lt range gt lt step gt 1 lt step gt lt plot_domain gt lt plot_domain gt lt variable_name gt T lt variable_name gt lt plot_order gt 1 lt plot_order gt lt range gt min O lt min gt lt max gt 26 lt max gt lt range gt lt step gt 1 lt step gt lt plot_domain gt lt data_file gt l
15. _name gt lt plot_order gt 2 lt plot_order gt lt range gt lt min gt 1 lt min gt lt max gt T 2 lt max gt lt range gt lt step gt 1 lt step gt lt plot_domain gt lt plot_domain gt lt variable_name gt T lt variable_name gt lt plot_order gt 1 lt plot_order gt lt range gt lt min gt 14 lt min gt lt max gt 16 lt max gt lt range gt lt step gt 1 lt step gt lt plot_domain gt lt data_file gt lt file_type gt binary lt file_type gt file name im_gj_s0jg5_s1_pf_0_0_0_p_0_0_0 bin lt s datan fien lt threept_multi_alt_exp_expE_model gt lt n_exp gt 1 lt n_exp gt lt A_name gt KAf lt A_name gt lt B_name gt KBf lt B_name gt lt E_name gt KEf lt E_name gt lt dE_name gt KdEf lt dE_name gt lt t_name gt t lt t_name gt lt T_name gt L4 lt T_name gt lt file_name gt KZ point iim gt lt fit_domain gt lt variable_name gt t lt variable_name gt lt range gt lt min gt 10 lt min gt lt max gt 54 lt max gt lt range gt lt fit_domain gt lt plot_domain gt lt variable_name gt t lt variable_name gt lt plot_order gt 1 lt plot_order gt lt range gt min 0 lt min gt lt max gt 64 lt max gt lt range gt lt step gt 0 01 lt step gt lt plot_domain gt lt data_file gt lt file_type gt ASCII lt file_type gt file name re ps ls mom 0 0 O dat lt file_name gt lt data_file gt lt multi_exp
16. ction s f t T c e variable s parameter s properties same as threept constant model 13 11 3 multi exp 2var model e function s N 1 f t T A le D B ne E 4E14 dE n T n l e variable s t T note t is a dummy variable This model is intended for fitting of three point functions in which the initial and the final state have identical energy levels and the off diagonal transition matrix elements vanish In this case the t dependence disappears 32 e parameter s A B n E dE n e properties Key content type n exp N integer gt 1 A_name A string B name B string E_name E string dE_name dE string t name t string T name T string 13 11 4 multi exp expE 2var model e function s N 1 f x T pe Tq Y Bn e Ee espe n 1 e variable s parameter s properties same as multi exp 2var model 13 12 Multi particle two point models 13 12 1 multi part exp expE model This model was implemented by W Detmold Currently it has no implementation of the symbolic derivatives and therefore this model must be used in combination with num diff first order true mnum diff first order in the fit settings node see Sec 12 to enable numerical differentiation e function s f t T zPe 0 2 cosn e P T 2 PP P E P E 92 7 Z_P APp e C C 7 2 cosh EP Jt T 2 p 1 ias P PA P y ZPgBPag v6 bee PAT cosh gp ugue
17. data and the values of the fitted functions are written to files in the specified directory these files can then be used for plotting With the option b directory XMBF performs the bootstrap procedure see Sec and writes the results for each parameter into an individual file in directory With the option m directory XMBF performs the multifit procedure see Sec and writes the results for each parameter into an individual file in directory The option v level determines how much information is printed to stdout during the fit The default corresponds to v 0 With v 1 after every iteration the current values of x dof and are printed with v 2 in addition the current values of all parameters are printed after every step 3 1 Using XMBF_mpack_qd The quad double version XMBF_mpack_qd can be used in the same way as the standard version 3 2 Using XMBF_mpi The MPI version XMBF_mpi is only intended for parallel bootstrap see Sec 11 It must be used as follows assuming Open MPI mpirun np nprocs XMBF_mpi b directory inputfile Here nprocs is the number of MPI processes to be used the number of bootstrap samples must be divisible by nprocs 4 Basic structure of the input file This is the basic structure of an input file lt xml version 1 0 gt lt fit gt macros TS combined model EN lt chi sqr extra term ooo coris lt fit_settings gt fit sertinge gt parameter values gt S parau
18. del 17 13 1 6 multi alt exp expE model 18 13 1 7 multi alt exp Asqr model 18 13 1 8 multi_alt_exp_Asqr_expE_model 18 CIV 19 13 3 Two point models with periodic B C 19 NN 20 FELE EEE EEE 22 13 5 1 multi exp mat model 22 13 5 2 multi exp expE mat model 22 13 5 9 multi_alt_exp_mat_modell 23 13 5 4 multi alt exp expE mat model eA 23 13 6 Matrix two point models type III 23 19 0 1 multi exp mat IL model 4 s 29 ox woo sc v obo OE ho drug rue 24 13 6 2 multi exp expE mat II model 24 ps dede ul gustu e eder oe eae fer pile ice tA ee 24 13 7 1 multi exp mat upper model 24 13 7 2 multi exp expE mat upper model 25 13 7 3 multi exp mat II upper model 25 13 7 4 multi exp expE mat II upper model 25 eae A de BA De dr D wes 26 13 8 1 multi exp nonsym mat model 26 13 8 2 multi_exp_expE_nonsym_mat_model 26 13 8 3 multi alt exp nonsym mat model 27 13 8 4 multi_alt_exp_expE_nonsym_mat_model 28 SU ang a ee ee OE ee Ss an
19. e gt lt second_deriv_minimization gt false lt second_deriv_minimization gt lt num_diff_step gt 1e 08 lt num_diff_step gt lt start_lambda gt 0 001 lt start_lambda gt lt lambda_factor gt 10 lt lambda_factor gt lt chi_sqr_tolerance gt 0 001 lt chi_sqr_tolerance gt lt chi_sqr_per_dof_tolerance gt true lt chi_sqr_per_dof_tolerance gt lt n_parameters_dof gt 18 lt n_parameters_dof gt lt inversion_method gt LU lt inversion_method gt lt bootstrap_normalization gt false lt bootstrap_normalization gt lt svd_fixed_cut gt 0 lt svd_fixed_cut gt lt svd_ratio_cut gt 1e 06 lt svd_ratio_cut gt lt svd_absolute_cut gt 1e 06 lt svd_absolute_cut gt lt max_iterations gt 1000 max iterations lt bin_size gt 1 lt bin_size gt lt bootstrap_samples gt 500 lt bootstrap_samples gt lt use_bse_file gt true lt use_bse_file gt lt bse_file gt bootstrap_1600configs_500samples bse lt bse_file gt lt restrict_bootstrap_range gt false lt restrict_bootstrap_range gt lt bootstrap range min gt 1 lt bootstrap range min gt lt bootstrap range max gt 50 lt bootstrap range max gt lt fit settings Most of the settings are as in to QMBF see the documentation of QMBF The property chi sgr per dof tolerance specifies whether the numerical value entered in chi sqr tolerance the abortion criterion for the Levenberg Marquardt iteration is used for the total x or for x dof 11 The optio
20. e models with periodic boundary conditions are called e multi_exp_BC_model e multi_exp_expE_BC_model e multi_exp_Asqr_BC_model e multi_exp_Asqr_expE_BC_model e multi alt exp BC model e multi alt exp expE BC model multi alt exp Asgr BC model 19 e multi alt exp Asgr expE BC model e multi exp vec BC model multi exp expE vec BC model e multi exp Asqr vec BC model e multi exp Asqr expE vec BC model multi alt exp vec BC model e multi alt exp expE vec BC model e multi alt exp Asqr vec BC model e multi alt exp Asqr expE vec BC model and require one further key in addition to the keys of the underlying models the name of the constant corresponding to the temporal extent of the lattice Key content type T name T string The models with periodic boundary conditions have the same parameters as the underlying models The only difference is the replacement fe gt filt f T t for all functions f of the model The value of T has to be specified in the constant_values node see section 9 13 4 Two point models with time independent contributions For all the scalar and vector two point models listed in and 13 2 as well as their versions with periodic boundary conditions Sec 13 3 an additional version exists which adds time independent pieces to the fit function JU gt Je for scalar models f t gt f t ce 1 co for scalar models wi
21. espected during the bootstrap even if a range bootstrap file is used 12 Multifit When starting XMBF with the command line option m directory the program performs the mul tifit procedure and writes the results for each parameter into an individual file in directory The output files have names that are combinations of the XML input file name and the parameter names The multifit procedure is the following XMBF performs N successive fits where the nth fit uses just the nth data sample instead of the average over all data samples The covariance matrix stays fixed and is computed as usual using all data samples The multifit procedure is useful when the data samples themselves were obtained through a bootstrap procedure and a corresponding resampling of the fit results is wanted For Bayesian fitting it is recommended to set the option random_priors in the fit_settings node see Sec to true in order to get the approximately correct probability distribution for the fit parameters lf this is activated the priors for each fit will be drawn randomly from Gaussian distributions with the given prior widths and central values This option does not affect the multifit procedure for non Bayesian fits 13 Built in Models In the following those parts of the parameter constant and variable names that are specified by the user are typeset in typewriter font 13 1 Scalar two point models 13 1 1 multi exp model e functio
22. eter_name gt 39 definition exp E t texp E T t lt definition gt lt derivative gt lt derivative gt lt function_number gt 2 lt function_number gt lt parameter_name gt E lt parameter_name gt definition A_2 t exp E t T t exp E T t lt definition gt lt derivative gt lt derivatives gt lt fit_domain gt lt variable_name gt t lt variable_name gt lt range gt lt min gt 10 lt min gt lt max gt 54 lt max gt lt range gt lt fit_domain gt lt data_file gt lt file_type gt ASCII lt file_type gt lt file_name gt correlator dat lt file_name gt lt data_file gt lt parse_model gt this particular example actually reimplements the case of multi_exp_vec_BC_model with n_exp 1 and dim 2 Note that the derivatives node in parse_model is only required if the option num_diff_first_order in the fit_settings node see Sec is set to false 36
23. etor values constant values Le C TIS lt fit gt There has to be a root node called fit which contains up to five main nodes in arbitrary order e macros optional cf section 5 e combined model cf section 6 chi_sqr_extra_tern optional cf section 7 e fit settings cf section 12 e parameter values cf section 9 e constant values optional cf section 9 5 The macros node Here is an example macros macro lt name gt INITIAL dE START VAL lt name gt value 1 1 lt value gt lt macro gt lt macro gt lt name gt INITIAL_dE_PRIOR lt name gt lt value gt 1 lt value gt lt macro gt lt macro gt lt name gt INITIAL_dE_PRIOR_WIDTH lt name gt lt value gt 1 lt value gt lt macro gt lt macros gt The macros node contains a list of macros each of them with a unique name and a value Both are strings spaces and newlines will be removed For the example shown here appearences of INITIAL_dE_START_VAL in content nodes elsewhere in the XML document will be replaced by 1 1 etc 6 The combined_models node The combined_models node contains one or more individual models to be fitted simultaneously Each individual model can either be a built in model cf Sec or a completely user defined model cf Sec 14 An example for a combined models node with 5 built in models is shown below combined model multi alt exp exp
24. exp model e function s 29 For M gt 0 and M gt 0 f t T Aee e te E T t y Been n e F GF_1 dF_n t E dE_1 dE_n T n 0 N 1 n 0 N 1 n n 0 0 1 soe p te ElT t y Y Boem n e FotdFo1 dFom t EtdE 1 dEn T n 0 N 1 m 0 M 1 n m 0 0 aM je Aeo e t Eo T t 5 y Beon mi e F dF 1 dF_n t m 0 M 1 n 0 N 1 m n 0 0 ET Aoo te Eo T t x y Bun vh e Fo dFo1 dFo m t Tea m 0 M 1 m 0 M 1 m m 4 0 0 Note for M 0 the second and fourth row disappear for M 0 the third and fourth row disappear e variable s t T e parameter s Aee Bee n n E dEn F dF_n For M gt 0 also Aeo Beon m Eo dEo_m For M O also Aoe Boe m n Fo dFo m For M gt 0 and M 5 0 also Aoo Boom m e properties 30 13 9 4 Key n_exp_initial n_o_exp_initial n_exp_final n_o_exp_final A_name B_name E initial name dE initial name E final name dE final name t name T name content type N integer gt 1 M integer gt 0 N integer gt 1 M integer 0 A string B string E string dE string F string dF string t string T string threept_multi_alt_exp_expE_model e function same as threept multi alt exp model but with the following replacements dE n F dF n Eo dEo m Fo
25. ey content type C_name C string 13 5 Matrix two point models Matrix models are very different from vector models In matrix models it is assumed that the ampli tudes factor into an outer product of a vector with itself like A4 Aj where the A i are used as fit parameters In the following the functions are labelled by two indices i j The required storage order in the data files is such that the first index 7 runs slow and the second index 7 runs fast 13 5 1 multi exp mat model e function s for i 1 dim 1 j 1 dim 2 N 1 falt A i Aj e t E y Bni Bni e EtdE 1 4 tdE n t n l e variable s t parameter s A_i B n 3 for i 1 max dim_1 dim 2 E dE_n e properties Key content type n exp N integer gt 1 A_name A string B_name B string E name E string dE_name dE string t name t string dim 1 t dim 1 integer gt 1 dim 2 Jj l dim 2 integer gt 1 13 5 2 multi exp expE mat model e function s for i 1 dim 1 j 1 dim 2 N 1 fet A d Aj es t y Bn 1 B_n__j e e p pet ny n l e variable s parameter s properties same as multi exp mat model 22 13 5 3 multi alt exp mat model e function s for i 1 dim 1 j 1 dim 2 N 1 Fate Ai Aj z t d y Bni Bn__j cae n 1 M 1 Li ho Ao j x ta y Bo m i Bom j pois m 1 e variable s t e parameter s A i Bni for i 1 max dim 1
26. he data When starting XMBF with the command line option b directory the program performs the boot strap procedure and writes the results for each parameter into an individual file in directory The output files have names that are combinations of the XML input file name and the parameter names On multi core systems the bootstrap procedure can be parallelized using XMBF_mpi instead of XMBF see Sec 8 2 The number of bootstrap samples is specified in the fit settings node via bootstrap samples Each bootstrap sample is obtained by randomly choosing N out of the N data configurations with allowed repetitions XMBF will recompute and invert the data correlation matrix for every single bootstrap sample When the bootstrap is completed the bootstrap averages and error estimates based on sorting the results and taking the 68 central part of the distributions of the fit results are also printed to the standard output 14 By default the random numbers of configurations are generated by XMBF at run time just before the bootstrap Alternatively if the option use_bse_file in the fit_settings node is set to true the numbers are read from a text file specified in bse_file The format of a bootstrap ensemble file is as follows the number of bootstrap samples S followed by the number of configurations N followed by S N random integer numbers in the range 1 N Such files can also be generated by QMBF see the QMBF manual For Bayesian fitti
27. le is shown below Note entries with parameter names that are not needed for the models are allowed and will be simply be ignored This is very convenient if for example changing the number of exponentials in a fit Also note the tags prior and prior width for each parameter are only needed for Bayesian fits which are enabled using lt bayesian gt true lt bayesian gt in the fit settings node see Sec 12 parameter values parameter lt name gt Ei lt name gt lt start_value gt 0 66 lt start_value gt lt prior gt 0 6622 lt prior gt lt prior_width gt 0 04 lt prior_width gt lt parameter gt lt parameter gt lt name gt Eio lt name gt lt start_value gt 0 33 lt start_value gt 12 lt prior gt 0 3270 lt prior gt lt prior_width gt 0 3 lt prior_width gt lt parameter gt lt parameter gt lt name gt Ai__1 lt name gt lt start_value gt 0 054 lt start_value gt lt prior gt 0 0544017 lt prior gt lt prior_width gt 0 007 lt prior_width gt lt parameter gt lt parameter gt lt name gt Aio__1 lt name gt lt start_value gt 0 044 lt start_value gt lt prior gt 0 04416 lt prior gt lt prior_width gt 0 07 lt prior_width gt lt parameter gt lt parameter gt lt name gt Ai__2 lt name gt lt start_value gt 0 18 lt start_value gt lt prior gt 0 179835 lt prior gt lt prior_width gt 0 03 lt prior_width gt lt parameter gt lt parameter gt
28. ll be common to which fit models XMBF uses XML input files to specify the models fitting ranges etc The XML files are read such that for each node the order of the child nodes does not matter Comments are also allowed using the standard XML syntax for comments To allow the correct calculation of correlations the data files for each model must correspond to the same order of measurements 2 Compiling XMBF 2 1 Standard Double Precision Build Required libraries are e GNU Scientific Library version gt 1 13 e libxml 4 e Boost C libraries and their dependencies When installing these libraries using a package manager note that the de velopment packages are also needed these usually have dev or devel in the package name A Makefile is supplied with the source code the variables INCPATH and LIBS may require adjustment for the specific machine 2 2 Build with Quad Double Inverter It is possible to compile a version of XMBF that uses the libraries e MPACK Multiple precision arithmetic BLAS MBLAS and LAPACK MLAPACK e QD Quad Double package to invert the data correlation matrix in quad double precision 256 bits approx 64 digits This is useful to prevent round off errors when the data correlation matrix has a condition number larger than 1016 Note that most numerical operations in the quad double build of XMBF are still performed in standard double precision only the inversion or pseudo inversion of the data cor
29. lt name gt Aio__2 lt name gt lt start_value gt 0 16 lt start_value gt lt prior gt 0 16123 lt prior gt lt prior_width gt 0 2 lt prior_width gt lt parameter gt lt parameter gt lt name gt dEi_1 lt name gt lt start_value gt INITIAL_dE_START_VAL lt start_value gt lt prior gt INITIAL_dE_PRIOR lt prior gt lt prior_width gt INITIAL_dE_PRIOR_WIDTH lt prior_width gt lt parameter gt lt parameter gt lt name gt dEi_2 lt name gt lt start_value gt INITIAL_dE_START_VAL lt start_value gt lt prior gt INITIAL_dE_PRIOR lt prior gt lt prior_width gt INITIAL_dE_PRIOR_WIDTH lt prior_width gt lt parameter gt lt parameter gt lt name gt dEi_3 lt name gt lt start_value gt INITIAL_dE_START_VAL lt start_value gt lt prior gt INITIAL_dE_PRIOR lt prior gt lt prior_width gt INITIAL_dE_PRIOR_WIDTH lt prior_width gt lt parameter gt lt parameter_values gt Note that in the above example macros named INITIAL_dE_START_VAL etc are used as defined in the example shown in Sec Shown below is an example for the constant_values node lt constant_values gt lt constant gt 13 lt name gt L4 lt name gt lt value gt 64 lt value gt lt constant gt lt constant_values gt 10 More details on fit ranges Every model inside combined_models see Sec 6 must have one node called fit_domain for each variable of that model Every fit_domain node can con
30. n s N 1 f t js Et BE Bos e EtdE1 dEn t n 1 e variable s t e parameter s A B n E dE_n e properties 16 Key content type n_exp N integer gt 1 A_name A string B name B string E_name E string dE_name dE string t name t string 13 1 2 multi exp expE model e function s N 1 f t A e ti y Bn n 1 e variable s parameter s properties same as multi exp model 13 1 3 multi exp Asqr model e function s N 1 f t A2 e ty Y ea 1 TL e variable s parameter s properties same as multi exp model 13 1 4 multi exp Asqr expE model e function s N 1 F t A e ti y Bn PA n 1 e variable s parameter s properties same as multi exp model 13 1 5 multi alt exp model e function s N 1 f t S A e eL y Bn re nel M 1 Add Ao et um y Bam pr m 1 e variable s t 17 e parameter s A B n E dE n Ao Bo m Eo dEo m e properties Key content type n exp N integer gt 1 n o exp M integer gt 1 A_name A string B name B string E name E string dE_name dE string t name t string 13 1 6 multi alt exp expE model e function s N 1 ft A4 e ty y Bn Liu n l M 1 1 tAo t ue p Bom PE m 1 e variable s parameter s properties same as multi alt exp model 13 1 7 multi alt exp Asgr model e function s N 1 f t a e ty SY Bn
31. nal property n_parameters_dof is analoguous to QMBF s setting Number of parameters to be subtracted from d o f If this property is not present in the XML file the default values are 0 for Bayesian fits or the total number of parameters in the fit for non Bayesian fits The property inversion_method specifies the method used in the calculation of the inverse of the data correlation matrix Allowed values are e LU for full inversion e svd_fixed_cut remove given number of smallest eigenvalues e svd_ratio_cut remove eigenvalues that are smaller than some given fraction of the largest eigenvalue e svd_absolute_cut remove eigenvalues smaller than some given value e diagonal keep only diagonal elements in data correlation matrix One very important setting is bootstrap_normalization If set to false the data correlation matrix will be normalized with the usual factor of 1 NN 1 where N is the number of data sets If set to true the data correlation matrix will instead be normalized with the factor 1 N 1 This is needed to get the correct error estimates for fit parameters for the case that the original data file was created using bootstrap over data sets e g in the calculation of ratios of three point and two point functions For more details on the setting concerning bootstrap see Sec 9 The parameter values and constant values nodes An excerpt of the parameter values node from an example XML fi
32. name B string E name E string dE name dE string t name t string dim 1 i dim 1 integer gt 1 dim 2 j l dim 2 integer gt 1 13 6 2 multi exp expE mat II model e function s for i 1 dim 1 j 1 dim 2 N 1 file 24 4 A Y Bn i Bn j ette n 0 e variable s parameter s properties same as multi_exp_mat_II_model 13 7 Triangular matrix two point models gems These models are like matrix models with dim 1 dim 2 but the triangular models consist of only the functions with j gt i This is intended for matrix fits with exactly symmetric i e symmetrized data 13 7 1 multi exp mat upper model e function s for i 1 dim j i dim total number of functions dim dim 1 2 N 1 fat A Aj e Et de y Bn_iBn_j e E dE 1 dE n t n 1 e variable s t e parameter s A i B n i for i 1 dim E dE_n e properties 24 Key content type n_exp N integer gt 1 A_name A string B name B string E name E string dE name dE string t name t string dim 1 dim j indim integer gt I 13 7 2 multi exp expE mat upper model e function s for i 1 dim j i dim total number of functions dim dim 1 2 N 1 fult A i Aj grum t b Bni B n j e e spem n 1 e variable s parameter s properties same as multi exp mat upper model 13 7 8 multi exp mat II upper model Note some parameters are redundant see
33. ng it is recommended to set the option random priors to true in order to get the approximately correct probability distribution If this is activated in addition to randomly choosing data set ensembles the priors will be choosen randomly from Gaussian distributions with the given prior widths This option does not affect the bootstrap for non Bayesian fits Finally by setting the optional property restrict_bootstrap_range to true the bootstrap pro cedure can be restricted to a certain range of the samples specified using bootstrap_range_min and bootstrap_range_max When a restricted range in the input XML file is specified only only the appropriate part of the bse file will be used Note that the option restrict_bootstrap_range is fully compatible with random_priors if bootstrap_range_min is greater than 1 the correct amount of random numbers is skipped so that also the sequence of random numbers for the priors remains unchanged 11 2 Resampling both the data and the fit ranges XMBF can performed a generalized bootstrap procedure such that at the same time as resampling the data configurations and parameter priors if activated the fit ranges for the variables are also resampled This allows the incorporation of systematic errors due to the choices of the fitting ranges into the bootstrap distribution Every range node can have an optional entry called range_bootstrap_file which contains the name of a file with the ranges for bootstrap
34. r_extra_term gt lt function gt sqr a b sqr sigma_a_b exp sqr c 1 0 sqr sigma_c lt function gt lt constant gt lt name gt sigma_a_b lt name gt lt value gt 0 1 lt value gt lt constant gt lt constant gt lt name gt sigma_c lt name gt lt value gt 0 01 lt value gt lt constant gt lt num_diff_step gt 1e 8 lt num_diff_step gt lt chi_sqr_extra_term gt In general the function can be constructed using the elementary operations 10 exp log sin cos tan sinh cosh tanh arcsin arccos arctan sqr sqrt alt The function may contain any of the fit parameters resulting from the models in combined model It may also contain the constants defined inside chi sqr extra term as well as numerical literal values The derivatives of the function with respect to the fit parameters are calculated numerically using the step size defined via num diff step 8 The fit settings node fit settings restrict data range false lt restrict data range data range min 1 lt data range min data range max 1000 data range max lt chi sgr extra term enabled false lt chi sqr extra term enabled lt bayesian gt true lt bayesian gt lt random_priors gt true lt random_priors gt lt num_diff_first_order gt false lt num_diff_first_order gt lt second_deriv_covariance gt false lt second_deriv_covarianc
35. relation matrix and some related operations are performed in quad double precision To compile this higher precision version install MPACK and QD and then compile XMBF using the makefile Makefile mpack qd after adjusting the variables INCPATH and LIBS This generates an executable called XMBF_mpack_qd When doing a fit with XMBF mpack qd if the XML input file specifies the inversion method LU see Sec 2 then MPACK s functions Rgetrf and Rgetri are used to fully invert the data correlation 3 matrix If the XML input file instead specifies svd_fixed_cut svd ratio cut or svd absolute cut see Sec 12 the MPACK function Rsyev is used to compute the spectral decomposition of the data correlation matrix and then the pseudo inverse removing the contributions from the smallest eigenvalues as determined by the user Note that with version 0 6 7 of MPACK the function Rsyev may fail for large matrices dimension more than about 500 for an unknown reason in which case XMBF will abort 2 3 Build for parallel bootstrap with MPI It is possible to build a version of XMBF that performs bootstrap see Sec in parallel using MPI To compile this version use make f Makefile_mpi after adjusting this Makefile for your machine if necessary This generates an MPI executable called XMBF_mpi Note that this executable has restricted functionality bootstrap only 2 4 Additional programs The source of XMBF includes some additional program
36. s for manipulating the XML files These programs can be found in subdirectories and must be compiled separately The most important tool is called MBF_to_XMBF and allows to convert mbf session files generated by QMBF into XML input files for use with XMBF The usage is as follows MBF_to_XMBF mbf_file xml_file 3 Using XMBF XMBF requires an XML input file containing all the settings e g the fit models start values for the parameters the locations of the data files The usage is as follows XMBF options inputfile options 0 output xml write fit results to output xml c cov dat write covariance matrix to cov dat r res dat write results to res dat re res err dat write results with errors to res err dat p directory plot data and fit functions write output files to directory b directory perform bootstrap write output files to directory m directory perform multifit write output files to directory v level verbose level 0 1 2 XMBF always reads the input file and performs a fit the results are printed to stdout When the option o outputfile is given the fit results are additionally written to an output file in XML format When the options c cov dat is specified the elements of the parameter covariance matrix are written to the specified file similarly r res dat writes the central values of the fitted parameters re res err dat writes the central values and errors With the option p directory the averaged
37. t file_type gt binary lt file_type gt c data file lt threept multi alt exp expE model lt combined model Every model has the nodes fit domain see Sec 10 for more details data_file and plot_domain the latter is only needed when plotting The allowed values for the property file_type are ASCII and binary For the other properties see the descriptions of the individual models in Secs and For the built in models he strings entered in fields such as dE_name are used as templates for the parameter names XMBF will decorate the names with additional indices as appropriate see Sec 13 for more details Fit parameters and constants with the same names will be shared between individual models i e they are forced to have the same value globally Note that variable names are only used individually for each model and only serve to specify the individual fitting ranges It does not matter whether two models have a common variable name or not 7 The chi_sqr_extra_term node The optional chi_sqr_extra_term node can be used to add an arbitrary function of the fit parameters to x Note that it must be enabled separately by putting the line lt chi_sqr_extra_term_enabled gt true lt chi_sqr_extra_term_enabled gt inthe fit settings node Here is an example which forces two fit parameters a and b to have similar values within a width sigma_a_b and puts a non gaussian constraint on another parameter c lt chi_sq
38. tain an arbitrary number of range nodes where every range node specifies a condition on the value of the variable required min max see Sec optional step see Sec 10 2 Every fit domain is the union rather than the intersection of the individual ranges That is a fit point is included in the fit if and only if the value of every variable at that point satisfies the condition of at least one of its range nodes 10 1 Lower and upper bounds Every range node must have two entries called min and max These entries can contain numerical values integer or floating point but also functions of other variables and constants for example in the model threept multi alt exp expE model shown in Sec 6 the range for the variable t is lt min gt 1 lt min gt and lt max gt T 2 lt max gt where T is the other variable The function strings are parsed by XMBE the allowed operations are the same as given in Sec If no step see Sec is specified in the range node a value x of a variable is considered inside the range if min lt x lt max 10 2 Step sizes Every range node can contain an optional entry called step which must contain a step size A which is a positive numerical value integer or floating point In this case a value x of a variable is considered inside the range if in addition to statisfying min lt x lt max the value satisfies as r min n A where n is an integer 11 More details on bootstrap 11 1 Resampling t
39. th oscillating contributions fi t fi t C_i for vector models and filt ee X xD fag for vector models with oscillating contributions The quantities C Co C i Co_i as appropriate are additional fit parameters These models are called e multi exp const model e multi exp expE const model 20 multi_exp_Asqr_const_model multi_exp_Asqr_expE_const_model multi_alt_exp_const_model multi_alt_exp_expE_const_model multi_alt_exp_Asqr_const_model multi_alt_exp_Asqr_expE_const_model multi_exp_vec_const_model multi_exp_expE_vec_const_model multi_exp_Asqr_vec_const_model multi_exp_Asqr_expE_vec_const_model multi_alt_exp_vec_const_model multi_alt_exp_expE_vec_const_model multi_alt_exp_Asqr_vec_const_model multi_alt_exp_Asqr_expE_vec_const_model multi_exp_BC_const_model multi_exp_expE_BC_const_model multi_exp_Asqr_BC_const_model multi_exp_Asqr_expE_BC_const_model multi_alt_exp_BC_const_model multi_alt_exp_expE_BC_const_model multi_alt_exp_Asqr_BC_const_model multi_alt_exp_Asqr_expE_BC_const_model multi_exp_vec_BC_const_model multi_exp_expE_vec_BC_const_model multi_exp_Asqr_vec_BC_const_model multi_exp_Asqr_expE_vec_BC_const_model multi_alt_exp_vec_BC_const_model multi_alt_exp_expE_vec_BC_const_model multi_alt_exp_Asqr_vec_BC_const_model 21 e multi_alt_exp_Asqr_expE_vec_BC_const_model and require one further key in addition to the keys of the underlying models the name template for the new parameter s K
Download Pdf Manuals
Related Search