Software/BDSIM: Difference between revisions

From PBTWiki
Jump to navigation Jump to search
No edit summary
 
(6 intermediate revisions by the same user not shown)
Line 17: Line 17:
In order to use the UCL HEP Linux cluster, you will need a HEP account: please contact Dr. Simon Jolly for more details.  
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 ===
=== Running on the UCL HEP Linux Cluster (EasyBuild) ===


In order to run <code>BDSIM</code> 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:
In order to run <code>BDSIM</code> 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:


<pre>
<pre>
source /unix/pbt/software/scripts/pbt.sh -vd
$ source /unix/pbt/software/scripts/bdsim.sh  
</pre>
</pre>


'''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.  
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 <code>BDSIM</code>. To check that it is working correctly, test the built-in help function:
 
<pre>
$ bdsim --help
</pre>
 
This should produce an output explaining all the possible options that can be used within <code>BDSIM</code>.
 
=== 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.'''


Following this, a second script must be sourced in order to create the environment required to run <code>BDSIM</code>:
In order to run <code>BDSIM</code> 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:


<pre>
<pre>
source /unix/pbt/software/scripts/bdsim_setup.sh
$ source /unix/pbt/software/scripts/pbt.sh -vd
</pre>
</pre>
'''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 <code>BDSIM</code>. To check that it is working correctly, test the built-in help function:  
Now your system is ready to use <code>BDSIM</code>. To check that it is working correctly, test the built-in help function:  


<pre>
<pre>
bdsim --help
$ bdsim --help
</pre>
</pre>


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


<pre> git clone --recursive <nowiki>https://bitbucket.org/jairhul/bdsim</nowiki> </pre>
<pre> $ git clone --recursive <nowiki>https://bitbucket.org/jairhul/bdsim</nowiki> </pre>


This creates a <code>/bdsim</code> folder within your current folder. This folder contains all the code, examples, documentation and associated Python packages.
This creates a <code>/bdsim</code> folder within your current folder. This folder contains all the code, examples, documentation and associated Python packages.
Line 83: Line 97:
'''Note:''' When installing <code>BDSIM</code>, all the <code>Geant4</code> environment variables must be available. This can be tested using the following command:
'''Note:''' When installing <code>BDSIM</code>, all the <code>Geant4</code> environment variables must be available. This can be tested using the following command:


<pre> echo $G4 <tab> </pre>
<pre> $ echo $G4 <tab> </pre>


If the <code>Geant4</code> environment variables are available, you should see an output similar to:
If the <code>Geant4</code> environment variables are available, you should see an output similar to:
Line 101: Line 115:


<pre>
<pre>
cd /unix/pbt/software/build
$ cd /unix/pbt/software/build
mkdir bdsim
$ mkdir bdsim
cd bdsim
$ cd bdsim
mkdir bdsim-0.9.9.2-build
$ mkdir bdsim-0.9.9.2-build
cd bdsim-0.9.9.2-build
$ cd bdsim-0.9.9.2-build
</pre>
</pre>


Line 111: Line 125:


<pre>
<pre>
cmake ../../../src/bdsim/bdsim-bitbucket/
$ cmake ../../../src/bdsim/bdsim-bitbucket/


ccmake .
$ ccmake .
</pre>
</pre>


Line 132: Line 146:


<pre>
<pre>
make
$ make
make install
$ make install
</pre>
</pre>


Line 145: Line 159:


<pre>
<pre>
cd /unix/pbt/software/build/bdsim/bdsim-0.92-dev/bdsim-build-updated/examples
$ cd /unix/pbt/software/build/bdsim/bdsim-0.92-dev/bdsim-build-updated/examples
cd simpleMachine
$ cd simpleMachine
</pre>
</pre>


Line 152: Line 166:


<pre>
<pre>
bdsim --file=sm.gmad
$ bdsim --file=sm.gmad
</pre>
</pre>


Line 158: Line 172:


<pre>
<pre>
bdsim --file=sm.gmad --outfile=output
$ bdsim --file=sm.gmad --outfile=output
</pre>
</pre>


Line 173: Line 187:


<pre>
<pre>
bdsim --file=sm.gmad --outfile=output --batch
$ bdsim --file=sm.gmad --outfile=output --batch
</pre>
</pre>


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.
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 ==
== AWAKE Spectrometer Simulation ==


A simple model of the AWAKE spectrometer is available at <code>/unix/pdpwa/AWAKE_spectrometer</code>. This model (<code>spectrometer.gmad</code>) 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:
A model of the AWAKE spectrometer is available at <code>/unix/pdpwa/AWAKE_spectrometer/spectrometer</code>. This model (<code>spectrometer.gmad</code>) describes the spectrometer, downstream of the plasma cell, and includes the quadrupole magnets, drift sections and the spectrometer. Also included in this folder are:


* <code>options.gmad</code> - includes definitions of constants used within the spectrometer model.
* <code>options.gmad</code> - includes definitions of constants used within the spectrometer model.
* <code>analysisConfig.txt</code> - a simple <code>rebdsim</code> 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 .
* <code>spec_test.C</code> - a ROOT macro that plots and fits the Energy vs. position on the screen for particles that pass through the spectrometer.
* <code>plot_xy.C</code> - a ROOT macro that plots histograms describing the position and momentum distributions at different points along the beam line.
* <code>vis.mac</code> - settings for the interactive BDSIM GUI.
*<code>vis.mac</code> - settings for the interactive BDSIM GUI.
* <code>README</code> - instructions on running the simulation.
*<code>README</code> - instructions on running the simulation.


=== Running the Simulation ===
=== Running the Simulation ===


First source the BDSIM environment as described [[#Running on the UCL HEP Linux Cluster| above]]. To run the simulation using the default supplied electron beam (E = 1.3+/-0.4 GeV), use the command:
First source the BDSIM environment as described [[#Running on the UCL HEP Linux Cluster| above]]. To run the simulation using the test electron beam (E = 0 -> 10 GeV), use the command:


<pre>
<pre>
$ bdsim --file=spectrometer.gmad --batch
$ bdsim --file=spectrometer.gmad --outfile=output --batch
</pre>
</pre>


The output is then stored in a file called <code>output_event.root</code>. There are two supplied scripts for analysis of this output: <code>analysisConfig.txt</code> and <code>plot_xy.C</code>.  
The output is then stored in a file called <code>output.root</code>. There one supplied script for analysis of this output: <code>spec_test.C</code>.  


==== REBDSIM ====
==== ROOT Macro ====


The first analysis script uses <code>rebdsim</code>, a set of analysis codes that are compiled into a library that is supplied with BDSIM. It can be used via:
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:


<pre>
<pre>
$ rebdsim analysisConfig.txt output_event.root analysis.root
$ root
root > .x spec_test.C
</pre>
 
=== Python Scripts - Creating Field Maps ===
 
There is a directory called <code>python_scripts</code> within the AWAKE spectrometer example directory on the UCL HEP cluster. The script <code>uniformfield.py</code> 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:
 
<pre>
$ git pull
$ git submodule init
$ git submodule update
</pre>
</pre>


where the third option, <code>analysis.root</code>, is the desired name of the output file. This can then be opened in ROOT:
To compile the modules, use:


<pre>
<pre>
$ root analysis.root
$ cd utils
root > TBrowser a;
$ make
</pre>
</pre>


The second command opens a <code>TBrowser</code> session. <code>TBrowser</code> is an interactive GUI provided by ROOT that can be used to visualise data. The histograms produced by the <code>rebdsim</code> analysis can be found under <code>EventHistograms;1</code>.  
This compilation assumes you are using a python environment with <code>pip</code> 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.


==== ROOT Macro ====
==== Creating a uniform magnetic field map ====


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:
To create a uniform magnetic field map, you can use the python script <code>uniformfield.py</code> in the following way from the command line:


<pre>
<pre>
$ root
$ python uniformfield.py --fieldstrength <fieldstrength> --length <length>
root > .x plot_xy.C
</pre>
</pre>


The output should look similar to the following images:
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 <code>spectrometer.gmad</code> when defining the <code>awakespectrometer</code> 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.
{{multiple image
| width = 80
| footer =
| image1 = position.png
| alt1 = Position evolution
| caption1 = Position
| image2 = momentum.png
| alt2 = Momentum evolution
| caption2 = Momentum
}}
 
<!--== References ==-->
 
<!--{{cite web |url=https://twiki.ph.rhul.ac.uk/twiki/bin/view/PP/JAI/BdSim |title=BDSIM - Accelerator Beamline Simulation Tool |last=Nevay |first=Laurence |date=30 August 2017 |website=Royal Holloway Physics TWiki |access-date=17 October 2017}}-->

Latest revision as of 09:34, 27 November 2018

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.

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.