MC Signal Generation

Last update: 14 Nov 2022 [History] [Edit]

Monte Carlo (MC) event generation in ATLAS uses AthGeneration, which provides a variety of generators and the detector simulation. While the generator software is available independent from ATLAS software, it is important to use it through the ATLAS interfaces to ensure consistent usage of these tools, as well as allowing access to ATLAS conditions.

There are numerous generators available for use in ATLAS, each with its own advantages and disadvantages. In most cases, however, new physics samples use the MadGraph event generator.

Directory setup

The MC generation part of the tutorial consists of two parts: generation and validation. These need to be done in separate directories, using different release setups. To keep a sensible directory structure, use the following commands:

mkdir MCTutorial
cd MCTutorial
mkdir MCGeneration

Basics of MC generation

Begin by moving to the MCGeneration directory and setting up a recent AthGeneration release. These use the 22.6 series.

cd MCGeneration
asetup AthGeneration,22.6.22

The MC generation tools make use of a jobOptions (often referred to as JOs) file that uses pseudo-python to define commands for AthGeneration to execute.

JOs are used for many different tasks using ATLAS software. The format and common methods used in JOs are very procedure-specific. If you need to write JOs for a task, it is helpful to look at existing examples.

We will create the JOs to produce a pair of leptoquarks with a mass of 1000 GeV that decay to first and second generation leptons/quarks with a final state containing either two electron or two muons.

In your MC generation work area, create a directory called 100000 and the file 100000/ Copy the code below into your file.

# Import all of the necessary methods to use MadGraph
from MadGraphControl.MadGraphUtils import *
from MadGraphControl.MadGraph_NNPDF30NLOMC_Base_Fragment import *

# Some includes that are necessary to interface MadGraph with Pythia

# Mass of the leptoquark
lq_mass = 500. # GeV

# Number of events to produce
safety = 1.1 # safety factor to account for filter efficiency
nevents = runArgs.maxEvents * safety

# Make sure LQ PDG IDs are known to TestHepMC:
pdgfile = open("pdgid_extras.txt", "w+")

# Here is where we define the commands that will be passed to MadGraph

# Import the LQ model
process = """
import model LO_LQ_S1

# Define some multi-particle represenations
process += """
define charm = c c~
define up = u u~
define q = u u~ d d~ c c~ s s~
define e = e- e+
define mu = mu- mu+

# Define the physics process to be simulated
process += """
generate g g > e mu up charm

# This defines the MadGraph outputs
process += """
output -f

# Define the process and create the run card from a template
process_dir = new_process(process)
settings = {'ickkw': 0, 'nevents':nevents}

# Set some values in the param card
# BSM particle masses
masses={'9000005':lq_mass, #S1
        '1000021':1000000. } # chi10 - needed because of a bug in the model

# Leptoquark width
# This is hard-coded here, but could be calculated on the fly with a function
lq_width = 39.7887
decays={'9000005':"""DECAY 9000005  %g #leptoquark decay""" % lq_width}

# These are the couplings of the leptoquarks to first and second
# generation fermions
yuks1ll={'1   1':"""0.000000e-00 # yll1x1"""}
yuks1rr={'1   1':"""1.000000e-01 # yRR1x1"""}
yuks1rr={'2   2':"""1.000000e-01 # yRR2x2"""}

# Create the param card and modify some parameters from their default values

# Do the event generation

# These details are important information about the JOs
evgenConfig.description = 'Single Leptoquark coupling lam1122. m_S1 = %s GeV' % (lq_mass) = [ "Jason Veatch <>" ]
evgenConfig.keywords += ['BSM','exotic', 'scalar', 'leptoquark']

arrange_output(process_dir=process_dir, runArgs=runArgs)

The 6-digit directory name is known as a DSID (dataset ID, sometimes also referred to as DID). This is used as a unique numerical identifier for the specific JOs. For local testing, you can use dummy 6-digit numbers, placing exactly one JOs in each DSID directory. A unique DSID is assigned to each of your JOs in the central sample production procedure.

The name of the JOs encodes important information about the physics process it represents. The first part (MGPy8EG) indicates which tools are used in the event generation. MG refers to LO MadGraph, which is used for the matrix element calculation. (N.B. NLO MadGraph is denoted as aMC) Py8 indicates that Pythia8 is used for the parton shower and hadronization step. EG refers to EvtGen, which is an afterburner that ensures the decays of B hadrons are correctly modeled. A14NN23LO refers to the LO NNPDF2.3 PDF set used with the A14 tune. LO_LQ_S1 is the MadGraph model that is used. The remaining terms describe the process as pair production of leptoquarks with a mass of 1000 GeV.

Running a command will use the JOs to produce an events file. This is a truth-level description of the event before detector effects are taken into account. In you work area, use the following command in your MCGeneration directory: --ecmEnergy=13600. \
          --maxEvents=100 \
          --randomSeed=123456 \
          --outputEVNTFile=evgen.root \

tip The maxEvents option controls how many events you want the job to produce in the output file. This differs from the nevents variable in the JOs, which is the number of events that are generated. If a generated event fails to meet certain criteria, it counts towards nevents but is discarded and does not count towards maxEvents. A safety factor is defined in the JOs to account for the efficiency of generated events being kept. This factor may need to be adjusted for your JOs.

tip is one of several transforms that Athena provides. A transform is a high-level configuration that combines multiple job option files that your job can build off of.

This will take a few minutes to run and will use the JOs in 100000 to generate 100 events at a center-of-mass energy of 13.6 TeV. A large amount of text will be written to your screen as well as log.generate. If the process runs successfully, you should see a message saying:

INFO leaving with code 0: “successful run”

and a file called evgen.root in the EVNT format.

If you rerun the command again in the same directory, it will overwrite all of the outputs.

Now let’s look at the output to see if we are generating the expected signal.