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 (EasyBuild)

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

$ source /unix/pbt/software/scripts/bdsim.sh 

This sets up all the required EasyBuild modules and environment variables. The version of BDSIM that is used within this script is not the latest build (v1.1.0 instead of v1.2.+) but should be stable. If a newer version is required then contact James Chappell and he will compile a newer version for you to use.

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.

Running on the UCL HEP Linux Cluster (Old)

These instructions are now out of date and it is not recommended that you use this version of BDSIM unless you have experience with the pain of compiling BDSIM, Geant4 and all their dependencies. Whenever possible, use the EasyBuild version. Contact Simon Jolly or James Chappell if any required functionality is missing.

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 either CentOS7 or 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.

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.

AWAKE Spectrometer Simulation

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

• options.gmad - includes definitions of constants used within the spectrometer model.
• spec_test.C - a ROOT macro that plots and fits the Energy vs. position on the screen for particles that pass through the spectrometer.
• 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 test electron beam (E = 0 -> 10 GeV), use the command:

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

The output is then stored in a file called output.root. There one supplied script for analysis of this output: spec_test.C.

ROOT Macro

The analysis script provided is a ROOT Macro that automatically plots the energy of the particle against the x-position on the screen and then fits this curve for comparison to the analytic model. It allows easy confirmation that the simulation is working as expected. It can be used via:

$ root
root > .x spec_test.C

Python Scripts - Creating Field Maps

There is a directory called python_scripts within the AWAKE spectrometer example directory on the UCL HEP cluster. The script uniformfield.py can be used to generate uniform magnetic field maps that can be used within the AWAKE spectrometer simulation.

Setting up pyBDSIM

BDSIM comes with a group of python modules that can be used to create and visualise aspects of the simulation, e.g. beam distributions and field maps. More information on these modules can be found at http://www.pp.rhul.ac.uk/bdsim/manual/python_modules.html. To download these modules from bitbucket, use the following commands from within your BDSIM source directory:

$ git pull
$ git submodule init
$ git submodule update

To compile the modules, use:

$ cd utils
$ make

This compilation assumes you are using a python environment with pip installed. If you are running this on the UCL HEP cluster, then follow the instructions on https://www.hep.ucl.ac.uk/twiki/bin/view/Computing/UsingPython to create a virtual environment in which you can install the modules.

Creating a uniform magnetic field map

To create a uniform magnetic field map, you can use the python script uniformfield.py in the following way from the command line:

$ python uniformfield.py --fieldstrength <fieldstrength> --length <length>

where you insert your desired values for the field strength (in T) and length (in m). The length variable must equal the length value given to spectrometer.gmad when defining the awakespectrometer class. It is required due to the way the spectrometer field map is defined within the source code. If you do not give the same length value, the field will be placed in the wrong position within the simulation and the results will be incorrect.