How to use the GainServer interface class and Gain client GUI
version 0.9, May 31 2002
revised for Geant4.4.1 release, July 03
revised 17 January 2003
H. Yoshida, H. Minamimoto
Naruto University of Education
A) Features of GainServer class and its client partner "Gain"
This new class belongs to the "interfaces" category and provides
a user interface using socket connection with a remote client GUI Gain.
The new client Gain is quite similar with GAG in that it provides the
fully graphical user interface to steer execution of the Geant4 simulation.
The new features using a socket connection are as follows;
1) GainServer uses TCP/IP socket to communicate with the
client GUI tool Gain.
In general, a server may be decoupled from the terminal
(or the control terminal) on which it was invoked and run
as a daemon (daemon mode).
The present Gain server class doesn't behave as a daemon, but
it requires the control terminal on which the Geant4 application
has been invoked and is coupled as long as
it is running (terminal mode).
In the terminal mode, all outputs from G4cout and G4cerr are
sent to the client by default and can be displayed
on the client remote terminal.
If you want to run Geant4 simulation even after having logged out,
the shell command "nohup" can be used (Linux and Solaris).
You have to run a Geant4 application like;
%nohup $G4WORKDIR/exampleN02 > exampleN02 &
and then log out.
%exit
2) The partner client GUI software is "Gain" which runs
on any platform running Java Virtual Machine, i.e.,
Windows, Linux etc.. Gain can be invoked from the
command line (pseudo-terminal in the X windows or
cygwin in Windows) or newly can be invoked directly from
the Web browser like Netscape/Mozilla and Internet Explorer,
when they are equipped with the plugin software "Java Web Start".
This new facility will be explained in the later sections.
B) Making the library
G4UIGainServer is a part of Geant4 distribution since Grant-4.4 or Geant-5.0.
GainServer class uses the standard socket implementation which is
usually found in the platforms like Solaris or Linux. It is tested against
G4SYSTEM=SUN-CC and Linux-g++ and WIN32-g++(Cygwin).
This new class depends on no external libraries (except the default system
libraries) so that no new environment variables G4UI_BUILD_XX is required.
GainServer.cc/hh files are located in source/interfaces/GAG and the
corresponding library is archived in the libG4UIGAG.a(so).
It is simple to make the library.
1. go to the directory "interfaces/GAG".
2. make (or gmake)
3. and you will have a libG4UIGAG.a (so)
C) How to use GainServer in your application
The way how to use it completely similar to G4UIterminal or G4UIGAG class.
In your main program
1. include the header file
#include "G4UIGainServer.hh"
2. instantiate the session and run
G4UIsession* session = new G4UIGainServer();
session->SessionStart();
delete session;
Your application can be compiled just like the ones using G4UIterminal
or G4UIGAG interface classes. No new environment variables are required
to use this new class.
D) How to get and run the Gain client
GainServer must communicate with its partner GUI Gain. Gain is
written in Java and Gain is distributed in two compiled forms.
In any forms, you have to install Java, i.e., j2sdk.
(See www.javasoft.com)
1. command line mode
One form is the common jar (Java archive) format; Gain.jar which
is provided at http://erpc1.naruto-u.ac.jp/~geant4/Sources.html.
To run it, you have to invoke Java Virtual Machine on your terminal;
% java -cp foobar/Gain.jar Gain
where foobar is the directory containing Gain.jar file.
On Windowz, use cygwin for the terminal.
2. Web Start mode
Another form is easier to use, once all set-up steps have been
completed. In this mode, Gain can be invoked by a simple mouse click
on the link in the Web page, which is provided by the Geant4
developer.
1. You connect to the Java site and install "Web Start" in your
PC, following the instructions. If you are using Mozilla/Netscape,
you have to add a new MIME type (JNLP) to your list of "Helper
programs".
2. Try if the examples associated with the Java Web Start kit
run correctly. Note that applications which
requires file I/O on your system asks you to go out of the
"sandbox" environment (three times on Windows).
This execution of Java applications including local I/O operation
is only allowed by your permission. To get your permission,
demos provided by Java Soft are digitally signed.
3. Then connect to http://erpc1.naruto-u.ac.jp/~geant4/Sources.html
and run Gain. It is digitally signed by the Geant4 developer
at Naruto University of Education.
On Windows, you may have the icon for "Java Web Start Manager" in which
Gain will be listed as one of the verified applications. Then, you can
use Gain directly from Java Web Start without the Internet connection.
The Manager also provides a focility to log the output from the
application. It will be helpful to see runtime warnings or error
messages as well as to see the G4cout of the Geant4 application.
E) What you can do with Gain
Gain has a graphical interface quite similar to that of GAG.
In addition, it provides a function to connect pluriel remote GainServers
simultaneously. Each connection has an independent GUI window in Gain
so that you can run several Geant4 applications on different remote sites
and run them simultaneously with the help of Gain which is running on your PC.
Gain and GainServers can run on the same host (localhost). The free ports are
allocated automatically to respective GainServer.
E) How to run GainServer ans Gain together
As stated above, the present implementation of GainServer doesn't run in the
daemon mode. So, you have to keep your terminal session as long as your
application is running.
The steps are as follows;
1. login to the remote host(s) on which you are going to run your
Geant4 application(s)
2. run your application. GainServer displays the message;
"GainServer waiting at port 40000"
The port number starting from 40000 is automatically allocated to
your application(s). This port number is used to connect Gain
client to the server.
If you run another Geant4 application on the same remote machine,
another port number is automatically allocated and displayed.
3. run Gain client on your PC. The upper left menu urges you to
type in the port number and host name. Select "localhost", if
GainServer is running on your PC.
When connection is established, you will have the commands tree
and parameter window just like those of GAG.
If you connect to another Geant4 application, another tabbed pane
is created to manage that connection.
4. You can disconnect one or all connections. By this disconnection,
corresponding Geant4 applications exit using a gentle exit command
of Geant4, so that normal exitng procedures of Geant4 is performed.
F) How to use VRML viewer together with Gain (Under test)
A prototype implementation of Gain is available (2002 end July)
which incorporates Geant4's vrmlview.
You can use VRML viewer to visualize the geometry and events.
Thus, you can use and run Geant4 on your PC running Java (i.e., Windows,
Linux, Solaris, MacOSX etc.) with Gain to control the execution and
with your VRML viewer of your choice to visualize, while your simulation
is being executed on a remote compute server (maybe with bad Java support).