Overview Contents Previous Next Geant4 User's Guide
For Application Developers
Getting Started with Geant4

2.8 How to Set Up an Interactive Session

2.8.1 Introduction

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;
  1. Character terminal (dumb terminal and tcsh(bash)-like terminal), the default user      interface of Geant4,
  2. Xm, Xaw, Win32, variations of the upper terminal by using a Motif, Athena or Windows widget to retrieve commands, and
  3. 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 directory.
           GAG, GainServer's client GUI Gain 

2.8.2 A Short Description of Available Interface Classes

1. G4UIterminal and G4UItcsh classes

 These 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] cursor)
                ^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
  In addition, the following string substitutions are supported;
                 %s          current application status
                 %/          current working directory
                 %h          history number

2. G4UIXm, G4UIXaw and G4UIWin32 classes

  These interfaces 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 WIN32 one.
  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 method.
            /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. G4UIWin32 runs on Windows.

3. G4UIGAG 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.

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;
 For a tcsh session, the second line must be :
           G4UIsession* 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.

About the authors