applications

This module provides functions that implements user-friendly interface to the functions and methods in other modules. It acts like a synthesis of all the other modules of their own physical purposes. In general, users only need to import functions in this module to implement their physical analysis instead of going into every modules. There are some example files where you can figure out how it is used.

cal_hesse_correct(fcn, params={}, corr_params={}, force_pos=True)

cal_hesse_error(fcn, params={}, check_posi_def=True, force_pos=True, save_npy=True)

This function calculates the errors of all trainable variables. The errors are given by the square root of the diagonal of the inverse Hessian matrix.

Parameters:

model – Model.

Return hesse_error:

List of errors.

Return inv_he:

The inverse Hessian matrix.

cal_significance(nll1, nll2, ndf)

This function calculates the statistical significance.

Parameters:

• nll1 – Float. NLL of the first PDF.

• nll2 – Float. NLL of the second PDF.

• ndf – The difference of the degrees of freedom of the two PDF.

Returns:

Float. The statistical significance

compare_result(value1, value2, error1, error2=None, figname=None, yrange=None, periodic_vars=None)

Compare two groups of fitting results. If only one error is provided, the figure is \(\frac{\mu_1-\mu_2}{\sigma_1}\); if both errors are provided, the figure is \(\frac{\mu_1-\mu_2}{\sqrt{\sigma_1^2+\sigma_2^2}}\).

Parameters:

• value1 – Dictionary

• value2 – Dictionary

• error1 – Dictionary

• error2 – Dictionary. By default it’s None.

• figname – String. The output file

• yrange – Float. If it’s not given, there is no y-axis limit in the figure.

• periodic_vars – List of strings. The periodic variables.

Returns:

Dictionary of quality figure of each variable.

corr_coef_matrix(err_mtx)

This function obtains correlation coefficients matrix of all trainable variables from *.npy file.

Parameters:

err_mtx – Array or string (name of the npy file).

Returns:

Numpy 2-d array. The correlation coefficient matrix.

fit(Use='scipy', **kwargs)

Fit the amplitude model using scipy, iminuit or pymultinest. It imports fit_scipy, fit_minuit, fit_multinest from module tf_pwa.fit.

Parameters:

• Use – String. If it’s "scipy", it will call fit_scipy; if it’s "minuit", it will call fit_minuit; if it’s "multinest", it will call fit_multinest.

• kwargs – The arguments will be passed to the three functions above.

For fit_scipy

Parameters:

• fcn – FCN object to be minimized.

• method – String. Options in scipy.optimize. For now, it implements interface to such as “BFGS”, “L-BFGS-B”, “basinhopping”.

• bounds_dict – Dictionary of boundary constrain to variables.

• kwargs – Other arguments passed on to scipy.optimize functions.

Returns:

FitResult object, List of NLLs, List of point arrays.

For fit_minuit

Parameters:

• fcn – FCN object to be minimized.

• bounds_dict – Dictionary of boundary constrain to variables.

• hesse – Boolean. Whether to call hesse() after migrad(). It’s True by default.

• minos – Boolean. Whether to call minos() after hesse(). It’s False by default.

Returns:

Minuit object

For fit_multinest (WIP)

Parameters:

fcn – FCN object to be minimized.

fit_fractions(amp, mcdata, inv_he=None, params=None, batch=25000, res=None, method='old')

This function calculate fit fractions of the resonances as well as their coherent pairs. It imports cal_fitfractions and cal_fitfractions_no_grad from module tf_pwa.fitfractions.

\[FF_{i} = \frac{\int |A_i|^2 d\Omega }{ \int |\sum_{i}A_i|^2 d\Omega }\approx \frac{\sum |A_i|^2 }{\sum|\sum_{i} A_{i}|^2}\]

gradients???:

\[FF_{i,j} = \frac{\int 2Re(A_i A_j*) d\Omega }{ \int |\sum_{i}A_i|^2 d\Omega } = \frac{\int |A_i +A_j|^2 d\Omega }{ \int |\sum_{i}A_i|^2 d\Omega } - FF_{i} - FF_{j}\]

hessians:

\[\frac{\partial }{\partial \theta_i }\frac{f(\theta_i)}{g(\theta_i)} = \frac{\partial f(\theta_i)}{\partial \theta_i} \frac{1}{g(\theta_i)} - \frac{\partial g(\theta_i)}{\partial \theta_i} \frac{f(\theta_i)}{g^2(\theta_i)}\]

Parameters:

• amp – Amplitude object.

• mcdata – MCdata array.

• inv_he – The inverse of Hessian matrix. If it’s not given, the errors will not be calculated.

Return frac:

Dictionary of fit fractions for each resonance.

Return err_frac:

Dictionary of their errors. If inv_he is None, it will be a dictionary of None.

force_pos_def(h)

from pricession lost hessian matrix eigen value is small

dot(H, v[:,i] = e[i] v[:,i] dot(H, v)[:,i] = e[i] v[:,i] dot(inv(v), dot(H, v)) = diag(e) H = dot(v, dot(diag(e), inv(v))

force_pos_def_minuit2(inv_he)

force positive defined of error matrix

from minuit2 https://github.com/root-project/root/blob/master/math/minuit2/sec/MnPosDef.cxx

gen_data(amp, Ndata, mcfile, Nbg=0, wbg=0, Poisson_fluc=False, bgfile=None, genfile=None, particles=None)

This function is used to generate toy data according to an amplitude model.

Parameters:

• amp – AmplitudeModel???

• particles – List of final particles

• Ndata – Integer. Number of data

• mcfile – String. The MC sample file used to generate signal data.

• Nbg – Integer. Number of background. By default it’s 0.

• wbg – Float. Weight of background. By default it’s 0.

• Poisson_fluc – Boolean. If it’s True, The number of data will be decided by a Poisson distribution around the given value.

• bgfile – String. The background sample file used to generate a certain number of background data.

• genfile – String. The file to store the generated toy.

Returns:

tensorflow.Tensor. The generated toy data.

gen_mc(mother, daughters, number, outfile=None)

This function generates phase-space MC data (without considering the effect of detector performance). It imports PhaseSpaceGenerator from module tf_pwa.phasespace.

Parameters:

• mother – Float. The invariant mass of the mother particle.

• daughters – List of float. The invariant masses of the daughter particles.

• number – Integer. The number of MC data generated.

• outfile – String. The file to store the generated MC.

Returns:

Numpy array. The generated MC data.

likelihood_profile(m, var_names, bins=20, minos=True)

Calculate the likelihood profile for a variable.

Parameters:

• m – Minuit object

• var_names – Either a string or a list of strings

• bins – Integer

• minos – Boolean. If it’s False, the function will call Minuit.profile() to derive the 1-d scan of var_names; if it’s True, the function will call Minuit.mnprofile() to derive the likelihood profile, which is much more time-consuming.

Returns:

Dictionary indexed by var_names. It contains the return of either Minuit.mnprofile() or Minuit.profile().

num_hess_inv_3point(fcn, params={}, _epsilon=0.0005)

This function calculates the errors of all trainable variables. The errors are given by the square root of the diagonal of the inverse Hessian matrix.

Parameters:

model – Model.

Return hesse_error:

List of errors.

Return inv_he:

The inverse Hessian matrix.

plot_pull(data, name, nbins=20, norm=False, value=None, error=None)

This function is used to plot the pull for a data sample.

Parameters:

• data – List

• name – String. Name of the sample

• nbins – Integer. Number of bins in the histogram

• norm – Boolean. Whether to normalize the histogram

• value – Float. Mean value in normalization

• error – Float or list. Sigma value(s) in normalization

Returns:

The fitted mu, sigma, as well as their errors