Source-linked AI summary
flavio: a Python package for flavour and precision phenomenology in the Standard Model and beyond
David M. Straub
TL;DR
Flavour phenomenology needs tools that can separate possible new-physics effects from hadronic uncertainties and handle complex Wilson-coefficient dependence. flavio addresses this with an open-source Python package combining EFT predictions, experimental measurements, likelihood construction, and visualization. It supports broad observable coverage and both Bayesian and frequentist analyses, while its version 1.0 scope remains incomplete and under active development.
Problem
Flavour analyses must disentangle non-perturbative strong-interaction effects from possible new-physics contributions while comparing predictions and uncertainties across complex theoretical and statistical frameworks.
Method
flavio combines EFT-based observable predictions, an experimental-measurement database, likelihood modules, and visualization routines in an extensible Python package.
Results
The package supports new-physics effects through dimension-6 Wilson coefficients in WET or SMEFT and provides fast likelihoods independent of nuisance parameters for rapid inference after data changes.
Takeaways & Limitations
flavio offers a general open-source framework for precision analyses across flavour and other observables without restricting users to specific new-physics models or one statistical framework.
Takeaways & Limitations
As of version 1.0, many precision observables are still missing, although the package scope can extend to observables parameterized by dimension-6 Wilson coefficients.
Abstract
from arXiv · showhide
flavio is an open source tool for phenomenological analyses in flavour physics and other precision observables in the Standard Model and beyond. It consists of a library to compute predictions for a plethora of observables in quark and lepton flavour physics and electroweak precision tests, a database of experimental measurements of these observables, a statistics package that allows to construct Bayesian and frequentist likelihoods, and of convenient plotting and visualization routines. New physics effects are parameterised as Wilson coefficients of dimension-six operators in the weak effective theory below the electroweak scale or the Standard Model EFT above it. At present, observables implemented include numerous rare $B$ decays (including angular observables of exclusive decays, lepton flavour and lepton universality violating $B$ decays), meson-antimeson mixing observables in the $B_{d,s}$, $K$, and $D$ systems, tree-level semi-leptonic $B$, $K$, and $D$ decays (including possible lepton universality violation), rare $K$ decays, lepton flavour violating $τ$ and $μ$ decays, $Z$ pole electroweak precision observables, the neutron electric dipole moment, and anomalous magnetic moments of leptons. Not only central values but also theory uncertainties of all observables can be computed. Input parameters and their uncertainties can be easily modified by the user. Written in Python, the code does not require compilation and can be run in an interactive session. This document gives an overview of the features as of version 1.0 but does not represent a manual. The full documentation of the code can be found in its web site.
1 Introduction
flavio addresses the need for low-energy flavour probes of new physics by providing an open-source, general-purpose framework for precision phenomenology. Its Python-based EFT approach combines broad observable coverage, experimental data, likelihood construction, and visualization without committing to specific models or statistical frameworks.
- Motivation: Flavour-changing neutral currents are especially sensitive to new physics because they are forbidden at tree level in the Standard Model.
- Motivation: Non-perturbative strong-interaction effects complicate the separation of possible new-physics contributions from hadronic observables.
- Package scope: flavio provides a library of flavour, electroweak, and other low-energy observables expressed through dimension-6 Wilson coefficients in EFTs above or below the electroweak scale.
- Package scope: The package combines an experimental-measurement database, automatic likelihood construction, and plotting and visualization routines.
- Design choices: Written entirely in Python, flavio supports runtime extension and interactive execution, installs without compilation, and aims to cover observables beyond flavour physics.
- Design choices: flavio focuses on EFT effects rather than specific new-physics models and supports both Bayesian and frequentist statistical approaches.
2 Getting started
flavio can be installed and used across major operating systems and interactive environments. It also supports batch workflows, where importing the package once avoids repeated loading overhead.
- Installation: Python 3.5 or newer is supported on Linux, Mac, and Windows, with installation through pip.The package is hosted on the Python Package Index.
- Maintenance: The package can be upgraded when a new version is released, and installation problems can be reported through the GitHub issue page.The document also directs users to the relevant documentation for installing IPython or Jupyter.
- Usage modes: flavio can be used as an imported library, command-line interface, IPython session, or Jupyter Notebook.The interfaces range from a simple terminal session to browser-based interactive notebooks.
- Batch operation: Parameter scans should import flavio once because loading experimental measurements creates a significant one-time overhead.The recommended pattern is to implement the loop in Python after importing the package.
3 Overview of features
flavio computes Standard Model and new-physics predictions, propagates input uncertainties, and connects them with experimental measurements. Its EFT interface, probability-distribution database, likelihood tools, and plotting routines support phenomenological comparisons and inference.
- SM predictions and uncertainties: flavio computes central values and uncertainties for flavour observables in the Standard Model and beyond.Observables are selected by string identifiers, and differential quantities can depend on parameters such as q2.
- SM predictions and uncertainties: Uncertainties are estimated by sampling input parameters, evaluating the observable repeatedly, and extracting the standard deviation of the resulting values.The default procedure uses 100 iterations, while increasing N improves the sampling precision.
- New-physics predictions: New physics is specified through dimension-6 Wilson coefficients in the WET below or SMEFT above the electroweak scale.The wilson package handles renormalization-group evolution, matching, and basis translation; vanishing new-physics coefficients correspond to the Standard Model.
- Experimental measurements: Experimental measurements are stored as univariate or multivariate probability distributions, allowing correlated and non-Gaussian data to enter likelihood construction.Users can add measurements through the central YAML file and obtain predictions for a defined new-physics parameter point.
- Plotting and visualization: The plotting tools display measurement distributions and compare theoretical predictions with existing binned measurements.They support observables depending on kinematic variables such as q2 and can be supplemented with matplotlib labels.
4 Constructing likelihoods
flavio provides statistical routines and experimental measurements for constructing Bayesian or frequentist likelihoods, including general and fast likelihood approaches. The fast approach removes nuisance parameters but relies on assumptions that must be checked.
- flavio combines a database of experimental measurements with statistical routines to construct likelihoods for Bayesian or frequentist inference and new-physics tests.
- 4.1 General likelihoods: The general Likelihood class defines likelihoods using Wilson coefficients, theory parameters, theory predictions, experimental measurements, and parameter probability distributions.
- 4.1 General likelihoods: Default inclusion of all parameter constraints and measurements can produce inconsistent results, including constraints derived from measurements already included in the likelihood.
- 4.2 Fast likelihoods: FastLikelihood approximates experimental and theory information with covariance matrices, with theory covariance obtained by sampling theory parameters and experimental distributions approximated as multivariate Gaussians.
- 4.2 Fast likelihoods: The fast approach yields a nuisance-parameter-independent likelihood, while its time-consuming theory-covariance calculation is independent of the data and supports fast inference after data changes.
- 4.2 Fast likelihoods: FastLikelihood assumes Gaussian experimental and theory uncertainties and weak dependence of covariances on parameters, with the last assumption requiring checks whenever the method is used.
5 Further information and outlook
The version 1.0 overview directs readers to evolving online documentation and identifies missing precision observables. Continued implementation could broaden flavio toward global EFT likelihoods.
- The document describes flavio’s features at version 1.0 and directs users to updated online documentation and an interactive browser-based tutorial.
- Version 1.0 still lacks several important precision observables, including non-leptonic B decays, rare D decays, atomic EDMs, and nuclear and collider measurements.
- Adding further low-energy precision tests could make flavio a basis for a global likelihood in EFT parameter space for testing Standard Model extensions.