GRAS commands

Geometry commands

Top level control

Select geometry type:

Command:    /gras/geometry/type   <type>
Guidance:   Select the geometry construction method

Parameter:  G4String    type
Candidates: gdml, mulassis, gemat, esabase
Omittable:  False

Note

If mulassis type geometry is selected, the full set of MULASSIS geometry commands become available. The detailed descriptions of these commands can be found in the MULASSIS Software User Manual

Note

If gemat type geometry is selected, the full set of GEMAT geometry commands become available. The detailed descriptions of these commands can be found in the SUM of GEMAT, which is available online

Set the verbose level

Command:    /gras/geometry/util/verbose     <level>
Guidance:   Set verbose level

Parameter:  G4int level
Range:      >=0
Omittable:  False

describe the geometry

Command:    /gras/geometry/util/describe  <level>
Guidance:   describe the geometry object properties

Parameter:  G4int level
Range:      >=0
Omittable:  True
Default:    0

Assign a sensitive detector to a logical volume

Command:    /gras/geometry/util/setVolumeSD <vol>  <sd>  <bool>
Guidance:   Assignment of a sensitive detector to a logical volume
Parameter 1: logical volume name
Parameter 2: sensitive detector name
Parameter 3: true/false --> Set/Unset the sensitive Detector for the volume

Parameter:  G4String    vol
Candidates: one of the logical volume names
Omittable:  False

Parameter:  G4String    sd
Candidates: Sensitive Detector name
Omittable:  False

Parameter:  G4bool bool
Candidates: true, false
Omittable:  False

List the logical volume in geometry

Command:    /gras/geometry/util/listLogicalVolumes
Guidance:   list of logical volumes
Parameter:  None

Assign a material to a logical volume

Command:    /gras/geometry/util/setVolumeMaterial  <vol>  <mat>
Guidance:   Assign a new material to a logical volume
Parameter 1: logical volume name
Parameter 2: material name

Parameter:  G4String vol
Candidates: Logical volume names
Omittable:  False

Parameter:  G4String    mat
Candidates:     material names
Omittable:  False

GDML commands

Specify the gdml input geometry file

Command:    /gdml/file  <name>
Guidance:   Select GDML input file

Parameter:  G4String name
Omittable:  False

Specify the gdml setup to be used

Command:    /gdml/setup  <setup>
Guidance:   Select geometry setup in GDML input
If none is specified the GDML processor will choose the first found

Parameter:  G4String setup
Candidates: ???
Omittable:  True
Default value: default

specify the gdml Version to be used

Command:    /gdml/version
Guidance:   Select a particular version of a given geometry setup in GDML input
If none is specified the GDML processor will choose the first found

Parameter:  G4String version
Candidates: ???
Omittable:  True
Default value: default

specify the gdml schema location

Command:    /gdml/schema <location>
Guidance:   Specify the GDML schema file location

Parameter:  G4String location
Omittable:  False

Dump geometry in GDML format

Command:    /gdml/dump  <file>
Guidance:   Dump the existing geometry setup to the specified file in GDML format

Parameter:  G4String    file
Omittable:  False

Dump a St_Viewer geometry in GDML file format

Command     /gdml/dumpSTViewer  <geom.> <tree> <gdml>
Guidance :  Dump a geometry setup in ST-Viewer format (.geom, .tree) to the specified file in GDML format

Parameter:  G4String    geom
Candidate:  Name of the ST-Viewer .geom file
Omittable:  False

Parameter:  G4String    tree
Candidate:  Name of the ST-Viewer .tree file
Omittable:  False

Parameter:  G4String    gdml
Candidate:  Name of the GDML output file
Omittable:  False

Commands for adjoint simulation source definition

External source

The external source is the source that would be used as primary source for a forward simulation. It represents the surface till which an adjoint particle is tracked during a reverse simulation. The maximum energy of the external source represents the energy above which adjoint particles are killed during their tracking.

Spherical external source

Format: /adjoint/DefineSphericalExtSource   <X Y Z R length_unit>
Argument:   G4String  length_unit
    G4double X, Y, Z, R
Function:   Set the external source as a spherical source of radius R centered on the position (X, Y, Z)

Spherical external source placed at the centre of a physical volume

Format: /adjoint/DefineSphericalExtSourceCenteredOnAVolume
<vol_name R  length_unit>
Argument:   G4String vol_name, length_unit
        G4double R
Function:   Set the external source as a spherical source of radius R with its centre placed at the centre of the physical volume identified by the name  vol_name.

External source on a physical volume

Format: /adjoint/DefineExtSourceOnExtSurfaceOfAVolume   <vol_name >
Argument:   G4String vol_name
Function:   Set the external source as the external surface of the  physical volume identified by the name  vol_name.

Maximum energy

Format: /adjoint/SetExtSourceEmax   <Emax energy_unit>
Argument:   G4String  energy_unit
        G4double Emax
Function:   Set the maximum energy of the spectrum of the external source. Adjoint particles that exceed this energy are killed during the reverse tracking phase.

Definition of the adjoint source

The adjoint source represents the primary source from which coupled adjoint and forward particles are generated in the reverse simulation. This source is generated on a surface that can be defined by the user and should enclose the part of the geometry where detection signals will be computed. For computing efficiency it should be the smallest as possible. It can be set either as a the external surface of a sphere or of a physical volume of the geometry. The minimum and maximum energies of the adjoint source should be set by the user as the minimum and maximum energies of the real external source. A list of types of adjoint primary particles considered in the simulation is built during the initialisation of the physics an depends on the type of reverse processes selected by the user. For example if only the ionisation for e- and protons ionisation are considered only adjoint e- and protons will appear in the list of adjoint primary after the initialisationof the physics. While if the reverse bremsstrahlung is also selected, the adjoint gamma will also be added in the list of primaries. By default all type of adjoint particles contained in the list of adjoint primaries after the physics initilisation wil be taken into account in the simulation, but the user can unselect/select seperatly each of them by using the commands /adjoint/NeglectAsPrimary and ConsiderAsPrimary. For the simulation with ions the name of the primary ion in the list of adjoint primaries is refered by the string “ion”.

Spherical adjoint source

Format: /adjoint/DefineSphericalAdjSource       <X Y Z R length_unit>
Argument:   G4String  length_unit
    G4double X, Y, Z, R
Function:   Set the adjoint source as a spherical source of radius R centered on the position (X, Y, Z)

Spherical adjoint source placed at the center of a physical volume

Format: /adjoint/DefineSphericalAdjSourceCenteredOnAVolume  <vol_name R  length_unit>
Argument:   G4String vol_name, length_unit
        G4double R
Function:   Set the adjoint source as a spherical source of radius R with its center placed at the center of the physical volume
identified by the name  vol_name.

Adjoint source on a physical volume

Format: /adjoint/DefineAdjSourceOnExtSurfaceOfAVolume   <vol_name >
Argument:   G4String vol_name
Function:   Set the adjoint source as the external surface of the  physical volume identified by the name  vol_name.

Minimum energy

Format: /adjoint/SetAdjSourceEmin   <Emin energy_unit>
Argument:   G4String  energy_unit
        G4double Emin
Function:   Set the minimum energy of the spectrum of the adjoint primary source.
Maximum energy
Format: /adjoint/SetAdjSourceEmax   <Emax energy_unit>
Argument:   G4String  energy_unit
        G4double Emax
Function:   Set the maximum energy of the spectrum of the adjoint primary source.
Neglect some adjoint primary type
Format: /adjoint/NeglectAsPrimary   <particle_name>
Argument:   G4String  particle_name
Candidates: Depends on the reverse physics selected. At most [e-, gamma,  proton, ion]
Function:   Neglect a given type of adjoint particle in the list of adjoint primaries. By default all type of primaries, that should be part of the simulation  following the user selected list of reverse processes, are considered. This command allows to remove some of them.
Consider a given type of adjoint primary
Format: /adjoint/ConsiderAsPrimary  <particle_name>
Argument:   G4String  particle_name
Candidates: Depends on the reverse physics selected. At most [e-, gamma,  proton, ion]
Function:   Consider a given type of adjoint particle in the list of adjoint primaries. By default all type  of primaries that should be part of the simulation  following the user slected list of reverse processes, are considered.

Physics commands

Physics list

Add a physics list or component

Command:    /gras/physics/addPhysics  <phys>
Guidance:   Add predefine Physics List or its component
                        (list Command:shows all options)
Remark: PhysicsList can be combined from components
    EM physics + Hadron Elastic + Hadron Inelastic + Extra

Parameter:  G4String  phys
Omittable:  False
Candidates:
 * Predefined PhysicsList available for AddPhysics
        <LHEP>  <QGSP_BERT>  <QGSP_BIC>  <QGSP_BERT_HP> <QGSP_BIC_HP>
        <QGSC>  <QBBC>  <QBBC_HP>
 * List of alternative EM builders
    <em_standard>  <em_standard52>  <em_standard_fast>  <em_standard_exp>  <em_lowenergy>   <rmc_em_standard>
 * List of alternative builders for the Elastic Process
    <elastic>  <HElastic> <QElastic> <LElastic>
 * List of alternative builders for the Hadron Inelastic
    <binary>  <binary_had>  <binary_hp> <bertini> <bertini_hp>
 * List of alternative builders for the Ion Inelastic
    <binary_ion>  <Abrasion>  <Abrasion+Ablation>
 * List of Extra components availbale for AddPhysics
    <decay>  <raddecay>  <gamma_nuc>  <stopping>

Analysis Commands

Top level control

List analysis modules

Command:    /gras/analysis/listModules
Guidance:   List of inserted analysis modules

Analysis manager verbose level

Command:    /gras/analysis/managerVerbose <VerboseLevel>
Guidance:   Set verbose level for GRASAnalysisManager

Parameter:  G4int VerboseLevel

GRAS verbose level

Command:    /gras/analysis/verbose <VerboseLevel>
Guidance:   Set verbose level for GRAS

Parameter:  G4int VerboseLevel

Analysis description

Command:    /gras/analysis/describe <VerboseLevel>
Guidance:   Describe modules with verbose level

Parameter:  G4int VerboseLevel

Draw tracks

Command:    /gras/event/drawTracks <ParticlesDraw>
Guidance:   Draw the tracks in the event

Parameter:  G4String ParticlesDraw
Candidates:     charged neutral all
Omittable:  True (the default is all)

Draw events

Command:    /gras/event/drawEvents <EventDraw>
Guidance:   Draw the tracks in the event

Parameter:  G4String EventDraw
Candidates:     none all trigger
Omittable:  True (the default is all)

CSV output

Command:    /gras/analysis/CSVOutput [true || false]
Guidance:   Decides if CSV files are created or not

Omittable:  True (the default is true)

Auto random seeds

Command:    /gras/analysis/autoSeed [true || false]
Guidance:   Switch on/off time-based random seeds

Omittable:  False

Remark:         GRAS default is false

Seeds in filename

Command:    /gras/analysis/seedsInFileName [true || false]
Guidance:   Switch on/off the addition of the random seeds to the output filenames

Omittable:  False

Remark:         GRAS default is true

Analysis initialisation

Command:    /gras/analysis/initialise
Guidance:   Initialisation of all analysis modules

Random engine status

Command:    /gras/random/showEngineStatus
Guidance:   Shows the status of the random engine

Normalisation factor

Command:    /analysis/normalise <normalisationFactor> <normalisationUnit>
Guidance:   Set the normalisation factor

Parameter1: G4double normalisationFactor
Range:          normalisationFactor > 0.
Omittable:  False

Parameter2: G4double normalisationUnit
Candidates:     cm2 m2
Omittable:  False

Source surface normalisation factor

Command:    /gras/analysis/setSourceSurface <sourceSurface> <sourceSurfaceUnit>
Guidance:   Set the source surface for normalisation

Parameter1: G4double sourceSurface
Range:          sourceSurface > 0.
Omittable:  False

Parameter2: G4double sourceSurfaceUnit
Candidates:     cm2 m2
Omittable:  False

Source fluence normalisation factor

Command:    /gras/analysis/setSourceFluence <sourceFluence> <sourceFluenceUnit>
Guidance:   Set the source fluence for normalisation

Parameter1: G4double sourceFluence
Range:          sourceFluence > 0.
Omittable:  False

Parameter2: G4double sourceFluenceUnit
Candidates:     1/cm2 1/m2 1/km2 1./cm2 1./m2  1./km2 cm-2 km-2 m-2
Omittable:  False

Normalisation type

Command:    /gras/analysis/setSourceFluence <normalisationType>
Guidance:   Set the type of  normalisation

Parameter:  G4String normalisationType
Candidates:     NONE NONORMALIZATION GEOMETRIC_FACTOR GEOFACTOR TO_SOURCE_SURFACE TOFLUENCE FLUENCE TOFLUENCE PEREVT PER_NB_EVENTS PER_NB_EVT PEREVENT
Omittable:  False

Source surface normalisation type

Command:    /gras/analysis/setSourceSurfaceType <sourceSurfaceType>
Guidance:   Set the type of the source surface for normalisation

Parameter:  G4String sourceSurfaceType
Candidates:     USER AUTO
Omittable:  False

Source fluence normalisation type

Command:    /gras/analysis/setSourceFluenceType <sourceFluenceType>
Guidance:   Set the type  of the source fluence for normalisation

Parameter:  G4String sourceFluenceType
Candidates:     FLUX CURRENT
Omittable:  False

Accumulate runs results

Command:    /gras/analysis/accumulateRunResults [true || false]
Guidance:   Set as true if multiple runs will be executed and results accumulated

Remark:         GRAS default is false

Enable scoring functionality

Command:    /gras/analysis/useMeshScoring  [true || false]
Guidance:   Set as true if meshing-scoring  analysis will be used!

Remark:         The command is available only in PreInit state!

Analysis module commands

Add analysis module

Command:    /gras/analysis/<moduleType>/addModule <moduleName>
Guidance:   Create new module of <moduleType> type analysis with name <moduleName>

Parameter:      G4String moduleName
Omittable:  False

Histograms creation

Command:    /gras/analysis/<moduleType>/<moduleName>/bookHistos [true || false]
Guidance:   Decides if histograms are created or not for the module

Omittable:  True (the default is true)

Histogram vs primary kinetic energy

Command:    /gras/analysis/<moduleType>/<moduleName>/book2DHistoVsPrimary [true || false]
Guidance:   Decides if 2D histogram versus primary kinetic energy is created or not for the module

Omittable:  True (the default is false)

Remark:         Deprecates the following command (still existing for backwards compatibility)
Deprecated cmd: /gras/analysis/<moduleType>/<moduleName>/bookHistosVsPrimary [true || false]

Advanced histograms creation

Command:    /gras/analysis/<moduleType>/<moduleName>/bookHistosAdvanced [true || false]
Guidance:   Decides if more advanced histograms  are created or not for the module

Omittable:  True (the default is false)

Tuples creation

Command:    /gras/analysis/<moduleType>/<moduleName>/bookTuples [true || false]
Guidance:   Decides if tuples are created or not for the module

Omittable:  True (the default is true)

Add volume

Command:    /gras/analysis/<moduleType>/<moduleName>/addVolume <volumeName> <copyNb>
Guidance:   Add a physical volume to the module

Parameter1:     G4String volumeName
Candidates:     One of the existing physical volumes
Omittable:  False

Parameter2:     G4int copyNb
Candidates:     Physical volume copy number, -1 for all
Omittable:  True (the default is -1)

Add volume interface

Command:    /gras/analysis/<moduleType>/<moduleName>/addVolumeInterface <volumeName1> <volumeName2> <copyNb1> <copyNb2>
Guidance:   Add to the module an interface between 2 physical volumes

Parameter1:     G4String volumeName1
Candidates:     One of the existing physical volumes, or * for whichever volume
Omittable:  False

Parameter2:     G4String volumeName2
Candidates:     One of the existing physical volumes, or * for whichever volume
Omittable:  False

Parameter3:     G4int copyNb1
Candidates:     Physical volume1 copy number, -1 for all
Omittable:  True (the default is -1)

Parameter4:     G4int copyNb2
Candidates:     Physical volume2 copy number, -1 for all
Omittable:  True (the default is -1)

Interface surface area

Command:    /gras/analysis/<moduleType>/<moduleName>/setInterfaceSurfaceArea <interfaceArea> <interfaceAreaUnit>
Guidance:   Set the interface surface area for the results normalisation

Parameter1:     G4double interfaceArea
Range:          interfaceArea > 0.
Omittable:  False

Parameter2:     G4String interfaceAreaUnit
Candidates:     mm2 cm2 m2
Omittable:  False

Interface surface area calculation type

Command:    /gras/analysis/<moduleType>/<moduleName>/autoInterfaceSurfaceArea [true || false]
Guidance:   If true, the interface surface area is automatically computed as the area of the surface of the 2nd volume in the inserted interface

Omittable:  True (the default is true)

Volume surface area

Command:    /gras/analysis/<moduleType>/<moduleName>/setVolumeSurfaceArea <volumeSurfaceArea> <volumeSurfaceAreaUnit>
Guidance:   Set the volume surface area for the results normalisation

Parameter1:     G4double volumeSurfaceArea
Range:          volumeSurfaceArea > 0.
Omittable:  False

Parameter2:     G4String volumeSurfaceAreaUnit
Candidates:     mm2 cm2 m2
Omittable:  False

Volume surface area calculation type

Command:    /gras/analysis/<moduleType>/<moduleName>/autoVolumeSurfaceArea [true || false]
Guidance:   If true, the volume surface area is automatically computed for the inserted volume

Omittable:  True (the default is true)

Volume volume

Command:    /gras/analysis/<moduleType>/<moduleName>/setVolume <volumeVolume> <volumeVolumeUnit>
Guidance:   Set the volume for the results normalisation

Parameter1:     G4double volumeVolume
Range:          volumeVolume > 0.
Omittable:  False

Parameter2:     G4String volumeVolumeUnit
Candidates:     mm3 cm3 m3
Omittable:  False

Volume volume calculation type

Command:    /gras/analysis/<moduleType>/<moduleName>/autoVolume [true || false]
Guidance:   If true, the volume is automatically computed as the sum of the volume of all inserted volumes

Omittable:  True (the default is true)

Module unit

Command:    /gras/analysis/<moduleType>/<moduleName>/setUnit <moduleUnit>
Guidance:   Set the unit for the output

Parameter:      G4String moduleUnit
Candidates:     One of the units acceptable by the module
Omittable:  False

List of module acceptable units

Command:    /gras/analysis/<moduleType>/<moduleName>/listUnits
Guidance:   List available units for the output

Verbose level

Command:    /gras/analysis/<moduleType>/<moduleName>/verbose <verboseLevel>
Guidance:   Set verbose level

Parameter:      G4int verboseLevel
Candidates:     Integer verbose level
Omittable:  False

Visualisation trigger

Command:    /gras/analysis/<moduleType>/<moduleName>/setVisTrigger [true || false]
Guidance:   Decides if the module triggers the visualisation of the event

Omittable:  True (the default is true)

Module initialisation

Command:    /gras/analysis/<moduleType>/<moduleName>/initialise
Guidance:   Initialisation of the analysis module

Detailed tuples creation

Command:    /gras/analysis/<moduleType>/<moduleName>/detailedTuples [true || false]
Guidance:   If true, more variables are recorded into the tuples

Omittable:  True (the default is true)

Precision Calculations

Since GRAS 6.0 it is possible to register one or more modules for precision calculation during the run. If the set precision is reached then the run will stop without reaching the number of events requested by the /run/beamOn command.

Global analysis precision
Command:    /gras/analysis/setSimPrecision <precision>
Guidance:   Set the precision (in %) to achieve for the registered modules, computed during a simulation

Parameter:      G4double precision
Range:          precision > 0.
Ommittable:     False

Remark:     The global precision can be overwritten with specific precision per module
Nb of events for precision check
Command:    /gras/analysis/setEventsForPrecision <eventsNb>
Guidance:   Set the number of events to test for convergence

Parameter:      G4int eventsNb
Range:          eventsNb > 0
Ommittable:     False

Remark:     If the command is not issued, the calculation will take place every print modulo event. For MT simulations it is recomended that this value is not very low.
Register for precision
Command:    /gras/analysis/<moduleType>/<moduleName>/registerForPrecision [true || false]
Guidance:   If true, the module will be registered for precision monitoring

Omittable:  True (the default is true)
Module precision
Command:    /gras/analysis/<moduleType>/<moduleName>/setModulePrecision <precision>
Guidance:   Set the precision (in %) to achieve for current module

Parameter:      G4double precision
Range:          precision > 0.
Ommittable:     False

Command-based scoring

GRAS supports the existing Geant4 scoring functionalities as described in Command-based scoring manual.

Additionally to the Geant4 functionalities, GRAS supports hollow cylinder meshes (available also in Geant4 from version 11.0) and a user defined mesh read from a gdml or gmsh file.

After activating the scoring functionality ([#Enablescoringfunctionality see here]) all the Geant4 scoring commands will be available under the /score/ commands directory, along with a duplicate of those in the /gras/score/ directory.

In the following sections the differences/extensions will be described. When a command is not mentioned it has the same functionality as in Geant4.