User Commands

1. User Commands Makoto Asai (SLAC) Geant4 Users Workshop @ SLAC Feb. 19th, 2002

2. Contents • Geant4 UI command • Built-in commands • Macro file • Alias, loop control • User-defined command

3. Geant4 UI command • Geant4 UI command can be issued by • (G)UI interactive command submission • Macro file • Hard-coded implementation • Slow but no need for the targeting class pointer G4UImanager* UI = G4UImanager::GetUIpointer(); UI->ApplyCommand("/run/verbose 1"); • A command consists of • Command directory • Command • Parameter(s)

4. Available Commands • You can get a list of available commands including your custom ones 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.

5. Available commands • The availability of individual commands, the ranges of parameters, the available candidates on individual command parameters vary according to the implementation of your application and may even vary dynamically during the execution of your job. • Commands may be available only for limited Geant4 application state(s). • E.g. /run/beamOn is available only for PreInit and Idle states. • A parameter can be a type of string, boolean, integer or double. • Use double-quotes (”) for string with space(s). • A parameter can be “omittable”. If it is the case, a default value will be taken if you omit the parameter. • Default value is either predefined default value or current value according to its definition • If you want to use the default value for your first parameter while you want to set your second parameter, use “!” as a place holder. /dir/command ! second

6. Available commands • Command will be refused if • Wrong application state • Wrong type of parameter • Insufficient number of parameters • Parameter out of its range • For ineteger or double type parameter • Parameter out of its candidate list • For string type parameter • Miss-use of alias • Command not found

7. Macro file • Macro file is an ASCII file contains UI commands. • All commands must be given with their full-path directories. • Use “#” for comment line. • First “#” to the end of the line will be ignored. • Comment lines will be echoed if /control/verbose is set to 2. • Macro file can be executed by • /control/execute • /control/loop • /control/foreach • You can recursively execute same and/or other macro file.

8. Alias • Alias can be defined by /control/alias [name] [value] • Also by /control/loop and /control/foreach commands. • Aliased value is string, even if it consists of numbers. • Alias can be used by other UI command(s), for command name, directory path, parameter(s) or any combination of these. • Use curly brackets “{” and “}” to use an alias. Alias can be interpreted recursively. /control/alias file1 /diskA/run1 /control/alias file2 /diskB/run2 /control/alias run 1 /myCommand/getFile {file{run}}.dat • You can shorten lengthy but frequently used command using alias.

9. Repeating macro exection /control/loop [macroFile] [counterName] [initialValue] [finalValue] [stepSize] • Execute a macro file more than once.Loop counter can be used as an aliased variable. /control/foreach [macroFile] [counterName] [valueList] • Execute a macro file more than once.Loop counter can be used as an aliased variable.Values must be separated by a space.

10. UI command and messenger (G)UI messenger 2. apply 1. register 4. invoke 3. do it UImanager Target class command parameter

11. User command • To define user commands, you need to make your own concrete messenger class implementation class G4ParticleGun; class G4UIcmdWithADoubleAndUnit; #include "G4UImessenger.hh" class G4ParticleGunMessenger: public G4UImessenger { public: G4ParticleGunMessenger(G4ParticleGun * fPtclGun); ~G4ParticleGunMessenger(); void SetNewValue(G4UIcommand * command,G4String newValues); G4String GetCurrentValue(G4UIcommand * command); private: G4ParticleGun * fParticleGun; G4UIcmdWithADoubleAndUnit * energyCmd; };

12. Messenger class • Constructor • Instanciate command objects, set guidance, parameter information, etc., and register commands to UImanager. • Destructor • Delete commands (automatically unregistered). • SetNewValue method • Convert parameter string to values • Invoke appropriate method of target class object • GetCurrentValue method • Get current values from target class • Convert to string

13. Command class • G4UIcommand • Base class, Still usable for complicated command • G4UIdirectory • Definition of (sub-)directory • G4UIcmdWith3Vector, G4UIcmdWith3VectorAndUnit, G4UIcmdWithADouble, G4UIcmdWithADoubleAndUnit, G4UIcmdWithAString, G4UIcmdWithABool, G4UIcmdWithAnInteger, G4UIcmdWithoutParameter • Each class has its adequate conversion methods. • Valid application state(s) can be set.

14. Parameter • Each parameter must has its unique name (within a command) • If a parameter is set as “omittable”, default value must be given, or “current value as default” flag must be set. • Range(s) of parameter(s) can be given by C++ syntax. • E.g. “x>=0. && y>= 0. && x > y” • Candidate list is a string consists of candidates separated by spaces. directionCmd = new G4UIcmdWith3Vector("/gun/direction",this); directionCmd->Set_guidance("Set momentum direction."); directionCmd ->Set_guidance("Direction needs not to be a unit vector."); directionCmd->SetParameterName("Px","Py","Pz",true,true); directionCmd->SetRange("Px != 0 || Py != 0 || Pz != 0"); • See section 7.2 of User's Guide For Application Developers for more detail and full example code.