Fortran Mokka Common Geometry Access (CGA) API

1. The Fortran subroutine library

1.1 Subroutine CGAInit

First of all, we have to build the geometry model, the one that is used by the simulation. This can be done by calling the cgainit subroutine:

call CGAInit(steer, model, setup, host, user, passwd)

The parameters of this subroutine 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 the default password for the "consult" account on the geometry database running on aldebaran.in2p3.fr.
 

The following example shows how one could call this subroutine:

CHARACTER*6 steer, model, setup, host, user, passwd

steer=' '
model='D08'
setup=' '
host=' '
user=' '
passwd=' '
call CGAInit(steer, model, setup, host, user, passwd)

OR

call CGAInit(' ', 'D08', ' ', ' ', ' ', ' ')

1.2 Subroutine CGAWhereAmI

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

call CGAWhereAmI(point, volname)

The parameters of the subroutine are as follows:

point=the x, y, z coordinates (in centimeters) of the point. MUST be defined REAL*8.
volname=the name of the volume (GEANT 4 logical volume) that "point" is situated in. This is filled by the subroutine. If one did not allocate enough memory for volname, the name will be truncated.

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

CHARACTER*30 volname
REAL*8 point(3)
point(1)=0
point(2)=175
point(3)=0

call CGAWhereAmI(point, volname)
write(*,15) volname
15    format(a)

1.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 subroutine CGABeamOn, and then to get the information by calling the subroutine CGAGetSteps or the subroutine CGAGetVolumeData.

1.3.1 Subroutine CGABeamOn

This subroutine allows one to to shoot the desired particle:

call CGABeamOn(initial, final, direction, particle, energy, nbp)

The parameters of this subroutine are:

initial: the coordinates (in centimeters) of the point from where the particle is shot. MUST be defined REAL*8.
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. MUST be defined REAL*8.
direction: the direction that the particle is shot. MUST be defined REAL*8.
particle:  the particle's name
energy: the particle's energy. MUST be defined REAL.
nbp: the number of particles that we want to shoot

The following example shows how one could call this subroutine:

CHARACTER*30 particle
REAL*8 initial(3), final(3), direction(3)
REAL energy
INTEGER nbp

initial(1)=-68
initial(2)=169
initial(3)=0
final(1)=-200*sin(3.1418/8)
final(2)=200*cos(3.1418/8)
final(3)=0
direction(1)=final(1)-initial(1)
direction(2)=final(2)-initial(2)
direction(3)=final(3)-initial(3)
particle='geantino'
energy=20
nbp=1

call CGABeamOn(initial, final, direction, particle, energy, nbp)

OR

call CGABeamOn(initial, final, direction, 'chargedgeantino', 20.0, 1)

1.3.2 Subroutine CGAGetSteps

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

call CGAGetSteps(volnames, matnames, distance, prepoints, nbx0, ninterlen, nsteps, okflag)

The parameters of the subroutine are as follows:

volnames=an array of names of the volumes (GEANT 4 logical volumes) that the particle went through. This array is filled by the subroutine. If one did not allocate enough memory for every name, the names will be truncated.
matnames=an array of names of the materials (GEANT 4 materials) that the particle went through. This array is filled by the subroutine. If one did not allocate enough memory for every name, the names will be truncated.
distance
=an array of distances that the particle went along in each volume. This array is filled by the subroutine. MUST be defined REAL*8.
prepoints=a matrix of the x, y, z coordinates of the entrance point in evry volume. This matrix is filled by the subroutine. MUST be defined REAL*8.
nbx0=an array containig the number of radiation lengths in evry volume that the particle went through. This array is filled by the subroutine. MUST be defined REAL*8.
ninterlen=an array containig the number of interaction lengths in evry volume that the particle went through. This array is filled by the subroutine. MUST be defined REAL*8.
nsteps=the number of elements/volumes:
    - the initial value is the number of elements allocated for volnames, distance, nbx0, and the number of rows allocated for prepoints.
    - the value after this subroutine returns is the real number of layers that the particle went through.
okflag=when this subroutine returns, it is set to true if the initial value of nsteps is greater or equal to the number of volumes that the particle went through, and if not, okflag is set to false  Thus, one should test okflag before trying to use the return values of the subroutine. If it is false, one should allocate a larger amount of elements for the above parameters.

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

CHARACTER*30 volnames(1000),  matnames(1000)
REAL*8 distance(1000), nbx0(1000), nintlen(1000), prepoints(1000, 3)
LOGICAL okflag
INTEGER nsteps

okflag=.true.
nsteps=1000

call CGAGetSteps(volnames, matnames, distance, prepoints, nbx0, nintlen, nsteps, okflag)

if(okflag .eqv. .true.) then
   do i=1,nsteps
        write(*,12)volnames(i), matnames(i), distance(i), prepoints(i,1), prepoints(i,2), prepoints(i,3), nbx0(i), nintlen(i)
   enddo
endif

12    format(a, 3x, a, 3x, f9.3, 3x, 3(f9.3, 3x), f9.5, 3x, f9.5)

1.3.3 Subroutine CGAGetVolumeData

Suppose we were interested in getting the above information as a sum over the layers of a module. We can call for this purpose the subroutine CGAGetVolumeData:

call CGAGetVolumeData(volname, distance, prepoints, nbx0, ninterlen, nsteps, okflag)

The parameters of the subroutine are as follows:

volname=the name of the (GEANT 4 logical volume) of the module of interest.
distance=an array of distances that the particle went along in each module. This array is filled by the subroutine. MUST be defined REAL*8.
prepoints=a matrix of the x, y, z coordinates of the entrance point in evry module. This matrix is filled by the subroutine. MUST be defined REAL*8.
nbx0=an array containig the number of X0 in evry module that the particle went through. This array is filled by the subroutine. MUST be defined REAL*8.
ninterlen=an array containig the number of interaction lengths in evry volume that the particle went through. This array is filled by the subroutine. MUST be defined REAL*8.
nsteps=the number of elements/modules:
    - the initial value is the number of elements allocated for distance, nbx0, and the number of rows allocated for prepoints
    - the value after this subroutine returns is the real number of modules that the particle went through.
okflag=when this subroutine returns, it is set to true if the initial value of nsteps is greater or equal to the number of modules that the particle went through, and if not, okflag is set to false  Thus, one should test okflag before trying to use the return values of the subroutine. If it is false, one should allocate a larger amount of elements for the above parameters.

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

CHARACTER*30 volname
REAL*8 distance(1000), nbx0(1000), nintlen(1000), prepoints(1000, 3)
LOGICAL okflag
INTEGER nsteps

okflag=.true.
nsteps=1000
volname='EnvLog'

call CGAGetVolumeData(volname, distance, prepoints, nbx0, nintlen, nsteps, okflag)

if(okflag .eqv. .true.) then
   do i=1,nsteps
      write(*,17)volname, distance(i), prepoints(i,1),prepoints(i,2), prepoints(i,3), nbx0(i)
    enddo
endif
17    format(a, 3x, f12.8, 3x, 3(f9.3, 3x), f9.5)

1.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 calling subroutine CGASetSD, and then call subroutine CGACellIndex to get the cell center coordinates. Example no. 6 shows how to get the cell center coordinates from an ASCII hit file written by Mokka. The rightmost column of every line is the flag that one has to pass to CGASetSD, and the second from right to left is the CellID that has to be passed to CGACellIIndex.


1.4.1 Subroutine CGASetSD

    Just call this subroutine with the flag as argument:

INTEGER Flag
call CGASetSD(Flag)

The subroutine selects the sensitive detector corresponding to the flag.


1.4.2 Subroutine CGACellIndex

    One can call this subroutine with the CellID as argument and the x, y, z variables that will contain the coordinates of the cell center as returned by the subroutine:

REAL*8 x, y, z
INTEGER CellID
call CGACellIndex(CellID, x, y, z)

 

1.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 CGASetSD, and then use CGAGetCellId 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.


1.5.1 CGAGetCellId

    One can call this function with the coordinates of the point, a flag that will be returned by the method to show 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), and a direction that is used by Geant 4 if the point is on the border of two volumina.

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

CGAGetCellId(x, y, z, cellId, flag, xDir, yDir, zDir);

if one had defined

double xDir = 0.0, yDir = 0.0, zDir = 0.0;

the direction would have been set by the CGA to default (0.0, 0.0, 1.0)

The example Ex06.f 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