Das ist der HAMMER: consistent new physics interpretations of semileptonic decays

Abstract

Precise measurements of $b\rightarrow c\tau \bar{\nu }$ decays require large resource-intensive Monte Carlo (MC) samples, which incorporate detailed simulations of detector responses and physics backgrounds. Extracted parameters may be highly sensitive to the underlying theoretical models used in the MC generation. Because new physics (NP) can alter decay distributions and acceptances, the standard practice of fitting NP Wilson coefficients to SM-based measurements of the $R(D^{(*)})$ ratios can be biased. The newly developed Hammer software tool enables efficient reweighting of MC samples to arbitrary NP scenarios or to any hadronic matrix elements. We demonstrate how Hammer allows avoidance of biases through self-consistent fits directly to the NP Wilson coefficients. We also present example analyses that demonstrate the sizeable biases that can otherwise occur from naive NP interpretations of SM-based measurements. The Hammer library is presently interfaced with several existing experimental analysis frameworks and we provide an overview of its structure.

1 Introduction

Precision analyses of semileptonic b-hadron decays typically rely on detailed numerical Monte Carlo (MC) simulations of detector responses and acceptances. Combined with the underlying theoretical models, these simulations provide MC templates that may be used in fits, to translate experimental yields into theoretically well-defined parameters. This translation though can become sensitive to the template and its underlying theoretical model, introducing biases whenever there is a mismatch between the theoretical assumptions used to measure a parameter and subsequent theoretical interpretations of the data.

Such biases are known to arise in the analyses of semileptonic decays of b hadrons, in particular, for the measurements of the CKM element $|V_{cb}|$, and in the ratio of semitauonic vs. semileptonic decays to light leptons, (see e.g. Refs. [1, 2] and Ref. [3], respectively),

$$\begin{aligned} R(H_c) = \frac{\varGamma (H_b\rightarrow H_c\tau \bar{\nu })}{\varGamma (H_b\rightarrow H_c l\bar{\nu })}\,, \qquad l = \mu , \,e\,, \end{aligned}$$

(1)

where $H_{b,c}$ denote b- and c-flavor hadrons. To avoid this, the size of these biases need to be either carefully controlled when experiments quote their results by reversing detector effects, or they can be avoided by using dedicated MC samples for each theoretical model the measurement is confronted with. In this paper we present the newly developed tool, Hammer (Helicity Amplitude Module for Matrix Element Reweighting), designed expressly for the latter purpose.

Semitauonic b hadron decays have long been known to be sensitive to new physics [4,5,6,7,8,9,10], and were first constrained at LEP [11]. At present, the measurements of the $R(D^{(*)})$ ratios show about a $3\sigma$ tension with SM predictions, when the D and $D^*$ modes are combined [12]. In the future, much more precise measurements of semitauonic decays are expected, not only for the $B\rightarrow D^{(*)}\tau \bar{\nu }$ channels, but also for the not yet studied decay modes, $\varLambda _b\rightarrow \varLambda _c\tau \bar{\nu }$, $B_s\rightarrow D_s^{(*)}\tau \bar{\nu }$, as well as involving excited charm hadrons in the final state.

All existing measurements of $R(D^{(*)})$ rely heavily on large MC simulations to optimize selections, provide fit templates in discriminating kinematic observables, and to model resolution effects and acceptances. Both the $\tau$ and the charm hadrons have short lifetimes and decay near the interaction point and measurements rely on reconstruction of the ensuing decay cascades. To reconstruct the decay products, often complex phase space cuts and detector efficiency dependencies come into play, and the measurement of the full decay kinematics is impossible due to the presence of multiple neutrinos. In addition, depending on the final state, a significant downfeed with similar experimental signatures from misreconstructed excited charm hadron states can be present. Isolation of semitauonic decays from other background processes and the light-lepton final states, then requires precise predictions for the kinematics of the signal semitauonic decay.¹ Often the limited size of the available simulated samples, required to account for all these effects, constitutes a dominant uncertainty of the measurements, see e.g. [1, 2, 13].

In the literature on the $R(D^{(*)})$ anomaly, it has become standard practice to reinterpret the experimental values of $R(D^{(*)})$ in terms of NP Wilson coefficients, even though all current ratio measurements were determined assuming the SM nature of semitauonic decays. However, NP couplings generically alter decay distributions and acceptances. Therefore, they modify the signal and possibly background MC templates used in the extraction, and thus affect the measured values of $R(D^{(*)})$. This may introduce biases in NP interpretations: preferred regions and best-fit points for the Wilson coefficients can be incorrect; an instructive example of this is provided in Sec 2.3.

Consistent interpretations of the data with NP incorporated requires dedicated MC samples, ideally for each NP coupling value considered, which would permit directly fitting for the NP Wilson coefficients. This approach is sometimes referred to as ‘forward-folding’, and is naively a computationally prohibitively expensive endeavour. Such a program is further complicated because none of the MC generators current used by the experiments incorporate generic NP effects, nor do they include state-of-the-art treatments of hadronic matrix elements.

In this paper we present a new software tool, Hammer, that provides a solution to these problems: A fast and efficient means to reweight large MC samples to any desired NP, or to any description of the hadronic matrix elements. Hammer makes use of efficient amplitude-level and tensorial calculation strategies, and is designed to interface with existing experimental analysis frameworks, providing detailed control over which NP or hadronic descriptions should be considered. The desired reweighting can be implemented either in the event weights or in histograms of experimentally reconstructed quantities (both further discussed in Sect. 3). The only required input are the event-level truth-four-momenta of existing MC samples. Either the event weights and/or histogram predictions may be used, e.g., to generate likelihood functions for experimental fits. Some of the main ideas of Hammer were previously outlined in Refs. [14, 15].

In Sect. 2 we demonstrate the capabilities of Hammer by performing binned likelihood fits on mock measured and simulated data sets, that are created using the Hammer library, and corrected using an approximate detector response. In Sect. 3 a brief overview of the Hammer library and its capabilities are given. Section 4 provides a summary of our findings. Finally, Appendix A provides a detailed overview of the Hammer application programming interface.

2 New physics analyses

We consider two different analysis scenarios:

• 1. In order to explore what biases may arise in phenomenological studies if NP is present in Nature, we perform an illustrative $R(D^{(*)})$ toy measurement. This involves carrying out SM fits to mockups of measured data sets, that are generated for several different NP models. The recovered $R(D^{(*)})$ values are then compared to their actual NP values.

• 2. To demonstrate using a forward-folded analysis to assess NP effects without biases, we carry out fits to (combinations of) NP Wilson coefficients themselves, with either the SM or other NP present in the mock measured data sets.

The setting of these analyses is a B-factory-type environment. We focus on leptonic $\tau$ decays, but the procedures and results in this work are equally adaptable to the LHCb environment, and other $\tau$ decay modes or observables. In our example we focus on kinematic observables important for the separation of signal from background and normalization modes. Fits using angular information may also be implemented, see e.g. Refs. [16, 17] for an example.

We emphasize that the derived sensitivities shown below are not intended to illustrate projections for actual experimental sensitivities per se. Such studies are better carried out by the experiments themselves.

2.1 MC sample

The input Monte Carlo sample used for our demonstration comprises four distinct sets of $10^5$ events: one for each of the two signal cascades $B \rightarrow D (\tau \rightarrow e\nu \nu )\nu$, $B \rightarrow (D^* \rightarrow D\pi ) (\tau \rightarrow e\nu \nu ) \nu$ and for the two background processes, $B \rightarrow D e\nu$ and $B \rightarrow (D^* \rightarrow D\pi ) e\nu$. These are generated with EvtGen R01-07-00 [18], using the Belle II beam energies of 7 GeV and 4 GeV. The second B meson decay, often used for identifying or ‘tagging’ the $B\bar{B}$ event and constraining its kinematic properties, are not included in the current analysis for simplicity, but can be incorporated in a Hammer analysis straightforwardly.

In each cascade, the $b \rightarrow c l \nu$ decay is generated equidistributed in phase space (“pure phase space”), instead of using SM distributions. This reduces the statistical uncertainties that can otherwise arise from reweighting regions of phase space that are undersampled in the SM to NP scenarios in which they are not.²

2.2 Reweighting and fitting analysis

Hammer is used to reweight the MC samples into two-dimensional ‘NP generalized’ histograms (see Sect. 3), with respect to the reconstructed observables $| \mathbf {p}^*_{\ell }|$ and $m^2_{\text {miss}}$, the light lepton momentum in the B rest frame and the total missing invariant mass of all neutrinos, respectively. Both variables are well-suited for separating signal from background decays involving only light leptons. In the cascade process of the leptonic $\tau$ decay in $B \rightarrow D^{(*)} \tau \nu$, the signal lepton carries less momentum than the lepton from prompt $B \rightarrow D^{(*)} \ell \nu$ decays. Similarly, the missing invariant mass of $B \rightarrow D^{(*)} \ell \nu$ decays peaks strongly near $m_\nu ^2 \simeq 0$, in contrast to $B \rightarrow D^{(*)} \tau \nu$ in which the multiple neutrinos in the final state permit large values of $m^2_{\text {miss}}$.

The $B \rightarrow D^{(*)}$ processes are reweighted to the BLPR form factor parametrization [19], which includes predictions for NP hadronic matrix elements using HQET [20,21,22,23] at $\mathcal {O}(1/m_{c,b},\, \alpha _s)$.

Charged particles are required to fall in the Belle II angular acceptance of $20^\circ$ and $150^\circ$, and leptons are required to have a minimum kinetic energy of 300 MeV in the laboratory frame. An additional event weight is included to account for the slow pion reconstruction efficiencies from the $D^* \rightarrow D\pi$ decay, based on an approximate fit to the pion reconstruction efficiency curve from BaBar data [1, 24]. The analysis assumes that the second tagging B meson decay was reconstructed in hadronic modes, such that its four-momentum, $p_{B_\mathrm{tag}}$, is accessible. In conjunction with the known beam four-momentum $p_{e^+ \, e^-}$, the missing invariant mass can then be reconstructed as $m^2_{\text {miss}} \equiv (p_{e^+ \, e^-} - p_{B_\mathrm{tag}} - p_{D^{(*)}} - p_\ell )^2$, and the four-momentum of the reconstructed lepton can be boosted into the signal B rest frame. A Gaussian smearing is added to the truth level $m^2_{\text {miss}}$ with a width of 0.5 GeV$^2$ to account for detector resolution and tagging-B reconstruction. No additional correction is applied to $|\mathbf {p}^*_{\ell }|$. Higher dimensional histograms including the reconstructed $q^2$ and the $D^* \rightarrow D\pi$ helicity angle may also be incorporated, but are omitted here for simplicity.

Hammer can be used to efficiently compute histograms for any given NP choice. The basis of NP operators is defined in Table 1, with respect to the Lagrangian

$$\begin{aligned} \mathcal {L} = \frac{4 G_F}{\sqrt{2}}\, V_{cb}\, c_{XY}\big (\bar{c}\, \varGamma _X\, b\big )\big (\bar{\ell }\, \varGamma _Y\, \nu \big )\,, \end{aligned}$$

(2)

where $\varGamma _{X(Y)}$ is any Dirac matrix and $c_{XY}$ is a Wilson coefficient. We shall generally write explicit Wilson coefficients as $c_{XY} = S_{qXlY}$, $V_{qXlY}$, $T_{qXlY}$, where the S, V, T denotes the Lorentz structure, and X, Y = L, R denotes the chirality. In this simplified analysis, we assume that NP only affects the $b \rightarrow c \tau \nu$ decays, and not the light-lepton modes.

In order to carry out Wilson coefficient fits, we wrap the Hammer application programming interface with a gammaCombo [25] compatible class. This allows one to use Hammer ’s efficient reweighting of histogram bins to generate the relevant quantities required to calculate a likelihood function for the binned observables of interest. We then carry out a fully two-dimensional binned likelihood fit in $|\mathbf {p}^*_{\ell }|$ and $m^2_{\text {miss}}$, assuming Gaussian uncertainties. The fit uses $12 \times 12$ bins with equidistant bin widths for $|\mathbf {p}^*_{\ell }| \in (0.2,\, 2.2)$ GeV and $m^2_{\text {miss}} \in (-2,\, 10)$ GeV${}^{2}$. The fits determine either $R(D^{(*)})$, or the real and imaginary parts of Wilson coefficients. The preferred SM coupling is determined simultaneously, in order to remove explicit dependence on $|V_{cb}|$.

Table 1 The $b \rightarrow c \ell \nu$ operator basis and coupling conventions. Also shown are the identifying Wilson coefficient labels used in Hammer. The normalization of the operators is as in Eq. (2)

We construct an Asimov data set [26] assuming the fractions and total number of events in Table 2, following from the number of events in Ref. [1, 24]. In the scans, the total number of events corresponds to an approximate integrated luminosity of $5 \, \text {ab}^{-1}$ of Belle II collisions. We assume events are reconstructed in two categories targeting $B \rightarrow D \, \tau \bar{\nu }$ and $B \rightarrow D^* \tau \bar{\nu }$. A fit for the real and imaginary parts of a single Wilson coefficient plus the (real) SM coupling thus has $2 \times 12 \times 12 - 3 = 285$ degrees of freedom.

Table 2 The Asimov data set components. The fractions were motivated by Refs. [1, 24]

A sizable downfeed background from $D^*$ mesons misreconstructed as a D is expected in the $B \rightarrow D \, \tau \bar{\nu }$ channel via both the $B \rightarrow D^* \, \tau \bar{\nu }$ and $B \rightarrow D^* \, \ell \bar{\nu }$ decays. This is taken into account by partitioning the simulated $B \rightarrow D^*\tau \nu$ and $B \rightarrow D^*\ell \nu$ events into two samples: One with the correct $m^2_{\text {miss}} = (p_B - p_{D^*} - p_\ell )^2$ and the other with the misreconstructed $m^2_{\text {miss}} = (p_B - p_{D} - p_\ell )^2$, which omits the slow pion. This downfeed reduces the sensitivity for the case that NP couplings induce opposite effects on the $B \rightarrow D \tau \bar{\nu }$ versus $B \rightarrow D^* \tau \bar{\nu }$ total rates or shapes. In addition to semileptonic processes, we assume the presence of an irreducible background from secondaries (i.e., leptons from semileptonic D meson decays), fake leptons (i.e., hadrons that were misidentified as leptons) and semileptonic decays from higher charm resonances (i.e., $D^{**}$ states). The irreducible background is modeled in a simplified manner by assuming 10 background events in each of the $12 \times 12$ bins, totaling overall 1440 events per category.

Figure 1 shows the impact on the fit variables of three benchmark models that we use to investigate the effects of new physics:

• i) The $R_2$ leptoquark model, which sets $S_{qLlL} \simeq 8 \, T_{qLlL}$ (including RGE; see, e.g., Refs. [27, 28]);

• ii) A pure tensor model, via $T_{qLlL}$;

• iii) A right-handed vector model, via $V_{qRlL}$ .

For the ratio plots in Fig. 1, we fix the NP Wilson coefficients to specific values to illustrate the shape changes they induce in $|\mathbf {p}^*_{\ell }|$ and $m^2_{\text {miss}}$. The $R_2$ leptoquark model and tensor model exhibit sizable shape changes. The right-handed vector model shows only an overall normalization change for $B \rightarrow D \, \tau \bar{\nu }$, with no change in shape compared to the SM, because the axial-vector $B \rightarrow D$ hadronic matrix element vanishes by parity and angular momentum conservation. For $B \rightarrow D^*$, both vector and axial vector matrix elements are nonzero, so that introducing a right-handed vector current leads to shape and normalization changes.

Figure 2 shows the projections of the constructed Asimov data set, as well as the distributions expected for the three NP models. The latter have the same couplings as those shown in Fig. 1.

Fig. 1

The ratios of differential distributions with respect to the SM, as functions of $|\mathbf {p}^*_{\ell }|$ and $m^2_{\text {miss}}$, for various Wilson coefficient working points. For more details see text

Fig. 2

The $B \rightarrow D \, \tau \bar{\nu }$ (top) and $B \rightarrow D^* \tau \bar{\nu }$ (bottom) distributions in $|\mathbf {p}^*_{\ell }|$ and $m^2_{\text {miss}}$ in the Asimov data set. The number of events correspond to an estimated number of reconstructed events at Belle II with $5 \, \text {ab}^{-1}$

Fig. 3

Top: Illustrations of biases from fitting an SM template to three NP ‘truth’ benchmark models: the 2HDM type II with $S_{qRlL} = -2$ (left), $S_{qRlL} = 0.75i$ (middle), and the $R_2$ leptoquark model with $S_{qLlL} = 8 \, T_{qLlL} = 0.25 + 0.25 i$ (right). The orange dot corresponds to the predicted ‘true value’ of $R(D^{(*)})$ for the NP model, to be compared to the recovered 68%, 95% and 99% CLs of the SM fit to the NP Asimov data sets (with uncertainties estimated to correspond to $\sim 5$ ab$^{-1}$) in shades of red. Bottom: The best fit regions for the 2HDM and $R_2$ model Wilson coefficients obtained from fitting $R(D^{(*)})$ NP predictions to the recovered $R(D^{(*)})$ CLs for each NP model. The shades of red denote CLs as in the top row. The best fit (true value) Wilson coefficients are shown by black (orange) dots

2.3 $R(D^{(*)})$ biases from new physics truth

Many NP analyses and global fits to the $R(D^{(*)})$ measurements – together with other potentially template-sensitive observables, including $q^2$ spectra – have been carried out by a range of phenomenological studies (see, e.g., Refs. [27,28,29,30,31,32,33,34,35,36,37,38,39]). As mentioned above, the standard practice has been to fit NP predictions to the world-average values of $R(D^{(*)})$ (and other data) to determine confidence levels for allowed and excluded NP couplings. However, because the $R(D^{(*)})$ measurements use SM-based templates, and because the presence of NP operators can strongly alter acceptances and kinematic distributions, such analyses can lead to incorrect best-fit values or exclusions of NP Wilson coefficients.

To illustrate such a bias, we fit SM MC templates to NP Asimov data sets, that are generated with Hammer for three different NP ‘truth’ benchmark points: the 2HDM Type II with $S_{qRlL} = -2$, corresponding to $\tan \beta / m_{H^+} \simeq 0.5$ GeV$^{-1}$; the same with $S_{qRlL} = 0.75i$; and the $R_2$ leptoquark model with $S_{qLlL} = 8 \, T_{qLlL} = 0.25 + 0.25\, i$. (These models and couplings are for illustration; our goal here is only to demonstrate the type of biases that may plausibly be presumed to occur.) We replicate the fit of all existing measurements, allowing the normalizations of the D and $D^*$ modes (and the light leptonic final states) to float independently, without imposing e.g. their predicted SM relationship. This fit leads to a best-fit ellipse in the R(D) – $R(D^*)$ plane.

In Fig. 3 we show the recovered values, $R(D^{(*)})_{\text {rec}}$, obtained from this procedure, and compare them to the actual predictions of the given NP truth benchmark point, $R(D^{(*)})_{\text {th}}$. For ease of comparison, we normalize the $R(D^{(*)})$ values against the SM predictions for $R(D^{(*)})_{\text {SM}}$. The resulting recovered best fit ratios, defining $\hat{R}(D^{(*)}) = R(D^{(*)})/R(D^{(*)})_{\mathrm {SM}}$

$$\begin{aligned} \text {2HDM }(-2): ~&\hat{R}(D)_{\text {rec}} = 1.35(7)\,,&\hat{R}(D)_{\text {th}} = 1.66 \\&\hat{R}(D^*)_{\text {rec}} = 0.96(2)\,,&\hat{R}(D^*)_{\text {th}} = 0.92 \\ \text {2HDM }(0.75i):~&\hat{R}(D)_{\text {rec}} = 1.24(7)\,,&\hat{R}(D)_{\text {th}} = 1.48 \\&\hat{R}(D^*)_{\text {rec}} = 1.01(2)\,,&\hat{R}(D^*)_{\text {th}} = 1.02 \\ {R_2:~}&\hat{R}(D)_{\text {rec}} = 1.24(7)\,,&\hat{R}(D)_{\text {th}} = 1.48 \\&\hat{R}(D^*)_{\text {rec}} = 0.92(2)\,,&\hat{R}(D^*)_{\text {th}} = 0.85\,. \end{aligned}$$

For two NP models, the recovered ratios from fitting the Asimov data set exclude the truth $R(D^{(*)})_{\text {th}}$ values at $\gtrsim 4\sigma$, and the other at $3\sigma$. The recovered ratios show deviations from the SM comparable in size (but in some cases a different direction) to the current world average $R(D^{(*)})$, and much smaller than the deviations expected from the truth $R(D^{(*)})_{\text {th}}$ values. This illustrates the sizable bias in the measured $R(D^{(*)})$ values that may be presumed to ensue from carrying out fits with an SM template, if NP actually contributes to the measurements. We emphasize that the degree to which a particular NP model is actually affected by this type of bias – including the size and direction of the bias – may be sensitive to the details of the experimental framework and is therefore a question that can only be answered within each experimental analysis.

We also show in Fig. 3 the equivalent bias arising from a naïve fit of the $R(D^{(*)})$ NP prediction that attempts to recover the complex Wilson coefficient. This is done by parametrizing $R(D^{(*)})_{\text {th}} = R(D^{(*)})[c_{XY}]$, and fitting this expression to the recovered $R(D^{(*)})_{\text {rec}}$ values. Explicitly, one calculates CLs in the Wilson coefficient space via the two degree of freedom chi-square $\chi ^2 = \varvec{v}^T \sigma _{R(D^{(*)})}^{-1} \varvec{v}$, with $\varvec{v} = \big (R(D)_{\text {th}} - R(D)_{\text {rec}}\,, R(D^*)_{\text {th}} - R(D^*)_{\text {rec}}\big )$. The resulting best fit Wilson coefficient regions similarly exclude the truth values.

Thus, the allowed or excluded regions of NP couplings determined from fits to the $R(D^{(*)})$ measurements must be treated with caution, as these fits do not include effects of the NP distributions in the MC templates. Similarly, results of global fits should be interpreted carefully when assessing the level of compatibility with specific NP scenarios.

2.4 New physics Wilson coefficient fits

Instead of considering observables like $R(D^{(*)})$, for phenomenological studies to be able to properly make interpretations and test NP models, experiments should provide direct constraints on NP Wilson coefficients themselves. For example, this could be done with simplified likelihood ratios that profile out all irrelevant nuisance parameters from, e.g., systematic uncertainties or information from sidebands or control channels, or by other means.

As an example, we now use Hammer to perform such a fit for the real and imaginary parts of the NP Wilson coefficients, using the set of three NP models in Sect. 2.2 as templates. These are fit to the same two truth benchmark scenarios as in Fig. 4: a truth SM Asimov data set; and a truth Asimov data set reweighted to the 2HDM Type II with $S_{qRlL} = -2$.

Figure 4 shows in shades of red the 68%, 95% and 99% confidence levels (CLs) of the three NP model scans of SM Asimov data sets. For the SM truth benchmark, the corresponding best fit points are always at zero NP couplings. The derived CLs then correspond to the expected median exclusion of the fitted NP coupling under the assumption the SM is true.

Fig. 4

The 68%, 95% and 99% CL allowed regions of the three models under consideration, from fitting the SM (red) and 2HDM type II (yellow and with $S_{qRlL} = -2$) Asimov data sets. (Top) $R_2$ leptoquark model with $S_{qLlL} = 8 T_{qLlL}$; (middle) NP in the form of a left-handed tensor coupling; (bottom) NP in the form of a right-handed vector coupling

We further show in shades of yellow the same fit CLs for the 2HDM truth benchmark Asimov data set. These latter fits illustrate a scenario in which NP is present, but is analyzed with an incomplete or incorrect set of NP Wilson coefficients. Depending on the set of coefficients, we see from the $\varDelta \chi ^2$ of the best fit points that the new physics might be obfuscated or wrongly identified. This underlines the importance for LHCb and Belle II to eventually carry out an analysis in the full multi-dimensional space of Wilson coefficients, spanned by the operators listed in Table 1.

3 The Hammer library

In this section we present core interface features and calculational strategies of the Hammer library. Details of the code structure, implementation, and use, can be found in the Hammer manual [40]; here we provide only an overview.

3.1 Reweighting

We consider an MC event sample, comprising a set of events indexed by I, with weights $w_I$ and truth-level kinematics $\{q\}_I$. Reweighting this sample from an ‘old’ to a ‘new’ theory requires the truth-level computation of the ratio of the differential rates

$$\begin{aligned} r_I = \frac{ d \varGamma ^{\text {new}}_I/d \mathcal {PS}}{d \varGamma ^{\text {old}}_I/d \mathcal {PS}}\,, \end{aligned}$$

(3)

applied event-by-event via the mapping $w_I \mapsto r_I w_I$. The ‘old’ or ‘input’ or ‘denominator’ theory is typically the SM plus (where relevant) a hadronic model — that is, a form factor (FF) parametrization. (It may also be composed of pure phase space (PS) elements, see App. A.2.) The ‘new’ or ‘output’ or ‘numerator’ theory may involve NP beyond the Standard Model, or a different hadronic model, or both.

Historically, the primary focus of the library is reweighting of $b \rightarrow c\ell \nu$ semileptonic processes, often in multistep cascades such as $B \rightarrow D^{(*,**)}(\rightarrow DY)\, \tau (\rightarrow X\nu ) \bar{\nu }$. However, the library’s computational structure is designed to be generalized beyond these processes, and we therefore frame the following discussion in general terms, before returning to the specific case of semileptonic decays.

3.2 New Physics generalizations

The Hammer library is designed for the reweighting of processes via theories of the form

$$\begin{aligned} \mathcal {L} = \sum _\alpha c_\alpha \, \mathcal {O}_\alpha \,. \end{aligned}$$

(4)

where $\mathcal {O}_\alpha$ are a basis of operators, and $c_\alpha$, are SM or NP Wilson coefficients (defined at a fixed physical scale; mixing of the Wilson coefficients under RG evolution, if relevant, must be accounted for externally to the library). We specify in Table 1 the conventions used for various $b \rightarrow c\ell \nu$ four-Fermi operators and other processes included in the library.

The corresponding process amplitudes may be expressed as linear combinations $c_\alpha \mathcal {A}_\alpha$. They may also be further expressed as a linear sum with respect to a basis of form factors, $F_i$, that encode the physics of hadronic transitions (if any).³ In general, then, an amplitude may be written in the form

$$\begin{aligned} \mathcal {M}^{\{s\}}\big (\{q\}\big ) = \sum _{\alpha , i} c_\alpha \, F_i\big (\{q\}\big ) \, \mathcal {A}^{\{s\}}_{\alpha i}\big (\{q\}\big )\,, \end{aligned}$$

(6)

in which $\{s\}$ are a set of external quantum numbers and $\{q\}$ the set of four-momenta.⁴ The object $\mathcal {A}_{\alpha i}$ is an NP- and FF-generalized amplitude tensor. In the case of cascades, relevant for $B \rightarrow D^{(*,**)}(\rightarrow DY)\, \tau (\rightarrow X\nu ) \bar{\nu }$ decays, the amplitude tensor may itself be the product of several subamplitudes, summed over several sets of internal quantum numbers. The corresponding polarized differential rate

$$\begin{aligned} \frac{d\varGamma ^{\{s\}}}{d\mathcal {PS}}&= \!\! \sum _{\alpha , i, \beta , j} \!\! c_\alpha c_\beta ^\dagger \, F_i F_j^\dagger \!\big (\{q\}\big ) \, \mathcal {A}^{\{s\}}_{\alpha i}\mathcal {A}^{\dagger \{s\}}_{\beta j}\!\big (\{q\}\big ) \,, \nonumber \\&= \!\! \sum _{\alpha , i, \beta , j} \!\! c_\alpha c_\beta ^\dagger \, F_i F_j^\dagger \!\big (\{q\}\big ) \,\mathcal {W}_{\alpha i \beta j}\,, \end{aligned}$$

(7)

in which the phase space differential form $d\mathcal {PS}$ includes on-shell $\delta$-functions and geometric or combinatoric factors, as appropriate.

The outer product of the amplitude tensor, defined as $\mathcal {W} \equiv \mathcal {A} \mathcal {A}^\dagger$, is a weight tensor. The object $\sum _{ij} F_i F_j^\dagger \mathcal {W}_{\alpha i \beta j}$ in Eq. (7) is independent of the Wilson coefficients: Once this object is computed for a specific $\{q\}$ – an event – it can be contracted with any choice of NP to generate an event weight. Similarly, on a patch of phase space $\varOmega$ — e.g., the acceptance of a detector or a bin of a histogram — the marginal rate can now be written as

$$\begin{aligned} \varGamma ^{\{s\}}_{\varOmega } = \sum _{\alpha , \beta } c_\alpha c_\beta ^\dagger \int _\varOmega d\mathcal {PS}\, \sum _{ij} F_i F_j^\dagger \big (\{q\}\big ) \mathcal {W}^{\{s\}}_{\alpha i \beta j} \big (\{q\}\big )\,. \end{aligned}$$

(8)

The Wilson coefficients factor out of the phase space integral, so that the integral itself generates a NP-generalized tensor. After it is computed once, it can be contracted with any choice of NP Wilson coefficients, $c_\alpha$, thereafter.

The core of Hammer ’s computational philosophy is based on the observation that this contraction is computationally much more efficient than the initial computation (and integration). Hence efficient reweighting is achieved by

• Computing NP (and/or FF, see below) generalized objects, and storing them;

• Contracting them thereafter for any given NP (and/or FF) choice to quickly generate a desired NP (and/or FF) weight.

Table 3 Presently implemented amplitudes in the Hammer library, and corresponding form factor parametrizations. SM-only parametrizations are indicated by a $*$ superscript. Form factor parametrizations that include linearized variations are denoted with a $\ddagger$ superscript. These are named in the library by adding a “Var” suffix, e.g. “BGLVar”

3.3 Form factor generalizations

Similarly to the NP Wilson coefficients, it is often desirable to be able to vary the FF parameterizations themselves. This can be achieved directly within Hammer by adjusting the choice of FF parameter values for any given parametrization. However, because the impacts of the form-factors depend on the kinematics of an event, they cannot be factored out of the phase-space integral in Eq. (8). Full reweighting to a different choice of form-factor parameters therefore requires full recalculation of each event weight on the phase space patch.

Instead, one might contemplate linearized variations with respect to the FF parameters, that commute with the phase space integration: For instance, variations around a (best-fit) point along the error eigenbasis of a fit to the FF parameters; or FF parametrizations that are linearized with respect to a basis of parameters, such as the BGL parametrization [43,44,45] in $B \rightarrow D^{(*)} \ell \nu$. To this end, an FF parametrization with a parameter set $\{\mu \}$ can be linearized around a (best-fit) point, $\{\mu ^0\}$ so that

$$\begin{aligned} F_{i}\big (\{q\}; \{\mu \}\big ) = F_i\big (\{q\}, \{\mu ^0\}\big ) + \sum _{a} F'_{i,a}\big (\{q\}, \{\mu ^0\}\big )\,e_a\,, \end{aligned}$$

(9)

where ‘a’ is one or more variational indices and $e_{a}$ is the variation. In the language of the error eigenbasis case, $F'_{i,a}$ is the perturbation of $F_i$ in the ath principal component $e_{a}$ of the parametric fit covariance matrix.

Defining $\xi _a \equiv (1, e_a)$ and $\varPhi _{i,a+1} \equiv (F_{i}, F'_{i,a})$, so that Eq. (9) becomes

$$\begin{aligned} \sum _{a} \xi _a \varPhi _{i,a} = F_{i} + \sum _{a'} F'_{i,a'}\,e_{a'}\,, \end{aligned}$$

(10)

then the differential rate

$$\begin{aligned} \frac{d\varGamma ^{\{s\}}}{d\mathcal {PS}}= & {} \!\! \sum _{\alpha , a, \beta , b} \!\! c_\alpha c_\beta ^\dagger \xi _a \xi ^\dagger _b \mathcal {U}^{\{s\}}_{\alpha a \beta b}\,, \nonumber \\ \mathcal {U}^{\{s\}}_{\alpha a \beta b}\equiv & {} \sum _{ij} \varPhi _{i,a} \varPhi _{j,b}^\dagger \big (\{q\}\big ) \mathcal {W}^{\{s\}}_{\alpha i \beta _j} \big (\{q\}\big )\,, \end{aligned}$$

(11)

with $\mathcal {U}$ an NP- and FF-generalized weight tensor. The $\xi _a$ are independent of $\{q\}$ and factor out of any phase space integral just as the Wilson coefficients do. That is, an integral on any phase space patch,

$$\begin{aligned} \varGamma ^{\{s\}}_{\varOmega } = \sum _{\alpha , \beta , a, b} c_\alpha c_\beta ^\dagger \xi _a \xi ^\dagger _b \int _\varOmega d\mathcal {PS}\,\, \mathcal {U}^{\{s\}}_{\alpha a \beta b}\,. \end{aligned}$$

(12)

One may thus tensorialize the amplitude with respect to Wilson coefficients and/or FF linearized variations, to be contracted later with with NP or FF variation choices (the latter within the regime of validity of the FF linearization). Hereafter, the $\xi _a$ are referred to as ‘FF uncertainties’ or ‘FF eigenvectors’ following the nominal fit correlation matrix example.

3.4 Rates

In certain cases, it is also useful to compute and fold in an overall ratio of rates $\varGamma ^{\text {old}}/\varGamma ^{\text {new}}$, or the rates themselves, $\varGamma ^{\text {new}, \text {old}}$, may be required. For example, if the MC sample has been initially generated with a fixed overall branching ratio, $\mathcal {B}_{\text {new}}$, one might wish to enforce this constraint via an additional multiplicative factor $\mathcal {B}_{\text {old}}/\mathcal {B}_{\text {new}}$.

The different components computed by Hammer are then:

• (i) The NP- and/or FF-generalized tensor for $(d \varGamma ^{\text {new}}_I/d \mathcal {PS}) / (d \varGamma ^{\text {old}}_I/d \mathcal {PS})$, via Eq. (11), noting that the denominator carries no free NP or FF variational index. (The ratio $r_I$ is then itself generally at least a rank-2 tensor.);

• (ii) The NP- and/or FF-generalized rate tensors $\varGamma ^{\text {old, new}}$, which need be computed only once for an entire sample. (These rates require integration over the phase space, which is achieved by a dedicated multidimensional Gaussian quadrature integrator.)

3.5 Primary code functionalities

The calculational core of Hammer computes the NP or FF generalized tensors event-by-event for any process known to the library (see Table 3 for a list), and as specified by initialization choices (more detail is provided in Sect. 3.6) and specified form factor parametrizations. This core is supplemented by a wide array of functionalities to permit manipulation the resulting NP- and FF-generalized weight tensors as needed. This may include binning — equivalent to integrating on a phase space patch — the weight tensors into a histogram of any desired reconstructed observables, and/or it may include folding of detector simulation smearings, etc. Such histograms have NP- and FF-generalized tensors as bin entries, and we therefore call them generalized or tensor histograms. Once such NP- and FF-generalized tensor objects are computed and stored, contraction with NP or FF eigenvector choices permits the library to efficiently generate actual event weights or histogram bin weights for any theory of interest.

The architecture of Hammer is designed around several primary functionalities:

• 1. Provide an interface to determine which processes are to be reweighed, and which (possibly multiple) schemes for form factor parametrizations are to be used. This includes handling for (sub)processes that were generated as pure phase space, and the ability to change the values of the form factor parameters.

• 2. Parse events into cascades of amplitudes known to the library, and compute their corresponding NP- and/or FF-generalized amplitude or weight tensor, as well as the respective rate tensors, as needed.

• 3. Provide an interface to generate histograms (of arbitrary dimension), and bin the event weight tensors — i.e., $r_I w_I$, as in Eq. (3) — into these histograms, as instructed. This includes functionality for weight-squared statistical errors, functionality for generation of ROOT histograms, as well as extensive internal architecture for efficient memory usage.

• 4. Efficiently contract generalized weight tensors or bin entries against specific FF variational or NP choices, to generate an event or bin weight. This includes extensive internal architecture to balance speed versus memory requirements.

• 5. Provide interface to save and reload amplitude or weight tensors or generalized histograms, to permit quick reprocessing into weights from precomputed or ‘initialized’ tensor objects.

Examples of the implementation of these functionalities are shown in many examples provided with the source code.

3.6 Code flow

A Hammer program may have two different types of structure: An initialization program, so called as it runs on MC as input, and may generate Hammer format files; or an analysis program, which may reprocess histograms or event weights that have already been saved in an initialization run. Pertinent details of the elements of the application programming interface mentioned below are provided in Appendix A, with more details in the Hammer manual.

An initialization program has the generic flow:

• 1. Create a Hammer object.

• 2. Declare included or forbidden processes, via and .

• 3. Declare form factor schemes, via and .

• 4. (Optional) Add histograms, via .

• 5. (Optional) Declare the MC units, via .

• 6. Initialize the Hammer class members with .

• 7. (Optional) Change FF default parameter settings with , or (if not SM) declare the Wilson coefficients for the input MC via .

• 8. (Optional) Fix Wilson coefficient (Wilson coefficient and/or FF uncertainty) choice to special choices in weight calculations (histogram binnings), via ( and/or ).

• 9. Each event may contain multiple processes, e.g., a signal and tag B decay. Looping over the events:

  • (a) Initialize event with . For each process in the event:

    • i. Create a Hammer object.

    • ii. Add particles and decay vertices to create a process tree, via and .

    • iii. Decide whether to include or exclude processes from an event via and/or .

  • (b) Compute or obtain event observables – specific particles can be extracted with or other programmatic means – and specify the corresponding histogram bins to be filled via .

  • (c) Initialize and compute the process amplitudes and weight tensors for included processes in the event, and fill histograms with event tensor weights – the direct product of include process tensor weights – via .

  • (d) (Optional) Save the weight tensors for each event, with to a buffer.

• 10. (Optional) Generate histograms with and/or save them with . NP choices are implemented with , FF variations are set with .

• 11. (Optional) Save the rate tensors, with to a buffer.

• 12. (Optional) Save an autogenerated bibTeX list of references used in the run with .

By contrast, an analysis program (from a previously initialized sample, stored in a buffer) has the generic flow:

• 1. Create a Hammer object and specify the input file.

• 2. Load or merge the run header — include or forbid specifications, FF schemes, or histograms — with (after ). One may further declare additional histograms to be compiled (from saved event weight data) via .

• 3. (Optional) Load or merge saved histograms with , and/or generate desired histograms with . NP choices are implemented with .

• 4. (Optional) Looping over the events:

  • (a) Initialize event with .

  • (b) If desired, remove processes from an event with .

  • (c) Reload event weights with .

  • (d) Specify histograms to be filled via .

  • (e) Fill histograms with event weights via .

4 Conclusions

Precision measurements of $b\rightarrow c \tau \bar{\nu }$ decays require large Monte Carlo samples, which incorporate detailed simulations of detector responses and physics backgrounds. The limited statistics due to the computational cost of these simulations are often a leading systematic uncertainty in the measurements, and it is prohibitively expensive to generate fully simulated MC samples for arbitrary NP models or descriptions of hadronic matrix elements.

In this paper we described the Hammer library, and illustrated its utility. Hammer allows the fast and efficient reweighting of existing SM (or phase-space based) MC samples to arbitrary NP models. In addition, Hammer can be used to change form factor parametrizations and/or incorporate uncertainties from form factors into experimental measurements. Hammer provides a computationally fast way for binned fits to generate predictions, and we implement a demonstrative forward-folding fit to constrain NP Wilson coefficients using this feature. Such a fit should be carried out by experimental collaborations in future measurements to provide reliable constraints on NP contributions in semileptonic $b\rightarrow c \tau \bar{\nu }$ decays. The results will allow people outside the collaborations to make correct interpretations of the data, which has not been possible to date without potentially sizeable biases. To demonstrate this latter point, we carried out toy NP analyses using SM fits to NP Asimov data sets, and showed that sizeable biases can indeed occur. Hammer is open source software and we are looking forward to the experimental results and interpretations it will enable.

A: Core elements of the Application Programming Interface

The user interface of the Hammer library provides four main classes: the class itself; the and classes, used to create events; and the class used for saving and loading precomputed objects. A schematic of the architecture of Hammer is shown in Fig. 5.

In the following we describe various core parts of the Hammer Application Programming Interface (API), with many more details available in the code manual. The library itself is implemented in C++, along with a Python3 wrapper of the API; we will consider here the C++ interface only. This discussion is ordered by scope, rather than the typical code flow. Further details can be found in the Hammer manual [40].

Fig. 5

Schematic architecture of Hammer. The flow of user specified choices or event data is shown by yellow arrows. Blue (green) arrows denote the flow of calculational information, in particular amplitude, weight or rate (form factor) tensors. Red arrows highlight the flow of Hammer output, which may be saved or reloaded. Most internal Hammer classes are not shown in this schematic

1.1 A.1: Building processes and events

A typical decay cascade is contained in the library by the class; an event may contain multiple instances as e.g., is the case for a signal plus tag B-$\bar{B}$ pair. Each cascade may be simply represented in graphical terms as a ‘process tree’, as shown in Fig. 6: Each particle in the cascade is assigned an index, and each decay vertex is represented as a map from a parent index, to the indices of all its daughters. Hammer assembles the process tree through two methods and . The former adds a class object – a momentum and a PDG code – to a container of particles; the latter fills the map of each parent index to its daughters for each decay vertex.

In the case of Fig. 6, the first two vertices of the cascade may be built explicitly as follows:

and so on. Particles and vertices need not be added in order; helper functions are provided in the code examples for automatically parsing HepMC files.

Fig. 6

Example process tree for a decay cascade involving 10 particles (numbers), 4 vertices (circles) and 3 edges (dark lines)

1.2 A.2: Specifications

The Hammer library contains an interpreter that maps a string representation of a vertex – a vertex string – to all possible charge conserving processes allowed by the specified particle names. The interpreter uses the syntax that particle names are parsed by a capital letter: the full list of names is provided in the manual. (For example the vertex string is interpreted as all twelve possible $D^* \rightarrow D\pi$ vertices, while is interpreted as only the $D^{*+} \rightarrow D^+\pi ^0$, $D^{*+} \rightarrow D^0\pi ^+$, and (the heavily CKM suppressed) $D^{*+} \rightarrow \bar{D}^0\pi ^+$ decay.)

The decay processes to be reweighed by Hammer are specified via , which takes a single vertex string or vector of vertex strings $\{V_1,V_2,\ldots , V_n\}$ as an argument, and may be invoked multiple times. Each specification is inclusive and permits any process tree whose full set of vertices contains all of $\{V_1,V_2,\ldots , V_n\}$. The boolean logic applied by is AND between each vertex string element, and OR between separate invocations of . For example

means ‘Reweight a process that either contains vertices ($B \rightarrow D^*\tau \nu$ and $D^* \rightarrow D\gamma$) or the vertex ($B \rightarrow D \mu \nu$)’. Hence, e.g., $\bar{B}^0 \rightarrow (D^{*+} \rightarrow (D^+ \rightarrow K^+ \pi ^+ \pi ^-)\gamma )(\tau ^- \rightarrow \ell ^-\nu \nu )$ would be included. Recombination of radiative photons (produced during MC generation by PHOTOS) is handled automatically by the library, and need not be specified in specifications. Processes may instead forbidden with the method, whose specifications are exclusive and forbids only process trees whose set of vertices P equals $\{V_1,V_2,\ldots , V_n\}$.

The Hammer library allows the user to specify multiple form factor ‘schemes’ to be used in reweighting. A form factor scheme is a set of FF parameterization choices for each hadronic transition involving form factors, and is labelled by a ‘scheme name’. These schemes are set by the method , which takes a scheme name plus a map from hadronic string representation to FF parametrization. The hadronic string follows the same syntax and uses the same particle symbols as for vertex strings. For example,

declares two different FF schemes, choosing BLPR for both $B \rightarrow D$ and $B \rightarrow D^*$ form factors in , and a mixture of schemes for . Separate histograms and event weights are generated for each scheme name. The list of available FF parametrizations are provided in Table 3. The hadronic strings are charge sensitive, hence, e.g., versus assigns two different FF parametrizations to charged and neutral $B \rightarrow D$ decays. Specification of the form factor schemes used to generate the MC sample, i.e., the denominator or input form factors, must be specified in order for Hammer to be able to generate the reweighting tensors. These schemes are specified by the method .

Units of the input MC sample may/should be specified via , for instance . The default is GeV.

The Hammer library permits the user to declare particular vertices, in either the denominator or numerator amplitude, to be evaluated as pure phase space. This is achieved by the method , which takes a set of string vertices as an argument, and an optional enum taking values (default), , or . As an example

requests all $\tau \rightarrow \mu \nu \nu$ and $D^{*+}\rightarrow D\pi$ vertices in the numerator and all $D^* \rightarrow D\gamma$ vertices in the denominator, to be evaluated as phase space. How these requests are enforced is subject to detailed rules explained in the manual. The library employs the pure phase space definition

$$\begin{aligned} \frac{1}{\prod _k |\{s_k\}|} \sum _{s_i, r_j} \big |\mathcal {M}_{s_1,\ldots , s_n; r_1,\ldots ,r_m}\big |^2 = 1 \times (m^{6-2n})\,, \end{aligned}$$

(A.1)

where $s_i$ ($r_i$) are incoming (outgoing) quantum numbers, $|\{s_k\}|$ is the number of states of $s_k$, m is the mass of the parent particle in the vertex, and n the number of daughters.

Once all specifications are declared (include histograms, as below), containers are initialized by . After invocation of , manipulation of the FF default settings may be achieved via , which takes YAML⁵ format arguments. For instance,

changes the two BGL outer function parameters from their default settings. (Note that the YAML key for the relevant FF class has a inserted in the hadronic transition, e.g., , rather than , to make it clear we are identifying settings for a particular class – the $B \rightarrow D$ BGL class – and not a process.)

By default the library computes the total rate (or looks up a partial width) the first time each unique vertex is encountered in a run. This behavior may be disabled, e.g., if the required integration is multidimensional and time consuming, via .

To permit full flexibility in FF settings, duplication of the same FF class is permitted and may be invoked by adding a token to a FF parametrization name in , separated by an underscore. For instance, one may declare

This example allows independent manipulation of the BGL parameterization for each of the charged versus neutral modes in the same scheme, or between different schemes: After , a succeeding would affect only the neutral B parametrization in .

Various other additional specification features are provided by the library, including e.g. specialization of Wilson coefficients to a particular global choice in the event tensor weight calculations. Specifications may also be declared through a card interface, as shown in demo...card.cc example programs provided with the source code.

1.3 A.3: Histogramming

Histograms of arbitrary dimensionality may be created by the Hammer library. In general, histogram bins contain event weight tensors (or direct products of them if there multiple processes in the event).

A histogram is declared by , which takes as arguments a name string and either: a vector of dimensions, a bool for under/overflow and a vector of ranges; or a vector of bin edges and a bool for under/overflow. The method does not create a single histogram, but rather a histogram set: A separate histogram is created for each unique event cascade and in turn for each FF scheme name specified by . For instance

The first declaration creates a histogram set each with $20\times 15$ bins, no under/overflow, binned uniformly over the respective ranges 3–12 and 0–2.5 (in appropriate units). With reference to the above example, this histogram set contains one histogram for each combination of either or with each unique $B \rightarrow D$ decay cascade. The second declaration similarly creates a set of $3\times 2$ histograms with non-uniform bins and additional under/overflow bins.

Filling of histograms for a specific event is performed by , which takes the histogram name and the values of the observables corresponding to each histogram dimension. For example, fills the appropriate bin element for the histograms belonging to the event being processed, and fills the relevant histograms for each declared FF scheme name. (Invocations of must occur before , discussed in Sect. A.4 below.) If is not invoked for a particular histogram for a particular event, the events tensor weight is not added to the histogram. When the under/overflow bool is set to , events outside the bin ranges are ignored by .

Computation of the weight-squared uncertainties is off by default. This may be enabled globally via the options setting . However, for computational speed and/or memory efficiency, it may be instead enabled or disabled for individual histograms via , which takes the name of the histogram as an argument, and a bool. For instance

enables weight-squared computation for this particular histogram. This method should be invoked before .

Various additional histogramming methods are provided by the library, that enable histogram compression, projection, and Wilson coefficient or FF specialization. These permit reduction of memory requirements or speed enhancements, and are detailed in the manual.

1.4 A.4: Processing

An event may contain multiple instances of , in order to account for the fact that a single event may feature, e.g., two B decay processes. The class is initialized by , which may take an optional initial event weight (this can also be set by ). instances are added by which also returns a hash ID of the process. If the process is not allowed according to the or specifications, the returned hash ID is zero, and the process is not added to the relevant containers.

Once a process is added, it is automatically initialized, which chiefly involves: calculating the signatures of each vertex in the decay cascade; identifying the various subamplitudes making up the cascade, as well as relevant form factor parametrizations and vertex decay rates, for both the numerator/output and denominator/input; and calculating the total rate for the vertex (this is done only the first time each unique vertex is encountered, i.e., only once per run per unique vertex and per FF scheme). The amplitude tensors and form factors are not computed, however, until the invocation of .

Once all processes are added and relevant histograms (if any) have been denoted to be filled, the weights are actually computed and added to the histogram (if any) bins by invocation of . A pseudo-example on a single event with a set of processes might look like

which might be emplaced in a larger loop over a set of events.

1.5 A.5: Setting Wilson coefficients and form factors

Once is completed, the event weight may be retrieved by , that takes the FF scheme name. For instance computes the currently loaded event weight for the currently specified WCs and FFs. The latter may be set via and .

The method takes a string that identifies which operator WCs are being set, and either a vector of the WC values or a map. The default WC settings are the SM. A typical example of the usage of this method is

where the first argument specifies $b \rightarrow c \tau \nu$ four-Fermi WCs are being set, and the second argument is a of each WC to its desired value. The full list of WCs and their definitions is supplied in the manual. An optional third argument is the enum, that declares whether the evaluation should be applied to the numerator and/or denominator (numerator by default). As an alternative, one may instead pass as second argument a , corresponding to the ordered basis

with the conventions for these WCs shown in Table 1. It is important to note that the method, when taking a , produces incremental settings changes. A subsequent invocation will result in $= 0.5$ and $= 0.25$. The method resets the corresponding WCs to the default SM values.

The FF eigenvectors are (re)set via the method ( ) in a similar way, identifying the FF eigenvectors to be set via the FF class prefix such as and the parametrization name. A typical example of the usage of this method is

See the manual for definitions of currently implemented FF variational classes (typically denoted with a suffix ).

1.6 A.6: Retrieval

Once all events or histograms have been processed (or reloaded from a file, see Sect. A.9), the user may retrieve a specific histogram with the method , that takes a histogram name and a FF scheme name. NP choices must be specified first via , as must FF uncertainties via . For example,

would contract the bin weights with the specified NP Wilson coefficients (and FF eigenvectors, if any) for each histogram in the histogram set with FF scheme , and then combines them together into a single final histogram. This contracted histogram output is a (row-major) flattened vector of structs. This struct has members , and for sum of weights, sum of squared weights and number of events in the bin, respectively. (By contrast, the method extracts all histograms of a specific name and scheme, producing a map of event hash IDs to histogram for all available histograms with the FF scheme .)

Integrated rates or partial widths for a specific vertex may be retrieved via . The vertex is specified via either a vertex string, or the parent and daughter PDG codes, plus an FF scheme. (Partial widths are returned in the units specified by ; the default is GeV.) For example

both return the partial width for the $B^0 \rightarrow D^{*-}\mu ^+\nu$ vertex, using the form factor parameterization specified in , and whatever WCs or FF uncertainties have been specified. (The method is charge conjugate sensitive, so the vertex string must specify sufficient charges to make the vertex charge unique. For example, writing just would correspond to not only $B^0 \rightarrow D^{*-}\mu ^+\nu$, but also the very heavily suppressed $B^0 \rightarrow D^{+}\mu ^-\bar{\nu }$.) The method similarly returns the partial width according to the specified denominator/input FF parametrization chosen in , and the denominator/input WCs or FF eigenvectors.

1.7 A.7: Multithreading

The library has the ability to perform lock-free parallelization of the and evaluations. This requires use of the thread local methods and to set the desired WC or FF uncertainties. These methods take the same syntax as and , but with different behaviour: They do not set the values incrementally from the current settings, but always increment from the SM and zero FF uncertainties, respectively. Global values of the WCs or FF variations are unaffected by the methods.

1.8 A.8: Saving

Hammer provides the ability to store header settings, generated event weights, histograms, and/or rates in binary buffers for later retrieval and reprocessing. These buffers are built on the cross-platform serialization library flatbuffers⁶: The buffer structs and permit writing/reading of Hammer internal objects using C++ binary files and ROOT trees, respectively.

In order to save a buffer, an outfile must first be designated. For example, . The methods , , , may be used to save: specification settings (like etc; the process weight(s) of the event currently loaded in memory (this should be invoked inside an event loop, after ); the computed rates; and histograms. Each of these methods returns a , which can be stored as sequential records in the buffer via an ostream operator. For example,

writes the declared run header, with all its settings, into an and passes it as a record into the buffer, and then does the same for the histogram . The record types are labelled by an enum with values , , , , , and . A histogram is always saved sequentially as a definition record then the histogram data record. The method may optionally take additional arguments – such as an FF scheme name – in order to save only part of an entire histogram set; see the manual for further details.

Saving a buffer in ROOT format is achieved by passing the output of the methods into a , that may then be stored in a ROOT . Explicit implementations of this functionality are provided in various demo...root.cc example programs.

1.9 A.9: Reloading and merging

Buffer records may be loaded from a declared infile into an via an operator. For example,

attempts to load the first buffer record as a run header (returning if this record is of a different type).

It is the responsibility of the user to curate the logic and order under which a buffer is saved and then read. For example, if a block of histograms have been saved before a set of rate records, then

would read through the buffer, with the method loading all the histograms, and all the histogram definitions, that are found before reaching the block of saved rates. The method behaves similarly to .

Once an object is loaded, it behaves just as the originally computed instance. So one may invoke for a reloaded histogram as described in Sect. A.5.

Event weights can be reloaded via . This permits recreating the original event loop provided and are called appropriately. For example, on a block of saved event records

would permit reprocessing of saved event weights into a newly created histogram.

Loading a buffer in ROOT format is achieved by reading the stored in a into an that can be passed to the methods. Explicit implementations of this functionality are provided in various demo...root.cc example programs.

In order to permit parallelization of initialization runs, the methods accept an additional bool, to specify whether to merge the buffer contents with existing objects in memory ( ), or overwrite them ( , default). Merging of histograms occurs if two histograms are loaded with a matching name. This merging is additive for histograms in each histogram set with the same FF scheme and hash IDs, and otherwise results in the new unique histograms being appended to the existing histogram set. (If one wishes instead to overwrite a histogram one may instead first invoke , and then reload the desired components of the histogram set.)

The methods and behave similarly. For weights (rates) with matching hash IDs, merging permits appending of process weights (rates) computed with new form factor schemes to the process weights (rates). Finally, permits merging of two sets of header specifications into their union. More details are provided in the manual.