How to Set Up an Interactive Session
Introduction
Roles of the "intercoms" category
The "intercoms" category provides an expandable command interpreter.
It is the key mechanism of Geant4 to realize secure user interactions
in all categories without being annoyed by the dependencies among categories.
The Geant4 commands can be used both in a interactive terminal session and
in a batch mode with a maco file or a direct C++ call.
User Interfaces to steer the simulation
Geant4 can be controllled by a seriese of Geant4 UI commands.
The "intercoms" category provides the abstract class
G4UIsession that processes interactive commands.
The concrete implementation of (graphical) user interfaceis is located
in the "interfaces" category. This interfacing strategy opens an
important door towards various user interface tools,
and allows Geant4 to utilize the state-of-the-art GUI tools
such as Motif, Qt, and Java etc.
The richness of the collaboration realizes
various user interfaces to the Geant4 command system.
The following interfaces is currently available;
Character terminal (dumb terminal and tcsh-like terminal),
that is the default user interface of Geant4
Xm, Xaw, Win32, Qt variations of the above terminal by using a
Motif, Athena, Qt or Windows widget
GAG, a fully graphical user interface and its network extension
GainServer of the client/server type.
Implementation of the user sesssions (1 and 2) is included
in the source/interfaces/basic directory.
As for GAG, the front-end class is included
in the source/interfaces/GAG directory,
while its partner GUI package MOMO.jar is available
under the environments/MOMO directory.
MOMO.jar, Java archive file, contains
not only GAG, but also GGE and other helper packages.
Supplementary information is available
from the author's web page (see URL below).
GAG, GainServer's client GUI Gain:
http://www-geant4.kek.jp/~yoshidah
A Short Description of Available Interface Classes
G4UIterminal and G4UItcsh classes
These interfaces open a session on the character terminal.
G4UIterminal runs on all platforms supported by Geant4,
including cygwin on Windows.
The following built-in commands are available in
G4UIterminal;
cd, pwd
change, display the current command directory.
ls, lc
list commands and subdirectories in the current directory.
history
show previous commands.
!historyID
reissue previous command.
?command
show current parameter values of the command.
help command
show command help.
exit
terminate the session.
G4UItcsh supports user-friendly key bindings a-la-tcsh.
G4UItcsh runs on Solaris and Linux.
The following keybindings are supported;
^A
move cursor to the top
^B
backward cursor ([LEFT] cursor)
^C (except Windows terminal)
abort a run (soft abort) during event processing.
A program will be terminated while accepting a user command.
^D
delete/exit/show matched list
^E
move cursor to the end
^F
forward cursor ([RIGHT] cursor)
^K
clear after the cursor
^N
next command ([DOWN] cursor)
^P
previous command ([UP] cursor)
TAB
command completion
DEL
backspace
BS
backspace
The example below shows how to set a user's prompt.
G4UItcsh* tcsh = new G4UItcsh();
tcsh-> SetPrompt("%s>");
The following strings are supported as substitutions in a prompt string.
%s
current application status
%/
current working directory
%h
history number
Command history in a user's session is saved
in a file $(HOME)/.g4_hist
that is automatically read at the next session,
so that command history is available across sessions.
G4UIXm, G4UIXaw, G4UIQt and
G4UIWin32 classes
These interfaces are versions of G4UIterminal
implemented over libraries Motif, Athena, Qt and WIN32 respectively.
G4UIXm uses the Motif XmCommand widget,
G4UIXaw the Athena dialog
widget, G4UIQt the Qt dialog widget,
and G4UIWin32 the Windows "edit" component to do the
command capturing. These interfaces are useful if working in
conjunction with visualization drivers that use the Xt library, Qt library or
the WIN32 one.
A command box is at disposal for entering or recalling Geant4 commands.
Command completion by typing "TAB" key is
available in the command box. The shell commands "exit, cont,
help, ls, cd..." are also supported. A menu bar can be customized
through the AddMenu and
AddButton method. Ex:
/gui/addMenu
test Test
/gui/addButton
test Init /run/initialize
/gui/addButton
test "Set gun" "/control/execute gun.g4m"
/gui/addButton
test "Run one event" "/run/beamOn 1"
G4UIXm runs on Unix/Linux with Motif. G4UIXaw,
less user friendly, runs on Unix with Athena widgets. G4UIQt run
everywhere with Qt.
G4UIWin32 runs on Windows.
G4UIGAG and G4UIGainServer classes
They are the front-end classes of Geant4 which make connection with their
respective graphical user interfaces, GAG (Geant4 Adaptive GUI) via pipe, and Gain
(Geant4 adaptive interface for network) via sockets. While GAG must run on the same
system (Windows or Unixen) as a Geant4 application, Gain can run on a
remote system (Windows, Linux, etc.) in which JRE (Java Runtime
Environment) is installed. A Geant4 application is invoked on a Unix
(Linux) system and behaves as a network server. It opens a port,
waiting the connection from the Gain. Gain is capable to connect to
multiple Geant4 "servers" on Unixen systems at different
institutes.
Client GUIs, GAG and Gain have almost similar look-and-feel. So,
GAG's functionalities are briefly explained here.
Please refer to the URL previously mentioned for details.
Using GAG, user
can select a command, set its parameters and execute it. It is adaptive, in the sense that it
reflects the internal states of Geant4 that is a state machine. So, GAG always provides users with
the Geant4 commands which may be added, deleted, enabled or disabled during a session. GAG does nothing by itself but to play an intermediate between user and
an executable simulation program via pipes. Geant4's
front-end class G4UIGAG must be instantiated to
communicate with GAG. GAG runs on Linux and Windows. MOMO.jar can be run by a command;
%java -jar $G4INSTALL/environments/MOMO/MOMO.jar
GAG has following functions.
GAG Menu:
The menus are to choose and run a Geant4 executable file, to kill or exit
a Geant4 process and to exit GAG. Upon the normal exit or an
unexpected death of the Geant4 process, GAG window are
automatically reset to run another Geant4 executable.
Geant4 Command tree:
Upon the establishment of the pipe connection with the Geant4 process, GAG displays
the command menu, using expandable tree browser whose look and feel is similar to
a file browser. Disabled commands are shown in opaque. GAG
doesn't display commands that are just below the root of
the command hierarchy. Direct type-in field is available for such
input. Guidance of command categories and commands are displayed
upon focusing. GAG has a command history function. User can
re-execute a command with old parameters, edit the history, or save
the history to create a macro file.
Command Parameter panel:
GAG's parameter panel is the user-friendliest part. It displays parameter
name, its guidance, its type(s) (integer, double, Boolean or string),
omittable, default value(s), expression(s) of its range and candidate list(s)
(for example, of units). Range check is done by intercoms and
the error message from it is shown in the pop-up dialog box. When a
parameter component has a candidate list, a list box is
automatically displayed . When a file is requested by a command,
the file chooser is available.
Logging:
Log can be redirected to the terminal (xterm or cygwin
window) from which GAG is invoked. It can be interrupted as will,
in the middle of a long session of execution. Log can be saved to a
file independent of the above redirection . GAG displays warning or
error messages from Geant4 in a pop-up warning widget.
Building the Interface Libraries
The libraries that do not depend on external packages are created by default,
using Geant4 configure scripts.
They include G4UIterminal, G4UItcsh
and G4UIGAG in libraries libG4UIbasic.a/so and
libG4UIGAG.a/so. G4UIGainServer.o is packed in
the libG4UIGAG.
To make the libraries of G4UIXm, G4UIXaw,
G4UIQt and
G4UIWin32 , respective environment variables
G4UI_BUILD_XM_SESSION,
G4UI_BUILD_XAW_SESSION,
G4UI_BUILD_QT_SESSION and
G4UI_BUILD_WIN32_SESSION must be set
explicitly before creating libraries.
If the environment variable G4UI_NONE is
set, no interface libraries are built at all.
The scheme of building the user interface libraries is
specified in "$G4INSTALL/config/G4UI_BUILD.gmk" makefile and the
dependencies on the external packages are specified in
"$G4INSTALL/config/interactivity.gmk".
How to Use the Interface in Your Application
To use a given interface
(G4UIxxx where xxx = terminal,Xm, Xaw, Win32, Qt,
GAG, GainServer) in your program, there are two ways.
Calling G4UIxxx directly :
#include "G4Uixxx.hh"
// to instantiate a session of your choice and start the session
G4UIsession* session = new G4UIxxx;
session->SessionStart();
// the line next to the "SessionStart" is necessary to finish the session
delete session;
If you want to select a session type according to your environment variable,
the code can be:
// to include the class definition in the main program:
#if defined(G4UI_USE_TCSH)
#include "G4UIterminal.hh"
#include "G4UItcsh.hh"
#elif defined(G4UI_USE_XM)
#include "G4UIXm.hh"
....
#endif
#if defined(G4UI_USE_TCSH)
session = new G4UITerminal(new G4UItcsh);
#elif defined(G4UI_USE_XM)
session = new G4UIXm(argc,argv);
#elif ...
Note : For a tcsh session, the second line must be
G4UIsession* session = new G4UIterminal(new G4UItcsh);
If the user wants to deactivate the default signal handler (soft abort)
raised by "Ctr-C", the false flag can be set in the second argument
of the G4UIterminal constructor like;
G4UIsession* session = new G4UIterminal(new G4UItcsh, false).
Using G4UIExecutive
(implemented in all novice examples) :
The above code is rather troublesome.
This is more convenient way for choosing a session type.
// to include the class definition in the main program:
#ifdef G4UI_USE
#include "G4UIExecutive.hh"
#endif
// to instantiate a session of your choice and start the session
#ifdef G4UI_USE
G4UIExecutive* ui = new G4UIExecutive(argc,argv);
ui->SessionStart();
// the line next to the "SessionStart" is necessary to finish the session
delete ui;
#endif
A corresponding environment variable must be preset
to select a given interface.
But some of them are set by defaults for your convenience.
G4UIterminal, G4UItcsh,
G4UIGAG and G4UIGainServer
can be used without setting any environment
variables. Sessions not needing external packages or libraries are
always built (see "G4UI_BUILD.gmk") and linked, so the user can
instantiate one of these sessions without rebuilding the libraries
and without setting any environment variables.
The environment variable G4UI_USE_XM,
G4UI_USE_QT, G4UI_USE_XAW or
G4UI_USE_WIN32 must be set to use the
respective interface. The file "$G4INSTALL/config/G4UI_USE.gmk"
resolves their dependencies on external packages.
If the environment variable G4UI_NONE is
set, no external libraries are selected. Also, for your convenience, if any
G4UI_USE_XXX environment variable is set,
then the corresponding C-pre-processor flag is also set. However, if the
environment variable G4UI_NONE is set,
no C-pre-processor flags are set.