GSTAR Overview and TutorialGSTAR Overview and Tutorial

Maxim PotekhinMaxim PotekhinSTAR Collaboration MeetingSTAR Collaboration Meeting

MSUMSU August 13, 2003August 13, 2003

Goals of this presentationGoals of this presentation

provide a quick intro to GSTARprovide a quick intro to GSTAR

increase the user awareness of this simple-to-use simulation toolincrease the user awareness of this simple-to-use simulation tool

illustrate the mechanism of geometry definitionillustrate the mechanism of geometry definition

show how a simple ad hoc simulation can be run by the user, and how to show how a simple ad hoc simulation can be run by the user, and how to modify and rebuild the geometrymodify and rebuild the geometry

encourage the community participation in the geometry maintenance and encourage the community participation in the geometry maintenance and future development of the STAR Detector Description Servicesfuture development of the STAR Detector Description Services

OverviewOverview

The concept of GSTARThe concept of GSTAR

Example of a simple GSTAR sessionExample of a simple GSTAR session

Geometry definition and versioningGeometry definition and versioning

How to modify and reload the geometryHow to modify and reload the geometry

Event inputEvent input

Event and geometry outputEvent and geometry output

Useful commands for geometry visualization and testingUseful commands for geometry visualization and testing

GSTAR (a.k.a. staf)GSTAR (a.k.a. staf)

GSTAR foundation: standard CERN software such as PAW and GEANT GSTAR foundation: standard CERN software such as PAW and GEANT 3.21, with manipulation of underlying ZEBRA banks.3.21, with manipulation of underlying ZEBRA banks.

GSTAR user interface: based on KUIP. Allows both interactive mode and GSTAR user interface: based on KUIP. Allows both interactive mode and full scripting (KUMAC files). Supports commands for interactive GEANT and full scripting (KUMAC files). Supports commands for interactive GEANT and PAW, plus ZEBRA debugging tools.PAW, plus ZEBRA debugging tools.

The not-so-standard GSTAR component: the Detector Geometry The not-so-standard GSTAR component: the Detector Geometry Description (distinct from the GSTAR core but interfacing it)Description (distinct from the GSTAR core but interfacing it)

The core design idea: instrument the GEANT code in a way that allows for The core design idea: instrument the GEANT code in a way that allows for dynamic loading of most functions. This gives the developer and users dynamic loading of most functions. This gives the developer and users much flexibility in enhancing the functionality without rebuilding the much flexibility in enhancing the functionality without rebuilding the executable, and provides for the code modularityexecutable, and provides for the code modularity

GSTARGSTAR

Practical benefits:Practical benefits:

– a versatile platform, the workhorse of the STAR simulationsa versatile platform, the workhorse of the STAR simulations– interactive detector exploration tool, friendly UIinteractive detector exploration tool, friendly UI– advanced scripting based on standard KUIPadvanced scripting based on standard KUIP– standardized output format – integration with the reco chainstandardized output format – integration with the reco chain– a few standard input formats – integration with the event generatorsa few standard input formats – integration with the event generators– useful help pages systemuseful help pages system– the ease of dynamic loading of user-created and/or user-modified the ease of dynamic loading of user-created and/or user-modified

functions (rebuilding on-the-fly)functions (rebuilding on-the-fly)– enhanced interface to the GEANT debugging toolsenhanced interface to the GEANT debugging tools– geometry persistent in the outputgeometry persistent in the output

GSTAR componentsGSTAR components

The GSTAR executableThe GSTAR executable

– named “staf” for historical reasons, resides in $STAF/binnamed “staf” for historical reasons, resides in $STAF/bin

The geometry DLL – compiled from source files located inThe geometry DLL – compiled from source files located in

– $STAR/pams/geometry $STAR/pams/geometry (more on the geometry description later)(more on the geometry description later)

Makefiles (used implicitly when running certain commands in GSTAR)Makefiles (used implicitly when running certain commands in GSTAR)

The i/o module handling a variety of event data formatsThe i/o module handling a variety of event data formats

KUMAC filesKUMAC files

Optional user DLL’s that can be built and loaded virtually at any timeOptional user DLL’s that can be built and loaded virtually at any time

Starting a GSTAR sessionStarting a GSTAR session

With the standard STAR environment:With the standard STAR environment:

~/myworkdir> staf –w 1~/myworkdir> staf –w 1

where “1” will open a standard X11 graphics window, and “0” can be where “1” will open a standard X11 graphics window, and “0” can be used for sessions without the need for graphics (obviously comes used for sessions without the need for graphics (obviously comes from PAW). This gets you to a prompt:from PAW). This gets you to a prompt:

staf>staf>

Alternatively, one can run in batch mode:Alternatively, one can run in batch mode:

~/myworkdir> staf –w 0 –b myscript.kumac~/myworkdir> staf –w 0 –b myscript.kumac

A simple GSTAR session: detector visualizationA simple GSTAR session: detector visualization

staf> detp geometry year2003staf> detp geometry year2003

staf> make geometrystaf> make geometry

staf> draw CAVEstaf> draw CAVE

staf> dcut CAVE z 0.1 10 10 0.02 0.02staf> dcut CAVE z 0.1 10 10 0.02 0.02

Getting help: an exampleGetting help: an examplestaf > man dcutstaf > man dcut

Command "/GEANT/DRAWING/DCUT" :Command "/GEANT/DRAWING/DCUT" :

* GEANT/DRAWING/DCUT NAME CAXIS CUTVAL [ U0 V0 SU SV ]* GEANT/DRAWING/DCUT NAME CAXIS CUTVAL [ U0 V0 SU SV ]

NAME C 'Volume name'NAME C 'Volume name' CAXIS C 'Axis value'CAXIS C 'Axis value' CUTVAL R 'Cut plane distance from the origin along the axis'CUTVAL R 'Cut plane distance from the origin along the axis' U0 R 'U-coord. (horizontal) of volume origin'U0 R 'U-coord. (horizontal) of volume origin' V0 R 'V-coord. (vertical) of volume origin'V0 R 'V-coord. (vertical) of volume origin' SU R 'Scale factor for U-coord.'SU R 'Scale factor for U-coord.' SV R 'Scale factor for V-coord.'SV R 'Scale factor for V-coord.'

Possible CAXIS values are:Possible CAXIS values are:

X X Y Y Z Z

CALL GDRAWC(name,iaxis,cutval,u0,v0,su,sv)CALL GDRAWC(name,iaxis,cutval,u0,v0,su,sv)

The cut plane is normal to caxis (X,Y,Z), corresponding to iaxis (1,2,3), The cut plane is normal to caxis (X,Y,Z), corresponding to iaxis (1,2,3), and placed at the distance cutval from the origin. The resulting picture and placed at the distance cutval from the origin. The resulting picture is seen from the the same axis. If optional parameters are missing, the is seen from the the same axis. If optional parameters are missing, the current values in /GCDRAW/ are taken. When HIDE Mode is ON, it is possible current values in /GCDRAW/ are taken. When HIDE Mode is ON, it is possible to get the same effect with the CVOL/BOX command. to get the same effect with the CVOL/BOX command.

Detector Geometry DescriptionDetector Geometry Description

Number of detector subsystems : 19 (not all necessarily included in a Number of detector subsystems : 19 (not all necessarily included in a particular configuration) particular configuration)

Custom macro “geometry language” (*.g files)Custom macro “geometry language” (*.g files)– based on the obscure Fortran preprocessor called Mortranbased on the obscure Fortran preprocessor called Mortran– ideally suited for application-specific Fortran code structuringideally suited for application-specific Fortran code structuring– in many cases, helps circumvent limitations of Fortranin many cases, helps circumvent limitations of Fortran– can be of help with the GEANT learning curvecan be of help with the GEANT learning curve– has been successfully used in a number of projectshas been successfully used in a number of projects

11+ k lines of geometry code, largely user maintained11+ k lines of geometry code, largely user maintained

volume numbering maps (not part of the geometry per se) are maintained volume numbering maps (not part of the geometry per se) are maintained separately in “g2t” files.separately in “g2t” files.– Difficult to version and maintain.Difficult to version and maintain.

Detector Geometry DescriptionDetector Geometry Description

[rcas6027] ~/> ls $STAR/pams/geometry/[rcas6027] ~/> ls $STAR/pams/geometry/

bbcmgeo/ bbcmgeo/ calbgeo/ calbgeo/ fpdmgeo/fpdmgeo/

geometry/ geometry/ magpgeo/ magpgeo/ phmdgeo/phmdgeo/

supogeo/ supogeo/ tpcegeo/ tpcegeo/ vpddgeo/vpddgeo/

btofgeo/ btofgeo/ cavegeo/ cavegeo/ ecalgeo/ ecalgeo/

ftpcgeo/ftpcgeo/ mfldgeo/ mfldgeo/ pipegeo/pipegeo/

richgeo/richgeo/ svttgeo/svttgeo/ upstgeo/upstgeo/

zcalgeo/zcalgeo/

Detector Geometry DescriptionDetector Geometry Description

Code example:Code example:

Block SVTT is the mother of all SVT volumesBlock SVTT is the mother of all SVT volumes

* * Material AirMaterial Air

Attribute SVTT seen=0 colo=1Attribute SVTT seen=0 colo=1

Shape TUBE Rmin=svtg_RsizeMin, Rmax=svtg_RsizeMax, dz=svtg_ZsizeMaxShape TUBE Rmin=svtg_RsizeMin, Rmax=svtg_RsizeMax, dz=svtg_ZsizeMax

* End rings to support the ladders:* End rings to support the ladders:

**

Create SIRP " inner end ring polygon piece " Create SIRP " inner end ring polygon piece "

Position SIRP Z=serg_EndRngZm+serg_EndRngTh/2 AlphaZ=22.5Position SIRP Z=serg_EndRngZm+serg_EndRngTh/2 AlphaZ=22.5

Detector Geometry VersioningDetector Geometry Versioning

STAR Geometry Versioning:STAR Geometry Versioning:

the steering file:the steering file:    $STAR/$STAR/pams/geometry/geometry/geometry.gpams/geometry/geometry/geometry.g – contains the complete history of the STAR configurationscontains the complete history of the STAR configurations– calls the constructors of individual detector subsystems and sets some of their parameterscalls the constructors of individual detector subsystems and sets some of their parameters– versioning is done at run time based on the value of “geometry” parameter. versioning is done at run time based on the value of “geometry” parameter.

Example: detp geometry year2003Example: detp geometry year2003

The The detpdetp command allows the user to set certain predefined configuration command allows the user to set certain predefined configuration parameters:parameters:

Configurations : year_1a,s,b,h,c;year_2a,Configurations : year_1a,s,b,h,c;year_2a,year2000, year2001, year2002, year2003 year2000, year2001, year2002, year2003

Gcalor : Gcalor_on, Gcalor_off Gcalor : Gcalor_on, Gcalor_off Geant Physics : Hadr_on, Hadr_off (GHEISHA)Geant Physics : Hadr_on, Hadr_off (GHEISHA)Geant Physics : Phys_off, Decay_Only Geant Physics : Phys_off, Decay_Only Geometry Detail : mwc_off, pse_off, 4th_off Geometry Detail : mwc_off, pse_off, 4th_off Magnetic Field : Field_on/off, field=value Magnetic Field : Field_on/off, field=value Auxillary keys : Debug_on/offAuxillary keys : Debug_on/off

The The detpdetp command also allows the user to set some variables (structure command also allows the user to set some variables (structure elements) prior to building the geometry, thus facilitating experimentation elements) prior to building the geometry, thus facilitating experimentation and debuggingand debugging

Detector Geometry VersioningDetector Geometry Versioning on YEAR2003 { draft 2003 geometry - TPC+CTB+FTPC+CaloPatch2+SVT3+BBC+FPD+ECAL;on YEAR2003 { draft 2003 geometry - TPC+CTB+FTPC+CaloPatch2+SVT3+BBC+FPD+ECAL; "svt: 3 layers ";"svt: 3 layers "; nsi=6 " 3 bi-plane layers, nsi<=7 ";nsi=6 " 3 bi-plane layers, nsi<=7 "; wfr=0 " numebring is in the code ";wfr=0 " numebring is in the code "; wdm=0 " width is in the code ";wdm=0 " width is in the code "; "tpc: standard, i.e. ""tpc: standard, i.e. " mwc=on " Multiwire chambers are read-out ";mwc=on " Multiwire chambers are read-out "; pse=on " inner sector has pseudo padrows ";pse=on " inner sector has pseudo padrows "; "ctb: central trigger barrer ";"ctb: central trigger barrer "; Itof=2 " btofgeo2 ";Itof=2 " btofgeo2 "; btofconfig=5;btofconfig=5; "calb" "calb" ems=on "endcap "ems=on "endcap " nmod={60,0}; shift={0,0}; " 60 sectors "nmod={60,0}; shift={0,0}; " 60 sectors " "ecal" "ecal" ecal_config=1 "one ecal patch, west "ecal_config=1 "one ecal patch, west " ecal_fill=1 " sectors 2-5 filled "ecal_fill=1 " sectors 2-5 filled " "beam-beam counter ""beam-beam counter " bbcm=onbbcm=on "forward pion detector ""forward pion detector " fpdm=onfpdm=on "field version ""field version " Mf=4; "tabulated field, with correction "Mf=4; "tabulated field, with correction " "geometry correction ""geometry correction " CorrNum = 0;CorrNum = 0; }}

Building geometry during a GSTAR sessionBuilding geometry during a GSTAR session

staf> detp geometry year2003staf> detp geometry year2003 The version tag is set, which will select the requisite GEANT The version tag is set, which will select the requisite GEANT

configuration and parameters at run time. configuration and parameters at run time.

staf> make geometrystaf> make geometry The “make” utility is invoked, which will keep track of any geometry The “make” utility is invoked, which will keep track of any geometry

source code that might be present in the pams/geometry path in the source code that might be present in the pams/geometry path in the working directory.working directory.

staf> gclose allstaf> gclose all Closes the Zebra banks, calculates various GEANT cross-sectionsCloses the Zebra banks, calculates various GEANT cross-sections

staf> * make some drawings or trigger events herestaf> * make some drawings or trigger events here Do something useful hereDo something useful here .................................................................................... ....................................................................................

““Hacking” the geometryHacking” the geometry

Check out (Check out (cvs cocvs co) and edit any of the files in the pams/geometry path ) and edit any of the files in the pams/geometry path in the working directory, as desired. The “make” command will take care in the working directory, as desired. The “make” command will take care of the dependencies.of the dependencies.

staf> detp geometry year2003staf> detp geometry year2003 Choose the base geometry with which to workChoose the base geometry with which to work

staf> make geometrystaf> make geometry Build the GEANT geometry which will now include your changesBuild the GEANT geometry which will now include your changes

staf> gclose allstaf> gclose all Get ready for the simulationGet ready for the simulation

staf> * make some drawings or trigger events herestaf> * make some drawings or trigger events here Do something useful hereDo something useful here .................................................................................... ....................................................................................

staf> gdrop allstaf> gdrop all Drop the Zebra banks, get ready for rebuilding geometryDrop the Zebra banks, get ready for rebuilding geometry

staf> * staf> * If needed, modify the geometry source and repeat the cycleIf needed, modify the geometry source and repeat the cycle

Debugging the geometryDebugging the geometry

Display the GEANT volume hierarchyDisplay the GEANT volume hierarchy dtree ECALdtree ECAL

Subsystem visualizationSubsystem visualization nextnext draw ECALdraw ECAL nextnext draw SVTT 40 30 120 10 10 0.18 0.18draw SVTT 40 30 120 10 10 0.18 0.18

Event visualizationEvent visualization

detp geometry year2003detp geometry year2003 make geometrymake geometry gclose allgclose all debug ondebug onenable track visualization:enable track visualization: switch 2 3switch 2 3 switch 4 3switch 4 3produce a view of the detectorproduce a view of the detector dcut CAVE z 0.1 10 10 0.02 0.02dcut CAVE z 0.1 10 10 0.02 0.02select one electron track per event:select one electron track per event: gkine 1 3 0.2 0.2 0.5 0.5gkine 1 3 0.2 0.2 0.5 0.5 trigtrigobserve the hits:observe the hits: dhitsdhits

Persisting GEANT geometry and outputPersisting GEANT geometry and output

This simple command during the session will open an output file:This simple command during the session will open an output file:

gfile o my_file.fzgfile o my_file.fz

After that, subsequent events shall be recorded in the file. The geometry will also be After that, subsequent events shall be recorded in the file. The geometry will also be persisted in a transparent manner.persisted in a transparent manner.

A neat exercise:A neat exercise: define a geometry, create a few events with kinematic tracks, save define a geometry, create a few events with kinematic tracks, save them in a file, then quit GSTAR.them in a file, then quit GSTAR.

Reopen the file in a fresh GSTAR/staf session using the command:Reopen the file in a fresh GSTAR/staf session using the command:

gfile p my_file.fzgfile p my_file.fz

And inspect the geometry using the command discussed above. Also, issue triggers And inspect the geometry using the command discussed above. Also, issue triggers and use the dhits command to look at the hits.and use the dhits command to look at the hits.

Using external input from event generatorsUsing external input from event generators

First, load the module responsible for First, load the module responsible for handling the various formats of input files, handling the various formats of input files,

make gstarmake gstar

then open a file with event data:then open a file with event data: us/input please my_event_file.ntus/input please my_event_file.nt

After that, subsequent events can be read After that, subsequent events can be read from the file, and propagated in GEANT, from the file, and propagated in GEANT, with each “trig” command.with each “trig” command.

Naturally, this can be combined with Naturally, this can be combined with opening an output file and recording the opening an output file and recording the simulated GEANT event data. simulated GEANT event data.

The following command, issued after The following command, issued after propagating a Hijing event, produced the propagating a Hijing event, produced the hits picture on the right:hits picture on the right:

dhitsdhits

Event diagnosticsEvent diagnosticsThe following commands are useful in inspecting the GEANT event’s contents:The following commands are useful in inspecting the GEANT event’s contents:

gprint kinegprint kineprints the contents of the event particle table (tracks)prints the contents of the event particle table (tracks)

gprint vertgprint vertprints vertices info, such as positions and generated track numbersprints vertices info, such as positions and generated track numbers

gprint hitsgprint hitsprints GEANT “hits” as recorded in various detector elements,prints GEANT “hits” as recorded in various detector elements,hits also can be inspected in individual detector subsystems:hits also can be inspected in individual detector subsystems:

gprint hits ecalgprint hits ecal

====> HITS IN DETECTOR ** ESCI ** OF SET ** ECAH ** <========> HITS IN DETECTOR ** ESCI ** OF SET ** ECAH ** <====

HITS TRACK ECVO EMOD ESEC EMGT EPER ETAR BIRK HITS TRACK ECVO EMOD ESEC EMGT EPER ETAR BIRK 1 377 2 4 1 3 1 7 2.482E-031 377 2 4 1 3 1 7 2.482E-03 2 276 2 2 1 16 1 6 1.160E-032 276 2 2 1 16 1 6 1.160E-03 3 248 1 5 2 1 5 2 1.646E-033 248 1 5 2 1 5 2 1.646E-03 4 248 1 5 3 1 5 2 2.072E-044 248 1 5 3 1 5 2 2.072E-04 5 248 1 5 3 1 5 3 1.308E-035 248 1 5 3 1 5 3 1.308E-03

Triggers and scalersTriggers and scalersWhen studying efficiencies of rare signal triggers, we want to save considerable When studying efficiencies of rare signal triggers, we want to save considerable computational resources by pre-selecting events according to some basic trigger computational resources by pre-selecting events according to some basic trigger criteria, avoiding the costly propagation and reconstruction of uninteresting events.criteria, avoiding the costly propagation and reconstruction of uninteresting events.

One recent example: the study of J/Psi and Upsilon trigger based on One recent example: the study of J/Psi and Upsilon trigger based on calorimeter hits.calorimeter hits.

A new feature has been implemented that includes:A new feature has been implemented that includes:1.1. A template for the event selection logicA template for the event selection logic

2.2. Augmented event header structure which carries the running scaler for rejected events, Augmented event header structure which carries the running scaler for rejected events, allowing the user to correctly calculate the normalization factors.allowing the user to correctly calculate the normalization factors.

3.3. The “g2t” interface with reconstruction for transparent access to such data in root files.The “g2t” interface with reconstruction for transparent access to such data in root files.

How to do that:How to do that:1.1. Write the “AGUDIGI” subroutine called automatically by GEANT at the hits digitization Write the “AGUDIGI” subroutine called automatically by GEANT at the hits digitization

stagestage

2.2. Use any of the methods available to check for the trigger condition such as number of Use any of the methods available to check for the trigger condition such as number of hits in a particular detector subsystemhits in a particular detector subsystem

3.3. Set the IEOTRI flag (standard GEANT) according to the event selection criteria. Rejected Set the IEOTRI flag (standard GEANT) according to the event selection criteria. Rejected events will then be completely ignored and won’t be present in the output stream.events will then be completely ignored and won’t be present in the output stream.

Triggers and scalers: a code exampleTriggers and scalers: a code example

subroutine AGUDIGIsubroutine AGUDIGI call hepevnt()call hepevnt() call ecal_trigger()call ecal_trigger() returnreturn endend**subroutine ECAL_TRIGGER()subroutine ECAL_TRIGGER()+CDE,GCBANK,GCUNIT,SCLINK+CDE,GCBANK,GCUNIT,SCLINK*KEEP,GCFLAG.*KEEP,GCFLAG.

COMMON/GCFLAG/IDEBUG,IDEMIN,IDEMAXCOMMON/GCFLAG/IDEBUG,IDEMIN,IDEMAX,ITEST,IDRUN,IDEVT,IEORUN,ITEST,IDRUN,IDEVT,IEORUN

+ ,IEOTRI,IEVENT,ISWIT(10),IFINIT(20),N+ ,IEOTRI,IEVENT,ISWIT(10),IFINIT(20),NEVENT,NRNDM(2)EVENT,NRNDM(2)

** COMMON/HTCHK/ CLHTSCOMMON/HTCHK/ CLHTS INTEGER CLHTSINTEGER CLHTS

integer NUM(3) /1,1,1/integer NUM(3) /1,1,1/ integer NREJECT/0/integer NREJECT/0/ integer LEN/7/, REJ_OFFSET/7/integer LEN/7/, REJ_OFFSET/7/ integer ia, Linteger ia, L

* make the event "bad" by default:* make the event "bad" by default: IEOTRI=1;IEOTRI=1;

call hit_check('CALH','CSUP')call hit_check('CALH','CSUP') if(CLHTS.eq.2) IEOTRI=0if(CLHTS.eq.2) IEOTRI=0

call hit_check('CALH','CSDA')call hit_check('CALH','CSDA') if(CLHTS.eq.2) IEOTRI=0if(CLHTS.eq.2) IEOTRI=0

call hit_check('ECAH','ESCI')call hit_check('ECAH','ESCI') if(CLHTS.eq.2) IEOTRI=0if(CLHTS.eq.2) IEOTRI=0

call hit_check('ECAH','EHMS')call hit_check('ECAH','EHMS') if(CLHTS.eq.2) IEOTRI=0if(CLHTS.eq.2) IEOTRI=0 if(IEOTRI.eq.0) thenif(IEOTRI.eq.0) then call REBANK('/EVNT/PASS/MPAR',NUM,-LEN,L,ia)call REBANK('/EVNT/PASS/MPAR',NUM,-LEN,L,ia) if (L>0) IQ(L+REJ_OFFSET+2)=NREJECTif (L>0) IQ(L+REJ_OFFSET+2)=NREJECT NREJECT=0NREJECT=0 elseelse NREJECT=NREJECT+1NREJECT=NREJECT+1 endifendif

returnreturn endend

The GSTAR Web pageThe GSTAR Web page

Please visit the GSTAR Web page:Please visit the GSTAR Web page:

http://www.star.bnl.gov/STAR/comp/simu/gstar/gstar.htmlhttp://www.star.bnl.gov/STAR/comp/simu/gstar/gstar.html

for more information on the topics presented herefor more information on the topics presented here