pedro arce gamos june 16th, 2008 1 gamos: a user-friendly and flexible framework for geant4 medical...

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


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


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


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…



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



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



EASY TO USE:

Almost everything can be done through user commands

A good design, applying software engineering

techniques

Well documented



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


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


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



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



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)


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


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


Hits energy spectra (BGO crystals, NEMA 1994 phantom)


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

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


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


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 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, …)


VRML view of PET detector & NEMA 1994 phantom


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 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


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 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


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]

pedro arce gamos june 16th, 2008 1 gamos: a user-friendly and flexible framework for geant4 medical...

Documents