Software/BDSIM

BDSIM

BDSIM (Beam Delivery Simulation) is a program that uses a suite of high energy physics software including Geant4, CLHEP & ROOT to build a 3D model of an accelerator and simulate the passage of particles through both the vacuum and the material of the accelerator itself seamlessly.

• Useful Links:
  • RHUL BDSIM Webpage
  • BDSIM Documentation
  • BDSIM Bitbucket Page
  • Official Installation Guide

This is a tutorial about installing and using BDSIM. BDSIM is installed on the HEP Linux cluster at UCL. You will need an account on that cluster to be able to use this software, run example tutorials and create your own simulations.

Running BDSIM Simulations

In order to run BDSIM simulations, you will either need to download and install the software yourself or make use of the existing installation on the UCL HEP Linux cluster.

In order to use the UCL HEP Linux cluster, you will need a HEP account: please contact Dr. Simon Jolly for more details.

Running on the UCL HEP Linux Cluster

In order to run BDSIM simulations on the UCL HEP Cluster, you must first source the development version of the PBT environment from a system within the cluster that is running Scientific Linux V6. This can be done using the following command:

source /unix/pbt/software/scripts/pbt.sh -vd

Note: the '-d' flag is essential as this sources the script that links the latest development software available on the PBT section of the cluster.

Following this, a second script must be sourced in order to create the environment required to run BDSIM:

source /unix/pbt/software/scripts/bdsim_setup.sh

Now your system is ready to use BDSIM. To check that it is working correctly, test the built-in help function:

bdsim --help

This should produce an output explaining all the possible options that can be used within BDSIM.

Required Software

BDSIM requires the following software to be installed:

• Recent compiler with full C++11 support - proven compiler versions are GCC v4.9 or higher, or Clang 6 or higher.
• CMake v2.8.12 or higher
• CLHEP v2.1.3.1 or higher
• ROOT v6.x or higher
• Geant4 v4.10 or higher
• Flex v2.5.37 or higher
• Bison v2.3 or higher

These are all installed on the UCL HEP cluster.

Details

Website

https://twiki.ph.rhul.ac.uk/twiki/bin/view/PP/JAI/BdSim

Latest Version

0.9.9.2 (19th October 2017)

Installation Instructions

The installation process follows the general process described on the UCL HEP Linux Cluster page. The basic method used is as follows:

1. Check that all the prerequisites for building BDSIM are installed (see above);
2. Download the latest version of the source code;
3. Create a build folder;
4. Configure, build and install BDSIM from within the build folder.

Download BDSIM from its central repository

The BDSIM source code can be downloaded from its git repository using:

 git clone --recursive https://bitbucket.org/jairhul/bdsim 

This creates a /bdsim folder within your current folder. This folder contains all the code, examples, documentation and associated Python packages.

Configure, build and install BDSIM

Note: When installing BDSIM, all the Geant4 environment variables must be available. This can be tested using the following command:

 echo $G4 <tab> 

If the Geant4 environment variables are available, you should see an output similar to:

 
$G4ABLADATA          $G4NEUTRONHPDATA      $G4REALSURFACEDATA 
$G4ENSDFSTATEDATA    $G4NEUTRONXSDATA      $G4SAIDXSDATA 
$G4LEDATA            $G4PIIDATA            $G4SHARE 
$G4LEVELGAMMADATA    $G4RADIOACTIVEDATA    $G4VERSION 

This output corresponds to using the UCL PBT environment, but it will be dependent on the installed Geant4 modules. If this does not return a list of environment variables, make sure you have correctly sourced the Geant4 environment script and updated all relevant path variables.

Once the source code has been downloaded, a build directory should be created alongside the src to hold the compiled BDSIM files before they are moved to their final installation location.

On the UCL HEP Linux Cluster, the build directory should be created in /unix/pbt/software/build:

cd /unix/pbt/software/build
mkdir bdsim
cd bdsim
mkdir bdsim-0.9.9.2-build
cd bdsim-0.9.9.2-build

Unlike other software installed on the UCL HEP Linux Cluster, there are a number of ways to configure the software before building. Using the ccmake command, each configuration option can be set interactively:

cmake ../../../src/bdsim/bdsim-bitbucket/

ccmake .

CMake opens an interactive configuration program. Set the options as required for your system e.g. on the UCL HEP Cluster:

CMAKE_INSTALL_PREFIX     /unix/pbt/software/dev/bdsim-0.9.9.2/
USE_AWAKE                ON

Note that the CMAKE_INSTALL_PREFIX=/unix/pbt/software/dev/bdsim-0.9.9.2 flag specifies that the resulting BDSIM should be installed in the directory /unix/pbt/software/dev/bdsim-0.9.9.2 after compilation: this should be changed to suit the particular installation in question.

• c to configure.

• g to generate and exit.

BDSIM can then be compiled and installed by running:

make
make install

Testing

Multiple examples are provided with the source code and can be found in the original build folder. A complete list of examples and tutorials for running them can be found at http://www.pp.rhul.ac.uk/bdsim/manual/examples/examples.html

Here, the simpleMachine example will be demonstrated.

First, navigate to the examples within build directory and find simpleMachine:

cd /unix/pbt/software/build/bdsim/bdsim-0.92-dev/bdsim-build-updated/examples
cd simpleMachine

To run the simulation via the GUI use the command:

bdsim --file=sm.gmad

An interface should load up and display the simpleMachine setup. It has a few drift beam pipes with a quadrupole, collimator and sector bend dipole magnet. To run the simulation once with any output exported to a file called output.root, use the following command:

bdsim --file=sm.gmad --outfile=output

From within the GUI command line, type:

/run/beamOn 1
exit

This will execute a single run of the simulation with the output data exported to output.root. This can then be analysed from within ROOT by following the tutorial at http://www.pp.rhul.ac.uk/bdsim/manual/output_analysis.html.

To run this simulation in Batch mode, the following command can be used:

bdsim --file=sm.gmad --outfile=output --batch

Batch mode has no interactive interface, but as a consequence is much faster and exits the program once it has finished. For simulations with large numbers of particles within the beam, this is the preferred method of use.

Basic AWAKE Spectrometer Simulation

A simple model of the AWAKE spectrometer is available at /unix/pdpwa/AWAKE_spectrometer. This model (spectrometer.gmad) describes the first part of the spectrometer, downstream of the plasma cell, and includes the quadrupole magnets and drift sections up until the dipole magnet. Also included in this folder are:

• options.gmad - includes definitions of constants used within the spectrometer model.
• analysisConfig.txt - a simple rebdsim script that is used to produce histograms describing the position and momentum distributions at different points along the beam line. More information can be found at http://www.pp.rhul.ac.uk/bdsim/manual/output_analysis.html .
• plot_xy.C - a ROOT macro that plots histograms describing the position and momentum distributions at different points along the beam line.
• vis.mac - settings for the interactive BDSIM GUI.
• README - instructions on running the simulation.

Running the Simulation

First source the BDSIM environment as described above. To run the simulation using the default supplied electron beam (E = 1.3+/-0.4 GeV), use the command:

$ bdsim --file=spectrometer.gmad --batch

The output is then stored in a file called output_event.root. There are two supplied scripts for analysis of this output: analysisConfig.txt and plot_xy.C.

REBDSIM

The first analysis script uses rebdsim, a set of analysis codes that are compiled into a library that is supplied with BDSIM. It can be used via:

$ rebdsim analysisConfig.txt output_event.root analysis.root

where the third option, analysis.root, is the desired name of the output file. This can then be opened in ROOT:

$ root analysis.root
root > TBrowser a;

The second command opens a TBrowser session. TBrowser is an interactive GUI provided by ROOT that can be used to visualise data. The histograms produced by the rebdsim analysis can be found under EventHistograms;1.

ROOT Macro

The second analysis script provided is a ROOT Macro that automatically plots the position and momentum distributions at different points within the beam line in two separate canvasses. It allows easy visualisation of the evolution of the beam. It can be used via:

$ root
root > .x plot_xy.C

The output should look similar to the following images: