Monte Carlo requests in the Top WG

You are interested in an analysis and you want to request one for multiple Monte Carlo samples? This is the right place to find all the information that is required to do exactly this - Placing a Monte Carlo request.

You want to request derivations from existing Monte Carlo samples? Please follow the information provided here. *Notice: Please note that DSIDs are not allocated to you until after you have developed your MC generation procedure, produced validation plots, presented your plots in a subgroup meeting, and filled out a complete JIRA request (including all the previous information). Please use dummy DSIDs until they are allocated to you.

This twiki page was prepared compiling information that was partially or fully provided on other twiki pages and are linked where needed. The request procedures are mainly inspired by the ATLASProductionGroup and ExoticsMCRequestHowTo twiki's.

Responsible Physics/MC contacts: Steffen Henkelmann and James Howarth (mailing list: atlas-phys-top-mc-contacts)

General Information

ATLAS Monte Carlo production system

The ATLAS MC production system is a highly automated system managing the production of tasks on remote computers. The production procedures aim to reduce the number of syntax and run-time errors during MC production. The Monte Carlo production chain is split into production steps:

  • Event generation (evgen),
  • Full Geant-4 simulation followed by digitization (simul), or fast AFII simulation,
  • Reconstruction (recon). This last step produces xAODs for analysis.
Each step uses a job option transform. Typically, the requester only cares about the evgen step, and just accepts the default production for simul and recon. If this is not the case, such as requesting re-digitiation for example, the requester should be very specific about which production tags are required and that existing evgen files (by specifying the tags) can be used. This information is specified in the request spreadsheet as described below.

xAODs are automatically saved, but saving different formats, for example ESDs, need to be specifically requested elsewhere (ask Takuya and Danilo). In addition, specific derivations of xAODs are requested elsewhere.

Placing a MC sample request

In general, a Monte Carlo request is broken down into the following phases to allow for an efficient workflow:

  1. Request preparation (constitutes the most important phase)
  2. JIRA ticket phase
  3. Official MC request compilation
  4. Top group convener handshake
  5. Official MC request
  6. PMG approval
  7. Official production
  8. Production monitoring
Step 1.-2. & 8. are expected from the requester side (analyzer(s)). Whereas all other steps are handled by the Top MC contacts including guidance and support for 1. & 8. and direct iterations during the JIRA ticket phase described in 2.

1. Request preparation

The preparation of the MC request constitutes the most important phase of a Monte Carlo request and is purely the duty of the analyzer(s), referred to as the requester in the following. The top Physics/MC production contacts (TopMC contacts) can provide guidance and assistance during that phase and can be contacted through this mailing list atlas-phys-top-mc-contacts. The PMG recommended procedure is outlined here.

Make your case as a requester

Try to answer the question: Why is the sample needed?

  • Check if samples suitable for your analysis already exist ( MC15 | MC16)
  • What type of Monte Carlo request suits your case?
    • Is it an extension of a Monte Carlo that already exists? [EVNT exists but no simulation]
    • Is it an alternative simulation model [AFII exists but FS does not, or vise versa]
    • Is it a systematic variation of an existing sample?
    • Is it a new sample?
  • What is the total number of statistics that you intend to request?
    • Justify the number of statistics that you intend to request by providing a valuable and thoughtful measure (where applicable)
    • Needs to be justified independent of the type of the Monte Carlo request
  • What type of simulation do you want to request?
    • Do you really need expensive FullSim samples? Why? Might AFII be sufficient? Do you need a detector simulated sample at all?
You are always encouraged to contact the Top MC contacts in case of questions or doubt via e-mail (as stated above). Depending on the outcome of these questions the requester starts the JO preparation and validation process underlining the case.

As a first starting point it is always good to start from something that already exists and works.

The requester has to

  • Prepare the JobOption (s) file (JO) and if needed the LHE files (for non-OTF ["On the fly production"])
    • In case of Sherpa samples, grid-packs need to be provided centrally (please contact Top MC contacts
A tutorial on how to prepare new JO(s) and suggestions on how to run code for the validation test are outlined in the TopWorkshopMCTutorial.

Twiki pages for specific productions:

Job Option Preparation

The job options should be named by the designation:


As described here. Common parameters are centrally defined by PMG and are listed on this twiki.

Running job(s) with prepared Job Options

Please, check the latest caches for AtlasProduction and MCProd before starting a test job here and check that a certain release is not blacklisted. Depending on the type of the MC request, identical caches to the existing samples could be used (check with TopMC contact on a case by case basis).

Validation Step

The requirements for a validation step are outlined here.

Sample requests are required to include, at a minimum:

  • Validation plots. The exact set of plots will depend on the physics process and generator, but you are expected to demonstrate that your job runs, and produces sensible results. For some samples, validation plots may not be appropriate, and in these cases you are expected to provide a justification for the absence of plots. It is expected that the validation plots were presented in a subgroup meeting and got approved by the respective sub-group conveners. After subgroup approval, a link to the presentation needs to be added to the TopMCValidation twiki.
  • Log files from test jobs (log.generate), or ideally the validation runs. This will demonstrate that the jobs work, and will help if technical problems appear later.
    • Ideally, also the which is a python script provided by PMG to extract important info from the log files is also ran. The instruction of this script can be found here. However, this step is generally handled by the Physics/MC contacts (but often results in one or two more iterations on the JOs with the requester).

The Checklist

  • Check if samples suitable for your analysis already exist ( MC15 | MC16)
  • Check MC request type
  • Justify statistics & simulation type
  • Prepare and validate JOs
  • Get approval from sub-conveners after showing validation plots and discussing appropriate statistics & simulation type
  • Attach a link to the presentation to the TopMCValidation twiki

2. JIRA ticket phase

You can access the MC request system (JIRA) using ATLMCPROD Instructions on how place a request via JIRA are available at ExoticsJIRARequests. Information on how the JIRA system works for MC requests can be found here MCProdJira

You need to include the following in the request:

  • Detailed description of the request that clearly makes your case based on the outcome of the request preparation (above)
    • Motivation for request: Group(s) and/or individual(s) requesting the sample and the motivation for requesting it. This helps us set the priority of the request on the grid.
    • Generation details: Number of samples (and DSIDs needed), events per sample, simulation type (AFII or fullsim - AFII is strongly preferred unless there is a strong reason for fullsim).
    • Generator (ME+PS or standalone): Which version of which generator required, and the pCache number if necessary (this can be checked in the release you are using and the Top MC contacts can help sorting it out)
    • UE tune: For MC tunes you can consult the MCTunes twiki. Explicitly mention why you would like to use a tune that is not a default one.
    • PDF: For the bulk of samples currently the NNPDF23LO PDF set is used. Defaults are listed at: McProductionCommonParameters
    • Additional files:
      • LHE files and hence 4-vectors should be generated, as described at PreparingLesHouchesEven. The input files (if required) are too big to attach. A link should include in the request text to their location in afs space. Put all the files in a single directory so that they can be copied with a simple unix command.
      • Grid packs: When you intend to run with Sherpa, either you can use gridpacks that are already available (check evgeninputfiles.csv) or you need to get in contact with Frank Siegert, cc'ing atlas-phys-top-mc-contacts.
      • Restrict cards: For some MadGraph productions, additional restrict cards are necessary and need to be attached
    • Job Options (aka JO, jobOptions): It is the responsibility of the requester(s) to provide these and the log file(s) that result from testing them.
      • Attach a tarball of job options, if needed (a single .tar.gz file is preferred with no directory in the tarball)
      • Attach log files produced with the dummy DSIDs (a single .tar.gz file is preferred)
    • Campaign: Depending on the conference the analysis you request the MC samples for is targeting, make sure that you ask for the production within the appropriate MC campaign (e.g., MC15c or upcoming MC16(a,b,c) productions). Details can be found here.
  • A link to the validation plots (as linked from TopMCValidation)
* Notice: if you need to update an attachment, there is no need to delete the old one as they are all time-stamped. Deleting old attachments just generates unnecessary extra email.

Basic steps to open TopMC ATLMCPROD JIRA ticket

1. Go to JIRA project page: ATLMCPROD

2. Click on "Create" button

3. Fill the required fields :

  • Issue Type : Task
  • Assignee: 'Atlas Top MC production'
  • Summary: Title for the task. Choose a meaningful title (eg "Powheg+Pythia8 radiation variation samples"). Notice that words such as "samples", "13 TeV ", "MC15" are redundant as that information is provided elsewhere.
  • Component: "Top"
  • Description: Detailed description of the full request as outlined above
  • Label: "TopMC"
  • Group Watchers: Add subgroup conveners mailing list.
* Notice: if you don't pick the components and labels correctly, the JIRA notification that we depend on to notice your request may not make it to your MC contacts!

To get email notification, add yourself as a "Watcher". To do this click on "Start watching this issue".

4. Attachments (as specified above) can be uploaded a this point.

The Top MC contacts will go through the MC request once all the information described above is provided on the JIRA ticket. After thorough checking of the provided information, official DSIDs will be assigned and the updated JOs need to be uploaded by the requester. During this phase one or two iterations on JIRA are usually required to converge on the JOs. After update of the JOs, the requester needs to run (not necessary in all cases but in the majority of cases) new log files which need to be added to the JIRA ticket. After the final check, the Top MC contacts asked for the collection of the JOs (and additional files needed to ensure a smooth official production).

The Top MC contacts follow up on the missing steps 3-7 outlined in " Placing a MC sample request".

Good practices (examples)

Please, find example links to JIRA requests constituting good practices:

8. Production Monitoring

Any ensuing discussion or requirements for the request should take place in the comments section of the JIRA ticket (and the production web page after the sample is requested). You can monitor your request on the production task link that is attached by the Top MC contacts to the end of the JIRA description. The link is of the form:

Please, feel free to contact the Top MC contacts at any time through atlas-phys-top-mc-contacts. We are always happy to help the best we can.


More information available here.

  • Q. How long does it take to get my sample processed?
    • A : One week to one month depending on grid occupancy etc.
  • Q : How to interpret production tags?
    • A : The new naming convention consists in adding to the sample name a number of tags, one for each production step. The most common tags are:
      • eXXX: evgen configuration
      • sXXX: simulation configuration
      • dXXX: digitization configuration
      • rXXX: reconstruction configuration
      • aXXX: atlfast configuration (both simulation and digit/recon)
      • tXXX: tag production configuration
      • bXXX: bytestream production configuration
  • Q : What are the production tags used for?
    • A : Each of the tags corresponds to a configuration (athena release, geometry tag, JOs set, ...) in a way that the configuration is unique.
  • Q. How do I find the cross-sections in AMI?
    • A : Go to dataset selection page ("simple search") in AMI. Search for an EVNT dataset like mc15_13TeV.410000.PowhegPythiaEvtGen_P2012_ttbar_hdamp172p5_nonallhad.evgen.EVNT.e4398. Click on 'details' in the first column of the returned table: On the right side you will see the cross-section info supplied by AMI as well as (possibily) a text field with details on the LO and NLO cross-sections and filtering efficiency.
  • Q. How to deal with private production?
    • A : Although for very initial studies (e.g. to determine parameters in the model you wish to study) it is ok to run private simulation however you want to, in order to show results outside the ATLAS collaboration (publication , conference etc) there are strict rules on how private simulation is done. All event generation must be done in the production system - private event generation might be allowed under exceptional circumstances. Detector simulation can be done privately, but official production job transforms must be used. This private production should not be undertaken until a sample of 10k detector level simulated events is made and compared to a 10k sample from the production system. Once validated further private production is allowed. Note that private production means private CPU and DISK space. If you'll consider to produce samples privately for the official analysis (it means analysis for CONF notes, papers etc, which will be public), please contact us (
-- SteffenHenkelmann - 2017-05-06
Edit | Attach | Watch | Print version | History: r2 < r1 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r2 - 2017-05-08 - SteffenHenkelmann
    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    Sandbox All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2020 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
or Ideas, requests, problems regarding TWiki? use Discourse or Send feedback