VLQcalc

a Python Module for Calculating Vector-like Quark Couplings

Ali Can Canbay and Orhan Cakir

VLQcalc works with the vector-like quark (VLQ) models VLQ_UFO [1], VLQ_v4_UFO and VLQ_v5_UFO [2], which were prepared with FeynRules [3]. It can:

• compute the couplings that give a chosen width-to-mass ratio (Γ/M) and chosen branching ratios,
• compute partial and total decay widths, with the same formulas and SM inputs as the models,
• include couplings to the 1st and 2nd generation quarks,
• convert couplings between VLQ_UFO and VLQ_v4_UFO/VLQ_v5_UFO,
• write MadGraph5 [4] input cards,
• write the results as tables (Markdown, CSV, JSON, text) and plots.

The tutorial can be run online with Binder [5] by clicking the launch binder button above.

Installation

pip install VLQcalc            # core package, no dependencies
pip install "VLQcalc[plot]"    # with matplotlib for plots

Python 3.9 or newer is needed.

From a copy of this repository, run one of the following in its main folder:

pip install .
python setup.py install        # older method; setuptools prints a deprecation warning

VLQcalc has no dependencies, so it can also be used without installation, for example on clusters where pip is not available: copy the VLQcalc folder next to your script, or add the main folder of the repository to PYTHONPATH.

Quick start

import VLQcalc.model as model
import VLQcalc.madgraph as madgraph

vlq = model.VLQ('T', FNS=4, LR=False)        # T quark, 4-flavour scheme, left-handed couplings
vlq.setMass(range(1000, 2001, 100))          # masses in GeV
vlq.calcRatioKappas([0.5, 0.25, 0.25], 0.05) # [BR(Ht), BR(Wb), BR(Zt)] and Gamma/M

print(vlq.KappaH, vlq.KappaW, vlq.KappaZ)    # couplings to 3rd generation quarks, one value per mass
print(vlq.table())                           # Markdown table of the results
vlq.save('kappas.csv')                       # .md, .txt, .csv or .json
vlq.plot(save='kappas.pdf')                  # needs matplotlib

mg5 = madgraph.MG5(vlq, 'VLQ_v4_UFO')
mg5.setProcess('p p > tp tp~, tp > w+ b')
mg5.createMG5Input('tp_pair')                # writes tp_pair.dat

Without zeta, all decays go to 3rd generation quarks (zeta=[0, 0, 1]). Couplings to lighter quarks are set with the generation fractions ζ_i, for example 20% of the decays into 2nd generation quarks:

vlq = model.VLQ('T')
vlq.setMass([1000, 1500, 2000])
vlq.calcRatioKappas([0.5, 0.25, 0.25], 0.05, zeta=[0, 0.2, 0.8])
print(vlq.table('txt'))

M [GeV]    k_H(c)   k_H(t)     k_W(s)    k_W(b)     k_Z(c)    k_Z(t)  Gamma [GeV]
   1000  0.720235  1.44185  0.0872882  0.174582   0.123449  0.258278      49.9998
   1500  0.713939  1.42814  0.0581893   0.11638  0.0822928  0.167886      74.9999
   2000  0.711762  1.42361  0.0436416  0.087284  0.0617187   0.12482          100

table('txt') prints the settings as comment lines above the table; they are left out here. Each coupling is also available under its name in the model, for example vlq.Kappas['KTLw2'] for T–W–s (left-handed).

More examples are in the examples folder.

Documentation

The documentation overview shows typical workflows step by step.

Testing

The tests are not part of the installed package. Run them from a copy of this repository:

git clone https://github.com/acanbay/VLQcalc.git
cd VLQcalc
pip install ".[test]"
pytest

The tests compare the widths with the formulas shipped with the UFO models and check the cards, the conversions and the output files.

AI assistance. Version 0.2.0 was developed with the help of AI assistants (Claude, Anthropic). All output was reviewed, tested and validated by the authors.

References

1. M. Buchkremer, G. Cacciapaglia, A. Deandrea, and L. Panizzi. Model-independent framework for searches of top partners. Nuclear Physics B, 876(2):376–417, 2013.
2. B. Fuks and H. S. Shao. QCD next-to-leading-order predictions matched to parton showers for vector-like quark models. The European Physical Journal C, 77(2):135, 2017.
3. N. D. Christensen and C. Duhr. FeynRules – Feynman rules made easy. Computer Physics Communications, 180(9):1614–1641, 2009.
4. J. Alwall, M. Herquet, F. Maltoni, O. Mattelaer, and T. Stelzer. MadGraph 5: going beyond. Journal of High Energy Physics, 2011(6):128, 2011.
5. Jupyter et al. Binder 2.0 - Reproducible, Interactive, Sharable Environments for Science at Scale. Proceedings of the 17th Python in Science Conference. 2018.
6. J. A. Aguilar-Saavedra, R. Benbrik, S. Heinemeyer, and M. Pérez-Victoria. Handbook of vectorlike quarks: Mixing and single production. Physical Review D, 88(9):094010, 2013.
7. S. Moretti, D. O'Brien, L. Panizzi, and H. Prager. Production of extra quarks at the Large Hadron Collider beyond the narrow width approximation. Physical Review D, 96(7):075035, 2017.