Open-source scientific software for flavour physics

HyperIsoFlavour observables · Wilson coefficients · statistical interpretation

A modular C++20 and Python framework for Standard Model and Beyond the StandardModel flavour studies. HyperIso combines model input, Wilson-coefficient evaluation, observable prediction, uncertainty propagation and statistical analysis in a common backend.

Download v1.0.3 Install from PyPI View on GitHub

Stable release · C++20 · Python · Linux · GNU GPL v3 or later

Scientific scope

One backend, several scientific workflows

The same runtime resolves inputs, computes Wilson coefficients and observables, propagates uncertainties and supports statistical inference through four public interfaces.

Physics

Wilson coefficients

Native SM, THDM and SUSY workflows, together with a MARTY-based route for user-defined BSM models at leading order.

Observables

Flavour predictions

Radiative, leptonic and semileptonic observables in the B, D and kaon sectors, including angular observables where available.

Statistics

Uncertainties and inference

Monte-Carlo propagation, covariance construction, maximum-likelihood estimation and two-dimensional confidence contours.

Interfaces

C++, Python, CLI and GUI

Compiled applications, notebooks, scripts, stable command-line workflows and interactive Dash studies all use the same backend.

Inputs

JSON, YAML and LHA-family files

Versioned defaults, explicit user overrides and LHA, SLHA or FLHA model inputs are combined through a documented precedence chain.

Reproducibility

Frozen reference suite

Release-level inputs, commands, expected outputs, numerical tolerances and binary provenance accompany the tagged source.

Quick start

Install, verify and run a first calculation

Choose the distribution that matches your workflow. Each path below ends with a concrete verification step, followed by ready-to-adapt CLI, Python and C++ examples.

01
Installation

Choose the setup that matches your workflow

Use the packaged release for analysis, an editable installation for development, or a local CMake installation for the C++ API and command-line interface.

Python
Recommended

Install from PyPI

Creates an isolated environment and installs the tagged Python package with its compiled backend.

Shellpyhyperiso 1.0.3
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "pyhyperiso==1.0.3"
python -c "import pyhyperiso; print(pyhyperiso.__version__)"
Use caseNotebooks, scans and scripted analyses
Source
Development

Install the local Python tree

Clone the tagged source and use an editable installation while working on wrappers, examples or tests.

ShellEditable source tree
git clone https://github.com/HyperIso/HyperIso.git
cd HyperIso
git checkout v1.0.3

python -m pip install ./Hyperiso/Hyperiso
# Editable install with tests:
python -m pip install -e "./Hyperiso/Hyperiso[test]"
Use caseContributing, wrappers, examples and local validation
CMake
Native build

Build the core and CLI with CMake

Build the C++20 libraries and hyperiso-ui, then install the exported CMake package under a user-owned prefix.

Requires CMake, Ninja, a C++20 compiler, GSL and Eigen
ShellRelease build
cmake -S Hyperiso/Hyperiso/core -B build \
  -G Ninja \
  -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_WITH_CLI=ON

cmake --build build -j
cmake --install build --prefix "$HOME/.local"
export PATH="$HOME/.local/bin:$PATH"
02
Verification

Check the installation with stable CLI workflows

These commands cover version reporting, Wilson coefficients, observable predictions and seeded uncertainty propagation.

VersionConfirm the executable
hyperiso-ui --version
hyperiso-ui --help
ObservablesCompute two SM predictions
hyperiso-ui observable summary \
  --observables BR_Bs__mu_mu,BR_B__Xs_gamma \
  --order NNLO
WilsonInspect B-sector coefficients
hyperiso-ui wilson summary \
  --groups BCoefficients \
  --coeffs C7,C9,C10 \
  --order NNLO
StatisticsRun a seeded uncertainty summary
hyperiso-ui statistic summary \
  --observables BR_Bs__mu_mu,BR_B__Xs_gamma \
  --uncertainties --draws 200 --seed 123456
03
First calculation

Evaluate the same observable from Python or C++

Both examples initialize the SM runtime from the FLHA input and evaluate the branching ratio for Bs → μ+μ− at NNLO.

Pythonexample.py
from pyhyperiso.Common import Model, Observables, QCDOrder
from pyhyperiso.Core import HyperisoConfig, HyperisoMaster
from pyhyperiso.Observable import ObservableInterface

master = HyperisoMaster()
master.init(
    lha_file="lha/si_input.flha",
    config=HyperisoConfig(model=Model.SM),
)

interface = ObservableInterface()
interface.add_observable(
    Observables.BR_BS_MUMU,
    QCDOrder.NNLO,
)
print(interface.compute_observable(Observables.BR_BS_MUMU))
python example.py
C++20main.cpp
#include <iostream>
#include "HyperisoMaster.h"
#include "Include.h"
#include "ObservableInterface.h"

int main() {
    HyperisoConfig config;
    config.model = Model::SM;

    HyperisoMaster master;
    master.init("lha/si_input.flha", config);

    ObservableInterface interface;
    interface.add_observable(
        Observables::BR_BS_MUMU,
        QCDOrder::NNLO
    );

    for (const auto& value : interface.compute_observable(
             Observables::BR_BS_MUMU)) {
        std::cout << value.id.str() << " = " << value.value << '\n';
    }
}
04
External C++ project

Link a standalone application against HyperIso

The installed package exports namespaced CMake targets. Point CMake to the installation prefix and link the observable backend.

Target Hyperiso::BusinessLogicLib

Provides the runtime, Wilson-coefficient and observable layers used by the example above.

ShellConfigure and run
cmake -S . -B build -G Ninja \
  -DCMAKE_PREFIX_PATH="$HOME/.local"
cmake --build build -j
./build/hyperiso_example
CMakeCMakeLists.txt
cmake_minimum_required(VERSION 3.20)
project(hyperiso_example LANGUAGES CXX)

set(CMAKE_CXX_STANDARD 20)
set(CMAKE_CXX_STANDARD_REQUIRED ON)

find_package(GSL REQUIRED)
find_package(Hyperiso REQUIRED)

add_executable(hyperiso_example main.cpp)
target_link_libraries(hyperiso_example PRIVATE
    Hyperiso::BusinessLogicLib
)
Complete examples Python examples C++ examples Build documentation CLI reference
Scientific examples

Prediction, validation and fit-oriented outputs

HyperIso supports precision observable calculations with propagated theory uncertainties as well as statistical interpretations in Wilson-coefficient parameter spaces.

HyperIso and SuperIso comparison for the P5 prime angular observable as a function of q squared.
Angular-observable comparisonIllustrative HyperIso and SuperIso predictions for P′5 in B → K* μμ, including uncertainty bands and the charmonium-resonance region.
Confidence contours in the delta C9 over C9 Standard Model and delta C10 over C10 Standard Model plane.
Confidence-contour representationExample confidence regions in the ΔC9/C9SM and ΔC10/C10SM plane for angular-observable fits.
Reproducibility

Compact R1–R7 reference suite

The release archive contains frozen inputs, CLI commands, expected outputs, tolerances and provenance metadata for compact release-to-release comparisons.

IDWorkflowReference check
R1B-sector Wilson coefficientsBCoefficients; C7, C8, C9, C10 at matching and low scales.
R2Scalar Wilson coefficientsBScalarCoefficients; CQ1μ and CQ2μ in the scalar sector.
R3Inclusive and leptonic observablesBR_Bs__mu_mu and BR_B__Xs_gamma.
R4Binned angular observableF_L_B0__K*0_mu_mu in the fixed q² bin [1.1, 6.0] GeV².
R5Seeded MC uncertainty propagationstatistic summary --uncertainties --draws 200 --seed 123456, including the frozen accepted-sample CSV.
R6THDM archived-spectrum benchmarkNNLO B-sector coefficients using the archived THDM spectrum with --spectrum true.
R7SUSY archived-spectrum benchmarkNNLO B-sector coefficients using the archived SUSY spectrum with --spectrum true.

The command definitions, input files, expected outputs and tolerances are recorded in reproducibility/manifest.json. Reference metadata also records the source tag, source commit, binary SHA-256 and build environment.

Browse the suite
Architecture

Modular by design

HyperIso separates the reference database, parameter overrides, model input, coefficient generation, observable calculations and statistical interpretation.

Reference database

Version-controlled JSON assets define the default numerical setup used by a clean installation.

User overrides

YAML files record explicit changes to values, uncertainties and phenomenological conventions.

Model inputs

LHA, SLHA and FLHA files supply the model-dependent numerical layer at runtime.

Common prediction layer

Wilson coefficients, observables and fit routines consume the same resolved parameter cache.

HyperIso data flow from model inputs through the database, Wilson coefficients, observables and statistical analysis.
High-level data flow shared by the public interfaces.
Resources

Code, archive, package and documentation

The tagged source, Python package, versioned software DOI and generated documentation are aligned with release 1.0.3.

Source

GitHub repository ↗

Code, issues, workflows and contribution history.

 Release

GitHub release ↗

Release notes, generated archives and distribution artifacts.

 Archive

Zenodo record ↗

Permanent software DOI and citation export for v1.0.3.

 Python

PyPI package ↗

Python distribution and source package for pyhyperiso.

 Reference

API documentation ↗

Generated API pages, examples and usage guides.

 Citation

CITATION.cff ↗

Machine-readable software citation metadata.

 Ecosystem

MARTY ↗

Symbolic BSM calculations and generic-model coefficient generation.

 BibTeX

Reference bundle ↓

Software, proceeding and related methodological references.
Software and methodological references

How to cite HyperIso

Please cite the versioned Zenodo software release. The proceeding and related methodological publications provide additional scientific context.

2026

HyperIso software archive v1.0.3

Versioned software release and formal archival citation.

DOI ↗
2026

HyperIso: A general BSM calculator for flavour observables

T. Reymermier, N. Fardeau and F. Mahmoudi · PoS EPS-HEP2025 (2026) 351

DOI ↗
2021

MARTY — A C++ framework automating symbolic calculations Beyond the Standard Model

G. Uhlrich, F. Mahmoudi and A. Arbey · Computer Physics Communications 264 (2021) 107928

DOI ↗
2012

Flavour Les Houches Accord: Interfacing flavour-related codes

F. Mahmoudi et al. · Computer Physics Communications 183 (2012) 285–298

DOI ↗
2009

SuperIso v3.0: Flavour observables in 2HDM and supersymmetry

F. Mahmoudi · Computer Physics Communications 180 (2009) 1579–1613

DOI ↗
Project team

Development and scientific coordination

The project combines software engineering, observable implementation, validation and scientific supervision.

Lead developer

Théo Reymermier

Software architecture, Wilson coefficients, Python and CLI interfaces, GUI, validation and reproducibility workflows.

Developer

Niels Fardeau

Mathematical routines, statistical framework, LHA parsing, observable calculations and validation studies.

Scientific supervision

Nazila Mahmoudi

Methodology, validation guidance, flavour-physics expertise and scientific oversight.

Open source

GNU General Public License v3 or later

You may run, study, modify and redistribute HyperIso under the GPL terms. Redistribution of the software or modified versions must preserve the licence notices and provide the corresponding source code as required by the GPL.

The software is provided without warranty. Third-party components remain subject to their own licences and notices.

Read the GPL licence ↗ Third-party notices ↗ Citation metadata ↗