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 across categories without being annoyed by dependencies among categories. Geant4 commands can be used in an interactive session, a batch mode with a macro file, or a direct C++ call.

User Interfaces to drive the simulation¶

Geant4 can be controlled by a series of Geant4 UI commands. The “intercoms” category provides the abstract class G4UIsession that processes interactive commands. The concrete implementations of (graphical) user interface are provided in the “interfaces” category. The strategy realize to adopt various user interface tools, and allows Geant4 to utilize the state-of-the-art GUI tools such as Motif, Qt, and Java etc. The following interfaces is currently available;

Command-line terminal (dumb terminal and tcsh-like terminal)
Xm, Qt, Win32, variations of the above terminal by using a Motif, Qt, Windows widgets
GAG, a fully graphical user interface and its network extension GainServer of the client/server type.

Implementation of the user sessions (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.

A Short Description of Available Interfaces¶

`G4UIterminal`¶

This interface opens a session on a command-line terminal. G4UIterminal runs on all supported platforms. There are two kinds of shells, G4UIcsh and G4UItcsh. G4UItcsh supports tcsh-like readline features (cursor and command completion) and works on Linux on Mac, while G4UIcsh is a plain standard input (cin) shell that works on all platforms. 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 Linux and Mac. 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`, `G4UIQt` and `G4UIWin32` classes¶

These interfaces are versions of G4UIterminal implemented over libraries Motif, Qt and WIN32 respectively. G4UIXm uses the Motif XmCommand 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. G4UIQt run everywhere with Qt. G4UIWin32 runs on Windows.

`G4UIGAG` and `G4UIGainServer` classes¶

They are front-end classes of Geant4 which make connections 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 has capability to connect to multiple Geant4 “servers” on Unixen systems at different hosts.

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 is supplied in the Geant4 source distribution and can be run by a command:

%java -jar  /path/to/geant4.10.00/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.

How to Select Interface in Your Applications¶

To choose an interface (G4UIxxx where xxx = terminal,Xm, Win32, Qt, GAG, GainServer) in your programs, there are two ways.

Calling G4UIxxx directly:
```
#include "G4Uixxx.hh"

G4UIsession* session = new G4UIxxx;
session-> SessionStart();

delete session;
```
Note

For using a tcsh session, G4UIterminal is instantiated like:
```
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 This is more convenient way for choosing a session type, that can select a session at run-time according to a rule described below.
```
#include "G4UIExecutive.hh"

G4UIExecutive* ui = new G4UIExecutive(argc, argv);
ui->SessionStart();

delete ui;
```

G4UIExecutive has several ways to choose a session type. A session is selected in the following rule. Note that session types are identified by a case-insensitive characters (“qt”, “xm”, “win32”, “gag”, “tcsh”, “csh”).

Check the argument of the constructor of G4UIExecutive. You can specify a session like new G4UIExecutive(argc, argv, "qt");
Check environment variables, G4UI_USE_XX (XX= QT, XM, WIN32, GAG, TCSH). Select a session if the corresponding environment variable is defined. Variables are checked in the order of QT, XM, WIN32, GAG, TCSH if multiple variables are set.
Check ~/.g4session . You can specify the default session type and a session type by each application in that file. The below shows a sample of .g4session.
tcsh # default session exampleN03 Qt # (application name / session type) myapp tcsh hoge csh
Guess the best session type according to build session libraries. The order of the selection is Qt, tcsh, Xm.

In any cases, G4UIExecutive checks if a specified session is build or not. If not, it goes the next step. A terminal session with csh is the fallback session. If none of specified session is available, then it will be selected.