Runs Geant4 simulation and propagation of electrons and photons to readout. More...

Inheritance diagram for larg4::LArG4:

Public Member Functions
	LArG4 (fhicl::ParameterSet const &pset)

Private Member Functions
void	produce (art::Event &evt) override

void	beginJob () override

void	beginRun (art::Run &run) override

std::unique_ptr < util::PositionInVolumeFilter >	CreateParticleVolumeFilter (std::set< std::string > const &vol_names) const
	Pointer used for correctly updating the clock data state. More...

Private Attributes
std::unique_ptr< g4b::G4Helper >	fG4Help {nullptr}
	G4 interface object. More...

larg4::ParticleListAction *	fparticleListAction
	Geant4 user action to particle information. More...

std::string	fG4PhysListName
	predefined physics list to use if not making a custom one More...

std::string	fG4MacroPath

bool	fCheckOverlaps
	Whether to use the G4 overlap checker. More...

bool	fMakeMCParticles
	Whether to keep a `sim::MCParticle` list. More...

bool	fStoreDroppedMCParticles
	Whether to keep a `sim::MCParticleLite` list of dropped particles. More...

bool	fdumpParticleList
	Whether each event's sim::ParticleList will be displayed. More...

bool	fdumpSimChannels
	Whether each event's sim::Channel will be displayed. More...

bool	fUseLitePhotons

bool	fStoreReflected {false}

int	fSmartStacking
	Whether to instantiate and use class to. More...

double	fOffPlaneMargin = 0.

std::vector< std::string >	fInputLabels

std::vector< std::string >	fKeepParticlesInVolumes
	Only write particles that have trajectories through these volumes. More...

bool	fSparsifyTrajectories
	Sparsify MCParticle Trajectories. More...

CLHEP::HepRandomEngine &	fEngine

detinfo::DetectorPropertiesData	fDetProp
	Must outlive fAllPhysicsLists! More...

AllPhysicsLists	fAllPhysicsLists

LArVoxelReadoutGeometry *	fVoxelReadoutGeometry

Detailed Description

Runs Geant4 simulation and propagation of electrons and photons to readout.

This module collects generated particles from one or more generators and processes them through Geant4.

Input

The module reads the particles to process from simb::MCTruth records. Each particle generator is required to produce a vector of such records: std::vector<simb::MCTruth>.

The module allows two operation modes:

process specific generators: the label of the generator modules to be processed is specified explicitly in LArG4 configuration
process all truth information generated so far: no generator is specified in the LArG4 module configuration, and the module will process all data products of type std::vector<simb::MCTruth>, in a non-specified order

For each simb::MCTruth, a Geant4 run is started. The interface with Geant4 is via a helper class provided by nug4. Only the particles in the truth record which have status code (simb::MCParticle::StatusCode()) equal to 1 are processed. These particles are called, in LArG4 jargon, primaries.

Output

The LArG4 module produces:

a collection of sim::SimChannel: each sim::SimChannel represents the set of energy depositions in liquid argon which drifted and were observed on a certain channel; it includes physics effects like attenuation, diffusion, electric field distortion, etc. Information of the generating Geant4 "track" is retained;
a collection of sim::SimPhotons or sim::SimPhotonsLite: each sim::SimPhotons represents the set of individual photons reaching a channel of the optical detector; it includes physics effects as well as quantum efficiency of the detector (to reduce data size early in the process); sim::SimPhotonsLite drops the information of the single photons and stores only collective information (e.g. their number).
a collection of sim::OpDetBacktrackerRecord (to be documented)
a collection of sim::AuxDetSimChannel (to be documented)
a collection of simb::MCParticle: the particles generated in the interaction of the primary particles with the material in the world are stored, but minor filtering by geometry and by physics is possible. An association of them with the originating simb::MCTruth object is also produced.

Notes on the conventions

all and the particles in the truth record (simb::MCTruth) which have status code (simb::MCParticle::StatusCode()) equal to 1 are passed to Geant4. These particles are called, in LArG4 jargon, primaries. The interface with Geant4 is via a helper class provided by nug4.
normally, information about each particle that Geant4 propagates (which Geant4 calls tracks), primary or not, is saved as an individual simb::MCParticle object into the output particle list. Each simb::MCParticle includes a Geant4-like track ID which is also recorded into each sim::IDE deposited by that particle. This information can be used to track all the deposition from a particle, or to backtrack the particle responsible of a deposition (but see below...). Note that the stored track ID may be different than the one Geant4 used (and, in particular, it's guaranteed to be unique within a sim::LArG4 instance output).
there are options (some set in sim::LArG4Parameters service) which allow for Geant4 tracks not to be saved as simb::MCParticle (e.g. ParticleKineticEnergyCut, KeepEMShowerDaughters). When these particles have deposited energy, their sim::IDE will report the ID of the first parent Geant4 track which is saved in the simb::MCParticle list, but with its sign flipped. Therefore, when tracking or backtracking (see above), comparisons should be performed using the absolute value of the sim::IDE (e.g. std::abs(ide.trackID)).

Timing

The LArG4 module produces sim::SimChannel objects from generated simb::MCParticle. Each particle ("primary") is assigned the time taken from its vertex (a 4-vector), which is expected to be represented in nanoseconds. The sim::SimChannel object is a collection of sim::IDE in time. The position in the sim::IDE is the location where some ionization occurred. The time associated to a sim::IDE is stored in tick units. The time it represents is the time when the ionization happened, which is the time of the primary particle plus the propagation time to the ionization location, plus the drift time, which the ionized electrons take to reach the anode wire. This time is then shifted to the frame of the electronics time via detinfo::DetectorClocks::G4ToElecTime(), which adds a configurable time offset. The time is converted into ticks via detinfo::DetectorClocks::TPCClock(), and this is the final value associated to the sim::IDE. For a more complete overview, see https://cdcvs.fnal.gov/redmine/projects/larsoft/wiki/Simulation#Simulation-Timing

Randomness

The random number generators used by this process are:

'GEANT' instance: used by Geant4
'propagation' instance: used in electron propagation

Configuration parameters

G4PhysListName (string, default: "larg4::PhysicsList"): whether to use the G4 overlap checker, which catches different issues than ROOT
CheckOverlaps (bool, default: false): whether to use the G4 overlap checker
DumpParticleList (bool, default: false): whether to print all MCParticles tracked; requires MakeMCParticles being true
DumpSimChannels (bool, default: false): whether to print all depositions on each SimChannel
SmartStacking (int, default: 0): whether to use class to dictate how tracks are put on stack (nonzero is on)
MakeMCParticles (flag, default: true): keep a list of the particles seen in the detector, and eventually save it; you almost always want this on
KeepParticlesInVolumes (list of strings, default: empty): list of volumes in which to keep simb::MCParticle objects (empty keeps all); requires MakeMCParticles being true
GeantCommandFile (string, required): G4 macro file to pass to G4Helper for setting G4 command
Seed (integer, not defined by default): if defined, override the seed for random number generator used in Geant4 simulation (which is obtained from NuRandomService by default)
PropagationSeed (integer, not defined by default): if defined, override the seed for the random generator used for electrons propagation to the wire planes (obtained from the NuRandomService by default)
InputLabels (list of strings, default: process all truth): optional list of generator labels whose produced simb::MCTruth will be simulated; if not specified, all simb::MCTruth vector data products are simulated
ChargeRecoveryMargin (double, default: 0): sets the maximum distance from a plane for the wire charge recovery to occur, in centimeters; for details on how it works, see larg4::LArVoxelReadout::SetOffPlaneChargeRecoveryMargin(). A value of 0 effectively disables this feature. All TPCs will have the same margin applied.

Simulation details

Source of the operational parameters

Some of the physical properties have their values set in FHiCL configuration (e.g. detinfo::LArParameters). Then, GEANT4 is informed of them via larg4::MaterialPropertyLoader. The material property table in GEANT4 is then used by other LArSoft components to discover the parameter values.

Among the parameters registered to GEANT4, the scintillation yields, i.e. how many scintillation photons are produced on average by 1 MeV of deposited energy, are also stored by type of ioniziong particle. These scintillation yields do include a prescale factor (that may include, for example, the photomultiplier quantum efficiency), from the ScintPreScale parameter of detinfo::LArPropertiesStandard or equivalent.

Reflectivity to optical photons

Two models are supported for the simulation of (scintillation) light crossing detector surfaces:

the standard one from GEANT4, implemented in G4OpBoundaryProcess
a simplified one, implemented in larg4::OpBoundaryProcessSimple

The model is chosen according to the value of detinfo::DetectorProperties::SimpleBoundary(), and the choice is currently exerted by larg4::OpticalPhysics.

The simplified model is faster and simpler: it only deals with absorption and reflection (both specular and diffues). This is the "default" model used in most contexts.

GEANT4 model is more complete and slower. It may take some art to fully configure all the properties of the materials at the sides of the surfaces. The price is a detailed simulation that includes among others refraction and wavelength shifting.

Scintillation

When using the fast optical simulation, which is the "standard" running mode, energy depositions from GEANT4 are "converted" into a number of scintillation photons by the global larg4::IonizationAndScintillation object instance, which internally utilizes the algorithm set up via configuration parameter IonAndScintCalculator in LArG4Parameters service (at the time of writing, "Separate" is supported and "NEST" is accepted too). The number of scintillation photons per energy unit is read from GEANT4 material properties table. It includes already quantum efficiency ("prescale") and it may depend on the type of ionizing particle, depending on the configuration (LArPropertiesStandard parameter ScintByParticleType). This value ("yield") is used as the average of a Poisson distribution from which the actual number of scintillation photons is extracted case by case. The implementation larg4::ISCalculationSeparate may also include medium saturation effects as well, if configured, but only if the scintillation yield is set not to depend on the type of ionizing particle. The number of scintillation photons is then distributed between the fast and slow component by a yield ratio also set in the material parameters, and the single photons are distributed in time accordingly to their component.

Definition at line 315 of file LArG4_module.cc.

Constructor & Destructor Documentation

larg4::LArG4::LArG4 ( fhicl::ParameterSet const & pset )

explicit

Definition at line 406 of file LArG4_module.cc.

     : art::EDProducer{pset}
     , fG4PhysListName(pset.get<std::string>("G4PhysListName", "larg4::PhysicsList"))
     , fCheckOverlaps(pset.get<bool>("CheckOverlaps", false))
     , fMakeMCParticles(pset.get<bool>("MakeMCParticles", true))
     , fStoreDroppedMCParticles(pset.get<bool>("StoreDroppedMCParticles", false))
     , fdumpParticleList(pset.get<bool>("DumpParticleList", false))
     , fdumpSimChannels(pset.get<bool>("DumpSimChannels", false))
     , fSmartStacking(pset.get<int>("SmartStacking", 0))
     , fOffPlaneMargin(pset.get<double>("ChargeRecoveryMargin", 0.0))
     , fKeepParticlesInVolumes(pset.get<std::vector<std::string>>("KeepParticlesInVolumes", {}))

Member Function Documentation

void larg4::LArG4::beginJob ( )

overrideprivate

void larg4::LArG4::beginRun ( art::Run & run )

overrideprivate

std::unique_ptr<util::PositionInVolumeFilter> larg4::LArG4::CreateParticleVolumeFilter ( std::set< std::string > const & vol_names ) const

private

Pointer used for correctly updating the clock data state.

Configures and returns a particle filter

void larg4::LArG4::produce ( art::Event & evt )

overrideprivate

The main routine of this module: Fetch the primary particles from the event, simulate their evolution in the detector, and produce the detector response.

Member Data Documentation

AllPhysicsLists larg4::LArG4::fAllPhysicsLists

private

Definition at line 354 of file LArG4_module.cc.

bool larg4::LArG4::fCheckOverlaps

private

Whether to use the G4 overlap checker.

Definition at line 334 of file LArG4_module.cc.

detinfo::DetectorPropertiesData larg4::LArG4::fDetProp

private

Must outlive fAllPhysicsLists!

Definition at line 353 of file LArG4_module.cc.

bool larg4::LArG4::fdumpParticleList

private

Whether each event's sim::ParticleList will be displayed.

Definition at line 337 of file LArG4_module.cc.

bool larg4::LArG4::fdumpSimChannels

private

Whether each event's sim::Channel will be displayed.

Definition at line 338 of file LArG4_module.cc.

CLHEP::HepRandomEngine& larg4::LArG4::fEngine

private

Random-number engine for IonizationAndScintillation initialization

Definition at line 350 of file LArG4_module.cc.

std::unique_ptr<g4b::G4Helper> larg4::LArG4::fG4Help {nullptr}

private

G4 interface object.

Definition at line 327 of file LArG4_module.cc.

std::string larg4::LArG4::fG4MacroPath

private

directory path for Geant4 macro file to be executed before main MC processing.

Definition at line 332 of file LArG4_module.cc.

std::string larg4::LArG4::fG4PhysListName

private

predefined physics list to use if not making a custom one

Definition at line 331 of file LArG4_module.cc.

std::vector<std::string> larg4::LArG4::fInputLabels

private

Definition at line 344 of file LArG4_module.cc.

std::vector<std::string> larg4::LArG4::fKeepParticlesInVolumes

private

Only write particles that have trajectories through these volumes.

Definition at line 346 of file LArG4_module.cc.

bool larg4::LArG4::fMakeMCParticles

private

Whether to keep a sim::MCParticle list.

Definition at line 335 of file LArG4_module.cc.

double larg4::LArG4::fOffPlaneMargin = 0.

private

Off-plane charge recovery margin dictate how tracks are put on stack.

Definition at line 342 of file LArG4_module.cc.

larg4::ParticleListAction* larg4::LArG4::fparticleListAction

private

Initial value:

{

nullptr}

Geant4 user action to particle information.

Definition at line 328 of file LArG4_module.cc.

int larg4::LArG4::fSmartStacking

private

Whether to instantiate and use class to.

Definition at line 341 of file LArG4_module.cc.

bool larg4::LArG4::fSparsifyTrajectories

private

Sparsify MCParticle Trajectories.

Definition at line 348 of file LArG4_module.cc.

bool larg4::LArG4::fStoreDroppedMCParticles

private

Whether to keep a sim::MCParticleLite list of dropped particles.

Definition at line 336 of file LArG4_module.cc.

bool larg4::LArG4::fStoreReflected {false}

private

Definition at line 340 of file LArG4_module.cc.

bool larg4::LArG4::fUseLitePhotons

private

Definition at line 339 of file LArG4_module.cc.

LArVoxelReadoutGeometry* larg4::LArG4::fVoxelReadoutGeometry

private

Initial value:

{

nullptr}

Definition at line 355 of file LArG4_module.cc.

The documentation for this class was generated from the following file:

LArG4_module.cc

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Input

Output

Notes on the conventions

Timing

Randomness

Configuration parameters

Simulation details

Source of the operational parameters

Reflectivity to optical photons

Scintillation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation