Sim-scripts

In dgcode the term “sim-script” is short for “simulation-script” and refers to the command-line scripts which are used to launch the simulations using a G4Launcher instance. They generally have the following structure (here using a sim script from the TriCorder example):

import G4GeoTriCorder.GeoTriCorder as geomodule
import G4StdGenerators.SimpleGen as genmodule
import G4Launcher

geo = geomodule.create()
geo.sample_posz_mm = 5.0

gen = genmodule.create()
gen.particleName = 'neutron'
gen.neutron_wavelength_aangstrom = 2.2
gen.fixed_z_meters = -0.1

launcher = G4Launcher(geo,gen)
launcher.setOutput('tricorder','REDUCED')#Griff output
launcher.go()

In other words, a geometry module and a generator module are loaded and configured, before their combination is used to initialise a G4Launcher instance (here named launcher). The G4launcher object can then itself be configured, before ultimately its .go() method is invoked as the last line in the file. At this point, command-line arguments of the script are investigated, and some sort of action happens. This is usually to launch the simulation, but might also be used to for instance query some details of the setup, launch a visualisation, or something else. Since the script itself in the TriCorder example is named sim and placed into the scripts folder of the TriCorder package, the simplebuild mechanics means that the command which is ultimately used to invoke the script is called sb_tricorder_sim. It comes with built-in documentation of how to use it, accessible by supplying the -h or --help flag:

$> sb_tricorder_sim -h
usage: sb_tricorder_sim [options] [par1=val1] [par2=val2] [...]

This script allows you to simulate or visualise particles from the
G4StdGenerators/SimpleGen generator hitting the G4GeoTriCorder/GeoTriCorder
geometry. Note that in addition to the options below, you can override
parameters of the generator and geometry by supplying them on the commandline
like par=val. Furthermore note that as a special case, you can disable the
parameter validation by setting forcepars=yes.

options:
  -h, --help            show this help message and exit
  -d, --dump            Dump parameters of both geometry and generator
  -g                    Dump parameters of just geometry
  -p                    Dump parameters of just generator
  -x                    Dump used cross-sections in text files
  --viewer              Experimental custom geometry visualisation
  --dataviewer          Experimental visualisation of both geometry and data
  --aimdataviewer       Like --dataviewer, but showing just first segment of
                        primary tracks
  --heatmap[=CFG]       Collect quantities from simulation steps into mesh3d
                        file. Use --heatmap=help for detailed instructions.
  --mcpl=CFG            Capture and write simulated particles to standardised
                        MCPL files. Use --mcpl=help for detailed instructions.
  -n N, --nevts=N       Simulate N events
  -j N, --jobs=N        Launch N processes [default 1]
  -t, --test            Test geometry consistency and exit
  -l PL, --physlist=PL  Physics List [default QGSP_BIC_HP_EMZ]
  --showphysicslists    Show available physics lists
  --allowfpe            Do not trap floating point errors
  -s S, --seed=S        Use S as seed for generation of random numbers
                        [default 123456789]
  -v, --visualise       Drop to G4 interactive prompt and launch viewer
  -e ENG, --engine=ENG  Use visualisation engine ENG [default OGL]
  -i, --interactive     Drop to G4 interactive prompt
  -r, --verbose         Enables tracking printouts (specify multiple times for
                        ever increasing levels of details, up to -rrrrrrr))
  -o FN, --output=FN    Filename for GRIFF output [default tricorder]
  -m MODE, --mode=MODE  GRIFF storage mode [default REDUCED]

Here is a bit of advice concerning when to typically use the options above:

  • Notice in particular the -n and -j options, which control the number of events to simulate and how many processes to use (i.e. if you have a 4-core machine with hyperthreading enabled, it makes sense to use -j8. If combining data from multiple runs, you should remember to use a different random seed in each job by using -s.

  • When debugging your geometry setup, you might want to use -g, and t. And most certainly you want to visualise the geometry with --viewer.

  • When debugging your particle generator setup, you might want to use -p, or visualise particles with --dataviewer and --aimdataviewer.

  • If you want to quickly see what happens in a particular event, you can use -r (supply it once or multiple times). You might also want to use -n1 -s <SEEDVALUE> to start the simulation at a particular event. You can of course also use a subsequent Griff analysis to investigate events programmatically.

  • To control the output of the simulation, you can use -o and -m for Griff output (disable it with -o none), --mcpl for MCPL output, or --heatmap to collect heat maps.

  • To modify and investigate physics, you can use -x to extract relevant cross section files, or use --showphysicslists and -l to control the physics list.