Skip to content

Getting started

This guide is a quick introduction to building and running iblep for the first time.

Dependencies

It is assumed that you have a working build of both Grid and Hadrons available on the target machine.

If you want to run the regression checks, you must have h5diff and sqlite3 installed, alongside Python 3.6+ with numpy and h5py.

Build and install

iblep uses a CMake build system that automatically discovers build options from the provided Grid and Hadrons paths. The "presets" are the recommended build method if your target machine is supported by them. Otherwise, three example build configurations are provided for CPU, NVIDIA GPU, and AMD GPU. Note that you may need to pass additional machine-specific configuration flags if you are not using a preset.

Preset Builds

cmake --preset=<preset> -DGrid_ROOT="/path/to/grid" -DHadrons_ROOT="/path/to/hadrons" -DCMAKE_INSTALL_PREFIX="/path/to/install/to"
cd build-<preset>
make -j <N>
make install -j <N>

Tip

You can always find an up-to-date list of available presets by running cmake --list-presets from the iblep root directory.

CPU Builds

mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_COMPILER=<gcc/clang> -DCMAKE_CXX_COMPILER=<gcc/clang> -DGrid_ROOT="/path/to/grid" -DHadrons_ROOT="/path/to/hadrons" -DCMAKE_INSTALL_PREFIX=/path/to/install/to
make -j <N>
make install -j <N>

NVIDIA GPU Builds

mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_COMPILER=nvcc -DCMAKE_CXX_COMPILER=nvcc -DGrid_ROOT="/path/to/grid" -DHadrons_ROOT="/path/to/hadrons" -DCMAKE_INSTALL_PREFIX=/path/to/install/to
make -j <N>
make install -j <N>

AMD Builds

mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DCMAKE_C_COMPILER=hipcc -DCMAKE_CXX_COMPILER=hipcc -DGrid_ROOT="/path/to/grid" -DHadrons_ROOT="/path/to/hadrons" -DCMAKE_INSTALL_PREFIX=/path/to/install/tomake -j <N>
make install -j <N>

A first run: Connected Workflow

We will use the connected workflow as an example test run.

Navigate to a directory from which you want to perform the run. The iblep executables are located in the bin directory of the CMAKE_INSTALL_PREFIX you provided to the build, assuming make install successfully completed.

The required runtime argument to each executable is a parameter file. These are workflow-specific. You can find examples of these files in the parameters directory of the iblep source repository. Here, we will use the parameter file iblep/parameters/iblep-conn/test.json, which is a test file for the iblep-conn-lep workflow.

If you have built iblep locally, you can run the programme immediately. If you are running this on a computing cluster with a job queue, DO NOT run this command directly, but use it as part of a job submission script. 

/path/to/iblep-conn-lep /path/to/test.json --grid 4.4.4.8
If you are running locally, you should see the programme progress in the terminal, and it will produce a result database, two_point result files, and leptonic_decay result files.

If the job ran successfully -- congratulations! This is the basic pattern for running all iblep workflows. To run a real job on a production ensemble, you will need a dedicated parameter file, and Grid-specific arguments passed to the executable beyond the grid size to perform a properly optimised run. You can find further details on the parameter files in the dedicated pages for the individual workflows.

Next steps

  1. Read the workflows summary. This provides an overview of all programmes in the iblep software and further links to more detailed pages.
  2. Read the disc workflows linked from the workflows page. For a run that includes disconnected isospin-breaking effects, you will need to run these workflows before a connected workflow.
  3. Read the conn workflows linked from the workflows page. These workflows relate to computations of connected isospin-breaking effects, and use data generated from the iblep-disc workflows.
  4. Read the real workflows linked from the workflows page. These workflows calculate real radiative corrections. They do not require an initial disc run, but can use the outputs of a disc run in offline analysis for computing disconnected contributions to the real radiative decay.