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

Production Scripts

Within the Mu2e/Production repo there are a set of scripts (Production/Scripts). Each script is prefixed with ``gen_" followed by the following:

• Primary : generic script to generate any primary (providing a generator for it exists)
• Digitize : runs standard digitization. User must define what type of digitization is needed
• Reco : runs standard reconstruction. User must define what type of reconstruction is needed
• Mix : combines given primary with pile-up and beam background frames.

All these scripts produce generate_fcl output for the specific job. The user should then run these on the grid. Or alternatively, the entire campaign can be run on POMs.

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

For easy running the gen_Primary.sh script can be used to generate fcl which can then be submitted to the grid:

gen_Primary.sh --primary CeEndpoint --pcamp p --scamp v --type MuMinus --njobs 1000 --events 1000

where:

[ --primary primary physics name ]
[ --pcamp primary campaign name ]
[ --scamp stops campaign name ]
[ --type stopped particle type ]
[ --njobs number of jobs ]
[ --events events per job ]
[ --flat (opt) set to flat type ]
[ --pdg (opt) for Flat spectra ]
[ --start (opt) for Flat spectra ]
[ --end (opt) for Flat spectra ]
 [ --field (opt) for special runs ]

The resulting "detector steps" files contain:

• 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.

e.g.Production/Scripts/gen_Digitize.sh --primary CeEndpoint --campaign MDC2020 --pver t --over t --digitype OnSpill --dbpurpose perfect --dbversion v1_0

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

 [ --primary primary physics process name ]
 [ --campaign campaign name e.g. MDC2020 ]
 [ --pver primary campaign version e.g 'p']
 [ --over output campaign version e.g. 'v' ]
 [ --digitype  digitization type e.g. OnSpill, OffSpill, NoField, Extracted]
 [ --dbpurpose purpose of db e.g. perfect, startup, best  ]
 [ --dbversion db version ]
 [ --merge (opt) merge factor, default 10 ]
 [ --owner (opt) default mu2e ]
 [ --samopt (opt) Options to samListLocation default "-f --schema=root" ]
 [ --field (opt) default = DS +TSD, override for special runs ]
 [ --dsteps (opt)  If specified, use this list of input dts.*.art files instead of the one generated by SAM ]
 

The above example will produce the digitize.fcl files for digitizing CeEndpoint primaries from a campaign called MDC2020t according to on-spill timing, using db 'v1_0' of the 'MDC2020_perfect' database for digitization parameters. It should also produce a directory of an appropriate name (given the input choices).

The output of this stage is split into multiple streams:

dig.MU2EGRIDDSOWNER.CeEndpointOnSpillCalo.MU2EGRIDDSCONF.001202_00000000.art
dig.MU2EGRIDDSOWNER.CeEndpointOnSpillDiag.MU2EGRIDDSCONF.001202_00000000.art
dig.MU2EGRIDDSOWNER.CeEndpointOnSpillSignal.MU2EGRIDDSCONF.001202_00000000.art
dig.MU2EGRIDDSOWNER.CeEndpointOnSpillTrk.MU2EGRIDDSCONF.001202_00000000.art
dig.MU2EGRIDDSOWNER.CeEndpointOnSpillUntriggered.MU2EGRIDDSCONF.001202_00000000.art

these represent different trigger streams (and the untriggered stream)

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 script: Production/Scripts/gen_Reco.sh. Again there are a number of inputs you need to give this script:

gen_Reco.sh --primary CeEndpoint --campaign MDC2020 --dver MDC2020v --rver MDC2020v  --dbpurpose perfect --dbversion v1_0 --merge 10 --digitype OnSpill --stream Signal --beam 1BB

where:

 [ --primary primary physics name ]
 [ --campaign campaign name ]
 [ --dver digi campaign version ]
 [ --rver reco campaign version ]
 [ --dbpurpose purpose of db e.g. perfect, startup, best  ]
 [ --dbversion db version ]
 [ --digitype OnSpill, OffSpill, Mix1BB, Mix2BB, etc. ]
 [ --stream Signal, Trk, Diag, Calo etc. ]
 [ --merge merge factor (opt) default 10]
 [ --owner (opt) default mu2e ]
 [ --samopt (opt) Options to samListLocation default "-f --schema=root" ]
 [ --digis (opt)  If specified, use this list of input dig.*.art files instead of the one generated by SAM ]

The example above will produce generate_fcl output for the specific job. The user should then run these on the grid. Or alternatively, the entire campaign can be run on POMs.

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.