BRIL_BIBGenerator

UNDER CONSTRUCTION

Introduction

This guide gives instructions on how to set up and run Beam Induced Background (BIB, alternatively MIB for Machine Induced Background) simulations in CMSSW with a two step method (BIB particle generation + simulation). For an official introduction and manual for CMSSW have a look at the offline workbook: https://twiki.cern.ch/twiki/bin/view/CMSPublic/WorkBook

Setup

Login to lxplus.

ssh -Y [email protected]

If you don't have any CMSSW release already, navigate to an empty directory and then type

cmsrel CMSSW_11_2_0_pre6

which creates a local copy of CMSSW version 11.2.pre6. To find out about a list of currently available CMSSW releases, type

scram list -a

or visit the official CMSSW github page, where you can also browse the simulation source code. Now you can navigate to the source directory within the created CMSSW release

cd CMSSW_11_2_0_pre6/src

and activate a CMSSW working environment, paths and compiler (while being in the /src directory) by typing

cmsenv

This command has to be issued only once but every time you open up a new terminal an start to wotk with CMSSW. In the /src directory you can now clone the current repository that will be used for BIB generation:

git clone https://github.com/pkicsiny/BRIL_BIBGenerator.git

CMSSW can only find and work with the code if it is located in the /src directory. Therefore the subdirectory BRIL_BIBGenerator/GeneratorInterface should be symlinked from the /src directory as shown below:

ln -s BRIL_BIBGenerator/GeneratorInterface GeneratorInterface

In addition, you will need to clone another repository that contains two config files which will be used to run the generation and simulation step respectively. This can be found here. You can simply clone the whole repository but we will need only the contents of the BIBGeneration directory. Type the following while being in the /src directory:

git clone https://github.com/pkicsiny/BRIL_ITsim.git

Getting the input

Some FLUKA simulated BIB files for beam halo and three types on beam gas (H, C and O) can be downloaded from https://bbgen.web.cern.ch/HL-LHC/. It is recommended to place these files to the /eos file system because of their large size.

Generation step

Before running the generation step, you might want to have a look at the contencts of the config file.

cd BRIL_ITsim/BIBGeneration
vi python/BH_generation.py

(You might use the tab key for auto-filling the path name when navigating in the terminal.) The config file accepts the following user parameters from the command line:
nEvents: number of events to read from the FLUKA input files. Can be set inside the config file through the nevents variable. If set to -1, all events from the inputs will be processed. Note that this is not recommended as CMSSW will throw an error when reaching the end of the last file. Instead, it is recommended to check the number of events input file beforehand and set this parameter accordingly, e.g. to 10000 if the inputs contain let's say 10426 events.
nThreads: number of parallel computing threads to use. Default is 1.
jobId: relevant when running the generation step on lxbatch, where the simulation is split into smaller chunks each having a unique job ID. Not used if the code is run locally on lxplus. Default is 0.
tDirectory: absolute path of the diractory to where the root file will be created. It will contain the same particles as in the FLUKA dump input, but in a different, CMSSW friendly format, called HEPMC.

In addition, some other parameters can be specified inside the config file:
inputPath: absolute path specifying the location of the FLUKA input files. The line options.inputFiles= [inputPath + "/" + f for f in os.listdir(inputPath) if f[:3] == "run"] automatically parses the file names in the inputPath directory and selects files whose name begins with run. This parsing can also be adapted or removed depending on the specific usecase.
nevents: number of events, alternative hard-coded variant of nEvents.
The output file name can be changed under the #specify output name comment.

Although the CMS geometry plays no role in the generation step, CMSSW always expects an input geometry to be specified. You can use the most up to date Phase 2 full CMS geometry, just as a 'placeholder':

process.load('Configuration.Geometry.GeometryExtended2026D63_cff')

You can run the generation step by running the cofig file BH_generation.py.

cmsRun python/BH_generation.py 

which invokes code from BRIL_BIBGenerator/GeneratorInterface/BeamHaloGenerator/python/MIB_generator_cff.py which in turn invokes CMSSW through BRIL_BIBGenerator/GeneratorInterface/BeamHaloGenerator/src/BeamHaloProducer.cc.

Simulation

The second step consists of the transport of paticles and the simulation of particle-matter interactions in the CMSSW geometry model. This step can be launched by executing: cmsRun BH_SimTrigRec.py

Running on lxbatch