Documentation of the Simulation for my PhD

This is the technical documentation for the spin transport simulation which I have developed for my PhD (thesis available here). It comprises the beamline simulation with Bmad, the simulation of the collision effects with Guinea-Pig++ and the analysis and presentation with ROOT. The first two programs are described below. The simulation framework is operated using a number shell scripts and ROOT scripts.

Main Simulation Framework

The basic structure of the simulation framework is sketched in figure 1. The programs/scripts are explained in detail below. A particle beam is generated with a Bmad program from a set a given beam parameters. This beam is propagated (element by element) through a given lattice in the Bmad format (a separate program to convert from the XSIF format to the Bmad format is available). The output (particles coordinates and spins at the end of each element/selected elements) is written to an text file which is then transformed into a ROOT tree. To save disk space and for the conversion between the different particle parametrizations, the output is always stored in ROOT trees (rather than text files), which is not explicitly drawn in figure 1. To simulate the collision effects, the particle beam at the IP is parsed to Guinea-Pig++ (via a text file with the GP++ parametrization). The spent beam text file can be read directly by the Bmad program in order to propagate the spent beam to the downstream polarimeter.

It is planned to feed to the beam at the laser-bunch IPs of the polarimeters into a simulation of the polarimeter response (LCPolMC). This simulation does already exist, but needs to be enabled to read a ROOT tree containing the particle information (already partially implemented) and to simulate the Compton scattering process for the parsed beam instead of for a beam which is only parametrized by the beam sizes etc.

The lattice information is written out by a separate Bmad program.

After the simulation of the particle transport, ROOT is used to calculate the beam parameters (beam size, average polarization etc.).


The procedure described above generates one single bunch. In principle, Bmad could generate also a bunch train with several bunches (e.g. to take wake field effects on subsequent bunches into account), but I never prepared my simulation for such studies.

To run this simulation on a grid (NAF2), it has been automatized as much as possible. For each sample with (typically) 1000 runs, the simulation jobs are run at first. In a second step, a quality control script is run. Thereafter, the simulation results of the sample are merged and the ROOT histograms and graphs are produced.

Programs based on Bmad

Bmad is a collection of Fortran libraries to simulate the propagation of a particle beam (including its polarization) through a beamline. There is a very extensive manual on the Bmad homepage. To learn more about single routines, the tool "getf" (see manual) is very helpful. For my studies, I have used the distribution bmad_dist_2012_0419_d. To use a more recent Bmad distribution, some data structures (e.g. particle_struct and coord_struct) have to adapted.


Main beamline simulation. Generates a particle beam (including its spin distribution) according to the input parameters and propagates it through a given lattice. In addition, it can generate misalignments and the corresponding orbit correction for the beam. Calling the program without any parameters prints out a short usage guide.
Input files:

Output files:


Extracts information from lattice files. Calling the program without any parameters prints out a short usage guide.
Input file: Same lattice file as for beam.f90 (above).
Output file: Lattice information either human- or ROOT-readable

convert_lattice(.f90) (additional tool)

Translates lattice files from Xsif to Bmad format. Calling the program without any parameters prints out a short usage guide.
Input file: Lattice file in the Xsif format (human-readable).
Output file: Lattice file in the Bmad format (human-readable).

typeele(.f90) (additional tool)

Prints out element information. Calling the program without any parameters prints out a short usage guide.
Input file: Lattice file in the Xsif format or Bmad format.

calcBfield(.f90) (additional tool)

Calculates the accumulated magnetic field the beam is exposed to along a given beamline, as well as the energy loss due to synchrotron radiation and the expected number of spin-flips per particle. Calling the program without any parameters prints out a short usage guide.
Input file: Lattice file in the Xsif format or Bmad format.

ROOT Scripts

ROOT is assumed to be known. ROOT Website
I have used version 5.28.00 (exceptions for plots employing a logarithmic z-axis, see script output).


Converts ROOT-readable files into ROOT trees for further processing.
Input file: Any ROOT-readable file (see the reference guide of TTree::ReadFile for more information on the file format).
Output file: File containing the corresponding root tree


Trims lattice tree to the same length and verbosity (*) as the beam data tree.
Input file: .root file with lattice tree
Output file: .root file with trimmed lattice tree


Extracts the particle data only at the "points of interests" (poi), i.e. the polarimeters and the IP (see also). In the end, the file containing the particle data everywhere can be deleted to save hard disk space.
Input files:

Output file: A .root file containing the tree with the particle coordinates only at the pois


Calculates the beam parameters (beam sizes, emittances, average polarization etc.) at each element.
Input files:

Output file: A .root file containing the tree with the beam parameters


Prints a text file confronting the most important beam parameters with each other and the design values. Serves to provide a short summary of the results for troubleshooting.
Input files:

Output file: See above


Produces a beam input file for GuineaPig++ to simulate the beam-beam collision at the IP. This includes the transformation to the Guinea-Pig++ coordinate system and system of units.
Input files:

Output file: An ascii file corresponding to the conventions of GuineaPig++


Guinea-Pig++ is a C++-based version of Guinea-Pig, which accounts for the beam polarization as well. Guinea-Pig++ had been developed at LAL (old Guinea-Pig++ homepage with some documentation) until 2008, now (2013) it is hosted at CERN (new Guinea-Pig++ homepage). For documentation see also my thesis, Appendix A of Daniel Schulte's thesis (TESLA 1997-08).

Input files:

Output files:


Adaptation to the NAF

To let this simulation framework run many times, it has been adapted to the NAF2 using a number of shell scripts. The archive naf.tar contains the entire framework, which should be copied to a large scratch space (like SONAS). Some pathes in the main scripts will have to be adjusted (unless you inherited my username). Storing the input files on the AFS is a bad idea: if too many jobs start running at the same time and want read/write, AFS will deny service.

The working procedure is the following:

  1. Run the main simulation framework (>~1000 jobs in parallel): (without/with collisions)

  2. Quality control: check whether all files have been written properly, sort out jobs with errors, etc.: (without/with collisions)
  3. Merge the data, fill ROOT histograms and print out summary tables: and

A quick reference is provided in Nafshort.txt


Location of the Files

Long-term storage on the grid: /grid/ilc/flc/user_tape/beckmann The simulated files are stored as nbeam0*.tar; the programs, scripts, input files etc. are stored in scriptsProgramsEtc.tar.gz as described in the following:

Currently, these files are also available in /afs/


This framework has been operated under Scientific Linux 5 (64-bit). It has been tested once under Scientific Linux 6 (64-bit) with the executables compiled under SL5: it ran without error messages, but the results have not been checked and no attempt has been made to compile the source code under SL6.

Proposed Improvements / Enhancements

Technical Improvements


Currently, a dedicated polarimeter simulation using LCPolMC is not included. LCPolMC would have to read in the beam at the polarimeter IPs and simulate the measurement for the given beams. For that purpose, a routine could be added to LCPolMC to directly access the ROOT tree printed out by ExtractPois. Some code for had already been added to LCPolMC to read a tree in a different format printed out by a program similar to Tree2GuineaPig. This code has become obsolete meanwhile.

(*) The full simulation output with the coordinates and spin vectors for each particle at each position (the end of each element) consumes enormous amounts of hard disk space. Furthermore, the lattice contains a large amount of markers and similar elements which do not affect the particles. Therefore, different levels of verbosity ("verbiage" in the program) can be used to reduce the output to a reasonable level (see beam.f90, subroutine "writeout").

(**) The data in the ROOT trees are structured as follows: Each entry corresponds to one beamline element. The elements are indexed using the element number in the full lattice, such that e.g. the IP has always the same element number in one lattice regardless of the verbosity level (*). The particle parameters come as arrays: for example, for a beam with 40000 particles, the leaf containing the x-coordinate of the particles would be an array of length 40000. Throughout the tree, each particle keeps it array position (lost particles are flagged as lost, but not removed from the array).

CategoryHomepage CategoryPolarimetry

MoritzBeckmann (last edited 2015-02-20 18:23:25 by AnnikaVauth)