gamos: a user-friendly and flexible framework for geant4 medical applications pedro arce dubois
DESCRIPTION
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 - PowerPoint PPT PresentationTRANSCRIPT
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
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
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
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)
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)
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)
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)
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
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-inDEFINE_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
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
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
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
Pedro Arce GAMOS June 16th, 2008 13
GeneratorC++ 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)
Pedro Arce GAMOS June 16th, 2008 14
Physics
C++ code
• The usual GEANT4 way• Add one line to transform your class in a plug-inDEFINE_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
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
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
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$<$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
Pedro Arce GAMOS June 16th, 2008 18
Hits energy spectra (BGO crystals, NEMA 1994 phantom)
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
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
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
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
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 nameGmAnalysisMgr::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
Pedro Arce GAMOS June 16th, 2008 24
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 codefloat 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
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
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
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
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.
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
…
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, …
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
Pedro Arce GAMOS June 16th, 2008 33
PET ApplicationA 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, …)
Pedro Arce GAMOS June 16th, 2008 34
VRML view of PET detector & NEMA 1994 phantom
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
Pedro Arce GAMOS June 16th, 2008 36
Radiotherapy ApplicationA 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
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
Pedro Arce GAMOS June 16th, 2008 38
Documentation and examplesUser´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
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: [email protected]