HOWTO run a single-particle-gun simulation

From GlueXWiki
Jump to: navigation, search

Introduction

A "particle gun" fires a single particle originating in the target region into the GlueX detector. The particle may be long-lived, such as a proton or charged pion. Additionally, some unstable particles such as πo and η mesons which decay essentially immediately are supported. One can specify the momentum, direction, and point of creation within the target. Alternatively a range of values can be specified, in which case particles will be randomly distributed according to the range given.

Running a single particle Gun

In this example we are going to use hdgeant4 and we are simulating a single particle eta to be generated. The eta is chosen to also show how to force geant to let eta decay only into one final state rather than all possible ones. To achieve all this we require two files:

  1. "control.in", (file name is important) to define the kinematics and with the particle type. The particle type number is defined in the standard particleType.h include file. An example of this files looks as follows:
    TRIG 1000
    KINE 117 5.97 0.01 0. 0.0 0.05 360.
    SCAP 0. 0. 1.
    TGTWIDTH 0.5 .5
    OUTFILE 'etaRAND.hddm'
    RNDM 2057859
    RUNG 30402
    • Note that if you want to restrict the angular range over which a particle is generated, you need to add 100 to the particle type, otherwise the particle will be generated over the full 4pi solid angle. For instance, in the above example, the particle type given is 117 = 17 (eta) + 100.
  2. "r.mac", (file name is arbitrary) this file contains the necessary commands to run hdgeant4 and also sets up the decay modes for the eta as follows, in this example decay mode 1 is given 100% (3pi0 decay) all other decay modes are zero and 1000 events are generated:
    /particle/select eta
    /particle/property/decay/select 0
    /particle/property/decay/br 0
    /particle/property/decay/select 1
    /particle/property/decay/br 1
    /particle/property/decay/select 2
    /particle/property/decay/br 0
    /particle/property/decay/select 3
    /particle/property/decay/br 0
    /run/beamOn 1000
  3. run this as follows:
    hdgeant4 r.mac
    and will create a file etaRAND.hddm as specified in the control.in file.
  4. the final step before analysis is smearing the simulated data which is done like this:
    mcsmear foo.hddm
    where foo.hddm is the simulated data from hdgeant4. The output will have the form foo_smeared.hddm
  5. here a few more pointers
    • Don't forget the appropriate setting for the environment variable JANA_CALIB_CONTEXT to have the desired variation like "variation=mc" or the like
    • In case you also have your own geometry also set the environment variable JANA_GEOMETRY_URL appropriately.
    • If you want to know which decay modes are defined for a given particle in "geant4 -i" you can execute the following two commands in hdgeant4:
      Idle> /particle/select eta
      Idle> /particle/property/decay/dump
      This will print out the all the decay modes with their branching ratios and what the decay modes are. For a full list of particles in geant execute the command:
      Idle> /particle/list

Running using MCWrapper

Here we assume that you have a typical GlueX environment set up, including MCWrapper. In particular, the environment variable $MCWRAPPER_CENTRAL is needed here. Additional modifications to environment required above (e.g.JANA_CALIB_CONTEXT) are handled internally. For more information about MCWrapper, see https://github.com/JeffersonLab/gluex_MCwrapper. This tutorial was tested with MCWrapper version v2.4.1 on the jlab ifarm cluster.

  • First, copy an MCWrapper configuration file and particle gun template to a local directory which we'll call [my_dir]:
cp $MCWRAPPER_CENTRAL/examples/MC.config  $MCWRAPPER_CENTRAL/Generators/particle_gun/examples/particle_gun.cfg [my_dir]
  • In the MCWrapper configuration file MC.config, modify GENERATOR, GENERATOR_CONFIG, DATA_OUTPUT_BASE_DIR, ENVIRONMENT_FILE, and WORKFLOW_NAME.
    • Your GENERATOR should be particle_gun and GENERATOR_CONFIG should point to the particle_gun.cfg you copied to the local directory
  • Make modifications to the particle_gun.cfg file:
    • The KINE flag specifies the particle species and output momentum/direction. Note that if delta_momentum, delta_theta, or delta_phi are nonzero, the distribution is uniform with a half-width of that value. Refer to comments for more info.
      • So for instance, a momentum of 2 and delta_momentum of 1 will produce a uniform distribution of particles from 1-3 GeV/c momentum.
      • Also note that events are generated uniform in angle θ. Not in cos(θ), as is often the case in physics generators.
    • The SCAP flag denotes the central point for particles to originate from in the target. By default, this should be (x,y,z)=(0,0,65)cm.
    • The TGTWIDTH flag gives the extent in r and z coordinates to generate particles in the target with. Again, the distribution is uniform.
  • For example here, we'll use the run number 31057 and generate 100 events locally. To simulate these events, do
$MCWRAPPER_CENTRAL/gluex_MC.py MC.config 31057 100
  • Assuming the command ran properly, the output files should be located in: DATA_OUTPUT_BASE_DIR
  • If you are running particle gun simulation, it's likely you'll want to use the hit-level (smeared) data. By default this is not saved, but adding the argument "cleanmcsmear=0" to the $MCWRAPPER_CENTRAL/gluex_MC.py command will save this data.
  • It may also be useful to turn the TRAJECTORIES flag on to track particles throughout their journey in the GlueX detector. This requires a little more work. Copy $MCWRAPPER_CENTRAL/Gcontrol.in to your local directory and modify CUSTOM_GCONTROL to point to it in your local MC.config. In your local Gcontrol.in, change the TRAJECTORIES flag to a non-zero value (see comments in this file for descriptions of options).
    • This data is then stored in a factory object called DMCTrajectoryPoint which you can later retrieve.