1 - The GAMBIT Interface #

Introduction to the interface #

The GAMBIT interface has two main parts: a master initialisation file which is a YAML file containing the inputs from the user, and the GAMBIT executable which has a number of command line options.

Using this interface, the GAMBIT workflow consists of the following steps:

1. The user inputs what is to be calculated into the YAML file, and then gives the file to the GAMBIT executable.
2. GAMBIT works out how to carry out the scan, and a dependency resolver makes sure that everything takes place in the right order.
3. The scan is made and output is returned.
4. Plots are produced by Pippi ⧉.

The top level of the master initialisation file contains eight entries specified by the user:

• Parameters describes the scan parameters for different models.
• Priors describes the priors to be placed on the scan parameters.
• ObsLikes describes observables and likelihoods that the user would like to be calculated in a scan.
• Rules specifies additional rules to guide the resolution of dependencies and backend requirements.
• Printer provides details about how and where to store the results of the scan.
• Scanner provides information about the scanning algorithm to be adopted in a scan.
• Logger chooses options for logging GAMBIT messages during the scan.
• KeyValues is an additional global option section.

To run the scan, the user runs the gambit executable with the -f flag:

./gambit -f $PATH_TO_YAML_FILE

A first example #

GAMBIT ships with a number of minimal example YAML files, found in yaml_files/. As a first example, try running the spartan.yaml file:

./gambit -f yaml_files/spartan.yaml

If GAMBIT has successfully run then you should receive the message GAMBIT has finished successfully!. By default, the results of this run will be saved in runs/spartan.

This example also comes with an accompanying .pip file, which is used to plot the results with Pippi. First make sure you have Pippi installed, either by cloning the GitHub repository ⧉ or by using the built-in command make get-pippi.

Pippi also requires some additional dependencies:

• The Python packages scipy and h5py, which can be installed using pip.
• The Ruby plotting package ctioga2, which can be installed using the Ruby package manager gem. Full instructions can be found here ⧉.

After installing these, you can plot the results using:

pippi yaml_files/spartan.pip

This will produce plots in runs/spartan/plots. Note that in order to work properly, pippi should be called from the base gambit install directory.

If everything works correctly, you should end up with three plots which look similar to those below.