SimulationFCL

This page provides documentation on the simulation infrastructure for the MDC2020 era of the Mu2e code base.

Introduction

• Mu2e/Production contains the code a user will use to generate a primary physics process, digitize the output and reconstruct the hits, timecluster, tracks,clusters etc.

Available Processes

Several new generators and workflows have been implemented for MDC2020. The Mu2e/Production/JobConfig/primary contains all the scripts presently available for generating primary processes. If the process you require doesn't have a fcl file here you will need to build one. Its probably also a good idea to check that the source code for that process is up to date too.

Simulation Workflow

Stopped Particles

In order to make a set of daughter particles, e.g. decay in orbit electrons, the user first needs a list of mother "stopped particles" these could be stopped muons or pions (or other) at either the stopping target or Inner Proton Absorber (IPA), at present these are the only stopping locations available.

These stopped particles must be stored within a .art file and must be created following the standard production workflow :

• Generate Protons on Target (POT) using the Production/JobConfig/beam/POT.fcl file. This will result in 2 output .art files: beam particles and neutral particles.
• Neutrals can be resampled and incorporated in pileup modeling. To make the stopped muons the beam output must be passed through the Production/JobConfig/beam/BeamSplitter.fcl. This will make 2 output .art files: beam electrons and muons. The electrons can be resampled and incorporated in the final mixing job.
• The muon output can then be passed into Production/JobConfig/pileup/MuBeamResampler.fcl. Two output streams are created : Target stops and IPA stops. These will be used to make your stopped muon .art files.
• The make the .art file of stopped muons at the target run the target output through Production/JobConfig/pileup/MuonStopSelector.fcl. The mu - output stream will be what you require.

Generating a Primary

All physics processes (signal and background) should have an associated generator script in the Production/JobConfig/primary directory. These files can be run using the driver fcl file examples in Production/Tests. The .art file of relevent mother stopped particles must be fed into the driver fcl files using the ``FileName" parameter for example:

physics.filters.TargetStopResampler.fileNames : ["/pnfs/mu2e/tape/phy-sim/sim/mu2e/MuminusStopsCat/MDC2020k/art/39/6a/sim.mu2e.MuminusStopsCat.MDC2020k.001201_00000000.art"]

To run on the grid you will need to follow the advice in GenerateFcl. In the case of running on the grid edit the path to the stopped muon file by first typing in the terminal

samweb list-file-locations --schema=root --defname="sim.mu2e.MuminusStopsCat.MDC2020k.art" | cut -f1

replace the FileName in the fcl file with the output of this command.

To run interactively for a pure primary CeEndpoint (as an example):

mu2e -c Production/Tests/CeEndpointSteps.fcl --nevts=1000

If you wish to look at the generator output you can use the fcl file Production/JobConfig/primary/GenPlots.fcl (i.e. include it in your driver fcl and ensure the analyzer is in your end path). If you want an output histogram/root tree file pass in an output file name to the TFileService:

services.TFileService.fileName: "nts.owner.GenPlots.version.sequencer.root"

The final output from the primary stage will be a "dts" type file in the form:

dts.tester.description.version.art

This file contains:

• Monte Carlo Info : GenParticles, SimParticles, StepPointMCs associated with the generator output
• Detector Steps : StrawGasSteps, CrvSteps, CaloShowerSteps - these will be used by the digitization modules to make the digis which will later be used for reconstruction.

Digitization

The next stage (if you intend to look at reconstructed objects) is to run the primary output (the dts file) through the digitization process. To do this you will need to run one of the scripts in Production: Production/Scripts/gen_Digitize.sh. This script takes a number of command line arguments.

 source Production/Scripts/gen_Digitize.sh [primaryName] [datasetDescription] \
   [campaignInput] [campaignOutput] [nmerge] [digitype] [dbpurpose] [dbversion] \
   [dsowner]

This script will produce the fcl files needed for the digitization stage. Here is a list of the arguments and their meaning:

• name of the primary [primaryName]
• dataset description [datasetDescription],
• campaign version of the input file [campaignInput],
• campaign version of the output file [campaignOutput],
• merge factor [nmerge],
• digitization type (OnSpill, OffSpill, NoField, Extracted) [digitype],
• database purpose (perfect, best, startup) [dbpurpose],
• database version [dbversion]
• dsowner of the FCL files (optional, default to mu2e)

For Example:

 gen_Digitize.sh CeEndpoint MDC2020 m m 1 OnSpill perfect v2_0

This will produce the digitize.fcl files for digitizing CeEndpoint primaries from a campaign called MDC2020m according to on-spill timing, using 'v2_0' of the 'MDC2020_perfect' database for digitization parameters.

The output of this stage is split into 2 streams:

• DigiUntriggered
• DigiTriggered

Reconstructing tracks from the target

As a user you can reconstruct either triggered or untriggered streams, it depends on what you are studying. To reconstruct particles from the target simply run the following:

mu2e -c Production/JobConfig/reco/Reco.fcl dig.owner/Digi(Un)Triggered.version.art

This will run the main reconstruction scripts with default cut parameters in the helix fitting and Kalman seeding modules.

The output file will be in the form:

mcs.owner.description.version.art

An "mcs" file contains reconstructed output, digi objects, and Monte Carlo truth information.

Reconstructing tracks from the IPA

To reconstruct output from stopped muons at the IPA some of the default parameters/cuts need to be altered, therefore a specific script for IPA originating particles is also available:

mu2e -c Production/JobConfig/reco/IPA-Michel.fcl dig.owner/Digi(Un)Triggered.version.art

The output will be in the same form as for daughter particles from the target.

NTupling for Analysis

The .art output is not much use for analysis. To analyze your reconstructed output you could make custom analyzers. However, for standard output the TrkAna package makes lists of negative and positive output and stores all reconstruction quantities:

mu2e -c TrkAna/fcl/TrkAnaReco.fcl mcs.owner.description.version.art

The output will be a .root file with "nts" prefix. To find out more about TrkAna: TrkAna.

Mixing

The above example assumed a primary sample. Mixing_and_Resampling explains the technical details of making mixed samples. The main difference from primary generation is that the user would need to ensure the additional files such as the neutral, electron beam, and pile-up .art files made via the workflow described in the first section of this page are also passed into the generator.

To run a mixed job the best thing to do is to begin with Production/Scripts/gen_Mix.sh to generate the fcl files. Once generated submit them to the grid as you would any other set of fcl files you have generated.

This script essentially writes a template fcl based on user input. There are a number of input parameters listed in that file. These include the name of the primary physics process. In addition, inside the script, you will need to point this file to your output from the beam and resampling stages.

Here is a list of what files you would need and where they are produced:

• "dts.mu2e.NeutralsFlashCat.version.art" : made via the Production/JobConfig/beam/POT.fcl file
• "dts.mu2e.MuBeamFlashCat.version.art"  : made via the Production/JobConfig/pileup/MuBeamResampler.fcl file
• "dts.mu2e.EleBeamFlashCat.version.art"  : made via the Production/JobConfig/pileup/EleBeamResampler.fcl file
• "dts.mu2e.MuStopPileupCat.version.art"  : made via the Production/JobConfig/pileup/mustop.fcl file

The best practice is to follow the logic of the gen_Mix script to create your template fcl with the required includes and definitions.

Your .art files are input to generate_fcl using the ``auxinput" parameter from within .txt files:

 --auxinput=1:physics.filters.MuStopPileupMixer.fileNames:MuStopPileupCat$3.txt 
 --auxinput=1:physics.filters.EleBeamFlashMixer.fileNames:EleBeamFlashCat$3.txt
 --auxinput=1:physics.filters.MuBeamFlashMixer.fileNames:MuBeamFlashCat$3.txt
 --auxinput=1:physics.filters.NeutralsFlashMixer.fileNames:NeutralsFlashCat$3.txt

The generated output can be passed through digitization and reconstruction stages in the same way the primary samples were.

Other Target Materials

The target material properties are defined in Offline/ConditionsService/data/global_constants01.txt. If you require an additional material add its properties to this file.

Workflow Diagram

Other Resources

• GenerateFcl - Learn how to generate a fcl file in preparation for running on the grid.