introduction to geant4 user interface j. perl1 6 june 2005 introduction to geant4 user interface...

Introduction to Geant4 User Interface J. PerlIntroduction to Geant4 User Interface J. Perl 116 June 20056 June 2005

Introduction to Geant4 User Introduction to Geant4 User InterfaceInterfaceJoseph PerlJoseph Perl

Stanford Linear Accelerator Stanford Linear Accelerator CenterCenter


ContentsContents Command SyntaxCommand Syntax Customizing the User Interface: Defining Your Own CommandsCustomizing the User Interface: Defining Your Own Commands Customizing the User Interface: Alternative InterfacesCustomizing the User Interface: Alternative Interfaces


Geant4 Command SyntaxGeant4 Command Syntax A Geant4 command consists of three parts:A Geant4 command consists of three parts:

/run/verbose

1 Parameters can be of type “string”, “Boolean”, “integer” or “double.”Parameters can be of type “string”, “Boolean”, “integer” or “double.”

Delimiter is space.Delimiter is space. Use double-quotes (“”) around strings that need to include spaces.Use double-quotes (“”) around strings that need to include spaces.

Some parameters can be omitted.Some parameters can be omitted. For some commands, the omitted parameter is replaced by a For some commands, the omitted parameter is replaced by a

predefined default value, for other commands, omitting a predefined default value, for other commands, omitting a parameter means to continue using the current value.parameter means to continue using the current value.

You can use the default value for the first parameter while setting You can use the default value for the first parameter while setting a non-default value for the second parameter by specifying the a non-default value for the second parameter by specifying the first parameter as the special character “!”:first parameter as the special character “!”:

/dir/command /dir/command !! second second

Directory Command Parameters


Command SubmissionCommand Submission A Geant4 command can come from one of three sources:A Geant4 command can come from one of three sources:

Interactive command submissionInteractive command submission Macro fileMacro file Hard-coded implementationHard-coded implementation

Slow but no need for the targeting class pointerSlow but no need for the targeting class pointer Take care not to do this from within the event loopTake care not to do this from within the event loop

G4UImanager* UI = G4UImanager::GetUIpointer();G4UImanager* UI = G4UImanager::GetUIpointer();UI->ApplyCommand("/run/verbose 1");UI->ApplyCommand("/run/verbose 1");

The availability of individual commands and the choice and The availability of individual commands and the choice and range of parameters can range of parameters can varyvary according to the your specific according to the your specific application and can even application and can even vary dynamicallyvary dynamically during the during the execution of your job. execution of your job.

Some commands are available only for limited Geant4 Some commands are available only for limited Geant4 application states. application states. Geant4 is a “state machine”, where states Geant4 is a “state machine”, where states are:are:PreInit, Init, Idle, GeomClosed, EventProc, QuitPreInit, Init, Idle, GeomClosed, EventProc, Quit E.g. E.g. /run/beamOn/run/beamOn is available only for is available only for IdleIdle state. state.


Command refusalCommand refusal Command will be refused ifCommand will be refused if

Command is not foundCommand is not found Insufficient number of parametersInsufficient number of parameters Wrong type of parametersWrong type of parameters Parameters out of its allowed range (integer or double Parameters out of its allowed range (integer or double

parameters)parameters) Parameter out of its list of allowed string valuesParameter out of its list of allowed string values

(allowed string values are called “candidates” in Geant4)(allowed string values are called “candidates” in Geant4) Application is in wrong state (such as an attempt to execute Application is in wrong state (such as an attempt to execute

/run/beamOn from a piece of C++ code that is called during /run/beamOn from a piece of C++ code that is called during

Geant4’s Init phase)Geant4’s Init phase)


Macro FilesMacro Files Macro files are ASCII files that contains UI commands.Macro files are ASCII files that contains UI commands. All commands must be given with their All commands must be given with their full-path directoriesfull-path directories.. Use “#” for comment lines.Use “#” for comment lines.

Everything form the first “#” to the end of the line will be Everything form the first “#” to the end of the line will be ignored.ignored.

Comment lines will be echoed if Comment lines will be echoed if /control/verbose/control/verbose is set to 2. is set to 2. Macro files can be executed Macro files can be executed

InteractivelyInteractively

/control/execute /control/execute file_namefile_name From within other macro filesFrom within other macro files

/control/execute /control/execute file_namefile_name Hard-codedHard-coded

G4UImanager* UI = G4UImanager::GetUIpointer();G4UImanager* UI = G4UImanager::GetUIpointer();UI->ApplyCommand("/control/execute UI->ApplyCommand("/control/execute file_namefile_name");");


Command GuidanceCommand Guidance Guidance on all commands is available from the command line:Guidance on all commands is available from the command line:

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


Guidance DetailGuidance Detail Guidance is hierarchical, providing full detail on all commands.Guidance is hierarchical, providing full detail on all commands.

Command /gun/energyCommand /gun/energy Guidance :Guidance : Set kinetic energy.Set kinetic energy. Parameter : EnergyParameter : Energy Parameter type : dParameter type : d Omittable : TrueOmittable : True Default value : taken from the current Default value : taken from the current

valuevalue

Parameter : UnitParameter : Unit Parameter type : sParameter type : s Omittable : TrueOmittable : True Default value : GeVDefault value : GeV Candidates : eV keV MeV GeV TeV Candidates : eV keV MeV GeV TeV

PeV J electronvolt kiloelectronvolt PeV J electronvolt kiloelectronvolt megaelectronvolt gigaelectronvolt megaelectronvolt gigaelectronvolt teraelectronvolt petaelectronvolt jouleteraelectronvolt petaelectronvolt joule

Particle Gun control commands.Particle Gun control commands. Sub-directories :Sub-directories : Commands :Commands : 1) List * List available particles.1) List * List available particles. 2) particle * Set particle to be generated.2) particle * Set particle to be generated. 3) direction * Set momentum direction.3) direction * Set momentum direction. 4) energy * Set kinetic energy.4) energy * Set kinetic energy. 5) position * Set starting position of the particle.5) position * Set starting position of the particle. 6) time * Set initial time of the particle.6) time * Set initial time of the particle. 7) polarization * Set polarization.7) polarization * Set polarization. 8) number * Set number of particles to be 8) number * Set number of particles to be

generated.generated. 9) ion * Set properties of ion to be generated.9) ion * Set properties of ion to be generated. Type the number ( 0:end, -n:n level back ) :Type the number ( 0:end, -n:n level back ) : 44


Command ListingCommand Listing You can generate a complete listing of commands byYou can generate a complete listing of commands by

/control/manual [directory]/control/manual [directory] Plane text format to standard outputPlane text format to standard output

/control/createHTML [directory]/control/createHTML [directory] HTML file(s)HTML file(s)

List of built-in commands is also available in section 7.1 of List of built-in commands is also available in section 7.1 of User's Guide For Application Developers.User's Guide For Application Developers.

Some “compound commands” are provided to allow you to Some “compound commands” are provided to allow you to accomplish several commands at once, such as:accomplish several commands at once, such as:

/vis/drawVolume/vis/drawVolume /vis/scene/create/vis/scene/create /vis/scene/add/volume/vis/scene/add/volume


AliasAlias An alias can be defined byAn alias can be defined by

/control/alias/control/alias [name] [value] [name] [value] In any subsequent command that contains the given “name” in curly brackets,In any subsequent command that contains the given “name” in curly brackets,

the aliased “value” will be substituted.the aliased “value” will be substituted. For example, after:For example, after:

/control/alias trv1 “/tracking/verbose 1”/control/alias trv1 “/tracking/verbose 1” You could issue the tracking command with justYou could issue the tracking command with just

{trv1}{trv1} Any alias that you set can be interpreted from within any subsequent macro:Any alias that you set can be interpreted from within any subsequent macro:

/control/alias file1 /diskA/dirX/fileXX.dat/control/alias file1 /diskA/dirX/fileXX.dat /control/execute myMacro/control/execute myMacro Then within myMacro:Then within myMacro:

/myCmd/getFile {file1}/myCmd/getFile {file1} Aliases can be used recursively:Aliases can be used recursively:

/control/alias file1 /diskA/dirX/fileXX.dat/control/alias file1 /diskA/dirX/fileXX.dat /control/alias file2 /diskB/dirY/fileYY.dat/control/alias file2 /diskB/dirY/fileYY.dat /control/alias run 1/control/alias run 1 /myCmd/getFile /myCmd/getFile {file{run}}{file{run}}


LoopLoop 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


Defining Your Own CommandsDefining Your Own Commands

(G)UI

G4UImanager

messenger(G4UImessenger)

command(G4UIcommand)

G4UIparameter

Target class

1. register command

2. apply

3. do it

4. invoke

Implement a messenger class. Instantiate commands. Register the commands with the

G4UImanager. When user invokes the commands, target

classes can use the results.


Messenger classMessenger class Each messenger class must be derived from the Each messenger class must be derived from the G4UImessengerG4UImessenger base base

class.class.A single messenger class can handle more than one UI command.A single messenger class can handle more than one UI command.

A messenger class A messenger class should be instantiated byshould be instantiated by the constructor of the the constructor of the target classtarget class to which commands should be delivered and to which commands should be delivered and should be should be deleteddeleted by the destructor of the target class. by the destructor of the target class.

Methods of the messenger classMethods of the messenger class ConstructorConstructor

Define (instantiate) commands / command directoriesDefine (instantiate) commands / command directories DestructorDestructor

Delete commands / command directoriesDelete commands / command directories void void SetNewValueSetNewValue(G4UIcommand* command,G4String newValue)(G4UIcommand* command,G4String newValue)

Convert "newValue" parameter string to appropriate value(s) Convert "newValue" parameter string to appropriate value(s) and invoke a method of the target classand invoke a method of the target class

This method is invoked when a command is issued.This method is invoked when a command is issued. G4String G4String GetCurrentValueGetCurrentValue(G4UIcommand* command)(G4UIcommand* command)

Access a get-method of the target class and convert the current Access a get-method of the target class and convert the current values to a stringvalues to a string

This method is invoked when the (G)UI asks for the current This method is invoked when the (G)UI asks for the current value(s).value(s).


Definition (instantiation) of a Definition (instantiation) of a commandcommand To be implemented in the constructor of a messenger class.To be implemented in the constructor of a messenger class.

A01DetectorConstMessenger::A01DetectorConstMessengerA01DetectorConstMessenger::A01DetectorConstMessenger(A01DetectorConstruction* tgt)(A01DetectorConstruction* tgt):target(tgt):target(tgt){{ mydetDir = new mydetDir = new G4UIdirectoryG4UIdirectory("("/mydet//mydet/");"); mydetDir->mydetDir->SetGuidanceSetGuidance("A01 detector setup commands.");("A01 detector setup commands.");

armCmd = new armCmd = new G4UIcmdWithADoubleAndUnitG4UIcmdWithADoubleAndUnit("("/mydet/armAngle/mydet/armAngle",this);",this);

armCmd->armCmd->SetGuidanceSetGuidance("Rotation angle of the second arm.");("Rotation angle of the second arm."); armCmd->armCmd->SetParameterNameSetParameterName("angle",true);("angle",true); armCmd->armCmd->SetRangeSetRange("angle>=0. && angle<180.");("angle>=0. && angle<180."); armCmd->armCmd->SetDefaultValueSetDefaultValue(30.);(30.); armCmd->armCmd->SetDefaultUnitSetDefaultUnit("deg");("deg");}}

Guidance should be more than one line with the first line Guidance should be more than one line with the first line utilized as a short command description.utilized as a short command description.


G4UIcommand and its G4UIcommand and its DerivativesDerivatives The classThe class G4UIcommand G4UIcommand represents a UI command. represents a UI command.

The classThe class G4UIparameter G4UIparameter represents a parameter for a command. represents a parameter for a command.

Your command can be a direct instance of G4UIcommand, but more often you 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 will find it convenient to use one of G4UIcommand’s derivatives that provides

additional functionality for specific types of parameters:additional functionality for specific types of parameters:

G4UIcmdWithoutParameterG4UIcmdWithoutParameter

G4UIcmdWithAStringG4UIcmdWithAString

G4UIcmdWithABool G4UIcmdWithABool

G4UIcmdWithAnIntegerG4UIcmdWithAnInteger

G4UIcmdWithADouble, G4UIcmdWithADoubleAndUnit G4UIcmdWithADouble, G4UIcmdWithADoubleAndUnit

G4UIcmdWith3Vector, G4UIcmdWith3VectorAndUnitG4UIcmdWith3Vector, G4UIcmdWith3VectorAndUnit

G4UIdirectoryG4UIdirectory

A UI command with other types of parameters must be defined by the A UI command with other types of parameters must be defined by the

G4UIcommand base class with G4UIparameter.G4UIcommand base class with G4UIparameter.


Parameter name(s)Parameter name(s)void SetParameterName(void SetParameterName(

const char*parName, const char*parName,

G4bool omittable, G4bool omittable,

G4bool currentAsDefault=false); G4bool currentAsDefault=false);

void SetParameterName(void SetParameterName(

const char*nam1, const char*nam2, const char*nam3, const char*nam1, const char*nam2, const char*nam3,

G4bool omittable, G4bool omittable,

G4bool currentAsDefault=false);G4bool currentAsDefault=false);

Parameter names are used in help, and also in the definition of parameter Parameter names are used in help, and also in the definition of parameter

range.range.

If "omittable" is true, the command can be issued without this particular If "omittable" is true, the command can be issued without this particular

parameter, and the default value will be used.parameter, and the default value will be used.

If "currentAsDefault" is true, current value of the parameter is used as a If "currentAsDefault" is true, current value of the parameter is used as a

default value, otherwise default value must be defined with default value, otherwise default value must be defined with

SetDefaultValue() method.SetDefaultValue() method.


Range, unit and candidatesRange, unit and candidatesvoid void SetRangeSetRange(const char* rangeString)(const char* rangeString) Available for a command with numeric-type parameters.Available for a command with numeric-type parameters. Range of parameter(s) must be given in C++ syntax.Range of parameter(s) must be given in C++ syntax.

aCmd->SetRange("x>0. && y>z && z>(x+y)");aCmd->SetRange("x>0. && y>z && z>(x+y)"); Not only comparison with hard-coded number but also comparison Not only comparison with hard-coded number but also comparison

between variables and simple calculation are available.between variables and simple calculation are available. Names of variables must be defined by Names of variables must be defined by SetParameterNameSetParameterName() method.() method.

void void SetDefaultUnitSetDefaultUnit(const char* defUnit)(const char* defUnit) Available for a command which takes unit.Available for a command which takes unit. Once the default unit is defined, no other unit of different unit Once the default unit is defined, no other unit of different unit

category (length, time, distance, etc.) will be accepted.category (length, time, distance, etc.) will be accepted. Alternatively, you can define a unit category without setting a default Alternatively, you can define a unit category without setting a default

unit.unit.

void void SetUnitCategorySetUnitCategory(const char* unitCategory)(const char* unitCategory)

void void SetCandidatesSetCandidates(const char* candidateList)(const char* candidateList) Available for a command with string type parameterAvailable for a command with string type parameter Candidates must be delimited by a space.Candidates must be delimited by a space. Candidates can be dynamically updated.Candidates can be dynamically updated.


Available stateAvailable statevoid void AvailableForStatesAvailableForStates(G4ApplicationState s1,…)(G4ApplicationState s1,…) Define command's applicability for Geant4 Define command's applicability for Geant4

application states.application states. Geant4 has six application states.Geant4 has six application states.

G4State_PreInitG4State_PreInit Material, Geometry, Particle and/or Material, Geometry, Particle and/or

Physics Process need to be initializedPhysics Process need to be initialized G4State_IdleG4State_Idle

Ready to start a runReady to start a run G4State_GeomClosedG4State_GeomClosed

Geometry is optimized and ready to Geometry is optimized and ready to process an eventprocess an event

G4State_EventProcG4State_EventProc An event is processingAn event is processing

G4State_Quit, G4State_AbortG4State_Quit, G4State_Abort UI command unavailableUI command unavailable

PreInit

Idle

EventProc

GeomClosed

Quit

Abort

initialize

beamOnexit


Converting between string and Converting between string and valuesvalues

Derivatives of G4UIcommand with numeric and boolean parameters have Derivatives of G4UIcommand with numeric and boolean parameters have

corresponding conversion methods.corresponding conversion methods.

From a string to valueFrom a string to value

G4bool GetNewBoolValue(const char*)G4bool GetNewBoolValue(const char*)

G4int GetNewIntValue(const char*)G4int GetNewIntValue(const char*)

G4double GetNewDoubleValue(const char*)G4double GetNewDoubleValue(const char*)

G4ThreeVector GetNew3VectorValue(const char*)G4ThreeVector GetNew3VectorValue(const char*)

To be used inTo be used in SetNewValue SetNewValue() method in messenger.() method in messenger.

Unit is taken into account automaticallyUnit is taken into account automatically..

From value to stringFrom value to string

G4String ConvertToString(...)G4String ConvertToString(...)

G4String ConvertToString(...,const char* unit)G4String ConvertToString(...,const char* unit)

To be used inTo be used in GetCurrentValue GetCurrentValue() method in messenger.() method in messenger.


SetNewValue and SetNewValue and GetCurrentValueGetCurrentValuevoid A01DetectorConstMessengervoid A01DetectorConstMessenger

::::SetNewValue(G4UIcommand* command,G4String newValue)SetNewValue(G4UIcommand* command,G4String newValue)

{{

if( command==armCmd )if( command==armCmd )

{ target->SetArmAngle(armCmd->{ target->SetArmAngle(armCmd->GetNewDoubleValueGetNewDoubleValue(newValue)); }(newValue)); }

}}

G4String A01DetectorConstMessengerG4String A01DetectorConstMessenger

::::GetCurrentValue(G4UIcommand* command)GetCurrentValue(G4UIcommand* command)

{{

G4String cv;G4String cv;

if( command==armCmd )if( command==armCmd )

{ cv = armCmd->{ cv = armCmd->ConvertToStringConvertToString(target->GetArmAngle(),"deg"); }(target->GetArmAngle(),"deg"); }

return cv; return cv;

}}


Alternative InterfacesAlternative Interfaces The interactive command submission interface described in the previous The interactive command submission interface described in the previous

slides is really just one concrete implementation (G4UIterminal) of an slides is really just one concrete implementation (G4UIterminal) of an abstract class (G4UIsession).abstract class (G4UIsession).

To allow interactive command submission, main routine needs to includeTo allow interactive command submission, main routine needs to include G4UIsession* session = new G4UIterminal();G4UIsession* session = new G4UIterminal(); session->SessionStart();session->SessionStart();

Additional tcsh-like functionality can be obtained by changing this line to Additional tcsh-like functionality can be obtained by changing this line to (but this option works only on Linux, not Windows)(but this option works only on Linux, not Windows) G4UIsession* session = new G4UIterminal(new G4UItcsh);G4UIsession* session = new G4UIterminal(new G4UItcsh);

An example of a different user interface is G4UIGAG, which is used by An example of a different user interface is G4UIGAG, which is used by GAG, the Geant4 Adaptive GUI.GAG, the Geant4 Adaptive GUI. G4UIsession* session = new G4UIGAG();G4UIsession* session = new G4UIGAG();


G4UIterminal CommandsG4UIterminal Commands G4UIterminal provides some additional commands that are not part of the G4UIterminal provides some additional commands that are not part of the

Geant4 kernel.Geant4 kernel. Provide additional uinx-like functionality from the command lineProvide additional uinx-like functionality from the command line But cannot be used from within macro filesBut cannot be used from within macro files

G4UIterminal commands:G4UIterminal commands: cdcd, , pwdpwd - change and display current command directory (so that you can - change and display current command directory (so that you can

omit that part of the directory string from subsequent commands).omit that part of the directory string from subsequent commands). lsls - list available UI commands and sub-directories - list available UI commands and sub-directories historyhistory - show previous commands - show previous commands !!historyIDhistoryID - - re-issue previous commandre-issue previous command arrow keys (TC-shell only)arrow keys (TC-shell only) ??UIcommandUIcommand - show current value - show current value helphelp [[UIcommandUIcommand]] - help - help exitexit - job termination - job termination

introduction to geant4 user interface j. perl1 6 june 2005 introduction to geant4 user interface...

Documents

ui commands

control ui control commands

run run control commands

command line

omitted parameter

idle state

predefined default value

nondefault value