User guide
The central object of thdmTools is the ParamPoint class. For each parameter point that one wishes to analyze, an instance of this class has to be created, giving the values of the free parameters as input.
Different theoretical and experimental constraints can be applied using the functions of the ParamPoint class.
ParamPoint¶
The base class for a 2HDM parameter point.
The arguments are the dictionary dc containing the values of the free parameter and the optional boolean flag debug. If this flag is set to True, then additional checks will be performed in several parts of the code.A typical generation of an instance of the ParamPoint class looks like:
from thdmtools.parampoint import Parampoint
dc = {
'type': 2,
'tb': 2.0,
'alpha': 1.27,
'mHh': 600.0,
'mHl': 125.09,
'mA': 700.0,
'mHp': 800.0,
'm12sq': 196000.0}
pt = ParamPoint(dc, debug=True)
check_vacuum_stability¶
Checks if the tree-level bounded-from-below conditions are satisfied by the scalar potential. An optional argument global_min can be set to True in order to also check if the EW minimum is the global minimum of the potential.
The function returns True if all conditions are satisfied and False otherwise.check_perturbative_unitarity¶
Checks if the tree-level perturbative unitarity conditions are satisfied. The optional argument pertunilimit is a float number thatn can be used to set the upper limit on the eigenvalues of the \(2 \times 2\) scalar scattering matrix in the high-energy limit. The upper limit is given by pertunilimit times 16\(\pi\). By default, pertunilimit is set to 0.5, which corresponds to an upper limit of 8\(\pi\).
The function returns True if all conditions are satisfied and False otherwise.check_perturbative_unitarity_nlo¶
This function works in the same way as the function check_perturbative_unitarity, but uses the next-to-leading order conditions from arXiv:1609.01290.
The function returns True if all conditions are satisfied and False otherwise.calculate_branching_ratios¶
This function can be used to compute the branching ratios of the Higgs bosons. Depending on the arguments, this function internally calls the AnyHDecay and HiggsTools interfaces.
This function is automatically called internally if the branching ratios are required in other functions, for instance for HiggsBounds and HiggsSignals.
If the optional argument effcpl_mode is set to False, then all branching ratios are calculated with AnyHDecay. If this argument is set to True, then the partial widths for the decays of the Higgs boson at 125 GeV into SM particles are computed using the effective-coupling input format of HiggsTools, and only the widths for the decays into BSM particles are computed with AnyHDecay.
The second optional argument hdecay_h125yy determines the way in which the width for the decay of the Higgs boson at 125 GeV into two photons is calculated. This flag is only relevant if effcpl_mode=True. If hdecay_h125yy is set to True, then the partial width for the diphoton decay is computed using AnyHDecay, thus including the contributions from the charged-scalar loops. If hdecay_h125yy is set to False, the partial width for the diphoton decay is computed using the HiggsTools effective-coupling input format, where the contributions from the charged-scalar loops are not included.
The values of the branching ratios are stored in the following dictonaries: The total widths of the scalars are stored in the dictionary:check_flavour_constraints¶
This function uses the interface to SuperIso to compute various flavour-physics observables. Two of the most important of these observables are \(\mathrm{BR} ( b \to s \gamma)\) and \(\mathrm{BR} ( B_s \to \mu^+ \mu^-)\). For these two observables, the function also checks whether the predicted values (according to SuperIso) are within the experimentally measured values within two standard deviations. In this case the function returns True. If either of the predicted values is not in agreement with the experimental data, the function returns False.
By default, thdmTools uses for the experimental
central values and the \(1\sigma\) uncertainties
the HFLAV values from 2022, as they can be
found under
this link
in Table 55 and Table 44.
These values are stored in the
thdmtools.constants module.
The user can provide different experimentally
allowed ranges by setting the optional arguments
b2sgamrange and bs2mumurange,
which each should be lists with two elements,
where the element 0 should contain the lower
limit and the element 1 should contain the
upper limit of the experimental allowed range,
respectively.
check_ewpo_constraints¶
This function uses the interface to THDM_EWPOS to compute the following three electroweak precision observables: the \(W\)-boson mass \(M_W\), the sinus squared of the leptonic effective weak mixing angle \(\sin^2 \Theta_{\rm eff}\), and the total width of the \(Z\) boson \(\Gamma_Z\). For these observables the function also checks whether the predicted values are within the experimentally measured values within two standard deviations. In this case the function returns True. If either of the predicted values is not in agreement with the experimental data, the function returns False.
pt.check_ewpo_constraints(
NSflag=3,
contflag=2,
loflag=2,
MWexp=const.MW_comb_wo_cdf,
delMWexp=const.MW_comb_wo_cdf_unc,
GamZexp=const.Gamma_tot_Z_pdg,
delGamZexp=const.Gamma_tot_Z_pdg_unc,
s2wexp=const.sin2w_exp,
dels2wexp=const.sin2w_exp_unc)
thdmtools.constants module.
For \(M_W\), the default value is the combination
excluding the 2022 CDF result taken
from
arXv:2308.09417.
For \(\Gamma_Z\) the default value is the
current PDG average value, and for
\(\sin^2 \Theta_{\rm eff}\) the default value
is the average value that is given
in Figure 7.6 of
arXiv:0509008.
The user can also provide different experimental
values via
optional arguments. For instance, one can
provide the experimental central value and
the one standard-deviation uncertainty
by setting the optional arguments
MWexp and delMWexp, respectively
The function has three more optional arguments NSflag, contflag and loflag that determine the radiative corrections included in the theory predictions computed with THDM_EWPOS. For their precise definition, we refer to the THDM_EWPOS manual. The default values are 3, 2 and 2, respectively.
Caution: The two-loop results of THDM_EWPOS have not been thoroughly tested by us. While the thdmTools interface to THDM_EWPOS allows for the computation of \(M_W\) at two-loop level, we adivse proceeding with caution when using this feature.
check_ewpo_fit¶
This function checks whether the electroweak precision observables in terms of the oblique parameters are predicted to be in agreement with the experimental data from electroweak fits. For the theory predictions, the functions computes the oblique parameters \(S\), \(T\) and \(U\) at the one-loop level based on generic expressions from arXiv:0802.4353. The function returns True if the oblique parameters lie within the experimentally allowed range at \(2\sigma\) level based on the fit results from Gfitter, and it returns False otherwise.
The function has the optional argument mode. By default, this argument is set to "STU", in which case the function performs a 3-dimensional \(\chi^2\) test taking into account \(S\), \(T\) and \(U\). The second possible option is to set mode to "ST", in which case \(U\) is neglected and a 2-dimensional \(\chi^2\) fit is performed taking into account \(S\) and \(T\). Typically, in the 2HDM the option "ST" yields slightly stronger constraints since the modifications to the \(T\) parameter are the dominant effect.check_collider_constraints¶
This function calls the HiggsTools interface in order to check against collider constraints. Both the HiggsBounds and the HiggsSignals checks are performed.
pt.check_collider_constraints(
delta_chisq_hs=6.18,
effcpl_mode=False,
hdecay_h125yy=True,
hbdata_path=None,
hsdata_path=None)
The optional arguments can be set to specify the following:
The arguments effcpl_mode and
hdecay_h125yy are transferred
to the function calculate_branching_ratios,
see the description here
for details.
Note that the function calculate_branching_ratios
is only called when calling this function
if it has not been called already before.
Hence, if the branching ratios have already been
calculated, the arguments effcpl_mode and
hdecay_h125yy are not used.
The argument delta_chisq_hs is the
maximal \(\Delta \chi^2\) value considered
to be allowed in the HiggsSignals \(\chi^2\) fit,
where the delta_chisq_hs values are
defined with respect to the SM predictions.
By default, this argument is set to 6.18.
In a 2-dimensional \(\chi^2\) fit this limit
will give rise to exclusions at the \(2\sigma\)
confidence level. One can also access the
HiggsSignals
\(\chi^2\) value itself with pt.chisq.
Using this value the user can define exclusion
limits that are independent of the SM.
By default, this function uses the data repositories
of HiggsBounds and HiggsSignals that are downloaded
during the installation and stored in the
external directory. If different data repositories
shall be used, one can provide the paths to these
repositories by setting the
arguments hbdata_path and
hsdata_path.
In addition to the two return values of this function, many more details about the HiggsBounds results are stored in the following attributes:
The expected and observed \(r\)-ratios and the most sensitive search channel for each Higgs boson are stored in the objects:
pt.expratiohb_Hl
pt.obsratiohb_Hl
pt.channelhb_Hl
pt.expratiohb_Hh
pt.obsratiohb_Hh
pt.channelhb_Hh
pt.expratiohb_A
pt.obsratiohb_A
pt.channelhb_A
pt.expratiohb_Hp
pt.obsratiohb_Hp
pt.channelhb_Hp
bounds object created by HiggsTools
containing the full information including
all searches (see the
HiggsTools documentation
for details
) is stored in the object:
The effective coupling coefficients that
are used as input in HiggsTools to compute
the cross sections are stored in the dictionary:
Various LHC cross sections for all Higgs bosons
are stored in the dictionary: