Introduction to Geant4 User Interface

1. Introduction to Geant4 User Interface Joseph Perl Stanford Linear Accelerator Center Introduction to Geant4 User Interface J. Perl

2. Contents • Command Syntax • Customizing the User Interface: Defining Your Own Commands • Customizing the User Interface: Alternative Interfaces Introduction to Geant4 User Interface J. Perl

3. Geant4 Command Syntax • A Geant4 command consists of three parts: Command Parameters Directory /run/verbose1 • 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 Introduction to Geant4 User Interface J. Perl

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 = G4UImanager::GetUIpointer(); UI->ApplyCommand("/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 are:PreInit, Init, Idle, GeomClosed, EventProc, Quit • E.g. /run/beamOn is available only for Idle state. Introduction to Geant4 User Interface J. Perl

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 Geant4’s Init phase) Introduction to Geant4 User Interface J. Perl

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 = G4UImanager::GetUIpointer(); UI->ApplyCommand("/control/execute file_name"); Introduction to Geant4 User Interface J. Perl

7. Command Guidance • Guidance on all commands is available from the command line: • Idle> 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 ( 0:end, -n:n level back ) : Introduction to Geant4 User Interface J. Perl

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 ( 0:end, -n:n 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 Introduction to Geant4 User Interface J. Perl

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 Introduction to Geant4 User Interface J. Perl

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 {file{run}} Introduction to Geant4 User Interface J. Perl

11. Loop • The /control/loopand /control/foreachcommands 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. • valueListmust 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 Introduction to Geant4 User Interface J. Perl

12. Contents • Command Syntax • Customizing the User Interface: Defining Your Own Commands • Customizing the User Interface: Alternative Interfaces Introduction to Geant4 User Interface J. Perl

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 Introduction to Geant4 User Interface J. Perl

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). Introduction to Geant4 User Interface J. Perl

15. Definition (instantiation) of a command • To be implemented in the constructor of a messenger class. A01DetectorConstMessenger::A01DetectorConstMessenger (A01DetectorConstruction* tgt) :target(tgt) { mydetDir = new G4UIdirectory("/mydet/"); mydetDir->SetGuidance("A01 detector setup commands."); armCmd = new G4UIcmdWithADoubleAndUnit("/mydet/armAngle",this); armCmd->SetGuidance("Rotation angle of the second arm."); armCmd->SetParameterName("angle",true); armCmd->SetRange("angle>=0. && angle<180."); armCmd->SetDefaultValue(30.); armCmd->SetDefaultUnit("deg"); } • Guidance should be more than one line with the first line utilized as a short command description. Introduction to Geant4 User Interface J. Perl

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 G4UIcommand’s 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. Introduction to Geant4 User Interface J. Perl

17. Parameter name(s) void SetParameterName( const char*parName, G4bool omittable, G4bool currentAsDefault=false); void SetParameterName( const char*nam1, const char*nam2, const char*nam3, G4bool omittable, G4bool currentAsDefault=false); • 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. Introduction to Geant4 User Interface J. Perl

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->SetRange("x>0. && y>z && z>(x+y)"); • 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. Introduction to Geant4 User Interface J. Perl

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 Introduction to Geant4 User Interface J. Perl

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. Introduction to Geant4 User Interface J. Perl

21. SetNewValue and GetCurrentValue void A01DetectorConstMessenger ::SetNewValue(G4UIcommand* command,G4String newValue) { if( command==armCmd ) { target->SetArmAngle(armCmd->GetNewDoubleValue(newValue)); } } G4String A01DetectorConstMessenger ::GetCurrentValue(G4UIcommand* command) { G4String cv; if( command==armCmd ) { cv = armCmd->ConvertToString(target->GetArmAngle(),"deg"); } return cv; } Introduction to Geant4 User Interface J. Perl

22. Contents • Command Syntax • Customizing the User Interface: Defining Your Own Commands • Customizing the User Interface: Alternative Interfaces Introduction to Geant4 User Interface J. Perl

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->SessionStart(); • 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(); Introduction to Geant4 User Interface J. Perl

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 Introduction to Geant4 User Interface J. Perl