|| Geant4 User's Guide
For Application Developers
Getting Started with Geant4
2.8 How to Set Up
an Interactive Session
Roles of the "intercoms" category
The "intercoms" category provides an expandable
command interpreter. It is the key mechanism of Geant4 to realize user interactions
of all categories without being annoyed by the dependencies among categories.
The direct use of Geant4 classes in a C++ program offers a first ground level
of interactivity, i.e., the batch session. As seen in the examples/novice/N01,
Geant4 commands and macros are to be hard-coded in the program.
User Interfaces to steer the simulation
To avoid too much programming, the "intercoms"
category provides the abstract class G4UIsession
that captures interactive
commands . The concrete implementation of the user interface and Graphical
User Interfaces (GUI) is left to 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 and
Java, etc..The richness of the collaboration has permitted for different groups
to offer various user interfaces to the Geant4 command system. Currently available
are the following;
- Character terminal (dumb terminal and tcsh(bash)-like terminal), the
default user interface of Geant4,
- Xm, Xaw, Win32, variations of the upper terminal by using a Motif,
Athena or Windows widget to retrieve commands, and
- GAG, a fully Graphical User Interface and its extension GainServer
of the client/server type.
Full implementation of the character terminals (1 and
2) is included in the standard Geant4 distribution in the source/interfaces/basic
directory. As for GAG with rich GUI functionalities,
its front-end classes are included in the Geant4 distribution in the source/interfaces/GAG
directory. The corresponding GUI package is available either from the author's
Web pages (see URL below) or in the distributed package under the environments/MOMO
2.8.2 A Short Description of Available Interface Classes
and G4UItcsh classes
interfaces open a session on the character terminal. G4UIterminal runs
on all platform supported by Geant4, including cygwin on Windows, while
G4UItcsh runs on Solaris and Linux. G4UItcsh supports user-friendly
key bindings a-la-tcsh (or bash);
^A move cursor to the top
^B backward cursor ([LEFT]
^D delete/exit/show matched list
^E move cursor to the end
cursor ([RIGHT] cursor)
^K clear after the cursor
^N next command ([DOWN] cursor)
^P previous command
TAB command completion
In addition, the following string substitutions
%s current application status
%/ current working directory
%h history number
G4UIXaw and G4UIWin32 classes
are versions of G4UIterminal implemented over libraries Motif, Athena
and WIN32 respectively. G4UIXm uses the Motif XmCommand widget,
G4UIXaw the Athena 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 or the
A command box is
at disposal for entering or recalling Geant4 commands. Command completion
by typing “TAB” key is available on the command line.
The shellcommands "exit, cont, help, ls, cd..." are also supported.
A menu bar could be customized through the AddMenu and AddButton
/gui/addMenu test Test
/gui/addButton test Init /run/initialize
/gui/addButton test "Set gun"
/gui/addButton test "Run one
event" "/run/beamOn 1"
on Unix/Linux with Motif. G4UIXaw, less user friendly, runs on Unix
with Athena widgets. G4UIWin32 runs on Windows.
and G4UIGainServer classes
They are the front-end
classes of Geant4 which interface with their respective
graphical user interfaces, GAG (Geant4 Adaptive GUI) and Gain (Geant4 adaptive
interface for network). 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.) to which JVM (Java Virtual Machine) 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 GUI, GAG and Gain have almost similar look-and-feel. So, GAG's functionalities
are briefly introduced here. Please refer to the above URL for details and
to download the client GUIs.
GAG is a Graphical User Interface tool with which user can set
parameters and execute commands. It is adaptive, since GAG reflects the internal
states of Geant4 that is a state machine. GAG is based on the server-client
model; GAG is the server, while Geant4 executables are clients. Hence, GAG
does nothing by itself and it must invoke an executable simulation program.
Geant4's front-end class G4UIGAG must be instantiated to communicate
with GAG. This runs on Linux and Windows 2000.
GAG is written in Java and its Jar
(Java Archive) file is available from the above URL. See the same pages to
know how to install and run Java programs.
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 accept another GEANT4 executable.
- GEANT4 Command tree: Upon the
establishment of the pipe with the GEANT4 process, GAG displays the command
menu tree whose look and feel is quite similar to Windows' file browser.
Disabled commands are shown 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 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.
2.8.3 Building the Interface Libraries
The libraries that don't depend on external packages are made
by default. 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 and G4UIWin32
, respective environment variables G4UI_BUILD_XM_SESSION , G4UI_BUILD_XAW_SESSION
or G4UI_BUILD_WIN32_SESSION must be set explicitly.
However, if the environment variable G4UI_NONE is set, no
interface libraries are built at all.
Build scheme of 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".
2.8.4 How to Use the Interface
To use a given interface (G4UIxxx where
xxx = terminal,Xm, Xaw, Win32, GAG, GainServer) in a user's program,
he has the following lines in his main program;
// to include the class definition in his main program:
// to instantiate a session of his choice and start the session
session = new G4UIxxx;
/ /the line next to the "SessionStart" is usually to finish the session
For a tcsh session,
the second line must be :
session = new G4UIterminal(new G4UItcsh);
See the examples in "examples/novice/N0x"
in which the terminal session is used.
Again, environment variable selects a given interface. But for your convenience,
some of them are set defaults.
G4UIterminal, G4UItcsh, G4UIGAG and G4UIGainServer
can be used without 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. For backwards compatibility
with user code, as typified by geant4/examples main programs, the C-pre-processor
variables corresponding to the original environment variables for the above
three (i.e., G4UI_USE_TERMINAL, G4UI_USE_TCSH and G4UI_USE_GAG
) are set. However, if he/she sets no environment variables, then the C-pre-processor
variable G4UI_USE_TERMINAL is set by default, although there is no
need to use it.
The environment variable G4UI_USE_XM, G4UI_USE_XAW or G4UI_USE_WIN32
must be set to use the respective interface. The file
"$G4INSTALL/config/interactivity.gmk" resolves their dependencies on external
If the environment variable G4UI_NONE is set, no externa ibraries
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.