1. Pedro Arce GAMOS June 16th, 2008 1 GAMOS: a user-friendly and flexible framework for GEANT4 medical applications Pedro Arce Dubois CIEMAT – Madrid - 16th June 2008

2. Pedro Arce GAMOS June 16th, 2008 2  Introduction  GAMOS objectives  plug-in’s  GAMOS components  Geometry  Generator  Physics  User actions  Sensitive detector and hits  Scoring  Histograms Index  Visualization  Utilities  Parameter management  Verbosity management  Input file management  PET application  Radiotherapy application  Examples  Summary

3. Pedro Arce GAMOS June 16th, 2008 3 The GEANT4 Toolkit is a very powerful code, continuously growing  But it is not easy to use  It needs a good knowledge of C++ and the GEANT4 code GAMOS is a framework designed to allow the user to Simulate a project with a minimal knowledge of GEANT4 and no need of C++ Easily add new functionality (even reuse GEANT4 code) and combine it with the existing functionality in GAMOS  It must be complete, flexible, easy to extend and easy to use GAMOS (Geant4-based Architecture for Medicine-Oriented Simulations)  plug-in’s

4. Pedro Arce GAMOS June 16th, 2008 4 COMPLETE:  Provide all the functionality for someone who wants to simulate a medical physics project  It is indeed impossible to cover all what all users may need  It must be extendible  It will keep growing with time… GAMOS (Geant4-based Architecture for Medicine-Oriented Simulations)

5. Pedro Arce GAMOS June 16th, 2008 5 FLEXIBLE:  Users should be able to control everything through user commands (= no recompiling)  Avoid hardcoding  Do not force users to call its detector “CRYSTAL”, or to have three levels of ancestors, or…  Do not force users to use your SD class, or your histogram format, or…  Different modules can be combined at users will  Change geometry but not the histograms  Change sensitive detector type but do not toch digitization  MODULAR: Each class, each module makes one and only one thing, clearly defined, but as general as possible  Keeping an eye on performance GAMOS (Geant4-based Architecture for Medicine-Oriented Simulations)

6. Pedro Arce GAMOS June 16th, 2008 6 EASY TO EXTEND:  Easy to add any new functionality  Mix seamlessy existing functionality together with new one  Add new modules without affecting others  Reuse any GEANT4 code  Based on “plug-in’s”  Convert new C++ code into user commands GAMOS (Geant4-based Architecture for Medicine-Oriented Simulations)

7. Pedro Arce GAMOS June 16th, 2008 7 EASY TO USE:  Almost everything can be done through user commands  A good design, applying software engineering techniques  Well documented GAMOS (Geant4-based Architecture for Medicine-Oriented Simulations)

8. Pedro Arce GAMOS June 16th, 2008 8  The main GAMOS program has no predefined components  At run-time user selects which components to load through user commands  User has full freedom in choosing components  User can define a component not foreseen by GAMOS  Write C++ and use it through an user command  Mix it with any other component For the plug-in's implementation in GAMOS it has been chosen the CERN library: SEAL GAMOS plug-in´s

9. Pedro Arce GAMOS June 16th, 2008 9 Three different ways to define it: C++ code:  The usual GEANT4 way  Add one line to transform your class in a plug-in DEFINE_GAMOS_GEOMETRY (MyGeometry); so that you can select it in your input macro /gamos/geometry MyGeometry Define it in ASCII files  The easiest way to define a geometry  Based on simple tags  Same order of parameters as corresponding GEANT4 classes Using one of the GAMOS examples  Simple PET detector can be defined through an 8-parameters file (n_crystals, crystal_x/y/z, radius, …) ... Geometry

10. Pedro Arce GAMOS June 16th, 2008 10  Based on simple tags, with same order of parameters as corresponding GEANT4 classes :ELEM Hydrogen H 1. 1. :VOLU yoke TUBE 62.*cm 820. 1.27*m Steel :PLACE yoke 1 expHall R0 0.0 0.0 370.*cm MATERIALS:  Isotopes  Elements  Simple materials  Material mixtures by weight, volume or number of atoms  G4NISTMaterials SOLIDS:  All “CSG” and “specific” solids  Boolean solids ROTATION MATRICES:  3 rotation angles around X,Y,Z  6 theta and phi angles of X,Y,Z axis  9 matrix values Geometry from ASCII files

11. Pedro Arce GAMOS June 16th, 2008 11 PLACEMENTS:  Simple placements  Divisions  Replicas  Parameterisations  Linear, circular or square  For complicated parameterisations example of how to mix the C++ parameterisation with the ASCII geometry file  Assembly volumes  Colour  Visualisation ON/OFF PARAMETERS:  Can be defined to use them later :P InnerR 12. :VOLU yoke TUBE $InnerR 820. 1270. G4_Fe  Arithmetic expressions : VOLU yoke BOX sin($ANGX)*2.+4 820. 1270. G4_Al Geometry from ASCII files

12. Pedro Arce GAMOS June 16th, 2008 12 UNITS:  Default units for each value  Each unit can be overridden by user  Include other files #include mygeom2.txt.  User can extend it: add new tags and process them without touching base code  Install and use it as another GEANT4 library G4VPhysicalVolume* MyDetectorConstruction::Construct(){ G4tgbVolumeMgr* volmgr = G4tgbVolumeMgr::GetInstance(); volmgr->AddTextFile(filename); // SEVERAL FILES CAN BE ADDED return = volmgr->ReadAndConstructDetector();  GEANT4 in memory geometry -> ASCII files HISTORY:  In use to build GEANT4 geometries since 10 years ago  An evolving code…  Built CMS and HARP experiments Geometry from ASCII files

13. Pedro Arce GAMOS June 16th, 2008 13 Generator C++ code The usual GEANT4 way Add one line to transform your class in a plug-in DEFINE_GAMOS_GENERATOR(MyGenerator); so that you can select it in your input macro /gamos/generator MyGenerator GAMOS generator Combine any number of single particles or isotopes decaying to β +, β -,  For each particle or isotope user may select by user commands a combination of time, energy, position and direction distributions Or create its own and select it by a user command (transforming it into a plug-in)

14. Pedro Arce GAMOS June 16th, 2008 14 Physics C++ code The usual GEANT4 way Add one line to transform your class in a plug-in DEFINE_GAMOS_PHYSICS(MyPhysicsList); so that you can select it in your input macro /gamos/physicsList MyPhysicsList GAMOS physics list Electromagnetic physics list Hadronic physics list (based on hadrotherapy advanced example) User can combine different physics lists for photons, electrons, positrons, protons and ions Dummy physics list for visualisation

15. Pedro Arce GAMOS June 16th, 2008 15 User actions User can have as many user actions of any type as he/she wants User can activate a user action by a user command GAMOS user actions or her/his own Just adding a line after the user action to transform it into a plug-in DEFINE_GAMOS_USER_ACTION(MyUserAction); /gasos/userAction MyUserAction  Many user actions in GAMOS providing different functionality

16. Pedro Arce GAMOS June 16th, 2008 16 Sensitive Detectors To produce hits in GEANT4 a user has to: Define a class inheriting from G4VSensitiveDetector Associate it to a G4LogicalVolume Create hits in the ProcessHits method Clean the hits at EndOfEvent In GAMOS you can do all this with a user command /gamos/assocSD2LogVol SD_CLASS SD_TYPE LOGVOL_NAME SD_CLASS: GAMOS or user C++ class SD_TYPE: an identifier string, so that different SD/hits can have different treatment User can create his/her own SD class, and make it a plug-in

17. Pedro Arce GAMOS June 16th, 2008 17 Hits A GAMOS hit has the following information G4int theDetUnitID; ID of the sensitive volume copy G4int theEventID; G4double theEnergy; G4double theTimeMin; time of the first E deposit G4double theTimeMax; time of the last E deposit G4ThreeVector thePosition; std::set$ $ theTrackIDs; list of all tracks that contributed std::set$ $ thePrimaryTrackIDs; list of all ‘primary´tracks that contributed std::vector$ $ theEDepos; list of all deposited energies G4String theSDType; User can create his/her own hit class

18. Pedro Arce GAMOS June 16th, 2008 18 Hits energy spectra (BGO crystals, NEMA 1994 phantom)

19. Pedro Arce GAMOS June 16th, 2008 19 Detector effects Resolutions - Energy, position and time Measuring time - A detector is not able to separate signals from different evetns if they come close in time Dead time - When a detector is triggered, this detector (or even the whole group it belongs to) is not able to take data during some time The three can be set by the user in the input macro A different time for each SD_TYPE /gamos/setParam SD:Hits:MeasuringTime:Calor 10. ns

20. Pedro Arce GAMOS June 16th, 2008 20 Digits and Reconstructed hits If you need much detail in simulating your detector, you should Convert your hits in digital signals (equal to the ones provided by hardware) Trigger, Pulse simulation, Sampling, Noise, … Reconstruct the required quantities (position, energy, time, …) This is very detector specific  it is not possible to provide a general solution GAMOS just provide a simple example to convert hits into reconstructed hits 1 hit  1 rechit Merge hits close enough Same set of sensitive volumes Closer than a given distance Digitizers and RecHitBuilders are plug-in’s so user can write her/his own and integrate it

21. Pedro Arce GAMOS June 16th, 2008 21 Scoring Many quantities can be scored with a few commands Define in which volumes the scoring is done Select scorer(s) Select filter(s) if wanted Select printer format(S) if wanted (or use default) Select indexer(s), i.e. a different scoring for each copy number, one unique for all, … (or use default) Scorers, filters, printers and indexers are plug-in’s You can use GAMOS ones or use your own ones Several scorers can be defined at the same time for each volume(s), with several filters and several printers

22. Pedro Arce GAMOS June 16th, 2008 22 Scoring (II) Available scorers Track length GmG4PSTrackLength GmG4PSPassageTrackLength Deposited energy GmG4PSEnergyDeposit GmG4PSDoseDeposit Current and flux GmG4PSFlatSurfaceCurrent GmG4PSCylinderSurfaceCurrent GmG4PSSphereSurfaceCurrent GmG4PSPassageCurrent GmG4PSFlatSurfaceFlux GmG4PSCylinderSurfaceFlux GmG4PSSphereSurfaceFlux GmG4PSCellFlux GmG4PSPassageCellFlux Others GmG4PSMinKinEAtGeneration GmG4PSNofSecondary GmG4PSNofStep GmG4PSCellCharge GmG4PSTrackCounter GmG4PSNofCollision GmG4PSPopulation GmG4PSTermination Available filters GmG4SDChargedFilter GmG4SDNeutralFilter GmG4SDParticleFilter GmG4SDKineticEnergyFilter GmG4SDParticleWithEnergyFilter Available printers GmPSPrinterDefault GmPSHistoPDD GmPSPrinter3ddose GmPSPrinterWeidose Available indexers GmPSIndexerByAncestors GmPSIndexerBy1Ancestor GMPSIndexerByVolume

23. Pedro Arce GAMOS June 16th, 2008 23 Histograms Originally based on CERN package PI/AIDA  But PI/AIDA is not supported any more Currently own format or ROOT Output in CSV(Comma Separated Value) or ROOT Same code to create and fill histograms independent of the format GAMOS takes care of writing the file in the chosen format at the end of job GmAnalysisMgr keeps a list of histograms so that they can be accessed from any part of the code, by number or name GmAnalysisMgr::GetInstance(“pet”)->GetHisto1(1234)->Fill(ener); GmAnalysisMgr::GetInstance(“pet”)->GetHisto1(“CalorSD: hits energy”)->Fill(ener); There can be several files, each one with its own histograms When creating an histogram, user chooses file name

24. Pedro Arce GAMOS June 16th, 2008 24

25. Pedro Arce GAMOS June 16th, 2008 25 Parameter management GmParameterMgr helps the user to define and use a parameter A parameter is defined in the input macro /gamos/setParam SD:Hits:EnergyResolution 0.1 User can get its value in any part of the code float enerResol = GmParameterMgr::GetInstance() ->GetNumericValue(“SD:Hits:EnergyResolution”,0.);  IF not provided in the input macro it takes the default value Parameters can be number, strings, list of numbers or list of strings

26. Pedro Arce GAMOS June 16th, 2008 26 Verbosity management  User can control the verbosity of the different GAMOS components independently /gamos/verbosity GamosGenerVerb 3 /gamos/verbosity GamosSDVerb 2 Can be used in new code trivially G4cout << AnaVerb(3) << “creating my histograms” << G4endl; User can easily define its own verbosity type controlled by a user command 5 + 1 levels of verbosity SilentVerb = -1 ErrorVerb = 0 (default) WarningVerb = 1 InfoVerb = 2 DebugVerb = 3 TestVerb = 4

27. Pedro Arce GAMOS June 16th, 2008 27 Verbosity management (II) TrackingVerbose by event and track number: It can be selected for which events and track numbers the “/tracking/verbose” command becomes active /gamos/userAction TrackingVerboseUA /gamos/setParam TrackingVerbose:EventMin 1000 /gamos/setParam TrackingVerbose:EventMax 1010 /gamos/setParam TrackingVerbose:TrackMin 10 /gamos/setParam TrackingVerbose:TrackMax 20 Event counting: Prints the number of simulated events with the number of tracks in the last event and accumulated (useful when you are waiting for long times without nothing happening…) /gamos/userAction TrackCountUA /gamos/setParam TrackCount:EachNEvent 1000

28. Pedro Arce GAMOS June 16th, 2008 28 Input file management  Some algorithms need to read in a data file In GAMOS the file does not have to be on the current directory Easier to use the same file in several applications  GAMOS_SEARCH_PATH variable contains the list of directories where the file is looked for User can add more directories

29. Pedro Arce GAMOS June 16th, 2008 29 Optimising your simulation  Apart from the GEANT4 possibilities Different physics lists Production cuts User limits Parameters controlling precision of electromagnetic physics Cross section number of bins Cross section limit for linear approximation Rover range / final range Multiple scattering range factor Multiple scattering geometry factor Skin definition for single scattering … etc.

30. Pedro Arce GAMOS June 16th, 2008 30 Optimising your simulation  GAMOS offers several utilities to help you  Production cuts and user limits can be set with user commands  Many histograms to understand what is passing in your simulation, selectable by user commands  Automatically obtaining optimal production cuts  Two bremsstrahlung splitting techniques selectable with user commands  …

31. Pedro Arce GAMOS June 16th, 2008 31 Optimising production cuts Which is the maximum production cut in each region that I can use without affecting sensibly my results? Define what is my results (track traverses linac and reaches phantom, track produces a hit in a PET detector, …) Define what is affecting sensibly (produce all possible ‘good’ tracks, allow not to produce a few becaue it is not much CPU, …)  GAMOS checks if a track satisfies the required condition  It translate the original energy (when track is created) to range in the material where created  You know then that if you use a cut bigger than this range, this particle would have not been created  It does the same for the track mother, grandmother, …

32. Pedro Arce GAMOS June 16th, 2008 32 Optimising production cuts  At the end of the run it tells you which is the minimum range for each particle type, each region and each creator process (plus the minimum for all processes) : this is the cut you should use  It also gives you the histograms of all calculated ranges so that you can use another cut and know how many ‘good’ particles you would not create  To use it, just select one of the user actions PETProdCutsStudyUA, RTProdCutsStudyUA  Or create your own defining your condition

33. Pedro Arce GAMOS June 16th, 2008 33 PET Application A set of user commands to help you in doing a PET detector simulation  Simple PET detectors can be built with a few parameters (crystal size, number of crystals, radius, …)  You can also use easy ASCII format  Sensitive detectors/hits of various types  Histograms with detailed hits information  Reading/writing of hits for later reprocessing  Framework for hits digitisation and reconstruction  Several simple reconstructed hits builders available  Histograms with detailed reconstructed hits information  Writing of reconstructed hits for sinogram building software (STIR, …)

34. Pedro Arce GAMOS June 16th, 2008 34 VRML view of PET detector & NEMA 1994 phantom

35. Pedro Arce GAMOS June 16th, 2008 35 PET Application  Detector effects  Energy resolution  Time resolution  Position resolution  Measuring time  Dead time (parallelizable/ non parallelizable)  PET event classification  Real and scattered events  Number of events with PET line far from vertex  Histograms about calssification  Histograms about positron/photon history

36. Pedro Arce GAMOS June 16th, 2008 36 Radiotherapy Application A set of user commands to help you in doing a teletherapy simulation  Geometry  Simple ASCII files to build linac geometry  BEAMnrc (EGSnrc) to GAMOS automatic geometry conersion  Reading of DICOM files  GEANT4 format  DOSXYZnrc format  Definition of simple phantoms with a few user commands  Writing phase space files in IAEA format  Several phase psaces at different Z planes in the same job  Optional killing of particles after last Z plane  Optianal saving of phase space headers to avoid losing all if job has problems

37. Pedro Arce GAMOS June 16th, 2008 37 Radiotherapy Application  Reading phase space files in IAEA format  Optional displacement and rotation of phase spaces  Optional reusing particles and recycling full phase space file  Optional mirroring of particles when reusing  Dose in phantoms voxels  Automatic scoring of dose and dose errors with user commands  Several formats (non-exclusive)  Simple ASCII list of voxel number / dose / dose error  Dose histograms (PDD, profiles, …)  DOSXYZnrc compatible format  Storing of dose & dose square for proper sumation of dose files  Linac simulation optimisation  Automatic calculation of optimal production cuts (RTProdCutsStudyUA)  Killing of particles with too big X/Y (automatic or user-defined limits)  Several bremsstrahlung splitting options

38. Pedro Arce GAMOS June 16th, 2008 38 Documentation and examples User´s guide:  A 120-page guide with detailed explanation of all GAMOS utilities Test examples:  Aimed to test that installation is OK Tutorials:  Detailed step by step tutorials on several topics  PET tutorial  Radiotherapy tutorial  Plug-in tutorial Examples of each type of plug-in

39. Pedro Arce GAMOS June 16th, 2008 39 Summary  GAMOS is a plug-in based, user-friendly framework based on GEANT4 Tries to hide the complexity of GEANT4 and at the same time allows to use all the GEANT4 functionality through the use of plug- in’s GAMOS core is application independent Several medical applications are being built on top of GAMOS core Other application can be built Further information: pedro.arce@ciemat.es