search

GambitBSM / gambit_2.0

GAMBIT: The Global and Modular Beyond-the-Standard-Model Inference Tool
https://gambit.hepforge.org
3 stars 1 forks source link

readme

GAMBIT

GAMBIT (the Global And Modular BSM Inference Tool) is a software code for performing statistical global fits of generic physics models using a wide range of particle physics and astrophysics data. It consists of a series of modules that provide native simulations of collider and astrophysics experiments, a flexible system for interfacing external codes (the "backend" system), a fully featured statistical and parameter scanning framework, and a host of tools for implementing and using hierarchical models.

Citation(s)

Please cite the following GAMBIT papers, depending on your use of different modules:

GAMBIT contains interfaces to various external codes, along with scripts for downloading and configuring them. Please cite as appropriate if you use those codes:

Documentation

Please see the above list of GAMBIT papers for the main documentation on the design and use of the GAMBIT Core and modules. Further details on the code are available via the doxygen documentation in the gambit/doc directory.

Supported Compilers and Library Dependencies

GAMBIT is built using the CMake system. The following libraries and packages must be installed prior to configuration:

COMPULSORY:

OPTIONAL:

Memory requirements

For building the entirety of GAMBIT without optimisation, at least 10 GB of RAM is required. The build can be completed with less RAM than this if enough modules are ditched when running cmake, with e.g. cmake -Ditch="ColliderBit;DarkBit" .., etc. See the Core paper ("GAMBIT: The Global and Modular Beyond-the-Standard-Model Inference Tool", the first link at the top of this README file) for further details of how to ditch components. For a list of commonly used cmake options, see the file CMAKE_FLAGS.md.

Building with optimisation enabled (e.g. using -DCMAKE_BUILD_TYPE=Release) may require more than 20 GB of RAM, depending on the compiler in use and precisely which optimisations it employs. Interprocedural optimisation in particular requires very large amounts of RAM. In general, Release mode is only intended for performance-critical applications, such as when running on supercomputer architectures. It is not advised for laptops.

Building GAMBIT

The basic build instructions are below.

Note that cmake will fail to find some dependencies on some systems without guidance. More information is provided in the Core paper. For a list of commonly used cmake options, see the file CMAKE_FLAGS.md. Configuration examples for specific computing clusters are available via gambit.hepforge.org.

Assuming that you have retrieved the git repository or the tarball and unpacked it:

  cd gambit
  mkdir build
  cd build
  cmake ..
  make -jn scanners (where n specifies the desired number of cores for the build, e.g. 4)
  cmake ..
  make -jn gambit

To build all backend codes:

  make -jn backends

If you don't want to wait for all backends to build, or if one fails to compile on your system for whatever reason, you can also build individual backends using:

  make -jn <backend name>

and clean them with:

  make clean-<backend name>

Running GAMBIT

For complete documentation on running GAMBIT, please see the Core and module papers (the latter include examples for both running within the full GAMBIT framework, and running standalone module examples). Here we provide a few basic examples.

To see which backends and scanners have been installed correctly, do:

  gambit backends
  gambit scanners

To run the GAMBIT spartan example, do

  gambit -f yaml_files/spartan.yaml

To run an example GAMBIT MSSM7 scan, do:

  gambit -f yaml_files/MSSM7.yaml

Other examples are provided in the yaml_files folder. Further readmes and documentation can also be found in the doc folder.

Running GUM

For a detailed description on how to use GUM please see the GUM paper (reference above). To run the simple model described in the tutorial, the MDMSM, do:

  gum -f Tutorial/MDMSM.gum

To revert the changes to the GAMBIT code brought upon by GUM run GUM in revert mode:

  gum -r mug_files/MDMSM.mug

Besides the tutorial model, other example models can be found in the gum_files directory.

Licensing

The BSD license below applies to all source files in the GAMBIT distribution, except for those contained in the contrib/fjcore-3.1.3, contrib/MassSpectra and contrib/multimin directories. The files in those directories belong to the FastJet, FlexibleSUSY/SOFTSUSY and multimin projects respectively, and are distributed under the GNU General Public License, with special exception (granted by the authors of these packages to GAMBIT) that their inclusion in GAMBIT does not require that the rest of GAMBIT be distributed under the GPL. Note that all provisions of the GPL continue to apply to any further redistribution of the files in contrib/fjcore-3.1.3, contrib/MassSpectra and contrib/multimin, whether in source or binary form.

License

Copyright (c) 2017-2021, The GAMBIT Collaboration All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.