Skip to content

User guide

Jump to bottom
Paola Ferrario edited this page Oct 26, 2023 · 7 revisions

This guide assumes you have already a working installation of NEXUS. If this is not the case, please refer to installation instructions.

You'll find two examples: the first one is a basic example, while the second one explains how to run in look-up table production mode.

Getting started: running a simple example

Move to your NEXUS installation folder and type:

bin/nexus -b -n 100 macros/nexus_example1.init.mac

On screen you should see a text like this:

*************************************************************
 Geant4 version Name: geant4-10-02-patch-01    (26-February-2016)
                      Copyright : Geant4 Collaboration
                      Reference : NIM A 506 (2003), 250-303
                            WWW : http://cern.ch/geant4
*************************************************************
<<< Geant4 Physics List simulation engine: G4GenericPhysicsList

[...]
### Run 0 start.  #######################################
 >> Event no. 0
 >> Event no. 10
 >> Event no. 20
 >> Event no. 30
 >> Event no. 40
 >> Event no. 50
 >> Event no. 60
 >> Event no. 70
 >> Event no. 80
 >> Event no. 90
### Run 0 end.  #########################################

You just simulated one hundred electrons moving through gaseous xenon at 15 bar pressure. In the .init.mac file, the basic characteristics of the job are specified, namely the geometry, the generator, the actions to be used, the physics list.

/control/execute macros/physics/DefaultPhysicsList.mac

/nexus/RegisterGeometry XeSphere

/nexus/RegisterGenerator SingleParticleGenerator

/nexus/RegisterPersistencyManager PersistencyManager

/nexus/RegisterRunAction DefaultRunAction
/nexus/RegisterEventAction DefaultEventAction
/nexus/RegisterTrackingAction DefaultTrackingAction

/nexus/RegisterMacro macros/nexus_example1.config.mac

Tha last line executes the .config.mac file, where specific parameters for each part of the simulation are given.

Let's have a look at the config.mac file (macros/nexus_example1.config.mac). The line:

/control/execute macros/geometries/XeSphere.mac

executes the bunch of commands related to geometry parameters. If we open the geometry configuration file macros/geometries/XeSphere.mac, we find:

/Geometry/XeSphere/LXe false
/Geometry/XeSphere/pressure 15. bar
/Geometry/XeSphere/radius 10. m

The geometry is a sphere full of gaseous xenon. In this file, the pressure of the gas and the radius of the sphere are specified with their units.

The generation configuration file (macros/generators/SingleParticle.mac) reads:

/Generator/SingleParticle/particle e-
/Generator/SingleParticle/min_energy 1. MeV
/Generator/SingleParticle/max_energy 2. MeV
/Generator/SingleParticle/region CENTER

It specifies the primary particle, its energy and the generation point. In this example, it is an electron with randomly sampled energy between 1 and 2 MeV, generated in the center of this specific geometry.

The command

/control/execute macros/physics/IonizationElectron.mac

must be used whenever we want to simulate the propagation of particles and their energy depositions, without simulating ionization and scintillation.

The parameter

/nexus/persistency/outputFile nexus.next

is the path of the output file of the job. The actual hdf5 file name will be that string + .h5 at the end.

A second example: the look-up table generation

./nexus -b -n 1 macros/NEXT100_S2_table.init.mac

In this job, a configurable number of photons are generated in a fixed point.

The macros/NEXT100_S2_table.init.mac file looks like the previous one:

/PhysicsList/RegisterPhysics G4EmStandardPhysics_option4
/PhysicsList/RegisterPhysics G4DecayPhysics
/PhysicsList/RegisterPhysics G4OpticalPhysics
/PhysicsList/RegisterPhysics NexusPhysics

/nexus/RegisterGeometry Next100OpticalGeometry

/nexus/RegisterGenerator ScintillationGenerator

/nexus/RegisterPersistencyManager PersistencyManager

/nexus/RegisterRunAction DefaultRunAction
/nexus/RegisterEventAction SaveAllEventAction
/nexus/RegisterTrackingAction DefaultTrackingAction 

/nexus/RegisterMacro macros/NEXT100_S2_table.config.mac

Compared to the previous example, we see a few differences:

  • We are registering the optical physics
/PhysicsList/RegisterPhysics G4OpticalPhysics

This is necessary whenever we want to simulate optical photons.

  • We are using a different generator:
/nexus/RegisterGenerator ScintillationGenerator

This generator produces a fixed number of photons with energy distributed according to the scintillation spectrum of the material where they are generated.

  • We don't specify any custom event action. because we want to save all events (default behaviour in Geant4).

The macros/NEXT100_S2_table.config.mac reads:

##### VERBOSITIES #####
/run/verbose 0 
/event/verbose 0 
/tracking/verbose 0

/process/em/verbose 0

##### JOB CONTROL #####
/nexus/random_seed -2

##### GEOMETRY #####
/Geometry/Next100/pressure 15. bar
/Geometry/Next100/max_step_size 1. mm
/Geometry/Next100/specific_vertex 0. 0. 0. mm

/Generator/ScintGenerator/nphotons 100000
/Generator/ScintGenerator/region   AD_HOC

/nexus/persistency/outputFile Next100_X_0_Y_0_Z_0.next
Clone this wiki locally