The GenieHad Event Generation Framework

GenieHad is an event generator systems developed for simulating in details the hadronic interactions between the proton beam and the nuclear matter of REDTOP target systems. GenieHad is configured as an add-on to the well-established Genie Neutrino event generator framework and it uses mostly the geometry and  the I/O systems of the latter (both based on root framework). The add-on consists of several interfaces to external nuclear scattering generators and to clusterization, evaporation and de-excitation programs. The nuclear model of choice is selected at run time. Consequently, the user is able to compare the outcome of several models by using the same beam description and the same geometry of the experimental apparatus.

The rationale behind GenieHad is that the dynamics of the scattering, occurring within the external scattering engines, is too complex to be maintained by small groups or single experiments and the update/improvement of the scattering engine is left to their respective authors. The software development of GenieHad is exclusively restricted to the interfaces between the underlying framework (Genie) and those external scattering engines. Since the description of the physics processes occurring inside a nucleus in an inelastic hadronic scattering are very much model-dependent, the implementation of GenieHad is not tied to a specific hadronic model. Instead, the generation process is interfaced to a list of compatible nuclear models which will be called every time a new event has to be generated.

Why GenieHad?

GenieHad is meant to overcome two major limitations  of  intra-nuclear scattering and transport models available from the nuclear theory community:

1. The target is a standalone nucleus surrounded by vacuum;

2. Except for the Incl++ case, the nucleons in the final state are returned to the user as a list of free (un-aggregated) particles.

As a consequence of point 1. the final state particles from the primary interaction are also generated in vacuum. When those particles are propagated throughout the detector during the next step of the simulation (for example by Geant4), an unrealistic situation occurs, caused by the fact that the matter in the target around the struck nucleus is not taken into account. Therefore, the secondary particles generated inside the target are underestimated. A consequence of 2. is that the final state nucleons are not condensed into on-shell ions (deuterium, tritium, alpha, etc.) or excited nuclear remnants but are simply listed in the final state as standalone particles.


The external generators

At present, GenieHad implements interfaces to the most advanced and well maintained  nuclear scattering generators and clusterization-evaporation models:

Furthermore, interfaces to some other generators are available:

New interfaces to three more nuclear scattering models: JAM, DPMJET-III and QGSM are already planned. The former (JAM) is largely in use at J-PARC (where it has been developed) and it will allow to compare the simulations performed  there. Furthermore, within the microscopic transport model JAM, three different modes are available: cascade, hadronic mean field, and a new mode with modified equations of state. DPMJET is the underlying scattering model used in Fluka while (a modified version of ) QGSM is at the core of MARS15.

A new, recent model implementing the beamsstrahlung of Axion-Like-Particles (ALPs) from protons scattering on nuclear matter will also be implemented. The model could be useful, among other things,  to study the capability of PIP-II to explore physics beyond the Standard Model at beam energies of the order of the GeV.

The architecture of GenieHad

The base architecture of GenieHad is entirely based on the original Genie package. Some internal structures had to be modified to accommodate the handling of non-neutrino beams (i.e. massive particles). Please refer to the official Genie website for any further insights or its documentation for information not found below. Details on GenieHad  are available in GenieHad User’s  Guide .

Those models are, in general, only capable of describing the intra-nuclear interactions between the incoming particle (namely, the beam) and one, isolated nucleus (in the target). In other words, the scattering occurs in vacuum and between a predefined scatterer and target nucleus. On the other side, GenieHad will take care of preparing the environment for the specific beam-particle scattering, by analyzing the materials on the path of the beam. The parameters of the materials are extracted from the geometry of the apparatus and a probability for a particular interaction is calculated from the table of cross-sections.

Once the event topology is prepared, the calculation is passed to the nuclear model engine which will return a final state based on its internal calculations. GenieHad is also responsible for the I/O and general services of the framework.

The advantages of such architecture are several. First of all, the user can repeat the same simulation multiple times adopting different models and compare the physics results obtained. This is particularly useful in the energy range of interest for REDTOP, since that range corresponds to a transition between a scattering occurring via the formation of intra-nuclear resonances or via fragmentation. Consequently, the outcome of the event generation is very dependent on the nuclear model applied and comparing multiple models gives a better idea of what to be expected. Furthermore, GenieHad provides only an interface the model and does not need to be updated as often as the model itself. When a nuclear model has changed by its authors, maintaining GenieHad framework, in most cases, means to recompile the updated library.

Another advantage of GenieHad is that the scattering is geometry-aware; the process does not occur in the vacuum (as for the vast majority of intranuclear scattering simulations) but, rather, inside a physical volume. When the list of final state particles is passed to Geant4 for their propagation in the detector, the origin of those particle corresponds to a position inside the target. Consequently Geant4 knows that it has to propagate them inside the matter (rather than in vacuum), by applying the interactions appropriate for that case.

GenieHad output is in root and hepevt format only (user selectable with a switch in the command line). An option for an output in stdhep format is under consideration. The entire package is under development: the source code will be available in the near future.

Instructions for installing and running GenieHad

Installing GenieHad

Only Windows 7 binaries are supported at present times (Linux binaries will be available soon). Prerequisites are Visual C++ 2010 Runtime Libraries and Microsoft .net4 libraries. If they are not already installed on the system, the setup process will prompt you accordingly. The installation instructions are listed below.

1. Download the zipped setup file from REDTOP repository. You will be asked for your Fermilab credentials. You need to connect to Fermilab VPN if you are outside of Fermilab’s firewall. The related instructions are at the following link. An alternate download link is here (ask your P.I. for login and password).

2. Unpack the zipped file in a temporary directory;

3. Double-click on the file >setup.exe to launch the installation;

4. If the setup prompts to install or repair the Visual C++ 2010 Runtime Libraries, accept the installation (repair) and let it finish;

5. When the GenieHad setup wizard starts, keep pressing next until the installation is complete. It is safer to leave all options and paths unchanged;

6. When the GenieHad setup wizard informs you that the installation is complete, close the Whizard.

When the setup is complete the framework and the libraries for the supported hadron models are also installed. You are ready to run GenieHad. The present GenieHad distribution installs .gdml files on your computer (in the C:\slic_3_1_6-VC10\REDTOP directory) with the geometry of the detector. If you have installed slic on your computer, all the latest .gdml files for REDTOP will be already available (and in the right path).

Running GenieHad

The event generation in GenieHad is controlled via two text based sources:

The batch file used to launch the simulation;

The .xml files contained in the directory config.

Batch file

The command line specified in the batch file used to launch GenieHad contains all the information necessary to configure the experiment. The options are selected trough switches used as arguments in the command. A detailed description of those switches is found here. Before running GenieHad, the batch file has to be edited to reflect the correct configuration of the simulation (i.e. all paths are correct and the files exist). Once that has been done, open a cmd window, cd into the genie directory (most likely, C:\genie2_8_6-VC10) and execute the batch file.

Xml config files

These configuration files are necessary to define the physics processes to be simulated as well as to pass some parameters to the underlying nuclear model engines. The physics processes to study are passed to GenieHad in the command line, through the switch: –event-generator-list. The string passed to GenieHad corresponds to an entry block into with the list of all the generators to be included in the process.

Refer to the specific nuclear model documentation on how to set those parameters. A list of reference is found below. The parameters related to the functioning of the genie framework are documented in the official Genie web site

GenieHad User’s Guide

Please, refer to the GenieHad User’s guide for more detailed instruction on how to run GenieHad. A summary of the command line switches is available at the following link.


The distribution has one  examples: example_urqmd.bat which can be run out of the box. To run it, open a  cmd window and type the following:

  •  user> cd C:\genie2_8_6-VC10
  •  user> example_urqmd.bat

The output file example.1800mev.urqmd.1001.hepevt will be located in your C:\ genie2_8_6-VC10 directory. The user can browse through the events using any text editor. On some systems, GenieHad does not exit gracefully. Nonetheless, if it had run correctly and it informs that the generation is done, just disregard the error message. In the example_urqmd.bat case there is only one entry in the \config\EventGeneratorListAssembler.xml file (genie::EventGenerator/REDTOP_URQMD) which corresponds to the REDTOP_URQMD event generator modules in the \config\EventGenerator.xml. There are five modules in that list:

  • <param type=”alg”    name=”Module-0″>   genie::InitialStateAppender/Default            </param>
  • <param type=”alg”    name=”Module-1″>   genie::VertexGenerator/Default                    </param>
  • <param type=”alg”    name=”Module-2″>   genie::UrqmdGenerator/Default                   </param>
  • <param type=”alg” name=”Module-3″>genie::UnstableParticleDecayer/AfterHadronTransport </param>
  • <param type=”alg”    name=”Module-4″>   genie::NucBindEnergyAggregator/Default  </param>

each one corresponding to a specific physics process. The specific process is controlled through a .xml file with the same name. For example, the UrqmdGeneratormodule is controlled by the \config\UrqmdGenerator.xml file, carrying specific parameters to be passed to the Urqmd engine. In the example_urqmd.bat case the UrqmdGenerator is configured in >default mode, corresponding to a very generic, inelastic hadron scattering (no specific final state is selected).

Documentation of the hadronic models in GenieHad

The documentation listed below should be used whenever the user wants to change the parameters of the model in the corresponding xml configuration file :

*The interface to Gibuu is still experimental and not entirely stable. Consequently, it should be used sparingly until further notice.