CERN School of Computing 2000 JAS-Geant4 Tutorial

Introduction - Starting JAS

Install JAS (see JAS). To run JAS all you need to do is to execute the command:


This will start JAS. Of course you can create a shortcut to this script in your ~/scripts directory to make it possible to start jas without remembering the whole path $JASPATH.

To check which version of Java you are using issue the command:

java -version

IBM JDK 1.1.8

The above is an older but very stable and fast implementation of Java for Linux. JAS works well with JDK 1.1.8, with the exception of printing. If you want to produce high quality printed plots from JAS you must use JDK 1.3


This is a newer version of Java but it is slightly less mature and still has a few problems. The most important problem is that it is incompatible with the FVWM2 window manager. If you wish to use JDK 1.3 you must select either gnome or KDE as your window manager. If you do not do this you will see a number of very strange effects when running JAS, such as blank or semi-blank windows, popup menus with window manager decorations, etc.

Using JAS

The official tutorial for the CSC, described below, shows only how to use JAS to view histograms created in Geant4. This makes sense since the OO Design and Implementation course covers Geant4 and JAS, however this tutorial shows only a very small fraction of the capabilities of JAS itself, and only involves writing C++ code, not Java code. If you are interested and have time I would encourage you to look at the tutorial built into JAS itself. I will be happy to help you with both this official tutorial and any other questions you may have about using JAS or Java.

Using JAS with Geant4


This tutorial shows how to use JAS to control Geant4, and to view histograms created by a Geant4 job. Before starting this tutorial you must have succeeded in starting JAS and you must have succeeded in building and running Geant4 according to the Geant4 tutorial.

For this will tutorial we will use a simple prototype of a mechanism for creating JAS histograms from C++ and for controlling a Geant4 job from JAS. The code for the Geant4-JAS interface is available here.

To set up your environment to run this tutorial, you will need to customize the scripts setup.csh (example for tcsh shell), according to your local installation paths, and then source it.

source $HOME/g4CSC2000/JASG4/setup.csh

This sets a few environment variables required for compiling and linking to the JASG4 and Java libraries. 

Before starting on the real tutorial, try running the following very simple program which will illustrate the (currently very trivial) C++ interface to JAS histograms, and make sure that everything is working as expected.

#include <jni.h>
#include <string.h>
#include <stdlib.h>
#include "JHistogram1D.hh"
#include "JHistogramFactory.hh"
int main(int argc, char** argv)
   JHistogramFactory factory;
   JHistogram1D* hist = factory.create1DHistogram("test");
   for (int i=0; i<1000; i++)
   return 0;

This test program simply creates a JHistogramFactory object, and uses it to create a one dimensional histogram, which is then filled with very boring data. The default constructor of JHistogramFactory causes it to wait for a connection from JAS rather than exiting at the end of the main routine.

Use cut and paste to paste the code above into your editor and save it in a file

Compile this routine and link it with the following command:

          gcc -I${JDK}/include/linux -I${JDK}/include -I${JASG4}
                  -L${JASG4} -L${JDK}/jre/bin/classic -lJASG4 -ljvm

This command is rather long but it simply compiles and links the test program with the JASG4 and Java libraries. 

Running the program should produce output similar to this:

Installed RMIWebServer at
Created RMI registry
Server bound in RMI registry as /JDSServer
Monitor bound in RMI registry as /JDSServer/Monitor

This indicates that the program is waiting for an RMI connection from JAS. (RMI stands for Remote Method Invocation - and is the OO network protocol supported by Java. It is similar to (and interoperable with) CORBA).

Now start JAS, and use the "Reconnect" item in the "File" menu to connect to your program. Assuming your are running JAS on the same machine as your program, you can just type localhost as the name of the machine to connect to.

In the next screen choose your job from the list (it will probably by the only entry)

Once you have connected you should be able to see an icon corresponding to your histogram in the tree on the left hand side of the JAS window (you may have to double click on items higher in the tree to find your histogram icon). Double clicking on the histogram icon (or right clicking and choosing Show from the popup menu) should display your (rather uninteresting) histogram in the window on the right hand side. You can do things such as re-bin the histogram (using the slider in the toolbar below the menu), change the axis limits, title, etc., since you have a live two-way connection to the histogram stored in your running test program.

If this worked OK you can disconnect from your program (use the File, Disconnect menu item) and then kill your test program using CTRL+C and proceed to the next part of the tutorial.

Modifying your Geant4 Example to use the JASG4 interface

Before starting this part of the exercise you must have a working version of Geant4. If you completed yesterdays exercises feel free to use your own version, otherwise you can use the solution from the Geant4 examples, by issuing the following commands:

cd $HOME/g4CSC2000/CSC

Now you should be able to modify the Geant 4 job example you previously created to use the JASG4 interface. There are several steps involved, each of which is described in more detail below.

  1. Copy the routines, which define the G4UIJAS class into your Geant4 source tree. Theses routines define a Geant4 SessionManager which allows JAS to control Geant4
  2. Modify your main routine to create a JHistogramFactory object, as in the test program above.
  3. Modify your main routine to pass a pointer to the created JHistogramFactory to the constructor of your EventAction class.
  4. In your EventAction class use the pointer to the JHistogramFactory to create any histograms you wish to fill.
  5. Modify your EventAction to fill the histograms in the appropriate place.
  6. Modify your main routine to create a G4UIJAS session manager instead of the default terminal manager.
  7. Run the program and connect to it using JAS as you did in the test case above.

Step 1 - Copy the routines, which define the G4UIJAS class

Simply issue the following commands to copy the predefined G4UIJAS class into your Geant4 source tree.

cp $JASG4/ src
cp $JASG4/G4UIJAS.hh include

The G4UIJAS class defines a Geant4 SessionManager, which allows Geant4 to be controlled by JAS.

Step 2 - Modify your main routine to create a JHistogramFactory object

You will need to create your JHistogramFactory object, as in the test case above. You will need to create it above where you create you EventAction class, since you will need to pass a pointer to the JHistogramFactory to your EventAction class.

Step 3 - Pass the pointer to your JHistogramFactory to the constructor of your EventAction class.

You will of course also need to modify the constructor of your EventAction class to accept the pointer.

Step 4 - In your EventAction class use the pointer to the JHistogramFactory passed to the constructor to create any histograms you wish to fill.

Your EventAction routine now gets passed a pointer to the JHistogramFactory, so you can use that to create new histograms. Use the create1DHistogram method as in the test program above. Since you will need the pointers to your histograms in other methods of your EventAction class you will need to store them in member variables of the EventAction class. Sensible things to histogram would include the number of hits in each tracking chamber, and the energy deposited in the calorimeter.

Step 5 - Modify your EventAction to fill the histograms.

In the EndOfEventAction method of your EventAction class, fill the histograms you created in Step 3, using the fill method of JHistogram1D.

Step 6 - Create a G4UIJAS session manager

In order for JAS to be able to control Geant4, you must use the G4UIJAS session manager instead of the normal G4UIterminal. To do this replace the old session manager in your main routine with the G4UIJAS session manager. You must pass a pointer to the JHistogramFactory you created earlier to the G4UIJAS constructor. A possible example of how to do this is:

//G4UIterminal session manager no longer used
//G4UIsession* session = new G4UIterminal(new G4UItcsh);
// Create a G4UIJAS session -- this allows JAS to control G4
G4UIsession* session = new G4UIJAS(&factory);
delete session;

Step 7 - Link your program

You are nearly done, the last thing to do is to compile and link your modified programs. Add the following lines to your makefile, before the line that includes binmake.gmk

CPPFLAGS += -I$(JASG4) -I$(JDK)/include -I$(JDK)/include/linux
EXTRALIBS += -L$(JASG4) -lJASG4 -L$(JDK)/jre/bin/classic -ljvm

As with the command to build the test program this simply tells Geant4 where to find the JASG4 and Java libraries and include files.

Once you have successfully linked your program you are ready to proceed to....

Running the Modified G4 Example

Once you have succeeded in compiling and linking your modified example program, you should run the executable with no arguments (i.e. no .mac file). After initialization you should see a message:

G4UIJAS -------- Waiting for commands from JAS

This indicates the G4 is waiting for you to connect to it with JAS and send it commands. Start JAS and use the "File, Reconnect" menu to connect to your job (as you did with the Test program). 

After you have connected, choose the "Job, Load Plugin" from the menu to bring up the load plugin dialog, type in JASG4Plugin and press "OK". 

This will dynamically load the client code for controlling G4 into JAS. (If your JAS client was running on a different computer from G4, or if your jas command was issued from a command prompt where your had not set the CLASSPATH to point to the JASG4 directory, then the code will be transparently sent across the network connection from the G4 job to the jas client).

Now you should see a new item in the JAS menu bar, labeled Geant 4. There are several items in this menu:

  • Beam On - starts the G4 job running
  • Beam Off - stops the G4 job.
  • Trap Geant4 output - redirects the output which would normally appear in the G4 console window to appear in the JAS console. Useful for debugging, but if your G4 job generates a lot of output the network traffic may slow down your G4 job.
  • Show Command Window - Opens a command prompt where you can issue any Geant4 command.

Start your G4 job running by choosing the "Beam On" command. Now look at the tree on the left hand side of your JAS client (labeled G4Job). By drilling down in here you should find your histograms, and by double clicking on the Histograms you should be able to see the results. If you view histograms while G4 is running you should be able to see the histograms updating in real time.

If all went well you should get a display something like this:


The JASG4 interface described here is just a prototype at present, although as you have hopefully discovered, it is possible to use it even now. The plan is to provide full access to JAS histograms from C++ code via an interface called AIDA. (The AIDA interface is designed to allow programs to talk to several different histogram implementations without any need to change the user code). In addition we hope to be able to improve the functionality of the JAS/G4 interface so that it provides full access to the Geant4 command line interface.  It will hopefully also be possible in future to view Geant4 events from JAS and to use the Java editor/compiler built into JAS to dynamically create histograms without having to modify/recompile/link Geant4.

Tony Johnson - Last modified: Thursday, September 21, 2000