PaperlayerView exact revision on arXiv

Source-linked AI summary

GAMBIT: The Global and Modular Beyond-the-Standard-Model Inference Tool

The GAMBIT Collaboration, Peter Athron, Csaba Balazs, Torsten Bringmann, Andy Buckley, Marcin Chrząszcz, Jan Conrad, Jonathan M. Cornell, Lars A. Dal, Hugh Dickinson, Joakim Edsjö, Ben Farmer, Tomás E. Gonzalo, Paul Jackson, Abram Krislock, Anders Kvellestad, Johan Lundberg, James McKay, Farvah Mahmoudi, Gregory D. Martinez, Antje Putze, Are Raklev, Joachim Ripken, Christopher Rogan, Aldo Saavedra, Christopher Savage, Pat Scott, Seon-Hee Seo, Nicola Serra, Christoph Weniger, Martin White, Sebastian Wild

arXiv:1705.07908v2hep-phastro-ph.CO

TL;DR

Global fits must combine disparate data to make rigorous statements about which theories are allowed, yet existing frameworks are difficult to extend. GAMBIT provides a modular global-fitting framework with automatic dependency resolution and multiple scanning options. This paper describes the framework and its implemented components.

  • Problem

    Global fits must combine disparate experimental data to assess theories, while existing frameworks are difficult to extend with new observables, datasets and likelihoods.

    Source: §1 · p. 3

  • Method

    GAMBIT combines a hierarchical model database and physics modules with automatic dependency resolution and ScannerBit sampling and statistics.

    Source: §1 · p. 3, §2.2 · p. 9, §8.1 · p. 45

  • Results

    The paper describes GAMBIT as a flexible global-fitting framework and details its design and currently implemented components.

    Source: §1 · p. 3

  • Takeaways & Limitations

    GAMBIT provides a framework for global BSM analyses that connects requested quantities to compatible calculations and sampling methods.

    Source: §1 · p. 3, §2.2 · p. 9, §8.1 · p. 45

    BOSS does not yet support backend template classes or some C++ constructs, and support for function pointers and C++11 declarations is partial.

    Source: §4.5 · p. 24

Abstract

from arXiv · show

We describe the open-source global fitting package GAMBIT: the Global And Modular Beyond-the-Standard-Model Inference Tool. GAMBIT combines extensive calculations of observables and likelihoods in particle and astroparticle physics with a hierarchical model database, advanced tools for automatically building analyses of essentially any model, a flexible and powerful system for interfacing to external codes, a suite of different statistical methods and parameter scanning algorithms, and a host of other utilities designed to make scans faster, safer and more easily-extendible than in the past. Here we give a detailed description of the framework, its design and motivation, and the current models and other specific components presently implemented in GAMBIT. Accompanying papers deal with individual modules and present first GAMBIT results. GAMBIT can be downloaded from gambit.hepforge.org.

1 Introduction

Global fits must combine data from disparate experiments to assess theories, but existing tools are limited in scope and difficult to extend. GAMBIT is introduced as a flexible, extensible framework for global BSM analyses, with this paper serving as an introduction and reference manual.

1 Introduction

  • Global fits combine predictions for many observables with statistical analyses of experimental searches, but weighing disparate data and making rigorous statements about allowed models is challenging.The introduction frames this as a multidisciplinary task spanning particle, astroparticle and nuclear physics.Source: §1 · pp. 2–3
  • Existing BSM global fits focus mainly on SUSY, and theory-specific software and long recoding cycles have limited analyses of other models.The introduction argues that rigorous global fits are needed for a wider range of theories.Source: §1 · p. 3
  • Existing frameworks lack easy public integration of new observables, datasets and likelihoods, and streamlined interfaces to external codes.Only one of the major SUSY global-fit codes had a public release, and that code was discontinued.Source: §1 · p. 3
  • Joint analyses of high-dimensional BSM parameter spaces require substantial theory, experimental, coding, computing and statistical expertise.Most global fits have used either Bayesian or frequentist statistics and a single sampling algorithm, despite complementary alternatives.Source: §1 · p. 3
  • GAMBIT is introduced as a flexible, extensible global-fitting framework, and the paper announces its public release, presents its design and serves as a reference manual.Accompanying papers describe constituent modules and report first results for SUSY and scalar singlet dark matter [119] [120] [121].Source: §1 · pp. 3–4

2 Design overview

GAMBIT’s design combines modular physics calculations, external backends and a hierarchical model database to assemble model-compatible analyses from reusable components. It supports this through runtime dependency resolution, deferred function selection, parallel scans and standalone module drivers.

2 Design overview

  • The framework comprises physics modules, ScannerBit and Core components; ScannerBit handles parameter sampling, prior transformations and interfaces to scanning and optimization packages.Physics modules include DarkBit and ColliderBit.Source: §2 · p. 5

2.1.1 Physics modules, observables and likelihoods

  • Physics modules provide observables, likelihoods and intermediate quantities through functions whose capability-type declarations let GAMBIT match dependencies automatically.At runtime, GAMBIT selects functions by matching declared capabilities and return types to the quantities and types requested by dependencies.Source: §2.1.1 · pp. 6–7

2.1.2 Backends

  • Backend requirements match module functions to backend functions or variables at runtime, allowing any qualifying backend to fulfil a request.Backend implementations can be written in any language, and matching requirements enable substitution among available backend versions.Source: §2.1.2 · pp. 7–8

2.1.3 Models

  • Model ancestry and parameter translations let GAMBIT activate compatible functions, reuse calculations across parameterisations and combine models in joint scans.Joint scans can vary Standard Model parameters as nuisance parameters alongside a BSM model; ancestry-based activation forbids calculations invalid for the scan.Source: §2.1.3 · p. 8

2.2 Adaptability and flexibility

  • GAMBIT resolves requested quantities into a directed acyclic dependency graph, then orders and optimizes function evaluation so prerequisites run first.The ordering also considers typical evaluation time and each function’s role in ruling out parameter combinations.Source: §2.2 · p. 9
  • GAMBIT reuses compatible calculations for new models, runs only required calculations once per parameter combination, and identifies missing or incompatible dependency links.Its backend and build systems can automatically add or disable components, and command-line diagnostics report component status and contents.Source: §2.2 · p. 10

2.3 Performance and parallelisation

  • MPI scanner-level and OpenMP module-function parallelism lets GAMBIT scale to thousands of cores and reduce a single MSSM combination, including LHC Monte Carlo simulation, to seconds [108].GAMBIT can connect OpenMP-aware module functions so other module functions run them in parallel.Source: §2.3 · p. 10

2.4 Available examples

  • Any GAMBIT module can be compiled with a basic driver as a standalone program, and utility functions let standalone drivers specify models, parameter values, module functions, dependencies, and backend functions or variables.The paper gives examples for running full GAMBIT code and standalone module drivers, including dedicated examples for modules in the first release [108] [109] [110] [111] [112].Source: §2.4 · p. 10

3 Modules

This section describes GAMBIT’s modular architecture, in which declarations specify function compatibility, dependencies, backend requirements, and access rules, while dependency-resolved pipes and loop managers connect and execute functions, including in parallel.

3 Modules

  • GAMBIT 1.0.0 has six physics modules and one scanning module, plus a virtual BackendIniBit for backend initialization and effective modules for model-parameter translation.The translation functions are assigned to effective modules of their own.Source: §3 · pp. 10–11

3.1 Module function declaration

  • Functions are standard C++ void functions taking one by-reference result argument, with their result type and capability declared in the module’s rollcall header.The result type must have a default constructor unless the module instead declares objects internally and returns pointers to them.Source: §3.1 · p. 11

3.1.1 Model compatibility

  • GAMBIT supports simultaneous scans of multiple models with independently varied parameters, letting functions require parameter values from arbitrary model combinations.Model declarations also grant runtime access to the relevant parameters; a model counts as in use even when its parameters are fixed during a scan.Source: §3.1.1 · pp. 11–12

3.1.2 Dependencies

  • Module functions depend on capabilities rather than specific functions, allowing GAMBIT to schedule producers first and deliver their results for the same parameter combination.Dependencies can be conditional on models or backend choices, but the framework does not support more complex combined conditions; such cases may call for splitting the function.Source: §3.1.2 · pp. 12–13

3.1.3 Backend requirements

  • Backend requirements identify a capability and type, while tags, model activation, backend options and same-backend rules constrain how requirements are filled.Specific backend versions may be listed, but version ranges cannot be specified except by listing each version explicitly.Source: §3.1.3 · p. 13

3.1.4 Parallel module functions

  • GAMBIT supports OpenMP within a single module function without special rollcall declarations, or through a loop manager that calls nested module functions inside an OpenMP block.Loop managers are declared using the CAN_MANAGE_LOOPS switch.Source: §3.1.4 · p. 14
  • The dependency resolver builds runtime mini dependency trees for nested functions, supplies ordered function lists to loop managers, and waits for their dependencies before invoking a loop.The Core does not ordinarily invoke nested functions itself; if a loop runs zero iterations and another function needs an unrun nested result, it evaluates that function on demand.Source: §3.1.4 · p. 14

3.1.5 One-line module function declaration

  • A QUICK_FUNCTION declaration can specify a module function's capability, type, allowed models, and dependencies in one line, with optional model and dependency lists of up to 10 entries each.The declaration also specifies whether the capability is new or previously declared; an empty model list is needed when dependencies are specified without model restrictions.Source: §3.1.5 · p. 14

3.2 Pipes

  • Module functions must be self-contained and avoid direct calls between functions, backend calls, and order-sensitive global state; their pipes let the resolver connect them to permitted data streams.Pipes are safe pointers declared with module functions; the resolver can set them and their data, while module-function code generally cannot.Source: §3.2 · pp. 14–15

3.2.1 Accessing dependencies

  • Functions access dependency values through safe pointers and can query the providing function's module, name, capability, and type from the dependency pipe.Source: §3.2.1 · p. 15

3.2.2 Accessing backend requirements

  • Backend requirement pipes provide access to backend variables and functions, and the system enforces type-safe calls; byVal() marks non-literal arguments that must be passed by value.A requirement pipe's pointer() method can provide the underlying backend function or variable pointer when needed.Source: §3.2.2 · pp. 15–16

3.2.3 Accessing model parameters

  • Model parameters are provided only to model-dependent functions, and ancestor-model functions receive ancestor parameters, enabling unaltered reuse with descendant models that may not yet exist.When multiple allowed ancestors apply, the least-distant ancestor's parameters are delivered.Source: §3.2.3 · p. 16

3.2.4 Accessing options from the input file

  • The dependency resolver generates a function-specific runOptions pipe from applicable input YAML entries, which functions can query or use to retrieve option values with or without defaults.Source: §3.2.4 · p. 16

3.2.5 Managing parallel module functions

  • Loop managers run nested dependency chains through OpenMP iterations, with thread-specific results enabling parallel execution and serial first and final iterations recommended for initialization and downstream synchronization.Nested functions can call wrapup() to signal termination; other threads may complete additional iterations before noticing the done flag.Source: §3.2.5 · p. 17

4 Backends

This section describes how GAMBIT loads backends as runtime plug-ins, connects their functions and variables to module requirements, and handles backend initialization and types. It introduces BOSS for generating interfaces to runtime-loaded C++ classes and the backend information utility, noting BOSS’s limitations, including unsupported backend template classes.

4 Backends

  • GAMBIT loads backend shared libraries at runtime, while capability tags match backend functions to module requirements and allow interchangeable backends that calculate the same quantity.Backend functions and variables can be declared model-independent or restricted to specified models.Source: §4 · pp. 17–18, §4.1 · p. 18

4.1 Backend function declaration

  • Backend functions are registered with their return type, call signature, library symbol, name, and capability using BE_FUNCTION; BE_VARIABLE similarly registers backend global variables.Function and variable declarations can also specify model restrictions.Source: §4.1 · p. 18

4.2 Convenience functions

  • BE_CONV_FUNCTION registers convenience functions that combine backend calls or variable manipulations into one GAMBIT-accessible function without requiring a library symbol.Convenience functions can be defined in a frontend header or separate source file and can be model-dependent.Source: §4.2 · p. 19

4.3 Backend initialisation functions

  • Backend initialization functions run before other operations from their backend and can reset state per parameter point, perform scan-level setup, and declare dependencies on GAMBIT module outputs.For scan-level initialization that writes temporary files, GAMBIT provides a file-locking utility to prevent simultaneous execution across MPI processes.Source: §4.3 · pp. 19–20

4.4 Backend types

  • CBGB parses Fortran backend code and generates GAMBIT declarations for required types, functions, and variables; GAMBIT also provides compatibility types and array and string classes for Fortran data.CBGB uses a configuration listing input files, functions, and common blocks; GAMBIT’s Farray class handles Fortran array indexing and storage semantics.Source: §4.4 · pp. 20–21

4.5 Loading C++ classes at runtime with BOSS

  • Existing C++ tools pose a runtime-loading problem because GAMBIT cannot impose a predefined factory interface on tools that already exist; BOSS is introduced to address this challenge.The passage identifies BOSS as a Python-based Backend-On-a-Stick Script, but does not describe its operation in this part.Source: §4.5 · p. 21
  • BOSS mirrors backend class inheritance with generated abstract base classes and constructor factories, enabling backend classes to be loaded at runtime.The generated ladder pattern mirrors the original class hierarchy; virtual inheritance avoids ambiguities.Source: §4.5 · p. 22, Figure 3 · p. 22
  • Generated interface classes wrap pointers to abstract classes, letting GAMBIT users access backend classes through a familiar interface.Factories initialize the pointers with instances of the original classes, and BOSS can also generate wrappers for global functions using those classes.Source: §4.5 · p. 22, Figure 4 · p. 23
  • BOSS uses CastXML and a Python configuration file to select backend classes and functions and specify their source and include paths.The configuration can restrict the GAMBIT-facing interface to selected classes while allowing independently included classes to be declared as known classes.Source: §4.5 · p. 23
  • BOSS does not yet support backend template classes or STL specialisations parameterised by backend classes, and support for function pointers and C++11 declaration features is partial.When a limitation affects a member, BOSS may exclude that member from the generated interface.Source: §4.5 · p. 24

4.6 Backend information utility

  • Backends::backendInfo() exposes runtime information on connected backends, including versions, class-loading status, and backend paths.It can also return the default version required by an unversioned NEEDS_CLASSES_FROM declaration.Source: §4.6 · p. 24

5 Hierarchical model database

This section describes GAMBIT’s hierarchical model database, including how scan parameters, model relationships, and parameter-to-capability mappings support dependency resolution. It catalogs model declarations and parameterizations spanning Standard Model, Higgs-sector, scalar-singlet, MSSM, flavour EFT, nuisance, and toy models.

5.1 Model declaration

  • Models are linked by parent–child translations and optional friend links, which the dependency resolver uses to determine function compatibility and resolve translation pathways.Translations may depend on module calculations, but the full machinery for conditional dependencies available to module functions is not supported for translation functions.Source: §5.1 · pp. 24–25

5.2 Model capabilities

  • A model parameter can be mapped directly to a capability, allowing GAMBIT to create a virtual module function that returns the parameter value.This shortcut covers only direct correspondences; transformations such as unit changes or dependencies on other calculations require a separate module function.Source: §5.2 · p. 26

5.3 Defining translation functions

  • Translation functions convert source-model parameters into parent or friend parameters, can copy matching values automatically, and can retrieve dependencies on externally calculated quantities.The functions take source and target ModelParameters objects; setValues can copy matching parameters and, by default, errors if source parameters are absent from the target.Source: §5.3 · p. 27

5.4 Models defined in GAMBIT 1.0.0

  • The first release of GAMBIT lists the models already defined in it, along with their parameters; the relationships between these models are shown in Fig. 2.Source: §5.4 · p. 27

5.4.1 Standard Model

  • The Standard Model is split between StandardModel_SLHA2 and separate Higgs-mass models, which are scanned together when studying the SM alone or an appropriate BSM theory.StandardModel_SLHA2 contains SM input parameters including couplings, masses, and mixing parameters defined in SLHA2 [168].Source: §5.4.1 · pp. 27–28
  • StandardModel_Higgs uses the tree-level Higgs mass as a free parameter, while StandardModel_Higgs_running supports calculations requiring running parameters and pole-mass corrections.The simple model can provide a spectrum without running; translation to its running parent sets m2_H to the tree-level mass squared and QEWSB to mt.Source: §5.4.1 · p. 28

5.4.2 Scalar singlet

  • SingletDM offers a simplified scalar-singlet model, while SingletDM_running includes the running couplings needed for pole-mass and vacuum-stability calculations.The simplified model omits the singlet quartic; translation to the running parent sets it to zero at mZ, though renormalisation group evolution regenerates it at other scales.Source: §5.4.2 · pp. 28–29

5.4.3 Weak-scale MSSM

  • The MSSM63 is the most general CP-conserving MSSM formulation, with 63 Lagrangian parameters; C terms, CP-violating gaugino masses, and complex phases are set to zero.Parameters are defined in the DR scheme at scale Q, except tan β, which is defined at mZ.Source: §5.4.3 · p. 30

5.4.4 GUT-scale MSSM

  • GUT-scale MSSM variants define soft parameters at the unification scale, and translating them to weak-scale parameters requires solving the model’s renormalisation group equations.The section also introduces NUHM2 as a reduced model descended from MSSM63atMGUT, with off-diagonal slepton mass elements set to zero and diagonal elements set equal.Source: §5.4.4 · p. 31
  • GUT-scale MSSM entries include NUHM1 with one Higgs mass parameter and CMSSM with a universal scalar mass m0; mSUGRA is commonly a CMSSM pseudonym.Source: §5.4.4 · p. 32

5.4.5 Flavour EFT

  • The Flavour EFT model varies the real and imaginary parts of Wilson coefficients for O7, O9, O10, Q1, and Q2, focusing on differences between expected SM and BSM values.Source: §5.4.5 · p. 32

5.4.6 Nuisance parameters

  • Halo nuisance models specify Milky Way dark-matter profiles and local properties for direct detection and solar capture, using generalized NFW or Einasto profiles and independent or derived density parameters.Source: §5.4.6 · pp. 32–33
  • Nuclear nuisance models parameterize nucleon quark and proton spin content, with alternatives replacing quark matrix elements by σl and σ0 or by σ0 and σs.Source: §5.4.6 · p. 33

5.4.7 Toys

  • Toy entries include a two-parameter Gaussian test model and a one-dimensional model for debugging prior transformations or serving as a dummy model; additional examples remain commented out to avoid cluttering the hierarchy.Source: §5.4.7 · p. 33

6 User interface and input file

Section 6 describes GAMBIT’s YAML input interface for configuring scans, including models, priors, observables, likelihoods, calculation and output settings, and scanner and printer plugins. It also explains how input rules resolve dependencies and backends, set module-function options, route logs, and control general behavior.

6.1 Command line switches and general usage

  • GAMBIT starts with `gambit`; `-f` supplies the YAML instructions, while `--dry-run` resolves dependencies and backend requirements without scanning, and `-r` restarts and overwrites output.Without `-r`, matching previous output can be used to resume a scan; dry runs also generate dependency-tree plotting files and instructions.Source: §6.1 · p. 34

6.2 The master initialisation file

  • The YAML master file uses indentation-sensitive syntax and has eight top-level entries for parameters, priors, targets, rules, output, scanning, logging, and global options.Any section can import other YAML files with `!import`, and imported files may themselves import further files.Source: §6.2 · p. 34

6.3.1 General setup and fast priors

  • Multiple models, including particle, dark-matter halo, and nuclear-physics models, can be scanned together, making it straightforward to add observables with additional nuisance parameters.The same arrangement supports observables spanning particle physics and cosmology or BSM and neutrino physics.Source: §6.3.1 · p. 35
  • Fast priors in `Parameters` can fix values, cycle through ordered values, specify flat, log, or trigonometric distributions, and link model parameters using `same_as`.A linked parameter can be scaled and shifted; parameters lacking a fixed value, `prior_type`, or `same_as` default to a flat prior when a range is given.Source: §6.3.1 · pp. 35–36

6.3.2 More involved priors

  • Correlated multidimensional priors must be declared in the separate `Prior` section, which supports Gaussian and Cauchy distributions and available ScannerBit prior plugins.Each declaration specifies its input-parameter vector, prior type, and any required options.Source: §6.3.2 · p. 36

6.4 ObsLikes: Target observables and likelihoods

  • `ObsLikes` entries request likelihoods or observables by capability and purpose: likelihoods drive the scan, while observables are recorded for post-processing.Likelihoods use log L = ln(likelihood); optional type, function, and module arguments help resolve competing providers, and `printme` defaults to true for recording results.Source: §6.4 · pp. 36–37

6.5.1 Module function dependencies

  • Rules resolve requested capability/type pairs to module functions, can specify dependency chains, and produce an error when conflicting rules are found.Rules can also be marked weak and overrideable; type matching incorporates configured type equivalences.Source: §6.5.1 · pp. 37–38

6.5.2 Backend requirements

  • Backend rules guide requirement resolution and can request specific versions, restrict permitted backends, or require requirements to use the same backend version.Some requirements can be conditional on the model.Source: §6.5.2 · pp. 38–39

6.5.3 Options for module functions

  • Rules can set module-function options, including the relic-density calculator’s fast = 1 accuracy setting, and ambiguous matching options cause an initialization error.Options may use simple or composite types; options never requested at runtime are silently ignored.Source: §6.5.3 · p. 39

6.6 Printer

  • The printer system routes scan output through a runtime-selected plugin, with ASCII tables for simplicity and HDF5 files better suited to large datasets.The common output_path and output_file options set the destination directory and filename; the ASCII printer’s buffer_length defaults to 100 model points.Source: §6.6 · p. 39, §6.6.1 · p. 40, §6.6.2 · p. 40

6.6.3 Specific options: hdf5 printer

  • HDF5 output can be organized in groups and appended to existing files, but reusing an existing group causes an error and write failures can corrupt files.Deleting groups does not reclaim their disk space without copying the file’s contents; separate files are safer when write errors are a concern.Source: §6.6.3 · p. 40

6.6.4 Output selection

  • Only results of module functions selected to fulfill ObsLikes capabilities are output; intermediate dependency results are not, and nonprintable results can be targeted without printing during debugging.The printer system cannot automatically output every result because some C++ types are not printable by every printer.Source: §6.4 · p. 37, §6.6.4 · p. 41

6.7 Scanner

  • Scanner plugins are selected in the YAML Scanner section along with plugin-specific options.GAMBIT ships with multiple plug-and-play scanner plugins.Source: §6.7 · p. 41
  • Scanner definitions can be named and selected with `use_scanner`; plugin options configure them, while multiple test-function objectives can be multiplied for a scan [112].GAMBIT also supplies objective test functions for testing scanners and other code components.Source: §6.7 · p. 41

6.8 Logger

  • Logger settings set a log-file prefix and route messages from specified components to designated output files.The prefix defaults to `default_output_path`.Source: §6.8 · p. 41

6.9 KeyValues: general purpose options

  • KeyValues options control general GAMBIT behavior; listed values are defaults when present, while options without defaults are required.Controls include invalid-point likelihood thresholds, debugging and exception fatality, model-specific function preference, output paths, MPI shutdown, and RNG selection.Source: §6.9 · pp. 41–42

7 Dependency Resolver

GAMBIT's dependency resolver builds a scan-specific dependency tree from requested observables and likelihoods, then orders and configures the functions needed to compute them. It also resolves backend choices and nested parallel loops while applying user-specified options.

7 Dependency Resolver

  • The resolver constructs a directed acyclic graph from scanned models and parameters to requested observables and likelihoods, selecting compatible functions and resolving dependencies automatically where possible.When multiple functions can provide the same quantity, input-file rules can specify the choice.Source: §7 · p. 42

7.1 General procedure

  • Resolution disables functions incompatible with the scanned models, works back from requested quantities, applies model-specific preferences and rules, and activates chosen functions and their dependencies.The process repeats until the dependency queue is empty.Source: §7.1 · pp. 42–43

7.2 Evaluation order

  • The resolver topologically sorts dependencies and orders likelihoods to minimise expected time until invalidation, using observed runtimes and invalidation frequencies updated during the scan.This can run fast physicality checks before expensive collider constraints; mutually dependent quantities require internal iteration or function-pointer workarounds.Source: §7.2 · pp. 43–44

7.3 Resolution of backend requirements

  • Backend requirements are resolved through repeated passes that defer ambiguous choices until linked requirements become resolvable, then fail if a final pass cannot resolve them.Groups may require all members to resolve or allow one matching backend function to satisfy the group.Source: §7.3 · pp. 44–45

7.4 Resolution of loops and nested functions

  • Loop managers receive miniature dependency trees for their nested functions and execute those functions in the resolver-provided order, enabling automatically parallelised loops.Nested functions declare a dependency on a loop manager capability.Source: Figure 5 · p. 43, §7.4 · p. 45

7.5 Option resolution

  • For each activated function, matching YAML Rules entries are collected into its runOptions pipe, and conflicting values for the same option trigger an error.Source: §7.5 · p. 45

8 Statistics and scanning

GAMBIT uses ScannerBit to sample model parameters through a dependency-resolved likelihood container, then supports statistical interpretation of scan outputs. It also supplies generic likelihood forms whose treatment of uncertainties depends on whether nuisance quantities are profiled or marginalised.

8.1 The role of ScannerBit

  • ScannerBit applies requested prior transformations, runs a selected sampling plugin, and sends sampled parameter combinations through a likelihood container assembled from the dependency tree.Available plugins include nested sampling, MCMC, population-based Monte Carlo, differential evolution, and grid or random samplers.Source: §8.1 · p. 45

8.2 Analysing samples

  • Saved samples can support Bayesian or frequentist inferences, while printer options enable output compatible with GetDist and pippi for plots and statistical summaries.The paper notes that not all inference options are valid for every sampler, and p values require a user-chosen log-likelihood distribution ansatz.Source: §8.2 · p. 46

8.3 Available likelihood forms

  • GAMBIT provides generic Gaussian and log-normal likelihoods for simple observables and uncorrelated data, with runtime options to profile or marginalise systematic uncertainties.More complicated likelihood calculations may have dedicated implementations.Source: §8.3 · p. 46

8.3.1 Profiled Gaussian / 8.3.2 Marginalised Gaussian

  • For Gaussian measurements, an additive Gaussian nuisance offset can be profiled or marginalised to obtain a likelihood for the observed quantity alone.Setting the profiling-versus-marginalisation option differently across functions may yield an arguably inconsistent composite likelihood.Source: §8.3.1 · p. 46, §8.3.2 · p. 47

8.3.3 Profiled Gaussian limits

  • Gaussian upper-limit likelihoods are flat below the limiting value and fall with Gaussian width above it; published limits typically need two confidence levels to infer the central value and width.The corresponding lower-limit form reverses the inequalities.Source: §8.3.3 · p. 48

8.3.4 Marginalised Gaussian limits

  • When systematic inputs are not strictly frequentist, profiling a Gaussian limit can produce an undesirable non-flat profile; marginalisation preserves flatness below the limit regardless of σϵ.The authors recommend marginalised variants in that case, even when the scan will ultimately report profile likelihoods.Source: §8.3.3 · p. 48, §8.3.4 · p. 48

8.3.5 Profiled log-normal

  • The log-normal likelihood models Gaussian variation in the logarithm of an observable, with multiplicative systematics represented by a log-normal error centred on 1.Its scale sensitivity makes it prone to systematics that also affect the observable's scale.Source: §8.3.5 · pp. 48–49

8.3.6 Marginalised log-normal

  • Profiled and marginalised log-normal likelihoods behave similarly in the toy comparison, while fixed absolute systematics can introduce extra features at low µ.The comparison also considers fixed fractional relative uncertainty.Source: §8.3.6 · p. 49

9 Output

GAMBIT's Printer subsystem routes scan output through a runtime-selected printer, with formats including ASCII tables and synchronised HDF5 datasets. The section also describes output identifiers, format-specific constraints, and how users can extend printable types.

9 Output

  • GAMBIT sends print commands through an abstract interface to a printer chosen at runtime, and issues module-function output automatically during evaluation.Writing a new printer is specialised and requires knowledge of the subsystem's class structure.Source: §9 · p. 49

9.1 Overview of the output format

  • Print commands identify their source and parameter-space point; MPIrank and pointID together provide a globally unique point identifier.Printers assemble these inputs into coherent output, while scanner plugins can add information such as posterior weights.Source: §9.1 · p. 50

9.2.1 ASCII output

  • The ASCII printer writes buffered print results as whitespace-separated rows and records column labels in an accompanying info file.Auxiliary posterior weights use a separate stream and can be joined to point data using MPIrank and pointID.Source: §9.2.1 · pp. 50–51
  • ASCII table columns are fixed from the buffer contents before the first dump, so variable-length vectors require a maximum-length example before that dump.Source: §9.2.1 · p. 50

9.2.2 HDF5 output

  • HDF5 output stores one synchronised dataset per quantity across scan points, with matching _isvalid datasets that flag invalid entries for filtering.The described layout applies to the final combined scan output.Source: §9.2.2 · pp. 51–52

9.3 Expanding the printable types

  • To make a new C++ result type printable, users register the type and add printer-specific overloads; corresponding inverse-printer support may also be needed for postprocessing.The example converts a map into vectors of values and labels for the ASCII buffer.Source: §9.3 · p. 52

10 Utilities

This section describes GAMBIT utilities for standardized particle handling, logging and diagnostics, exception control, type resolution, and thread-safe random-number generation, as well as documenting random-number choices and components and supporting scan shutdown and resumption with scanner-specific handling of quit flags.

10.1 Particle database

  • The particle database standardizes particle references across GAMBIT, includes SM and MSSM particles and other entries, and supports SM-specific handling and generic decay-channel states.Particles can be identified by full name, PDG-context pair, or short name and set index; generic states cannot be used in mass-spectrum calculations.Source: §10.1 · pp. 52–53

10.2 Logging

  • GAMBIT logging writes tagged messages to disk, supports routing by tags and module, and separates log files by MPI rank.The default output path can be overridden through YAML settings, while matching is inclusive, so messages with Error or Fatal tags can also appear in the default log.Source: §10.2 · pp. 53–54

10.3 Exceptions

  • Invalid-point exceptions can short-circuit likelihood calculations, skipping later dependency-tree work; invalid observables not needed for the likelihood do not invalidate the point.Errors are fatal by default and warnings non-fatal, with configurable fatality; piped exception objects let nested functions defer exceptions across OpenMP boundaries.Source: §10.3 · pp. 54–55

10.4.1 Modules diagnostic

  • Diagnostics report available modules and capabilities, and show backend versions, library locations, published functions and variables, and load status.Backend status distinguishes OK, absent/broken, and bad types; a non-OK BOSSed library disables module functions needing its classes, while individual symbol errors can disable only affected functions or variables.Source: §10.4 · p. 55, §10.4.1 · p. 55, §10.4.2 · p. 55

10.4.4 Models diagnostic

  • Model, scanner, test-function, and prior diagnostics list their respective contents, versions, or options; free-form queries provide component status, relationships, and detailed information.Queries can report model family trees and parameters, plugin headers and links, module dependencies and backend requirements, or which functions can compute a capability.Source: §10.4.4 · p. 56, §10.4.5 · p. 56, §10.4.6 · p. 56

10.5 Type handling

  • Dependency resolution matches capabilities and types; backend types are broadly available, while module and model types are restricted to associated functions.Because types are matched as strings at runtime, GAMBIT uses an equivalency database to treat typedefs in the same class as identical for resolution.Source: §10.5 · p. 57

10.6 Random numbers

  • GAMBIT provides thread-safe wrappers for C++11 random-number generators, maintaining a separate generator per thread seeded with system clock time plus the thread index.The underlying generator used by Random::draw() can be configured in the input file’s KeyValues section.Source: §10.6 · p. 57
  • GAMBIT accepts recognized C++ random engines, and its default generator in version 1.0.0 is the 64-bit Mersenne Twister mt19937_64.The engine can be selected by name or by using default.Source: §10.6 · pp. 57–58

10.7 Component databases and documentation

  • Descriptive databases document models, capabilities, scanners, objective test functions, and priors; adding descriptions for new components is recommended, and missing descriptions trigger a warning.The databases are editable YAML text files, while Doxygen documents GAMBIT classes, functions, variables, namespaces, and macros.Source: §10.7 · p. 58

10.8 Signal handling and resuming a scan

  • GAMBIT can resume a prematurely terminated scan by reusing its original YAML file without the -r flag; ScannerBit and each scanner plugin handle preservation of scan-algorithm state [112].On SIGINT, SIGTERM, SIGUSR1, or SIGUSR2, GAMBIT attempts a clean shutdown while preserving output and information needed to resume.Source: §10.8 · p. 58

10.8.1 Shutdown behaviour

  • When a scanner plugin supports a quit flag, GAMBIT completes the current likelihood evaluation, broadcasts a stop command, finalizes output, and lets the plugin shut down before MPI exits.GAMBIT infers quit-flag support from whether the plugin calls like_ptr::disable_external_shutdown() in its constructor.Source: §10.8.1 · p. 58
  • Without a quit flag, GAMBIT retries MPI synchronization around plugin calls, but shutdown cannot be guaranteed and failed attempts can leave processes hung or output, including HDF5 files, corrupted.GAMBIT recommends plugins with quit-flag support, such as Diver, for large scans that produce valuable data.Source: §10.8.1 · pp. 58–59

11 Configuration and automatic component registration

GAMBIT uses CMake and Python harvesters to configure builds and register detected components, while providing tools for managing external backends and scanners. The section documents component additions, build targets, and configuration options.

11.1 Adding new models, modules, backends and other components to GAMBIT

  • Python harvesters generate registration boilerplate for detected components; adding files or moving existing ones requires rerunning CMake and updating the component database.New models may also require new module functions or verification that existing functions are safe for that model.Source: §11 · p. 59, §11.1 · pp. 59–60

11.2 Building backends and scanners

  • GAMBIT offers backend and scanner installers with consistent compiler settings; adding one requires download, checksum, and build details, while scanner registration requires rerunning CMake after installation.Python and other non-C/C++ backends require a shipped C API in GAMBIT 1.0.0; native-language support was a future priority.Source: §11.2 · pp. 60–61

11.3 Miscellaneous build targets

  • Build targets install, clean, or remove individual backends and scanners, or perform those operations across all registered components; clean and distclean also differ in what they remove.The clean target removes GAMBIT's compiled and generated files; distclean additionally removes documentation, scratch files, and downloaded or compiled backend and scanner content.Source: §11.2 · pp. 60–61, §11.3 · p. 61

11.4 Configuration options

  • CMake options can select compiler or library versions and disable components or features during configuration.The documented options are generally not required, but can guide or force CMake's choices.Source: §11.4 · p. 61

11.4.1 CMake standard variables

  • CMAKE_BUILD_TYPE offers several build profiles: None builds fastest but runs slowest, while Release targets faster execution and Release_O3 passes -O3 instead of -O2.Compiler paths and language-specific flags can also be supplied through CMake variables or environment variables.Source: §11.4.1 · p. 61

11.4.2 CMake library and GAMBIT-specific variables

  • The Ditch option excludes matching components from the next build without cleaning their compiled code; Release_O3 may offer no significant advantage and may destabilize some backends.The section advises using Release_O3 with caution.Source: §11.4.2 · pp. 61–62

12 Examples, releases and support

GAMBIT includes minimal examples, standalone module drivers, and YAML scan configurations, alongside fuller example scans. It provides versioned releases, support information, and channels for bug reports and code contributions.

12.1 Minimal examples

  • Minimal examples demonstrate modules, backends, model hierarchies, scans, and plotting; standalone drivers offer manual control of module functions without the dependency resolver.Standalone modules often need simple spectrum objects in place of spectra normally created by SpecBit.Source: §12.1 · pp. 62–63

12.2 Releases

  • GAMBIT releases use major.minor.revision numbering and are available as tarballs or Git repositories; each release also offers module-specific bundles for standalone use.Physics-module bundles include models, backend interfaces, logs, and utilities except printers; ScannerBit bundles include printers, logs, and a smaller utility subset.Source: §12.2 · p. 63

12.3 Support

  • Support resources include documentation, known issues, FAQs, and scan data; the project plans regular updates, welcomes bug reports, and reviews proposed code contributions.Bug reports go through the TRAC ticket system, while suggested contributions undergo code review before integration.Source: §12.3 · p. 63

13 Summary

GAMBIT integrates BSM observables, likelihoods, model definitions, external-code interfaces, and scanning tools in an extensible analysis framework. The package is open source, with accompanying papers describing its modules and first BSM results.

13 Summary

  • GAMBIT combines specialized physics modules, a hierarchical BSM model database, interfaces to phenomenology codes, and automatic connections between calculations and their required inputs, outputs, and models.Its modules cover spectrum and decay calculations, collider, flavour, dark matter, and precision physics.Source: §13 · p. 63
  • GAMBIT provides statistical and parameter-scanning options alongside utilities intended to make BSM phenomenological and statistical analyses extensible.Source: §13 · p. 63
  • The package is fully open source, and accompanying papers describe individual modules and present first BSM results.The paper gives gambit.hepforge.org as the download site.Source: §13 · pp. 63–64

Appendix A: Quick start guide

The quick-start instructions use CMake and make to build GAMBIT, then show how to run included YAML examples or build a module as a standalone executable.

Appendix A: Quick start guide

  • Build GAMBIT with CMake and make, and use the included spartan.yaml or MSSM7.yaml files to run example analyses.Source: Appendix A · p. 64
  • The guide provides a route to build all backends supported for automatic download and to build individual backends.Source: Appendix A · p. 64
  • A module can also be built as a standalone example and run as module_name_standalone.Source: Appendix A · p. 64

Appendix B: Supported compilers and library

The appendices document GAMBIT's platform, compiler, and library requirements, define Standard Model parameter conventions, and provide a glossary of framework-specific terms.

Appendix B: Supported compilers and library

  • GAMBIT builds and runs on Linux and Mac OS X, requires C++11 support and a Fortran compiler for Fortran backends, and does not support Clang in the stated setting.Some backend and scanner codes may be incompatible with newer compiler versions; missing optional packages cause dependent components or features to be omitted.Source: dependencies · pp. 64–65
  • Required build dependencies include supported C/C++ and Fortran compilers, Python 2.7 or greater, Boost, and GSL, while MPI and other packages are optional for particular features.The listed additional linear algebra libraries were required at the time, with plans to make them optional in future releases.Source: dependencies · p. 64

Appendix C: Standard Model definitions

  • The Standard Model definitions specify parameter meanings and conventions, including quark and lepton masses, mixing angles, and CKM Wolfenstein parameters.Examples include MS quark masses at stated scales and Wolfenstein parameters defined in the MS scheme at mZ.Source: Appendix C · p. 65

Appendix D: Glossary

  • The glossary defines GAMBIT-specific concepts such as dependency resolution, which selects and orders functions and backend requirements for a scan, and the resulting dependency tree.The tree is a directed acyclic graph of module functions connected by resolved dependencies.Source: Appendix D · p. 66
  • The glossary defines a GAMBIT model as named parameters sampled according to a prior, with scanner and prior chosen at runtime.Source: Appendix D · p. 66

Addendum for GAMBIT 1.1

GAMBIT 1.1 adds full support for Mathematica backends and describes the SUSYHD interface, alongside updates to likelihoods and decay data. SUSYHD calculates the MSSM Higgs-boson mass using effective field theory.

Addendum for GAMBIT 1.1

1 Using Mathematica backends in GAMBIT

This section describes GAMBIT 1.1’s Mathematica interface, which lets modules use public and private Mathematica packages through WSTP-based wrappers exposing functions and variables. It presents SpecBit’s `SHD_HiggsMass` integration of SUSYHD for MSSM Higgs-mass and uncertainty calculations, including a pure-EFT option and module-declared dependencies and model support.

1 Using Mathematica backends in GAMBIT

  • GAMBIT 1.1 gives modules access to public and private Mathematica packages through an interface designed to work like existing C, C++ and Fortran backend interfaces.Users must obtain a Mathematica license; a standard license typically allows 8 Kernel instances and 16 subprocesses.Source: §1 · p. 77

1.1 The Wolfram Symbolic Transfer Protocol

  • WSTP links GAMBIT’s C++ code to a Mathematica Kernel, enabling modules to call Mathematica functions and exchange data through two-way messaging.GAMBIT opens a Kernel link and uses WSTP messaging functions to send requests and receive information.Source: §1.1 · p. 77

1.2 Configuration and backend setup

  • Mathematica backends are detected and configured at CMake time, use the BACKENDLANG macro and Mathematica-specific types, and require a Kernel link and package import at runtime.They need a download link and installation directory but no backend configuration or build step; the package is imported with Get, run once per Kernel session.Source: §1.2.1 · pp. 77–78, §1.2.2 · p. 78, §1.2.3 · p. 78

1.3.1 Backend functions

  • For Mathematica functions, BE_FUNCTION creates wrappers that send arguments to the Kernel and return its result, including for function names with special characters.Special characters must be written using Mathematica full names, such as \[CapitalDelta], and converted to an expression for the Kernel.Source: §1.3.1 · p. 79

1.3.2 Backend variables

  • Because WSTP exposes Kernel variables by value rather than by pointer, GAMBIT wraps them in mathematica_variable<TYPE> objects that support reading, assignment and use in C++ expressions.The wrapper overloads assignment to modify the Kernel variable and conversion to TYPE to read it.Source: §1.3.2 · p. 80

1.4 Diagnostics

  • GAMBIT diagnostics report when a required Mathematica installation is absent and check whether each backend function or variable is present in the Kernel.The symbol-presence check uses Mathematica’s NameQ function.Source: §1.4 · pp. 80–81

1.5 Higgs mass calculations with SUSYHD

  • SUSYHD adds a pure-EFT MSSM Higgs-mass calculation using three-loop Standard Model renormalisation group equations and two-loop matching, suited to MSUSY ≫ mt.It resums logarithms through matching and running; because it neglects terms of order O(v0^2/M_SUSY^2), the approach can be less appropriate at the TeV scale and below.Source: §1.5 · p. 81
  • `SHD_HiggsMass` provides the `prec_mh` capability using the unimproved MSSM spectrum and SUSYHD Higgs-mass and uncertainty backend functions, for `MSSM63atQ` and `MSSM63atMGUT`.Its declaration requests `SUSYHD_MHiggs` and `SUSYHD_DeltaMHiggs`.Source: §1.5 · p. 81

2 SpecBit, DecayBit and PrecisionBit updates

GAMBIT 1.1 updates SpecBit, DecayBit and PrecisionBit, refreshing likelihood and decay inputs while expanding options for precision Higgs calculations. DarkBit adds DDCalc 1.1 and likelihoods for XENON1T and 2017 PICO-60.

2 SpecBit, DecayBit and PrecisionBit updates

  • PrecisionBit likelihoods and DecayBit data were updated to match the 2017 Particle Data Book central values and uncertainties.Updates cover first- and second-generation quark masses, strong and electromagnetic couplings, the muon anomalous magnetic moment, Δρ, and SM particle widths and branching fractions.Source: §2 · pp. 81–82
  • SpecBit and PrecisionBit functions were rearranged to accommodate alternative spectrum generators and precision calculators, including renamed FlexibleSUSY functions.The renaming distinguishes FlexibleSUSY spectrum generation from equivalent functions using SPheno or other generators.Source: §2 · p. 82
  • The SM-like Higgs mass can be improved independently of the other MSSM Higgs masses, using SUSYHD for one and another calculator for the others.A fallback option controls whether invalid precision-mass results invalidate a parameter point or retain the original spectrum-generator masses.Source: §2 · p. 83

3 Updated DarkBit likelihoods

  • DarkBit 1.1 adds DDCalc 1.1 interfaces and likelihoods for XENON1T and 2017 PICO-60.It also offers one-loop direct-detection cross-section corrections with DarkSUSY, enabled by default, and defaults micrOMEGAs internal decays to false.Source: §3 · p. 83
Loading 1705.07908v2…