Project

General

Profile

GENIEHelper

GENIEHelper is the ART glue to GENIE. This section of the wiki is intended to help document using the GENIEHelper class (and .fcl file) to configure GENIE to individual needs.

Quick Guide to FHCL parameter variables

Basic GENIEHelper Parameters

Name Description
single interactions or pile-up?
POTPerSpill pile-up parameter (either this or the next should be 0)
EventsPerSpill pile-up parameter - generate fixed # of GENIE events per ART record
basic GENIE parameters
TopVolume top volume in geometry hierarchy within which events are generated e.g. "vDetEnclosure"
XSecTable name of GENIE cross-section spline file e.g. "gxspl-FNALsmall.xml"
EventGeneratorList select event topologies e.g. "CCQE" ["Default"] see GENIE Configuration Files
GeomScan how is the maximum path length determined see GENIEHelper Geometry wiki page
FiducialCut selecting/exclude a sub-region see GENIEHelper Geometry wiki page
GHepPrintLevel -1=no print, otherwise verbosity for printing generated GHepRecord see below
GMSGLAYOUT GENIE's messenger format: "SIMPLE" or "BASIC"
GENIEMsgThresholds additional XML files to set GENIE Messenger thresholds (colon separated)
GXMLPATH additional path for XML file locations (colon separated)
basic Helper parameters
ProductionMode quiet down GENIE Messenger ["no"] or "yes"
RandomSeed random seed used by GENIE and GENIEHelper
time within the record parameters
GlobalTimeOffset overall time added to time-of-flight (in ns)
RandomTimeOffset simulate flat spill distribution e.g. ~9600.0 (in ns)
SpillTimeConfig use "evgb::EvtTimeFNALBeam" (standard NuMI beam; to-do: not yet parsing config string)
use "evgb::EvtTimeFlat" (no beam structure)
or write self-registering class deriving from EvtTimeShiftI for the EvtTimeShiftFactory;
leave blank for old behavior (flat w/ RandomTimeOffset) [default]

Flux Choices & Handling

Name Description
FluxType "ntuple" (GNuMIFlux), "simple_flux" (GSimpleNtpFlux), "dk2nu" (GDk2NuFlux),
"atmo_FLUKA", "atmo_BGLRS" (="atmo_BARTOL") , "atmo_HAKKM" (="atmo_HONDA"),
"histogram", "mono"
FluxFiles vector of file name patterns
FluxSearchPaths lead part of path(s) to flux files (colon separated list)
BeamName semi-arbitrary ["numi"]
ROOT file based fluxes ("ntuple", "simple_flux", "dk2nu") see additional info at see: Flux_File_Handling
DetectorLocation flux driver coordinate transformation identifier (<param_set>)
FluxCopyMethod how to make local copies of flux files ("DIRECT", "IFDH")
FluxCleanup what to do at job end when using copied flux files ("ALWAYS","NEVER","/var/tmp") see: Flux_File_Handling
MaxFluxFileMB limit the collective size of files passed to flux driver (Mbytes)
FluxUpstreamZ start flux ray from a z other than the flux window (use for rock generation)
neutrino flavors
GenFlavors list of nu flavors to accept from the flux driver
MixerConfig string to configure flux mixer see GENIEHelper Flux wiki page
MixerBaseline distance to use if flux mixer is doing oscillations and flux files don't support a distance
parameters for alternative flux models
AtmoEmax Atmospheric
AtmoEmin Atmospheric
Rl AtmoRl parameter: radius of the sphere on where the neutrinos are generated [20]
Rt AtmoRt parameter: radius of the transvere (perpendicular) area on the sphere [20]
(Rl,Rt) The position of each flux neutrino [going towards a detector centered
at (0,0,0)] is generated uniformly on a plane that is perpendicular
to a sphere of radius Rl at the point that is determined by the
generated neutrino direction (theta,phi). The size of the area of
that plane, where flux neutrinos are generated, is determined by the
transverse radius Rt. You can tweak Rl, Rt to match the size of your
detector.
BeamCenter Hist/Mono
BeamDirection Hist/Mono
BeamRadius Hist/Mono
MonoEnergy Mono (energy)

Miscellaneous Parameters

Name Description
DebugFlags see below
Environment deprecated key/value pairs to set as environment variables
UseHelperRndGen4GENIE use GENIEHelper's TRandom3 instead of gRandom
SurroundingMass for fluxes that don't know pot normalization (?)

Hey, you're missing FHiCL parameters for ...

Okay, I’ve looked at the GENIEHelper wiki and I don’t see any way to change physics parameters (e.g. M A, MEC values) or choose physics models from within a FHiCL file for event generation. What gives?

Long answer: GENIE must be run in a consistent mode

To decide whether a ν flux ray interacts at all and to pick event vertex GENIE
  • samples the material along the ray’s path for the amount of material transversed
  • P interaction ≃ the number of nuclei × total cross-section (flavor,E ν )
  • total cross-section splines are pre-calculated; this is computationally expensive!
  • GENIE parameters / models controlled by UserPhysicsOptions.xml (and possibly EventGeneratorListAssembler.xml )

It makes no sense to generate events with varied parameters / models without an accompanying gxspl spline file.

This is why the spline file is distributed as a UPS product that, when relevant, distributes the appropriate XML config file with it.

See GENIE Configuration Files for further details

Flux

The flux driver is GENIE's source of neutrinos. The driver must supply a chosen neutrino flavor, a starting position and a 4-momentum. Information on selecting and configuring the flux driver can be found on the page: GENIEHelper_Flux

Geometry

Once GENIE is configured with a source of neutrinos it must propagate them thorough a geometry representing the detector in order to decide where interactions occur and off what target materials. Information about selecting and configuring the geometry driver can be found on the page: GENIEHelper_Geometry

Other GENIE configurations

The use of GENIE via pairs of strings in the Environment parameter is obsolete with GENIE R-2_8_0 and should not be used any more.

Event Types (EventGeneratorList)

Normally GENIE will generate the correct relative proportions of various event types (NC vs. CC, QE vs. DIS, etc). Generally this is set to Default (or Default<something>MEC<something>, per version specific GENIE configuration files. In general the lead developer for GENIE discourages overriding this approach because using a not-default set selects only at the basic interaction level. After the initial interaction, effects such as intra-nuclear scattering can cause the event structure as it leaves the initial nucleus to appear different from what was selected. Also the transition from one type to another (e.g. resonance to DIS) is not particularly well defined and it really is only the aggregate that can be modelled.

The definitive list of allowed values can be found from the param_set names in the file $GENIEXSECPATH/EventGeneratorListAssembler.xml if there is one, otherwise $GENIE/config/EventGeneratorListAssembler.xml (pre-R-3_X-Y).

Precomputed cross section tables (XSecTable)

Cross-section splines used by GENIE are precomputed and the file used must be consistent with the version of GENIE used for event generation. There are spline for each combinations of neutrino flavor, nucleus isotope, and physics sub-process. Currently the appropriate file for NuMI experiments is GSPLOAD set to gxspl-FNALsmall.xml.

GENIE's use of log4cpp message service

GENIE's message service tags output by a timestamp by default; this can make log comparisons difficult. To change the GENIE output format one can use: "GMSGLAYOUT" set to "SIMPLE" (the default is "BASIC"). GENIE tends to be quite verbose by default. Setting ProductionMode to YES will set the GENIE message service threshold to a quite high level. If it is desired to selectively lower those of a few streams one can set a non-blank "GENIEMsgThresholds" to "MyMessenger.xml:My2ndAltMess.xml",. Where MyMessenger.xml is a file that might look like:

<?xml version="1.0" encoding="ISO-8859-1"?>

<messenger_config>
  <!-- 
    Defines the priority levels for GENIE message streams

    The priority (in descending importance order) can be 
    FATAL, ALERT, CRIT, ERROR, WARN, NOTICE, INFO, DEBUG

    To change the default priority level for a message stream
    or to add a default priority level for a new message stream
    a) edit this file OR b) set the GMSGCONF env. var to point to 
    your custom messenger config file. More than one custom files
    may defined in the GMSGCONF var delimited with a ':'. Example:
    export GMSGCONF= /home/me/msgconf1.xml:/home/me/tmp/msgconf2.xml

    These files are read in addition to the default priority levels
    file and after it. The later each file is in the Messenger 
    configuration file chain the higher priority it has, eg. if the 
    same stream is listed twice with conflicting priority then the 
    one found last is used
   -->

  <priority msgstream="GEVGDriver">          WARN   </priority>
  <priority msgstream="GMCJDriver">          WARN   </priority>
  <priority msgstream="GEVGPool">            WARN   </priority>
  <priority msgstream="GMCJob">              WARN   </priority>
  <priority msgstream="GMCJMonitor">         WARN   </priority>
  <priority msgstream="GROOTGeom">           INFO   </priority>
  <priority msgstream="Flux">                INFO   </priority>
  <priority msgstream="XSecSplLst">          WARN   </priority> <!-- important -->
  <priority msgstream="Messenger">           WARN   </priority>

</messenger_config>

Alternative locations for XML files (GXMLPATH)

By setting GXMLPATH to a colon separated list of file locations (analogous to LD_LIBRARY_PATH) XML files that GENIE wants can be located in alternative directories. Adding a path including "." can be useful. Versions of GENIEHelper after 2012-05-24 will automatically add together difference sources to the path in the following priority:

  • GXMLPATH set in the .fcl file via physics.producers.generator.GXMLPATH
  • GXMLPATH set in the .fcl file via physics.producers.generator.Environment
  • any value of GXMLPATH in the environment before job start
  • the value of $FW_SEARCH_PATH; by default this pre-defined path includes (in order):
    • $SRT_PRIVATE_CONTEXT
    • $SRT_PUBLIC_CONTEXT
    • /nova/data or equivalent
    • /grid/fermiapp/nova/aux or equivalent

For files that GENIE expects a fixed file name, such as UserPhysicsOptions.xml, it will only look in places explicitly named; for cases like $GMSGCONF above one can use a partial path, e.g. EventGenerator/MyGenieMsg.xml. For GeomScan one could make use of a name such as file: Geometry/gdml/mymaxpathlengthfile.xml and modified version could be found in $SRT_PRIVATE_CONTEXT/Geometry/gdml/mymaxpathlengthfile.xml if it exists.

physics.producers.generator.ProductionMode: "no" 
physics.producers.generator.GXMLPATH: "/path/to/myGenieMsg/:/another/for/XMLfiles/" 
physics.producers.generator.GENIEMsgThresholds: "Messenger_Production.xml:MyGenieMsg.xml" 

Setting GENIE's random number seed (RandomSeed)

Both GENIEHelper and GENIE itself use random numbers. By default a random seed is chosen vis evgb::GetRandomNumberSeed(). If reproducibility is required (i.e. generate the same run of GENIE events) the RandomSeed variable can be set. If one is using exactly the same code build, then the same sequence of events should be the same.

Printing GENIE Event Record

GENIE can be instructed to print out it's event record as each interaction is generated by the use of GHepPrintLevel, ala:

physics.producers.generator.GHepPrintLevel: 10

This value is passed along to the GHepRecord::SetPrintLevel() method.

Print levels:

value Description
0 prints particle list
1 prints particle list + event flags
2 prints particle list + event flags + wght/xsec
3 prints particle list + event flags + wght/xsec + summary
10 as in level 0 but showing particle positions too
11 as in level 1 but showing particle positions too
12 as in level 2 but showing particle positions too
13 as in level 3 but showing particle positions too

A quick note about units and coordinate systems

From the manual:

GENIE uses the natural system of units (hbar = c = 1) so (almost) everything is expressed in [GeV ]n. Notable exceptions are the event vertex (in SI units, in the detector coordinate system) and particle positions (in fm, in the hit nucleus coordinate system).

fm = femtometer = 1.0e-15m

Notice that in GENIE a separate variable represents the vertex (i.e. nucleus) position in the lab frame; individual particles are relative to the nucleus. One must retain the fm level accuracy in order to do re-weighting (especially intranuclear scattering). When this GENIE GHepRecord is translated ART based structure in preparation for handing particles off to Geant4 to propagate, the positions of those particles must be in the lab frame. So for entries with status code 0 (the initial neutrino and nucleus) and 1 (those to be propagated by Geant4) the positions in the ART structure are converted to cm and have the event vertex added. All other entries retain their original fm unit, nucleus-centered values.

Example GHepRecord Dump

|------------------------------------------------------------------------------------------------------------------|
|GENIE GHEP Event Record [print level:  10]                                                                        |
|------------------------------------------------------------------------------------------------------------------|
| Idx |          Name | Ist |        PDG |   Mother  | Daughter  |    Px(x) |   Py(y) |   Pz(z) |    E(t) |     m  | 
|------------------------------------------------------------------------------------------------------------------|
|   0 |         nu_mu |   0 |         14 |  -1 |  -1 |   4 |   4 |  -0.079 |  -1.512 |  24.596 |  24.643 |   0.000 | 
|     |               |     |            |     |     |     |     |   0.108 |   0.084 |   0.149 |   0.000 |         | 
|   1 |           C12 |   0 | 1000060120 |  -1 |  -1 |   2 |   3 |   0.000 |   0.000 |   0.000 |  11.179 |  11.179 | 
|     |               |     |            |     |     |     |     |   0.000 |   0.000 |   0.000 |   0.000 |         | 
|   2 |       neutron |  11 |       2112 |   1 |  -1 |   5 |   5 |   0.136 |  -0.145 |  -0.074 |   0.933 | **0.940 | M = 0.909 
|     |               |     |            |     |     |     |     |   0.108 |   0.084 |   0.149 |   0.000 |         | 
|   3 |           C11 |   2 | 1000060110 |   1 |  -1 |  19 |  19 |  -0.136 |   0.145 |   0.074 |  10.246 |  10.243 | 
|     |               |     |            |     |     |     |     |   0.000 |   0.000 |   0.000 |   0.000 |         | 
|   4 |           mu- |   1 |         13 |   0 |  -1 |  -1 |  -1 |  -1.319 |  -1.674 |   8.633 |   8.893 |   0.106 | P = (0.148,0.188,-0.971)
|     |               |     |            |     |     |     |     |   0.108 |   0.084 |   0.149 |   0.000 |         | 
|   5 |      HadrSyst |  12 | 2000000001 |   2 |  -1 |   6 |   7 |   1.376 |   0.018 |  15.889 |  16.683 | **0.000 | M = 4.896 
|     |               |     |            |     |     |     |     |   0.000 |   0.000 |   0.000 |   0.000 |         | 
|   6 |            D+ |  14 |        411 |   5 |  -1 |  14 |  14 |   0.216 |  -0.387 |   6.342 |   6.626 |   1.869 | 
|     |               |     |            |     |     |     |     |   0.148 |   0.014 |   1.310 |   0.000 |         | 
|   7 |      HadrBlob |  12 | 2000000002 |   5 |  -1 |   8 |   9 |   1.160 |   0.404 |   9.547 |  10.057 | **0.000 | M = 2.912 
|     |               |     |            |     |     |     |     |   0.108 |   0.084 |   0.149 |   0.000 |         | 
|   8 |             d |  12 |          1 |   7 |  -1 |  10 |  10 |   0.969 |   0.202 |   9.315 |   9.374 |   0.330 | 
|     |               |     |            |     |     |     |     |   0.108 |   0.084 |   0.149 |   0.000 |         | 
|   9 |          ud_0 |  12 |       2101 |   7 |  -1 |  10 |  10 |   0.191 |   0.202 |   0.232 |   0.683 |   0.579 | 
|     |               |     |            |     |     |     |     |   0.108 |   0.084 |   0.149 |   0.000 |         | 
|  10 |        string |  12 |         92 |   8 |  -1 |  11 |  13 |   1.160 |   0.404 |   9.547 |  10.057 | **0.000 | M = 2.912 
|     |               |     |            |     |     |     |     |   0.108 |   0.084 |   0.149 |   0.000 |         | 
|  11 |           pi- |  14 |       -211 |  10 |  -1 |  15 |  15 |   0.910 |   0.054 |   7.637 |   7.693 |   0.140 | FSI = 1
|     |               |     |            |     |     |     |     |   1.429 |   0.133 |  11.527 |   0.000 |         | 
|  12 |           pi+ |  14 |        211 |  10 |  -1 |  16 |  17 |  -0.092 |  -0.064 |   0.012 |   0.179 |   0.140 | FSI = 4
|     |               |     |            |     |     |     |     |  -0.117 |  -0.073 |   0.179 |   0.000 |         | 
|  13 |       neutron |  14 |       2112 |  10 |  -1 |  18 |  18 |   0.341 |   0.414 |   1.898 |   2.185 |   0.940 | FSI = 1
|     |               |     |            |     |     |     |     |   0.233 |   0.235 |   0.840 |   0.000 |         | 
|  14 |            D+ |   3 |        411 |   6 |  -1 |  20 |  23 |   0.216 |  -0.387 |   6.342 |   6.626 |   1.869 | 
|     |               |     |            |     |     |     |     |   0.148 |   0.014 |   1.310 |   0.000 |         | 
|  15 |           pi- |   1 |       -211 |  11 |  -1 |  -1 |  -1 |   0.910 |   0.054 |   7.637 |   7.693 |   0.140 | 
|     |               |     |            |     |     |     |     |   1.429 |   0.133 |  11.527 |   0.000 |         | 
|  16 |           pi+ |   1 |        211 |  12 |  -1 |  -1 |  -1 |  -0.053 |  -0.010 |  -0.022 |   0.151 |   0.140 | 
|     |               |     |            |     |     |     |     |  -2.561 |  -1.782 |   0.504 |   0.000 |         | 
|  17 |        proton |   1 |       2212 |  12 |  -1 |  -1 |  -1 |  -0.085 |  -0.045 |   0.003 |   0.943 |   0.938 | 
|     |               |     |            |     |     |     |     |  -2.561 |  -1.782 |   0.504 |   0.000 |         | 
|  18 |       neutron |   1 |       2112 |  13 |  -1 |  -1 |  -1 |   0.341 |   0.414 |   1.898 |   2.185 |   0.940 | 
|     |               |     |            |     |     |     |     |   1.756 |   2.082 |   9.308 |   0.000 |         | 
|  19 |      HadrBlob |  15 | 2000000002 |   3 |  -1 |  -1 |  -1 |  -0.090 |   0.135 |   0.106 |   9.331 | **0.000 | M = 9.329 
|     |               |     |            |     |     |     |     |   0.000 |   0.000 |   0.000 |   0.000 |         | 
|  20 |          K_L0 |   1 |        130 |  14 |  -1 |  -1 |  -1 |  -0.043 |  -0.780 |   2.003 |   2.207 |   0.498 | 
|     |               |     |            |     |     |     |     | 28930036689.694 | -51666695170.006 | 847744896354.761 |   0.000 |         | 
|  21 |           pi+ |   1 |        211 |  14 |  -1 |  -1 |  -1 |  -0.189 |   0.012 |   1.172 |   1.195 |   0.140 | 
|     |               |     |            |     |     |     |     | 28930036689.694 | -51666695170.006 | 847744896354.761 |   0.000 |         | 
|  22 |         gamma |   1 |         22 |  14 |  -1 |  -1 |  -1 |   0.401 |   0.326 |   2.481 |   2.535 |   0.000 | 
|     |               |     |            |     |     |     |     | 29129036042.752 | -51497548951.466 | 849148788640.363 |   0.000 |         | 
|  23 |         gamma |   1 |         22 |  14 |  -1 |  -1 |  -1 |   0.048 |   0.055 |   0.686 |   0.690 |   0.000 | 
|     |               |     |            |     |     |     |     | 29129036042.752 | -51497548951.466 | 849148788640.363 |   0.000 |         | 
|------------------------------------------------------------------------------------------------------------------|
|       Fin-Init:                                                |   0.000 |   0.000 |   0.000 |   0.000 |         | 
|------------------------------------------------------------------------------------------------------------------|
|       Vertex:          nu_mu @ (x =    -0.18354 m, y =    -0.13078 m, z =     2.05119 m, t =     2.35639e-08 s)  |
|------------------------------------------------------------------------------------------------------------------|

fcl File Examples

Additions to master the fcl file might look something like (don't use these, they're just examples):

#physics.producers.generator.RandomSeed:  123456789  # force GENIE to use starting seed
physics.producers.generator.MixerConfig: "map 12:14 14:12 -12:-14 -14:-12" 
physics.producers.generator.FluxUpstreamZ: -100000 
physics.producers.generator.FiducialCut:  "rockbox:(-780,-780,20)(780,780,6500),0,800,1.0e-5,1.10" 
physics.producers.generator.FiducialCut: "mbox:-200,-200,-50,200,200,1600"     # NearDet to exclude rock inside vDetEnclosure
physics.producers.generator.GeomScan:     "flux: 10000 1.2 1" 
##physics.producers.generator.DebugFlags:   4294967295 # 0xFFFFFFFF
physics.producers.generator.ZCutOff:      100000

## do not use the following any more
#physics.producers.generator.Environment: [
#     "GSPLOAD",    "gxspl-NUMI-R2.6.0.xml",
#     "GEVGL",      "Default",    # older method, in the future use EventGeneratorList
#     "GPRODMODE",  "YES",      # supress lots of GENIE messages
#     "GMSGLAYOUT", "SIMPLE",  # [BASIC] or timestamp-less SIMPLE
#     "GMSGCONF",   "MyGenieMsgVerbose.xml:EventGenerator/MyGenieMessengerVerbose.xml",  # override log mesg levels
#     "GXMLPATH",   "/path/to/my/xml/files:/another/path" 
#]

physics.producers.generator.EventGeneratorList:    CCQE  # new setting for what was GEVGLprecedence 

Here be dragons:

DebugFlags

  • 0x01 - ask GFlavorMixerI to print its current configuration at initialization
  • 0x02 - ask GFluxBlender to print its current configuration after event generation
  • 0x04 - print vertex and neutrino flux ray information after event generation
  • bits [16-23] are passed to ROOTGeomAnalyzer (need RWH_DEBUG defined at compile time)
    • 0x01 0000 - do cross-check
    • 0x02 0000 - print weight map material
    • 0x04 0000 - trimmed steps
    • 0x08 0000 - print if if beyond wgt distance
    • 0x10 0000 - (NO) add start point to top volume to path segment list
    • 0x20 0000 - do cross-check before trimming (RWH_DEBUG_2)
    • 0x40 0000 - fill material step sum to see summed mass
    • 0x80 0000 - keep segments that are zeroed out
  • ... more to come