Updates to the STM simulation framework

JobConfig/pileup/STM/BeamToVD.fcl

@@ -1,121 +1,163 @@
+# Run Stage 1 of the STM simulation defined in docdb 51487 
 # Re-sample EleBeamCat and MuBeamCat datasets, propagate them to a chosen virtual detector, and write out the events with SimParticles and StepPointMCs travelling through that virtual detector only
+# Based on Production/JobConfig/Pileup/EleBeamResampler.fcl and Production/JobConfig/Pileup/MuBeamResampler.fcl 
+# Usage:
+#  - General modifications should not be required to this file.
+#  - To generate fcl files that use this file, follow up with Production/Scripts/STM/gen_BeamToVD.sh
+#  - To change the virtual detector ID, compression settings, or output data products, modify the relevant parameters in Production/JobConfig/pileup/STM/prolog.fcl
+#  - To change the GEANT verbosity, see the bottom of this file
 # Original author: Yuri Oksuzian, 2019
 # Updated for MDC2020 (DetectorSteps): D. Brown
 # Updated for STM studies: P. Plesniak
 
 # Offline includes
-#include "Offline/CommonMC/fcl/prolog.fcl"
+# Offline/fcl/standardServices.fcl - contains standard Mu2e services
 #include "Offline/fcl/standardServices.fcl"
-#include "Offline/STMMC/fcl/prolog.fcl"
 
 # Production includes
+# Production/JobConfig/common/prolog.fcl - contains Mu2eG4 common configuration
 #include "Production/JobConfig/common/prolog.fcl"
+# Production/JobConfig/pileup/prolog.fcl - contains beam resampling common configuration
 #include "Production/JobConfig/pileup/prolog.fcl"
+# Production/JobConfig/pileup/STM/prolog.fcl - contains STM pileup common configuration
 #include "Production/JobConfig/pileup/STM/prolog.fcl"
 
 
-process_name: BeamToVD
+process_name : BeamToVD
 
 source : {
   module_type : EmptyEvent
   maxEvents : @nil
 }
 
+# Import the current geomety, calibration, and conditions data, as well as the RandomNumberGenerator and seed services
 services : @local::Services.Sim
 
-physics: {
+physics : {
   producers : {
-    @table::Common.producers
-    @table::Pileup.producers
+    @table::Common.producers # Contains Mu2eG4 common configuration (drives the Mu2eG4 simulation)
+    @table::Pileup.producers # TODO - see if this can be deleted, following discussion with Andy
     extractVirtualDetectorSteps : {
-      # Creates "mu2e::StepPointMCs_extractVirtualDetectorSteps__BeamToVD" products that only store StepPointMCs in the selected virtual detector
-      # Want to only keep events with the given virtual detector ID and filter out the rest
-      # Empty collections will be generated if the selected virtual detector has no associated StepPointMCs to allow the compression to take place
+      # Creates "mu2e::StepPointMCs_extractVirtualDetectorSteps_virtualdetecctor_BeamToVD" products that only store StepPointMCs in the selected virtual detector.
+      # Want to only keep events if a SimParticle crosses the selected virtual detector.
+      # Empty collections will be generated if the selected virtual detector has no associated StepPointMCs to allow the filtering to take place.
       module_type : STMResamplingProducer
-      StepPointMCsTag : @local::ResamplingProducer.StepPointMCsTag
-      VirtualDetectorID : @local::ResamplingProducer.VirtualDetectorID
+      StepPointMCsTag : @local::STMPileup.ResamplingProducer.StepPointMCsTag
+      VirtualDetectorID : @local::STMPileup.ResamplingProducer.VirtualDetectorID
     } 
     compressDetStepMCsSTM : {
-      # Creates "mu2e::SimParticlemv_compressDetStepMCsSTM__BeamToVD" and "mu2e::StepPointMCs_compressDetStepMCsSTM__BeamToVD" products from "mu2e::StepPointMCs_extractVirtualDetectorSteps__BeamToVD" products
-      # Keeps SimParticles and StepPointMCs going through the selected virtual detector only
+      # Creates "mu2e::StepPointMCs_compressDetStepMCsSTM_virtualdetecctor_BeamToVD" and "mu2e::SimParticlemv_compressDetStepMCsSTM_virtualdetecctor_BeamToVD" products from "mu2e::StepPointMCs_extractVirtualDetectorSteps_virtualdetecctor_BeamToVD" products.
+      # These collections contain the StepPointMCs and SimParticles that pass through the selected virtual detector only, any other daughter particles are removed.
+      # Keeps SimParticles and StepPointMCs going through the selected virtual detector only.
       module_type : CompressDetStepMCs
-      strawGasStepTag : ""
-      caloShowerStepTag : ""
-      surfaceStepTag : ""
-      crvStepTag : ""
-      simParticleTags : ["g4run"]
+      strawGasStepTag : @local::STMSimDataProducts.EmptyString
+      caloShowerStepTag : @local::STMSimDataProducts.EmptyString
+      surfaceStepTag : @local::STMSimDataProducts.EmptyString
+      crvStepTag : @local::STMSimDataProducts.EmptyString
+      simParticleTags : [
+        @local::STMSimDataProducts.Stage1.GEANT.SimParticles
+      ]
       debugLevel : 0
-      stepPointMCTags : ["extractVirtualDetectorSteps"]
+      stepPointMCTags : [
+        @local::STMSimDataProducts.Stage1.ExtractedStepPointMCs
+      ]
       compressionOptions : {
-        strawGasStepCompressionLevel: "noCompression"
-        caloShowerStepCompressionLevel: "noCompression"
-        crvStepCompressionLevel: "noCompression"
-        surfaceStepCompressionLevel: "noCompression"
-       	simParticleCompressionLevel : "noCompression"
-       	stepPointMCCompressionLevel : "noCompression"
-       	keepNGenerations : -1
-       	mcTrajectoryCompressionLevel : "noCompression"
+        strawGasStepCompressionLevel : @local::STMPileup.CompressionParameters.NoCompressionString
+        caloShowerStepCompressionLevel : @local::STMPileup.CompressionParameters.NoCompressionString
+        crvStepCompressionLevel : @local::STMPileup.CompressionParameters.NoCompressionString
+        surfaceStepCompressionLevel : @local::STMPileup.CompressionParameters.NoCompressionString
+       	simParticleCompressionLevel : @local::STMPileup.CompressionParameters.NoCompressionString
+       	stepPointMCCompressionLevel : @local::STMPileup.CompressionParameters.NoCompressionString
+       	keepNGenerations : @local::STMPileup.CompressionParameters.CompressionGenerations
+       	mcTrajectoryCompressionLevel : @local::STMPileup.CompressionParameters.NoCompressionString
       }
-      mcTrajectoryTag : ""
+      mcTrajectoryTag : @local::STMSimDataProducts.EmptyString
     }
   }
   filters : {
-    @table::Common.filters
-    @table::Pileup.filters
-    filterVirtualDetectorSteps: {
-      # Filters events based on the size of "mu2e::StepPointMCs_compressDetStepMCsSTM__BeamToVD"
-      # If there are no StepPointMCs in the selected virtual detector, the event is not kept
-      # Required as extractVirtualDetectorSteps will create a StepPointMCCollection even if the collection is empty
-      module_type: STMResamplingFilter
-      StepPointMCsTag : @local::ResamplingFilter.StepPointMCsTag
+    @table::Common.filters # Contains Mu2eG4 common filters (consistent filter, required for all Mu2eG4 jobs)
+    @table::Pileup.filters # Contains beam resampling common filters (contains the beamResampler definition)
+    filterVirtualDetectorSteps : {
+      # Filters events based on the size of "mu2e::StepPointMCs_compressDetStepMCsSTM_virtualdetector_BeamToVD".
+      # If there are no StepPointMCs in the selected virtual detector, the event is not kept.
+      # Required as extractVirtualDetectorSteps will create a StepPointMCCollection even if the collection is empty.
+      module_type : STMResamplingFilter
+      StepPointMCsTag : @local::STMPileup.ResamplingFilterStepPointMCs
     }
   }
   analyzers : {
-    @table::Common.analyzers
+    @table::Common.analyzers # Contains Mu2eG4 common analyzers (includes genCountLogger, which generates a nice generated event summary)
     countVirtualDetectorHits : {
       # Runs a counter over the virtual detectors to keep track of hits
       module_type : CountVirtualDetectorHits
-      stepPointMCsTag : @local::VirtualDetectorCounter.StepPointMCsTag
-      virtualDetectorIDs : @local::VirtualDetectorCounter.virtualDetectorIDs
+      stepPointMCsTag : @local::STMPileup.VirtualDetectorCounter.StepPointMCs
+      virtualDetectorIDs : @local::STMPileup.VirtualDetectorCounter.VirtualDetectorIDs
     }
   }
-  # setup paths
-  STMCompressedPath : [@sequence::Pileup.beamResamplerSequence, @sequence::Common.g4Sequence, extractVirtualDetectorSteps, compressDetStepMCsSTM, filterVirtualDetectorSteps]
-  trigger_paths: [STMCompressedPath]
-  outPathCompressed : [genCountLogger, countVirtualDetectorHits, compressedOutput]
-  end_paths: [outPathCompressed]
+  # Setup the trigger paths
+  STMCompressedPath : [
+    @sequence::Pileup.beamResamplerSequence, # Resample beam particles from input datasets
+    @sequence::Common.g4Sequence, # Run the Mu2eG4 simulation
+    extractVirtualDetectorSteps, # Extract StepPointMCs in the selected virtual detector
+    filterVirtualDetectorSteps, # Filter events based on presence of StepPointMCs in the selected virtual detector
+    compressDetStepMCsSTM # Compress to keep only SimParticles and StepPointMCs contributing to a particle crossing the selected virtual detector
+  ]
+  trigger_paths : [
+    STMCompressedPath
+  ]
+  # Setup the output paths
+  outPathCompressed : [
+    genCountLogger, # Generates a nice generated event summary
+    countVirtualDetectorHits, # Counts the number of hits in the selected virtual detector
+    compressedOutput # Output module to write out the compressed data products
+  ]
+  end_paths : [
+    outPathCompressed
+  ]
 }
 
-# Keep only the necessary data
-outputs: {
+# Set up the output paths, keeping only the desired data products
+outputs : {
   compressedOutput : {
-    module_type: RootOutput
-    outputCommands:   [
-      "drop *_*_*_*",
-      @sequence::Pileup.BeamToVDKeptProducts
+    module_type : RootOutput
+    outputCommands : @local::STMSimDataProducts.BeamToVDKeptProducts
+    SelectEvents : [ # Only write out events that pass through the selected virtual detector
+      STMCompressedPath
     ]
-    SelectEvents: [STMCompressedPath]
-    fileName : "dts.owner.BeamToVD.version.sequencer.art"
+    fileName : @local::STMPileup.SimulationOutputFilenames.Stage1
   }
 }
 
-# Point Mu2eG4 to the pre-simulated data
-physics.producers.g4run.inputs: {
-  primaryType: "StepPoints"
-  primaryTag: "beamResampler:Beam"
-  inputMCTrajectories: ""
-  simStageOverride: 1
-  inputPhysVolumeMultiInfo: "beamResampler"
-  updateEventLevelVolumeInfos: {
-    input: "beamResampler:eventlevel"
-    outInstance: "eventlevel"
+# GEANT variables
+# Point Mu2eG4 to input data
+physics.producers.g4run.inputs : {
+  primaryType : @local::STMSimDataProducts.Stage1.InputType.BeamCatDatasets
+  primaryTag : @local::STMSimDataProducts.Stage1.InputTag.BeamCatDatasets
+  inputMCTrajectories : @local::STMSimDataProducts.EmptyString
+  simStageOverride : 1
+  inputPhysVolumeMultiInfo : @local::STMSimDataProducts.Stage1.InputPhysVolumeMultiInfo.BeamCatDatasets
+  updateEventLevelVolumeInfos : {
+    input : @local::STMSimDataProducts.Stage1.UpdateEventLevelVolumeInfos.Input.BeamCatDatasets
+    outInstance : @local::STMSimDataProducts.Stage1.UpdateEventLevelVolumeInfos.OutInstance
   }
 }
-physics.producers.g4run.SDConfig.preSimulatedHits:  ["beamResampler:virtualdetector"]
-physics.producers.g4run.SDConfig.enableSD: [virtualdetector]
-physics.producers.g4run.Mu2eG4CommonCut: {}
+# Specify pre-simulated hits for beam resampling
+physics.producers.g4run.SDConfig.preSimulatedHits : @local::STMSimDataProducts.Stage1.PreSimulatedData.BeamCatDatasets
+
+# Enable the virtual detector sensitive detector - without this the virtualdetector data products will not be created
+physics.producers.g4run.SDConfig.enableSD : [
+  virtualdetector
+]
+
+# Explicitly disable common cuts for STM pileup generation
+physics.producers.g4run.Mu2eG4CommonCut : {}
+
+# Optional debugging output - makes it very clear what is happening in GEANT
+# physics.producers.g4run.debug.trackingVerbosityLevel : 1
+# physics.producers.g4run.debug.steppingVerbosityLevel : 1
+
 
 # Epilog includes
 #include "Production/JobConfig/common/MT.fcl"
 #include "Production/JobConfig/common/epilog.fcl"
-#include "Production/JobConfig/pileup/epilog.fcl"
+# #include "Production/JobConfig/pileup/epilog.fcl" # Note - this was present for the study in 51487, and has been removed for subsequent studies to help quantify if this cut impacts results