Mokka Java Common Geometry Access (CGA) API

3. The Java library

The Java CGA API is written using the Java Native Interface (JNI). Everything is handled by the CGARunManager class that has several native methods:
 

public class CGARunManager {
        public CGARunManager() {
        }

        public native void init(String steer, String model, String setup,
                                String host, String user, String passwd);
        public native void beamOn(double []start, double []end,
                double []direction, String particle, float energy,
                int nbPart);
        public native String whereAmI(double []position);
        public native void getSteps(Vector cont);
        public native void getVolumeData(String name, Vector cont);
        static {
               System.loadLibrary("CGA");
        }
}

Its static initializer loads the libCGA.so library that includes the CLHEP, GEANT4 and Mokka libraries.
 

3.1 init

This native method builds the geometry model, the one that is used by the simulation.

        public native void init(String steer, String model, String setup,
                                String host, String user, String passwd);

The parameters of this method allow access to the MySql geometry database used by the geometry model.

steer=the content of the steering file. If not present, the empty string ("") can be passed.
model=the model name in the geometry database. Required.
setup=the detector setup. Can be passed the empty string ("").
host=the host name where the geometry database is running. Can be passed as ' ' if one wants to connect to the geometry database running on aldebaran.in2p3.fr.
user=the user name for geometry database access. Can be passed as ' ' if one wants to log on the "consult" account on the geometry database running on aldebaran.in2p3.fr.
passwd=the user password for geometry database access. Can be passed as ' ' which means passing the default password for the "consult" account on the geometry database running on aldebaran.in2p3.fr.

The following example shows how one could use this method:

                CGARunManager run = new CGARunManager();

                run.init("", "D09M1", "", "", "", "");
 
 

3.2 whereAmI

This native method gives you the name of the volume that a given point (x, y, z) is situated in:

        public native String whereAmI(double []position);

The parameters of the method are as follows:

position=the x, y, z coordinates (in centimeters) of the point.

This method returns the name of the volume (GEANT 4 logical volume) that the point is situated in.

The following example shows how one could use this method and its return value:

                CGARunManager run = new CGARunManager();

                double end[]={-200*Math.sin(3.1418/8), 200*Math.cos(3.1418/8), 0};

                System.out.println(run.whereAmI(end));

3.3 Getting the information on the particle passage through the volumes

One of the items of interest in reconstruction is to know the distances, or the number of X0 (the radiation length) that a particle traveled along in the different volumes, layers, etc. In order to get this information, one has first to shoot the desired particle, using the method beamOn, and then to get the information using the method getSteps or the method getVolumeData.

3.3.1 beamOn

This native method allows one to shoot the desired particle:

        public native void beamOn(double []initial, double []final,
                double []direction, String particle, float energy,
                int nbPart);

The parameters of this function are:

initial: the coordinates (in centimeters) of the point from where the particle is shot.
final: the coordinates (in centimeters) of the final point of the particle's trajectory. If the particle is charged, it shall be killed as soon as it enters the volume (layer) that the final point is situated in.
direction: the direction that the particle is shot.
particle:  the particle's name.
energy: the particle's energy.
nbPart: the number of particles that we want to shoot.

The following example shows how one could use this function:

                double start[]={-68, 169, 0};
                double end[]={-200*Math.sin(3.1418/8), 200*Math.cos(3.1418/8),
                                0};//z = -283.5 to touch four EnvLogs
                double direction[]={end[0]-start[0], end[1]-start[1],
                                end[2]-start[2]};

                CGARunManager run = new CGARunManager();

                run.beamOn(start, end, direction, "geantino", 20, 1);

3.3.2 getSteps

One can get the information on distances, number of X0 and the entrance point in evry volume by calling the native method getSteps:

        public native void getSteps(Vector cont);

This method fills the "cont" Vector with objects of the class "Step", one for each step:

public class Step {
        public Step() {};
        public Step(String volumeName, String materialName, double dist,
                double xx, double yy, double zz, double x0, double InterLen) {
                                                                               
                volName = volumeName;
                matName = materialName;
                distance = dist; nbX0 = x0; nInterLen = InterLen;
                X = xx; Y = yy; Z = zz;
        }
                                                                               
        private String volName, matName;
        private double distance, nbX0, nInterLen;
        private double X, Y, Z;
                                                                               
        public String VolName() { return volName;}
        public String MatName() { return matName;}
        public double Distance() { return distance; }
        public double X0() { return nbX0; }
        public double InterLen() { return nInterLen; }
        public double X() { return X; }
        public double Y() { return Y; }
        public double Z() { return Z; }
}

The data members of this class are as follows:

volName=the name of the volume (GEANT 4 logical volume) that the particle went through.
matName=the name of the material (GEANT 4 material).
distance
=the distance that the particle went along in the volume.
X, Y, Z=the x, y, z coordinates of the entrance point in the volume.
nbX0=the number of radiation lengths in the volume that the particle went through.
nInterLen=the number of interaction lengths in the volume that the particle went through.

The following example shows how one could use the getSteps method and its return values:

                CGARunManager run = new CGARunManager();

                Vector vec = new Vector();
                run.getSteps(vec);

                for(int i = 0; i < vec.size(); i++)
                        System.out.println(i + " " +
                        ((Step)vec.elementAt(i)).VolName()
                        + " " + ((Step)vec.elementAt(i)).Distance() + " " +
                        ((Step)vec.elementAt(i)).X() + " " +
                        ((Step)vec.elementAt(i)).Y() + " " +
                        ((Step)vec.elementAt(i)).Z() + " " +
                        ((Step)vec.elementAt(i)).X0());
 
 

3.3.3 getVolumeData

Suppose we were interested in getting the above information as a sum over the layers of a module. We can use for this purpose the native method getVolumeData:

        public native void getVolumeData(String name, Vector cont);

The parameters of the method are as follows:

name=the name of the (GEANT 4 logical volume) of the module of interest.
cont=a vector containing objects of the above shown "Step" class, one object for each module. This vector is filled by the function.

The following example shows how one could use this method and its return values:

                CGARunManager run = new CGARunManager();

                Vector vec2 = new Vector();
                run.getVolumeData("EnvLog", vec2);

                for(int i = 0; i < vec2.size(); i++)
                        System.out.println(i + " " +
                        ((Step)vec2.elementAt(i)).VolName()
                        + " " + ((Step)vec2.elementAt(i)).Distance() + " " +
                        ((Step)vec2.elementAt(i)).X() + " " +
                        ((Step)vec2.elementAt(i)).Y() + " " +
                        ((Step)vec2.elementAt(i)).Z() + " " +
                        ((Step)vec2.elementAt(i)).X0());
 

3.4 Getting the coordinates of the cell center

    The cell center coordinates are calculated by the sensitive detector. One has to set the right sensitive detector first by using setSD, and then use cellIndex to get the cell center coordinates. Example no. 5 shows how to get the cell center coordinates from a LCIO file written by Mokka. One first has to read a SIMCALORIMETERHIT collection, get its flag and pass it to setSD. Then make a loop over all hits of the collection and for every hit call cellIIndex with the CellID0 of the hit.

3.4.1 setSD

    Just call this function with the flag as argument:

CGARunManager run = new CGARunManager();
LCCollection col = evt.getCollection(name);
run.setSD(col.getFlag());

3.4.2 cellIndex

    One can call this function with the CellID 0 of the hit as argument and it will return the x, y, z coordinates of the cell center as a Vector of Double's:

int id0 = hit.getCellID0() ;
Vector cgaResult = run.cellIndex(id0);
System.out.print(" - pos from CGA: ("
                + ((Double)(cgaResult.elementAt(0))).floatValue() + ", "
                + ((Double)(cgaResult.elementAt(1))).floatValue() + ", "
                + ((Double)(cgaResult.elementAt(2))).floatValue() + ")");
 
  

3.5 Getting the CellId of a point

    The CellId of a point of given coordinates is calculated by the sensitive detector. One has to set the right sensitive detector first by using setSD, and then use getCellId to get the compressed cell index.

NB: With the latest versions of Geant 4, one has also to shoot first a particle, so that Geant 4 doest its initializations.


3.5.1 getCellId

    One can call this function with an object of the CellIdUtility class that needs to be initialized with the coordinates of the point and a optionally a direction (the default is (0.0, 0.0, 1.0)) that is used by Geant 4 if the point is on the border of two volumina.When the method returns, the object of CellIdUtility class passed as an argument will also contain the CellId and a flag that shows if the point was really inside a cell (flag = 1), inside a guard-ring (flag = 0; the CellId will be the one of the nearest cell), or inside another volume that is not sensitive (flag = -1 and CellId = 0),

int cellId, flag;
double x = 50.0, y = 20.0, z = -15.0;
double xDir = 1.0, yDir = 0.0, zDir = 1.0;

CGARunManager run = new CGARunManager();
run.setSD(SDIndex);

CellIdUtility theUtility = new CellIdUtility(x, y, z);// the direction defaults to (0.0, 0.0, 1.0)

or

CellIdUtility theUtility = new CellIdUtility(x, y, z, xDir, yDir, zDir)

run.getCellId(theUtility);
cellId = theUtility.cellId();
flag = theUtility.flag();

The example Ex05.java shows the usage of this method.

Back to CGA API home page


Team working on the Geant4 simulation for The Next Linear Collider:
      Henri VIDEAU
      Jean-Claude BRIENT
      Paulo Mora de Freitas
      Gabriel Musat