Configuring the Simulation

This page details some of the parameters you can use to tune the simulation to behave how you want it to. This page is manually written and is focused on introducing folks to important parameters. Please refer to the Python Configuration Reference for a more complete list of parameters - many of which are documented from the code itself.

General

Like any other Producer, the simulation is configured by passing parameters to it in the python configuration file.

simulation.parameter_name = parameter_value

The parameter keys, types, accessing locations, and descriptions are documented on this page. A minimal working example is displayed on Generating Simulation Samples

Biasing

Biasing is helpful for efficiently simulating the detector's response to various events. The biasing parameters are given directly to the simulation and are listed below.

In v3.0.0 of ldmx-sw, we transitioned the biasing operators to be configured by their own Python classes. Those operators are stored in the SimCore.bias_operators module and are attached to the Simulator class similar to generators and actions.

# config script snippet example for biasing
from LDMX.SimCore import bias_operators
# Enable and configure the biasing
sim.biasing_operators = [ 
    bias_operators.PhotoNuclear('ecal', 450., 2500., only_children_of_primary=True)
]

Dark Brem Process (Signal)

The signal generation is done by enabling the dark bremsstrahlung process in Geant4. We do this using another Python configuration class DarkBrem in the SimCore.dark_brem module. A more full description of the Dark Brem process and how these parameters affect its abilities is described [on its own page]({% link docs/Dark-Brem-Signal-Process.md %}). The most direct way of starting the dark brem process is to simply activate by providing the minimal parameters for it to run.

# config script snipet example for dark brem
from LDMX.SimCore import dark_brem
db_model = dark_brem.G4DarkBreMModel(lhe)
db_model.threshold = 2. #GeV - minimum energy electron needs to have to dark brem
db_model.epsilon   = 0.01 #decrease epsilon from one to help with Geant4 biasing calculations
sim.dark_brem.activate(ap_mass , db_model)

UserActions

Because of the wide variety and flexibility of Geant4's UserActions, we have implemented a way for these various classes to all be passed along with their parameters. This method is extremely similar to how you create Event Processors and give them parameters. The best way to illustrate how to use one is with an example:

# First create the UserAction, configuring its various parameters
from LDMX.Biasing import filters
target_brem_filter = filters.TargetBremFilter(
    recoil_max_p_threshold = 3000.0, # MeV
    brem_min_energy_threshold = 5000.0 # MeV
)
# Then give the UserAction to the simulation so that it knows to use it
simulation.actions.append( target_brem_filter )

No matter the UserAction, the last line above is how you tell the simulation to use it.

The details of how each UserAction works and what parameters are used are (read: should be) documented within each of those classes. There are a few user actions that do more technical things modifying how the simulation progresses. The majority of user actions are "filters" of some kind which are explained in a bit more detail below.

Filters

These UserActions filter for specific behavior in the simulation. Some of them abort an event if certain criteria aren't met and others make sure tracks matching certain criteria are saved into the output simulation file.

Access with: from LDMX.Biasing import filters

The first type of filter aborts events if certain requirements aren't met.

The other type of filter looks for tracks (what Geant4 call's individual particles) in Geant4 that match certain conditions and tell Geant4 (and our simulation) to save them in the output SimParticles collection.

Generators

There are a few general options that determine how primaries are generated. These parameters must be passed directly to the simulation (like the biasing parameters).

Like UserActions, PrimaryGenerator is a python class that you can create using the LDMX.SimCore.simcfg python module. And actually, there are several helpful functions defined in the LDMX.SimCore.generators python module. These helpful functions return the correct python class and set some helpful defaults. Look at that file for more details. The most widely used primary generator is a simple one: a single 4GeV electron fired from upstream of the tagger. You could use that generator in your simulation with the following lines:

from LDMX.SimCore import generators
simulation.generators = [ generators.single_4gev_e_upstream_tagger() ]

Several of these generators can be used at once, although not all combinations have been tested. All of these generators have a beam_spot_smear parameter that defines how to smear the primary vertex it generates in each of the Cartesian directions (x,y,z).

A more detailed description of the parameters you can pass the various generators are listed below. All of the python code below requires the LDMX.SimCore.generators module to be imported:

from LDMX.SimCore import generators

Simple Particle Gun

This generator is the basic Geant4 particle gun. It can shoot one particle of a definite position and momentum into the simulation. Create a ParticleGun with:

myParticleGun = generators.Gun( "myParticleGun" )
# set the parameters, for example, to use electrons:
myParticleGun.particle = 'e-'

LHE vertices as primaries

This generator copies the primary vertex from an LHE file into our simulation framework. Create one with:

myLHE = generators.Lhe("path/to/file.lhe")

Geant4's General Particle Source

This generator is the "General Particle Source". It is implemented in Geant4, and has too many parameters to copy over into our framework. This means you will pass the GPS commands as strings that will be given to Geant4. Create one with:

myGPS = generators.Gps(
  init_commands = [
    # list of init commands for GPS messenger
  ]
)

Multiple Particle Gun

This generator can generate multiple copies of the same primary particle with the same kinematics. The number of primaries it generates can also be Poisson distributed. Create one with:

myMPG = generators.Multi(
  # set the parameters
)

Here are the parameters you have access to:

Photonuclear model

The hadronic interaction used by Geant4 in ldmx-sw to perform photonuclear interactions can be configured to load an arbitrary other model from a dynamic library. There are a couple available within ldmx-sw that are listed here but you can add new ones from any library and load them the same way. For details about this, see Alternative photo-nuclear models.

By default, the simulation will be configured to use the default version of the Bertini model that comes with LDMX's version of Geant4. If you want to change to a different model, you can do so through

from LDMX.SimCore import photonuclear_models as pns
simulation.photonuclear_model = pns.SomeModel()

Note that some of these models should probably be used together with a corresponding filter from Biasing.particle_filter.