UI commandUI command

Makoto Asai (SLAC)Makoto Asai (SLAC)

Geant4 Tutorial Course @ BordeauxGeant4 Tutorial Course @ Bordeaux

NovemberNovember 20052005

November 2005, Geant4 v7.1

UI CommandUI Command 22

ContentsContents

�� Command syntaxCommand syntax

�� G4UIterminalG4UIterminal

�� Alias and loopAlias and loop

�� Mechanism of UI commandMechanism of UI command

�� Messenger classMessenger class

�� Defining a commandDefining a command

�� Implementing a messengerImplementing a messenger

UI CommandUI Command 33

Geant4 UI commandGeant4 UI command�� A command consists of A command consists of

�� Command directoryCommand directory

�� CommandCommand

�� Parameter(sParameter(s))

�� A parameter can be a type of string, A parameter can be a type of string, booleanboolean, integer or double., integer or double.

�� Space is a delimiter.Space is a delimiter.

�� Use doubleUse double--quotes (quotes (“”“”) for string with ) for string with space(sspace(s).).

�� A parameter may be A parameter may be ““omittableomittable””. If it is the case, a default value will be . If it is the case, a default value will be

taken if you omit the parameter.taken if you omit the parameter.

�� Default value is either predefined default value or current valuDefault value is either predefined default value or current value e

according to its definitionaccording to its definition

�� If you want to use the default value for your first parameter whIf you want to use the default value for your first parameter while ile

you want to set your second parameter, use you want to set your second parameter, use ““!!”” as a place holder.as a place holder.

/dir/command /dir/command !! secondsecond

/run/ verbose 1

/vis/viewer/ flush

UI CommandUI Command 44

Command submissionCommand submission�� Geant4 UI command can be issued byGeant4 UI command can be issued by

�� (G)UI interactive command submission(G)UI interactive command submission

�� Macro fileMacro file

�� HardHard--coded implementationcoded implementation

�� Slow but no need for the targeting class pointerSlow but no need for the targeting class pointer

�� Should Should notnot be used inside an event loopbe used inside an event loop

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

�� The availability of individual command, the ranges of parametersThe availability of individual command, the ranges of parameters, the , the available candidates on individual command parameter available candidates on individual command parameter varyvary according according to the implementation of your application and may even to the implementation of your application and may even vary vary dynamicallydynamically during the execution of your job. during the execution of your job.

�� some commands are available only for limited Geant4 some commands are available only for limited Geant4 application application state(sstate(s).).�� E.g. E.g. /run//run/ beamOnbeamOn is available only for is available only for IdleIdle states.states.

UI CommandUI Command 55

Command refusalCommand refusal

�� Command will be refused ifCommand will be refused if

�� Wrong application stateWrong application state

�� Wrong type of parameterWrong type of parameter

�� Insufficient number of parametersInsufficient number of parameters

�� Parameter out of its rangeParameter out of its range

�� For integer or double type parameterFor integer or double type parameter

�� Parameter out of its candidate listParameter out of its candidate list

�� For string type parameterFor string type parameter

�� Command not foundCommand not found

UI CommandUI Command 66

Macro fileMacro file

�� Macro file is an ASCII file contains UI commands.Macro file is an ASCII file contains UI commands.

�� All commands must be given with their All commands must be given with their fullfull--path directoriespath directories..

�� Use Use ““##”” for comment line.for comment line.

�� First First ““##”” to the end of the line will be ignored.to the end of the line will be 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 file can be executed Macro file can be executed

�� interactively or in (other) macro fileinteractively or in (other) macro file

/control/execute /control/execute file_namefile_name

�� hardhard--codedcoded

G4UImanager* UI = G4UImanager::GetUIpointer();G4UImanager* UI = G4UImanager::GetUIpointer();

UIUI -- >>ApplyCommandApplyCommand("/control/execute ("/control/execute file_namefile_name");");

UI CommandUI Command 77

Available CommandsAvailable Commands

�� You can get a list of available commands including your custom oYou can get a list of available commands including your custom ones bynes by

/control/manual [directory]/control/manual [directory]

�� Plane text format to standard outputPlane text format to standard output

/control//control/ createHTMLcreateHTML [directory][directory]

�� HTML file(s)HTML file(s)

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

UI CommandUI Command 88

G4UIterminalG4UIterminal�� G4UIterminal is a concrete implementation derived from G4UIsessiG4UIterminal is a concrete implementation derived from G4UIsession on

abstract class. It provides characterabstract class. It provides character--base interactive terminal base interactive terminal functionality to issue Geant4 UI commands.functionality to issue Geant4 UI commands.

�� CC--shell or TCshell or TC--shell (Linux only)shell (Linux only)new G4UIterminal(new new G4UIterminal(new G4UItcshG4UItcsh ););

�� It supports some UnixIt supports some Unix--like commands for directory.like commands for directory.�� cdcd , , pwdpwd -- change and display current command directorychange and display current command directory

�� By setting the current command directory, you may omit (part of)By setting the current command directory, you may omit (part of)directory string.directory string.

�� lsls -- list available UI commands and sublist available UI commands and sub--directoriesdirectories

�� It also supports some other commands.It also supports some other commands.

�� historyhistory -- show previous commandsshow previous commands

�� !! historyIDhistoryID -- rere--issue previous commandissue previous command

�� arrow keys (TCarrow keys (TC--shell only)shell only)�� ??UIcommandUIcommand -- show current valueshow current value

�� helphelp [[UIcommandUIcommand]] -- helphelp

�� exitexit -- job terminationjob termination

�� Above commands are interpreted in G4UIterminal and are not passeAbove commands are interpreted in G4UIterminal and are not passed to d to

Geant4 kernel. You cannot use them in a macro file.Geant4 kernel. You cannot use them in a macro file.

UI CommandUI Command 99

AliasAlias�� Alias can be defined byAlias can be defined by

/control/alias/control/alias [name] [value][name] [value]

�� It is also set with It is also set with /control/loop/control/loop and and /control//control/ foreachforeach commandscommands

�� Aliased value is always treated as a string even if it contains Aliased value is always treated as a string even if it contains only numbers.only numbers.

�� Alias is to be used with other UI command.Alias is to be used with other UI command.

�� Use curly brackets, Use curly brackets, {{ and and }}..

�� For example, frequently used lengthy command can be shortened byFor example, frequently used lengthy command can be shortened by

aliasing.aliasing.

/control/alias trv1 /control/alias trv1 "" /tracking/verbose 1/tracking/verbose 1 ""

{trv1}{trv1}

�� Aliases can be used recursively.Aliases can be used recursively.

/control/alias file1 //control/alias file1 / diskA/dirX/fileXX.datdiskA/dirX/fileXX.dat

/control/alias file2 //control/alias file2 / diskB/dirY/fileYY.datdiskB/dirY/fileYY.dat

/control/alias run 1/control/alias run 1

// myCmd/getFilemyCmd/getFile {{ file{runfile{run }}}}

UI CommandUI Command 1010

LoopLoop� /control/loop and /control/foreach commands execute a macro file

more than once. Aliased variable name can be used inside the macro file.

� /control/loop [ macroFile] [ counterName]

[ initialValue] [ finalValue] [ stepSize]

� counterName is aliased to the number as a loop counter

� /control/foreach [ macroFile] [ counterName] [ valueList]

� counterName is aliased to a value in valueList

� valueList must be enclosed by double quotes (" ")

� on UI terminal or other macro file

/control/loop myRun.mac Ekin 10. 20. 2.

� in myRun.mac

/control/foreach mySingleRun.mac pname “proton pi+ mu+”

� in mySingleRun.mac

/gun/particle {pname}

/gun/energy {Ekin} GeV

/run/beamOn 100

UI CommandUI Command 1111

Mechanism of UI commandMechanism of UI command

(G)UI

G4UImanager

messenger

(G4UImessenger)

command

(G4UIcommand)

G4UIparameter

Target class

1. register

command2. apply

3. do it

4. invoke

Object shown in green must be instantiated by the user

Class shown in blue must be implemented and instantiated by the user

UI CommandUI Command 1212

Messenger classMessenger class�� Each messenger class must be derived from Each messenger class must be derived from G4UImessengerG4UImessenger base class. A base class. A

messenger class can handle more than one UI commands.messenger class can handle more than one UI commands.

�� 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 deletedshould be deleted by the by the

destructor of the target class.destructor of the target class.

�� Methods of messenger classMethods of 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 (G4UIcommand* command,G4String newValuenewValue))

�� Convert "Convert "newValuenewValue" parameter string to appropriate " parameter string to appropriate value(svalue(s) and ) and

invoke a method of the target classinvoke 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 to a getAccess to a get--method of the target class and convert the current method of the target class and convert the current

values to a stringvalues to a string

�� This method is invoked when the current This method is invoked when the current value(svalue(s) of ) of parameter(sparameter(s) of a ) of a

command is asked by (G)UI.command is asked by (G)UI.

UI CommandUI Command 1313

Definition (instantiation) of a commandDefinition (instantiation) of a command�� To be implemented in the constructor of a messenger class.To be implemented in the constructor of a messenger class.

A01DetectorConstMessenger::A01DetectorConstMessenge rA01DetectorConstMessenger::A01DetectorConstMessenge r(A01DetectorConstruction* (A01DetectorConstruction* tgttgt )):: target(tgttarget(tgt )){{

mydetDirmydetDir = new = new G4UIdirectoryG4UIdirectory ("(" /mydet//mydet/ ");");mydetDirmydetDir -- >>SetGuidanceSetGuidance ("A01 detector setup commands.");("A01 detector setup commands.");

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

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

}}

�� Guidance can (should) be more than one lines. The first line is Guidance can (should) be more than one lines. The first line is utilized utilized as a short description of the command.as a short description of the command.

UI CommandUI Command 1414

G4UIcommand and its derivativesG4UIcommand and its derivatives�� G4UIcommandG4UIcommand is a class which represent a UI command. G4UIparameter is a class which represent a UI command. G4UIparameter

represents a parameter.represents a parameter.

�� G4UIcommand can be directly used for a UI command. Geant4 providG4UIcommand can be directly used for a UI command. Geant4 provides its es its

derivatives according to the types of associated parameters.derivatives according to the types of associated parameters.

�� G4UIcmdWithoutParameterG4UIcmdWithoutParameter

�� G4UIcmdWithAStringG4UIcmdWithAString

�� G4UIcmdWithABool G4UIcmdWithABool

�� G4UIcmdWithAnIntegerG4UIcmdWithAnInteger

�� G4UIcmdWithADouble, G4UIcmdWithADoubleAndUnit G4UIcmdWithADouble, G4UIcmdWithADoubleAndUnit

�� G4UIcmdWith3Vector, G4UIcmdWith3VectorAndUnitG4UIcmdWith3Vector, G4UIcmdWith3VectorAndUnit

�� G4UIdirectoryG4UIdirectory

�� A UI command with other type of parameters must be defined by A UI command with other type of parameters must be defined by

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

UI CommandUI Command 1515

Parameter Parameter name(sname(s))void void SetParameterNameSetParameterName ((

const char*const char* parNameparName, ,

G4bool G4bool omittableomittable , ,

G4bool G4bool currentAsDefaultcurrentAsDefault =false); =false);

void void SetParameterNameSetParameterName ((

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

G4bool G4bool omittableomittable , ,

G4bool G4bool currentAsDefaultcurrentAsDefault =false);=false);

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

�� If "If "omittableomittable" is true, the command can be issued without this particular " 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 "If "currentAsDefalultcurrentAsDefalult" is true, current value of the parameter is used as a default " is true, current value of the parameter is used as a default

value, otherwise default value must be defined with value, otherwise default value must be defined with SetDefaultValueSetDefaultValue() method.() method.

UI CommandUI Command 1616

Range, unit and candidatesRange, unit and candidatesvoid void SetRangeSetRange (const(const char* char* rangeStringrangeString ))

�� Available for a command with numericAvailable for a command with numeric--type parameters.type parameters.

�� Range of Range of parameter(sparameter(s) must be given in C++ syntax.) must be given in C++ syntax.

aCmdaCmd-- >>SetRange("xSetRange("x >0. && y>z && z>(>0. && y>z && z>( x+yx+y )");)");

�� Not only comparison with hardNot only comparison with hard--coded number but also comparison between coded number but also comparison between

variables and simple calculation are available.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(const char* char* defUnitdefUnit ))

�� 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 dimOnce the default unit is defined, no other unit of different dimension will be ension will be

accepted.accepted.

�� Alternatively, you can define a dimension (unit category) withouAlternatively, you can define a dimension (unit category) without setting a t setting a

default unit.default unit.

void void SetUnitCategorySetUnitCategory (const(const char* char* unitCategoryunitCategory ))

void void SetCandidatesSetCandidates (const(const char* char* candidateListcandidateList ))

�� 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.

UI CommandUI Command 1717

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

UI CommandUI Command 1818

Converting between string and valuesConverting between string and values�� Derivatives of G4UIcommand with numeric and Derivatives of G4UIcommand with numeric and booleanboolean parameters have parameters have

corresponding conversion methods.corresponding conversion methods.

�� From a string to valueFrom a string to value

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

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

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

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

�� To be used inTo be used in SetNewValueSetNewValue() 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 G4String ConvertToStringConvertToString (...)(...)

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

�� To be used inTo be used in GetCurrentValueGetCurrentValue() method in messenger.() method in messenger.

UI CommandUI Command 1919

SetNewValueSetNewValue and and GetCurrentValueGetCurrentValuevoid A01DetectorConstMessengervoid A01DetectorConstMessenger

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

{{

if( command==if( command== armCmdarmCmd ))

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

}}

G4String A01DetectorConstMessengerG4String A01DetectorConstMessenger

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

{{

G4String G4String cvcv ;;

if( command==if( command== armCmdarmCmd ))

{ { cvcv = = armCmdarmCmd-- >>ConvertToStringConvertToString (target(target -- >>GetArmAngle(),"degGetArmAngle(),"deg "); }"); }

return return cvcv ; ;

}}

�� G4ParticleGunMessenger is a good example of implementing a messeG4ParticleGunMessenger is a good example of implementing a messenger and nger and

defining various types of commands.defining various types of commands.