Next: 3 CREATING GEANT HITS Up: Advanced Geometry Interface for Previous: 1 Introduction

2 GEOMETRY DESCRIPTION

The geometry of each STAR detector in GSTAR is described in a single module. Modules are written in the geant language and translated by the parser into conventional, well commented Fortran subroutines compiled and linked with the rest of GSTAR libraries. A module consists of the module header, the data definition part and of a number of blocks, each describing one GEANT elementary volume and its content.

2.1 geant language

The geant language is a Fortran extension oriented to the GEANT application. In addition to Fortran statements, it contains a number of geant statements in the form:

OPERATOR NAME [ = value ... = value ]

where the OPERATOR defines a specific service to be performed by the AgSTAR interface. Apart from the declarations and data handling operators, described in sections 2.4 and 2.5, there are 9 GEANT dedicated operators and 3 control operators in the basic geant language set. For these operators:

NAME is the name of a GEANT volume or of a volume shape (4 letters), or a material or medium name (up to 20 letters). A Fortran string variable is generated by the parser by converting the NAME into upper-case letters.
Keywords (left parts of assignment) are variables used in the GEANT3 manual [1] to describe the parameters of the corresponding GEANT3 routine .
Their values (right parts of assignment) are any legal Fortran expression.

The language is neither case nor position sensitive. Unlike conventional Fortran, statements can be continued on the next line only using a comma or an underscore at the end of a line as a continuation sign. A comma can also be used between keywords to improve the readability. All geant comments mentioned below are mandatory. A list of keywords with their values is called below a definition.

2.2 Volume description

2.2.1 General structure

Any GEANT volume in a module is described as a block. A block consists of two parts - the description of its own properties and the description of its content - and has the following structure (last column shows the corresponding GEANT3 routine) :

BLOCK, ENDBLOCK and CREATE are control operators because they affect the execution order: CREATE is executed as a jump to the requested BLOCK code and the return back when its ENDBLOCK is reached. All other are GEANT dedicated operators and are substituted by a call to one or a few GEANT routines via the AgSTAR interface .

Example 1:

Block VPDD  is the Vertex Position Detector assembly
     Material  Air
     Medium    Standard
     Attribute VPDD   Seen=0  colo=5
     Shape     TUBE   Rmin=vpdg_Rmin  Rmax=vpdg_Rmax,
                      Dz=vpdg_Length/2
     Rcurrent = vpdg_Rmin
     Do iLayer = 1,2     
        Create   VRNG
        Position VRNG 
        Rcurrent = Rcurrent + vpdl_DrLayer
     enddo
Endblock

The AgSTAR interface maintains GEANT tables of materials, mediums, volumes and rotation matrices. After checking that the requested name already exists in the corresponding table or having created a new table entry, the interface returns the entry number used in the GEANT routines.

The only mandatory operator inside a block is its SHAPE, others can be omitted.

In this case the volume properties are inherited from it's mother volume, and position definitions are assumed to be default (x=y=z=0, no rotation).

If needed, material, medium and attribute operators should be defined before the SHAPE operator.

2.2.2 More on SHAPE

The name argument of the SHAPE operator contains a name of any of the 16 legal GEANT shapes described in the manual. Keywords in the definition part are the names of parameters, used in the GEANT manual (section GEOM 050) to describe these shapes. The only exception are multiple z,Rmin and Rmax parameters of the PCON and PGON shapes, which should be supplied as vectors named Zi, Rmn and Rmx, defined in one of the following two forms:

where a vector stands for Zi, Rmn or Rmx, are any Fortran expressions, and A is a Fortran array.

As the parameters are transmitted to the GSVOLU routine via the AgSTAR interface, they can be provided in any order or be inherited from the mother volume.

Example 2: the PCON specification from the GEANT manual (GEOM 050, figure 23) may look like:

    SHAPE PCON phi1=180 dphi=279 Nz=4 Zi={-400,-300,300,400},
               Rmn={50,50,50,50}      Rmx={250,100,100,250}

The GEANT divisions in the geant language are particular cases of the SHAPE operator. The actual division mechanism is automatically selected by the AgSTAR interface depending upon the parameters supplied.

Example 3: this will create divisions of a TUBE in using GSDVN (GEOM 130):

   ....
     Shape  TUBE      Rmin=Rcurrent  Rmax=Rcurrent+vpdl_DrLayer,
                      Dz=Detector_length/2  
     Create VSEC
   ....
* 
Block VSEC  is one VPD sector with all stuff inside
     Shape  Division  Iaxis=2    Ndiv=vpdl_NumPMT,
                      C0=90+180/vpdl_NumPMT/iLayer
     Create ....
endblock

2.2.3 Inheritance rules

Unless defined explicitly, parameters of the MATERIAL, MIXTURE, MEDIUM, and SHAPE operators in a new block are inherited from the block creating it

Normally this is also its mother volume. If no material or medium are defined in a new block at all, the are inherited from the mother block.

A MATERIAL or a MEDIUM operator without parameters can be used to refer to an already defined material (mixture) or medium.

Default materials, a priori known to the AgSTAR interface , are the 16 GEANT standart materials plus other materials described in the Particle Data Book [4].

The only tracking medium, known to the AgSTAR interface is the standart one, defined as following:

  Medium   Standard  Ifield=1 FieldM=20 TmaxFd=20 Epsil=0.01,
                     SteMax=10.0   DeeMax=-0.02   StMin=-0.01

A new GEANT medium is automatically introduced even without a MEDIUM operator, if the material in a block has been changed by a MATERIAL or MIXTURE operator.

2.3 Volume positioning

Unless defined explicitly, the parameters of a POSITION operator have the default values: x=y=z=0, KONLY='ONLY', unit rotation matrix.

If the volume being positioned has been defined with all parameters equal to zero, the GSPOSP routine will be called, otherwise the GSPOS is used. In case of the GSPOSP call, the actual parameters of the volume shape supplied in the POSITION operator still follow the inheritance rules for the SHAPE operator.

If a rotation should be defined when positioning a volume, it is possible to define it in several ways:

Providing up to 6 parameters, describing a new orthogonal coordinate system (GEOM 200). The parameter names and their default values defining the unit matrix are ,

Only those parameters which are different from the default unit matrix should be given.

Example: The two copies of the VPDD block, mentioned in the example 1, are positioned in CAVE with

      Position VPDD in Cave  z=+vpdg_Position
      Position VPDD in Cave  z=-vpdg_Position   ThetaZ=180

A rotation around one of the x,y,z axis can be introduced simply by defining one of the following parameters: or AlphaZ.
Axis subsitutions, often used in GEANT for positioning certain combinations of shapes, can be introduced by defining the ORT parameter as ORT = XYZ (default), YZX or ZXY

The ORT parameter can be combined with the other rotation definition taken into account that the axis substitution is done after all other rotations, i.e. rotation is defined in old axis.

For example to position a TRD1 trapesoid in a TUBS sector with a tilt angle alp relative to the tube axis, one can use POSITION IT somewhere AlphaZ=alp ORT=YZX

Rotation parameters are not inherited from one POSITION operator to another.

2.4 Volume naming mechanism

All volumes in GSTAR are referenced by their generic names, consisting of 4 upper-case letters

. When the real dimensions of the same generic volume are variable, the supporting AgSTAR library provides an automatic and transparent mechanism which, for physically different volumes with the same generic name, generates nicknames used by GEANT, by changing last letters of the generic name into numbers or lower-case letters. These volumes with different nicknames are considered as instances of the same generic object. The original generic name is also kept in each instance together with its nickname.

The positioning of all volumes is done using their generic names, the latest generated instance of the object being actually used. When positioned in the same mother volume such instances will be distinguished also by their GEANT copy numbers. If a volume instance has been defined with all parameters equal to zero, it will be positioned by the AgSTAR interface using the GSPOSP routine, with the dimensions defined in the POSITION operator.

This mechanism provides a simple and effective way to automatically generate the unique path to each GEANT volume, needed for the HIT package, without additional user code.

2.5 Module header

The module header in AgSTAR is used to provide the Fortran declarations as well as the program maintenance information. It consists of the following geant declarations :

Note that:

The first line should be the MODULE declaration. The order of other statements is irrelevant. The module name consists of a 4-letter STAR detector code plus the module type code (GEO, DIG etc). It is also used to identify module input and output data structures (GEANT hits and digits, parameter records in the DETM geometry database).
The format of MODULE comment, author list and creation date is arbitrary, but their presence is mandatory.
The CONTENT declaration should list all blocks used in the module.
The STRUCTURE declaration groups together real variables or arrays , which are subject to potential change using KUIP datacards or should be accessible from external routines, for example at the reconstruction stage. Their usage is described in the next section.

Example:

     module   VPDDGEO  is the Vertex Position Detector of STAR
     Author   Z.Milosevich, P.Nevski 
     Created  27 March 1996

     CONTENT   VPDD,VRNG,VSEC,VDET,VCNV,VRAD,VSUP,VPMT,VXST
     Structure VPDG { Version, Rmin, Rmax, Length, Position,
                      PMTradi, PMTwall, PMTleng, 
                      EleLeng, ConvThk, RadiThk, 
                      TubeThk, SuppThk, SuppDist }
     structure VPDL { Layer,   DrLayer, NumPMT   }

* external (GEANT and AGI) sequences 
     +include,AGECOM,GCUNIT,GCONST

* Local variables
     Real      Rcurrent, Detector_Length
     Integer   iLayer

2.6 Data structure handling

A group of logically linked variables, which are declared in a STRUCTURE operator, is defined using the FILL statement:

The whole collection of user's banks, created by FILL operators, is kept as a single tree DETM of structurally linked banks. It is saved after the program execution in the RZ data base (both the bank content and the relevant documentation) and can be used by reconstruction programs.

Note that:

The structure name consists of 4 letters and is used as the ZEBRA bank name and as the prefix of its variables in the Fortran code.
The order of assignments is irrelevant, but comments and explanations are mandatory.
Other comment lines cannot be interleaved with FILL assignements.
are Fortran expressions in case of a simple variable or a vector in the form for an array.
When the FILL statement is executed by the AgSTAR interface, the data are saved as a bank in the DETM structure.

There may be two levels of data structures (banks) defined and used in a module: the structure name, defined by the first FILL operator, becomes the high level structure name. All structures with other names are considered as lower level structures associated to it.

Each of these structures may be a linear chain of similar banks, created by sequential FILL operators with the same name. They all are considered as instances of the same generic object, so at any moment only one selected copy of each structure is available. A typical usage of the high level structure is to provide different geometry versions of the same detector, the actual version been selected using the datacard input. Instances of the low level structures can be used to provide parameters for different components of the of the same detector.

Example:

     FILL VPDG           ! VPD basic dimensions
        Version  = 1         ! geometry version
        Rmin     = 4         ! VPD inner radius
        Rmax     = 16        ! VPD outer radius
        Length   = 30        ! full VPD assembly length along the beam 
        Position = 250       ! Z position of VPD along beam axis
        PMTwall  = 0.1       ! PMT wall thickness
        PMTradi  = 2.54      ! PMT and detector radius
        PMTLeng  = 8.0       ! PMT tube length 
        EleLeng  = 15.0      ! electronics mount length
        ConvThk  = 0.635     ! Converter layer thickness
        RadiThk  = 0.635     ! Radiator layer thickness
        TubeThk  = 0.00      ! piece of beam pipe thickness (if needed)
        SuppThk  = 0.64      ! Support rings thickness
        SuppDist = 16        ! distance between supporting rings
*
     FILL VPDL           ! single PMT layer
        layer    = 1         ! layer number
        DrLayer  = 6         ! layer radial width
        NumPMT   = 8         ! number of PMT in layer
*
     FILL VPDL           ! single PMT layer
        layer    = 2         ! layer number
        DrLayer  = 6         ! layer radial width
        NumPMT   = 16        ! number of PMT in layer      
     Endfill

Example: data structures produced by the previous example:

One can select the actual copy of the structure to be used by the program (an instance of the data structure) with the help of the USE statement :

USE NAME variable=value

Any variable from the corresponding structure can be used to select the current instance of the bank. The value may be any Fortran expression.

Example: USE VPDG version=1
USE VPDL layer=1

Once the top level bank is selected with the USE operator, the descendent lower level banks are selected only within the same branch. In geometry modules selected top level bank is re-linked at the first position of a possible linear chain, so that it always become default bank for any further selection. Also at that moment their content is changed by the standard datacard input.

Once selected with the USE operator, variables from the data structure can be referenced by the program in the form BankName_Variable. In this way they are easy to recognize among the other program variables (see first example).

This mechanism provides an easy and flexible way of the geometry versioning within each module.

Next: 3 CREATING GEANT HITS Up: Advanced Geometry Interface for Previous: 1 Introduction

William J. Llope

Thu Aug 15 17:05:49 EDT 1996