390 likes | 633 Views
GAMOS: a user-friendly and flexible framework for GEANT4 medical applications Pedro Arce Dubois CIEMAT – Madrid - 16th June 2008. Index. Visualization Utilities Parameter management Verbosity management Input file management PET application Radiotherapy application Examples
E N D
GAMOS: a user-friendly and flexible framework for GEANT4 medical applications Pedro Arce Dubois CIEMAT – Madrid - 16th June 2008
Index • Visualization • Utilities • Parameter management • Verbosity management • Input file management • PET application • Radiotherapy application • Examples • Summary • Introduction • GAMOS objectives • plug-in’s • GAMOS components • Geometry • Generator • Physics • User actions • Sensitive detector and hits • Scoring • Histograms
GAMOS (Geant4-based Architecture for Medicine-Oriented Simulations) 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++ • Easilyadd 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 plug-in’s
GAMOS (Geant4-based Architecture for Medicine-Oriented Simulations) 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) 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) 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) EASY TO USE: • Almost everything can be done through user commands • A good design, applying software engineering techniques • Well documented
GAMOS plug-in´s • 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
Geometry 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 from ASCII files • 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 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 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
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 β+, β-, g • 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)
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
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
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
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$<$G4int$>$ theTrackIDs; list of all tracks that contributed • std::set$<$G4int$>$ thePrimaryTrackIDs; list of all ‘primary´tracks that contributed • std::vector$<$GamosEDepo*$>$ theEDepos; list of all deposited energies • G4String theSDType; • User can create his/her own hit class
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
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
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
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
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 • GmAnalysisMgrkeeps 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
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
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
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
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
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.
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 • …
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, …
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
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, …)
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
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
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
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
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