Introduction to Geant4 User Interface

1
Introduction to Geant4 User Interface

• Joseph Perl
• Stanford Linear Accelerator Center

2
Contents

• Command Syntax
• Customizing the User Interface Defining Your Own
  Commands
• Customizing the User Interface Alternative
  Interfaces

3
Geant4 Command Syntax

• A Geant4 command consists of three parts

Command
Parameters
Directory
/run/verbose 1

• Parameters can be of type string, Boolean,
  integer or double.
• Delimiter is space.
• Use double-quotes () around strings that need
  to include spaces.
• Some parameters can be omitted.
• For some commands, the omitted parameter is
  replaced by a predefined default value, for other
  commands, omitting a parameter means to continue
  using the current value.
• You can use the default value for the first
  parameter while setting a non-default value for
  the second parameter by specifying the first
  parameter as the special character !
• /dir/command ! second

4
Command Submission

• A Geant4 command can come from one of three
  sources
• Interactive command submission
• Macro file
• Hard-coded implementation
• Slow but no need for the targeting class pointer
• Take care not to do this from within the event
  loop
• G4UImanager UI G4UImanagerGetUIpointer()
• UI-gtApplyCommand("/run/verbose 1")
• The availability of individual commands and the
  choice and range of parameters can vary according
  to the your specific application and can even
  vary dynamically during the execution of your
  job.
• Some commands are available only for limited
  Geant4 application states. Geant4 is a state
  machine, where states arePreInit, Init, Idle,
  GeomClosed, EventProc, Quit
• E.g. /run/beamOn is available only for Idle
  state.

5
Command refusal

• Command will be refused if
• Command is not found
• Insufficient number of parameters
• Wrong type of parameters
• Parameters out of its allowed range (integer or
  double parameters)
• Parameter out of its list of allowed string
  values(allowed string values are called
  candidates in Geant4)
• Application is in wrong state (such as an attempt
  to execute /run/beamOn from a piece of C code
  that is called during Geant4s Init phase)

6
Macro Files

• Macro files are ASCII files that contains UI
  commands.
• All commands must be given with their full-path
  directories.
• Use for comment lines.
• Everything form the first to the end of the
  line will be ignored.
• Comment lines will be echoed if /control/verbose
  is set to 2.
• Macro files can be executed
• Interactively
• /control/execute file_name
• From within other macro files
• /control/execute file_name
• Hard-coded
• G4UImanager UI G4UImanagerGetUIpointer()
• UI-gtApplyCommand("/control/execute file_name")

7
Command Guidance

• Guidance on all commands is available from the
  command line
• Idlegt help
• Command directory path /
• Sub-directories
• 1) /control/ UI control commands.
• 2) /units/ Available units.
• 3) /geometry/ Geometry control commands.
• 4) /tracking/ TrackingManager and
  SteppingManager control commands.
• 5) /event/ EventManager control commands.
• 6) /run/ Run control commands.
• 7) /random/ Random number status control
  commands.
• 8) /particle/ Particle control commands.
• 9) /process/ Process Table control commands.
• 10) /vis/ Visualization commands.
• 11) /mydet/ A01 detector setup control
  commands.
• 12) /hits/ Sensitive detectors and Hits
• 13) /gun/ Particle Gun control commands.
• Commands
• Type the number ( 0end, -nn level back )

8
Guidance Detail

• Guidance is hierarchical, providing full detail
  on all commands.

• Particle Gun control commands.
• Sub-directories
• Commands
• 1) List List available particles.
• 2) particle Set particle to be generated.
• 3) direction Set momentum direction.
• 4) energy Set kinetic energy.
• 5) position Set starting position of the
  particle.
• 6) time Set initial time of the particle.
• 7) polarization Set polarization.
• 8) number Set number of particles to be
  generated.
• 9) ion Set properties of ion to be generated.
• Type the number ( 0end, -nn level back )
• 4

• Command /gun/energy
• Guidance
• Set kinetic energy.
• Parameter Energy
• Parameter type d
• Omittable True
• Default value taken from the current value
• Parameter Unit
• Parameter type s
• Omittable True
• Default value GeV
• Candidates eV keV MeV GeV TeV PeV J
  electronvolt kiloelectronvolt megaelectronvolt
  gigaelectronvolt teraelectronvolt
  petaelectronvolt joule

9
Command Listing

• You can generate a complete listing of commands
  by
• /control/manual directory
• Plane text format to standard output
• /control/createHTML directory
• HTML file(s)
• List of built-in commands is also available in
  section 7.1 of User's Guide For Application
  Developers.
• Some compound commands are provided to allow
  you to accomplish several commands at once, such
  as
• /vis/drawVolume
• /vis/scene/create
• /vis/scene/add/volume

10
Alias

• An alias can be defined by
• /control/alias name value
• In any subsequent command that contains the given
  name in curly brackets,the aliased value
  will be substituted.
• For example, after
• /control/alias trv1 /tracking/verbose 1
• You could issue the tracking command with just
• trv1
• Any alias that you set can be interpreted from
  within any subsequent macro
• /control/alias file1 /diskA/dirX/fileXX.dat
• /control/execute myMacro
• Then within myMacro
• /myCmd/getFile file1
• Aliases can be used recursively
• /control/alias file1 /diskA/dirX/fileXX.dat
• /control/alias file2 /diskB/dirY/fileYY.dat
• /control/alias run 1
• /myCmd/getFile filerun

11
Loop

• The /control/loop and /control/foreach commands
  execute a macro file repeatedly.
• They provide a variable that changes with each
  iteration of the loop.
• In /control/loop, a variable starts at a
  specified initial value and then increases to a
  final value by a step size
• /control/loop macroFile counterName
• initialValue finalValue
  stepSize
• Within the macro, counterName is the loop
  variable.
• In /control/foreach, a variable iterates through
  a specifed list of values
• /control/foreach macroFile counterName
  valueList
• Within the macro, counterName is the loop
  variable.
• valueList must be enclosed by double quotes (" ")
• For example,
• /control/loop myRun.mac Ekin 10. 20. 2.
• in myRun.mac
• /control/foreach mySingleRun.mac pname p pi-
  mu-
• in mySingleRun.mac
• /gun/particle pname
• /gun/energy Ekin GeV
• /run/beamOn 100

12
Contents

• Command Syntax
• Customizing the User Interface Defining Your Own
  Commands
• Customizing the User Interface Alternative
  Interfaces

13
Defining Your Own Commands

• Implement a messenger class.
• Instantiate commands.
• Register the commands with the G4UImanager.
• When user invokes the commands, target classes
  can use the results.

(G)UI
messenger (G4UImessenger)
1. register command
2. apply
4. invoke
3. do it
G4UImanager
Target class
command (G4UIcommand)
G4UIparameter
14
Messenger class

• Each messenger class must be derived from the
  G4UImessenger base class.A single messenger
  class can handle more than one UI command.
• A messenger class should be instantiated by the
  constructor of the target class to which commands
  should be delivered and should be deleted by the
  destructor of the target class.
• Methods of the messenger class
• Constructor
• Define (instantiate) commands / command
  directories
• Destructor
• Delete commands / command directories
• void SetNewValue(G4UIcommand command,G4String
  newValue)
• Convert "newValue" parameter string to
  appropriate value(s) and invoke a method of the
  target class
• This method is invoked when a command is issued.
• G4String GetCurrentValue(G4UIcommand command)
• Access a get-method of the target class and
  convert the current values to a string
• This method is invoked when the (G)UI asks for
  the current value(s).

15
Definition (instantiation) of a command

• To be implemented in the constructor of a
  messenger class.
• A01DetectorConstMessengerA01DetectorConstMesseng
  er
• (A01DetectorConstruction tgt)
• target(tgt)
• mydetDir new G4UIdirectory("/mydet/")
• mydetDir-gtSetGuidance("A01 detector setup
  commands.")
• armCmd new G4UIcmdWithADoubleAndUnit("/mydet/a
  rmAngle",this)
• armCmd-gtSetGuidance("Rotation angle of the
  second arm.")
• armCmd-gtSetParameterName("angle",true)
• armCmd-gtSetRange("anglegt0. anglelt180.")
• armCmd-gtSetDefaultValue(30.)
• armCmd-gtSetDefaultUnit("deg")
• Guidance should be more than one line with the
  first line utilized as a short command
  description.

16
G4UIcommand and its Derivatives

• The class G4UIcommand represents a UI command.
• The class G4UIparameter represents a parameter
  for a command.
• Your command can be a direct instance of
  G4UIcommand, but more often you will find it
  convenient to use one of G4UIcommands
  derivatives that provides additional
  functionality for specific types of parameters
• G4UIcmdWithoutParameter
• G4UIcmdWithAString
• G4UIcmdWithABool
• G4UIcmdWithAnInteger
• G4UIcmdWithADouble, G4UIcmdWithADoubleAndUnit
• G4UIcmdWith3Vector, G4UIcmdWith3VectorAndUnit
• G4UIdirectory
• A UI command with other types of parameters must
  be defined by the G4UIcommand base class with
  G4UIparameter.

17
Parameter name(s)

• void SetParameterName(
• const charparName,
• G4bool omittable,
• G4bool currentAsDefaultfalse)
• void SetParameterName(
• const charnam1, const charnam2, const
  charnam3,
• G4bool omittable,
• G4bool currentAsDefaultfalse)
• Parameter names are used in help, and also in the
  definition of parameter range.
• If "omittable" is true, the command can be issued
  without this particular parameter, and the
  default value will be used.
• If "currentAsDefault" is true, current value of
  the parameter is used as a default value,
  otherwise default value must be defined with
  SetDefaultValue() method.

18
Range, unit and candidates

• void SetRange(const char rangeString)
• Available for a command with numeric-type
  parameters.
• Range of parameter(s) must be given in C
  syntax.
• aCmd-gtSetRange("xgt0. ygtz zgt(xy)")
• Not only comparison with hard-coded number but
  also comparison between variables and simple
  calculation are available.
• Names of variables must be defined by
  SetParameterName() method.
• void SetDefaultUnit(const char defUnit)
• Available for a command which takes unit.
• Once the default unit is defined, no other unit
  of different unit category (length, time,
  distance, etc.) will be accepted.
• Alternatively, you can define a unit category
  without setting a default unit.
• void SetUnitCategory(const char unitCategory)
• void SetCandidates(const char candidateList)
• Available for a command with string type
  parameter
• Candidates must be delimited by a space.
• Candidates can be dynamically updated.

19
Available state

• void AvailableForStates(G4ApplicationState s1,)
• Define command's applicability for Geant4
  application states.
• Geant4 has six application states.
• G4State_PreInit
• Material, Geometry, Particle and/or
  Physics Process need to be initialized
• G4State_Idle
• Ready to start a run
• G4State_GeomClosed
• Geometry is optimized and ready to
  process an event
• G4State_EventProc
• An event is processing
• G4State_Quit, G4State_Abort
• UI command unavailable

PreInit
initialize
Idle
beamOn
exit
GeomClosed
Quit
EventProc
Abort
20
Converting between string and values

• Derivatives of G4UIcommand with numeric and
  boolean parameters have corresponding conversion
  methods.
• From a string to value
• G4bool GetNewBoolValue(const char)
• G4int GetNewIntValue(const char)
• G4double GetNewDoubleValue(const char)
• G4ThreeVector GetNew3VectorValue(const char)
• To be used in SetNewValue() method in messenger.
• Unit is taken into account automatically.
• From value to string
• G4String ConvertToString(...)
• G4String ConvertToString(...,const char unit)
• To be used in GetCurrentValue() method in
  messenger.

21
SetNewValue and GetCurrentValue

• void A01DetectorConstMessenger
• SetNewValue(G4UIcommand command,G4String
  newValue)
• if( commandarmCmd )
• target-gtSetArmAngle(armCmd-gtGetNewDoubleValue(
  newValue))
• G4String A01DetectorConstMessenger
• GetCurrentValue(G4UIcommand command)
• G4String cv
• if( commandarmCmd )
• cv armCmd-gtConvertToString(target-gtGetArmAng
  le(),"deg")
• return cv

22
Contents

• Command Syntax
• Customizing the User Interface Defining Your Own
  Commands
• Customizing the User Interface Alternative
  Interfaces

23
Alternative Interfaces

• The interactive command submission interface
  described in the previous slides is really just
  one concrete implementation (G4UIterminal) of an
  abstract class (G4UIsession).
• To allow interactive command submission, main
  routine needs to include
• G4UIsession session new G4UIterminal()
• session-gtSessionStart()
• Additional tcsh-like functionality can be
  obtained by changing this line to (but this
  option works only on Linux, not Windows)
• G4UIsession session new G4UIterminal(new
  G4UItcsh)
• An example of a different user interface is
  G4UIGAG, which is used by GAG, the Geant4
  Adaptive GUI.
• G4UIsession session new G4UIGAG()

24
G4UIterminal Commands

• G4UIterminal provides some additional commands
  that are not part of the Geant4 kernel.
• Provide additional uinx-like functionality from
  the command line
• But cannot be used from within macro files
• G4UIterminal commands
• cd, pwd - change and display current command
  directory (so that you can omit that part of the
  directory string from subsequent commands).
• ls - list available UI commands and
  sub-directories
• history - show previous commands
• !historyID - re-issue previous command
• arrow keys (TC-shell only)
• ?UIcommand - show current value
• help UIcommand - help
• exit - job termination