Analysis

GRAS adopts a modular approach to the analysis of the impact of radiation to the systems. The user can select to perform in parallel several analysis types on independent set of volumes or volume boundaries. All analysis details can be specified via UI script commands, from the type of analysis to be performed, to the volumes to which it is applied, to the output unit and format.

More details on the analysis modules, on their usage and on the available analysis types can be found in the [#AnalysisTypes] section below.

Script example:

/gras/analysis/tid/addModule doseDetector
/gras/analysis/tid/doseDetector/addVolume Detector
/gras/analysis/tid/doseDetector/addVolumeInterface World  Detector
/gras/analysis/tid/doseDetector/setUnit Rad
/gras/analysis/tid/doseDetector/verbose 2

Analysis in detail

Existing analysis types include cumulative effects such as Total Ionizing Dose (TID) or Total Non Ionizing Dose (TNID), to study performance degradation in scientific detectors, commercial payload components or service elements such as solar arrays. Specific modules have been developed for the evaluation of the effects of radiation to humans: “Dose Equivalent” analysis, based on LET quality factors (QF); and “Equivalent Dose” based on the incident particle weights are available in GRAS, with a choice among several factor functions from existing protocols in the literature. Fluence of primary or secondary particles crossing a volume boundary is tallied in the Fluence modules. In addition to the total integrated fluence by particle, individual energy spectra are recorded for the particle types requested by the user. Specific modules implementing single event effects models available in the literature have been developed. Transient effects are addressed at present by Pulse Height, included in the dose modules, an LET module and a “track length” analysis.

All analyses can be applied to any user defined set of volumes or surfaces, chosen among those present in the geometry model.

Results are saved as histograms or “tuples” (tabular data for later analysis), while basic summary quantities are also output in simple text format. Users also have the choice of the units for the result output.

Analysis module

The core part of the analysis is constituted by the “analysis modules”, which can be inserted by the user via UI commands to perform the individual analysis tasks. The modular approach keeps analysis types independent and isolates each complete analysis inside one class.

After the setup of the analysis, the user can output to the terminal the main parameters of the inserted volumes with the Command:/gras/analysis/describe, with the optional verbosity integer parameter to increase/decrease the level of detail.

Script example:

/gras/analysis/tid/addModule doseDetector
...
/gras/analysis/describe 2

“Object oriented” scripting

The analysis can be performed in parallel by many modules during the same simulation, and each module, even if of the same type (e.g. “tid”) can have different parameters (e.g. it can be applied to different volumes). To offer an intuitive access to all parameters of each individual module,

GRAS adopted an “object oriented” scripting interface, following the example of the GATE application 11. Each time a module is created, a new set of UI scripting commands are automatically created. These commands contain the module name in them, and are therefore unique to the module.

Script example:

/gras/analysis/tid/addModule doseDetector1
/gras/analysis/tid/doseDetector1/addVolume Detector1
/gras/analysis/tid/addModule doseDetector2
/gras/analysis/tid/doseDetector2/addVolume Detector2

Volumes and boundaries for the analysis

All analyses can be applied to any user defined set of volumes or surfaces, chosen among those present in the geometry model. Some modules perform the analysis “in the volumes”, others “at the boundaries”, others combine the two to get more advanced results.

The user can insert (for each module, independently) a series of volumes and/or a series of boundaries at which the relevant quantities are tallied, thus obtaining the results in complex shapes automatically (and with the related uncertainty). This avoids the need to perform several parallel analyses and combine results and uncertainties at post processing.

The wildcard symbol ‘*’ can be used in volume names (e.g. * identifies all volumes including the “world” volume, or ‘det*’ all volume names beginning with ‘det’).

Script example:

/gras/analysis/tid/addModule doseDetector
/gras/analysis/tid/doseDetector/addVolume Detector1
/gras/analysis/tid/doseDetector/addVolume Detector2
/gras/analysis/tid/doseDetector/addVolume *Target*
/gras/analysis/tid/doseDetector/addVolumeInterface Box Detector1
/gras/analysis/tid/doseDetector/addVolumeInterface * Detector2

If necessary, in case the selection of the volumes by name is not unique, the user can specify as additional parameters, specific copy numbers in the definition of volumes and volume interfaces. In case the copy number must be ignored, the user can use the value -1: in this case, all volume copies are accepted.

Command:syntax:

/gras/analysis/tid/doseDetector/addVolume volume_name [copy_number]
/gras/analysis/tid/doseDetector/addVolumeInterface volume_name1 volume_name2
[copy_number1] [copy_number2]

Script example:

/gras/analysis/tid/doseDetector/addVolume Box1
/gras/analysis/tid/doseDetector/addVolume Box2 2
/gras/analysis/tid/doseDetector/addVolumeInterface * Box1 -1 1

Results by particle type

For many analysis types the results for can be split into contributions coming from the different “incident particle types”. The definition of “incident” particle depends on the track crossing of user defined volume interfaces. A volume interface is the boundary between 2 volumes. When a track is crossing the boundary, its type is stored as “incoming particle type” and all secondary particles produced by that “incident” particle will be given the same “incident particle type”, unless they pass one of the user defined boundaries themselves.

The mechanism is applied for example to all cumulative effect analyses. As an example, it is used in the “TID Modules”, to distinguish the contribution to the TID from different “incident” particle types, as opposed to different “local” types of radiation depositing a dose at a point. The usefulness of this method is apparent when analyzing shielding effectiveness from the separate effects of charged and neutral particles, as the latter only deposit energy locally through the charged products after interaction. Typical applications are the separate contributions after shielding given by input electrons and generated Bremsstrahlung photons, or by spallation neutrons produced from hadronic interactions.

Script example:

/gras/analysis/<module_type>/<module_name>/addVolumeInterface Volume1 Volume2

Uncertainties

Visualisation

As introduced in Section 2.6.2, the visualisation of the events can be triggered by the analysis modules. The UI Command setVisTrigger is available to set/unset this option for each module. By default the modules do not trigger the event visualisation.

Script example:

/gras/analysis/<module_type>/<module_name>/setVisTrigger [true | false]

/gras/event/drawEvents trigger
/vis/drawOnlyToBeKeptEvents

Normalisation

GRAS offers different types of normalisation of the simulation results. By default all the simulation results are simply divided by the number of primary events, but the user can also select no normalisation at all, a normalisation to compute the geometric factor (sensitive area) of the computed signals, or a normalisation to the current/flux of particles passing trough the primary source surface. The type of normalisation can be selected by the command:

/gras/analysis/setNormalisationType   typeOfNorm (NONE, NONORMALIZATION, GEOMETRIC_FACTOR, GEOFACTOR TO_SOURCE_SURFACE, TOFLUENCE,
                                                  FLUENCE, TOFLUENCE, PEREVT, PER_NB_EVENTS, PER_NB_EVT, PEREVENT)

Difference between flux and current

When speaking of normalisation, it is important to remind the difference between the concept of flux and current in particle physics. The current refers to the number of particles going trough a given surface divided by the surface area, per time unit. The flux refers to the number of particle going trough a surface element perpendicular to the particle directions divided over the area of the surface element, per time unit. The essential difference comes form the fact that in the flux concept the surface element trough which particle are counted is always perpendicular to the particle direction, while in the current concept the element surface is fixed. In the isotropic case the omnidirectional flux is 4 times the current.

Geometric factor normalisation

In this normalisation mode the results of the simulation are multiplied by the normalisation factor:

fN = S/4/Nb_prim

with ‘’S’’ the area of the source surface and ‘’Nb_prim’’ the number of primary particles generated from the source. In the case of an isotropic source, the user has to multiply the simulation results by the omnidirectional fluence integrated over the spectrum used for the simulation, in order to get the results normalised to the external flux. For a non isotropic case the geometric factor multiplied by 4 times the current going trough the primary source surface gives the final normalised results.

Normalisation to external flux or current

In this normalisation mode the results are normalised to a primary source fluence that is defined by the user through the command:

/gras/analysis/setSourceFluence fluence fluence_unit (1/cm2 1/m2 1/km2 1./cm2 1./m2  1./km2 cm-2 km-2 m-2)

The user can specify if the fluence is related to an isotropic omnidirectional flux or to the current going trough the primary surface. This is done by using the command

/gras/analysis/setSourceFluenceType (CURRENT FLUX)

By default the source fluence type is set to ‘’FLUX’’. In this ‘’FLUX’’ case the normalisation factor considered in the simulations is given by:

fN = Fluence*S/4/Nb_prim

It is importnat to note that for the for the ‘’FLUX’’ case it is assumed that the external flux is isotropic. Therefore the primary angular distribution should be set to a ‘’cosine’’ law relative to the normal of the source surface. This is done by using the following ‘’gps’’ commands

/gps/ang/type   cos
/gps/ang/mintheta 0. degree
/gps/ang/maxtheta 90. degree

This cosine law explains the 1/4 factor in the normalisation.

In the case that the fluence refers to a ‘’CURRENT’’ the normalisation factor is given by:

fN = Fluence*S/Nb_prim

In this case no restriction is needed considering the angular distribution, as the user defines through the current fluence the number of particle going trough the source surface per unit area.

Area of the primary source surface

For the “geometric factor” or “fluence” normalisation mode the area of the source surface has to be known to compute the normalisation factor. This area can be computed automatically by GRAS providing that the type of source selected in ‘’gps’’ is either PLANAR or SURFACE. The user can decide to switch on/off this automatic computation by using the command:

/gras/analysis/setSourceSurfaceType AUTO/USER

where in the AUTO mode the area is computed automatically while in the USER mode the area is taken is defined with the command

/gras/analysis/setSourceSurface area area_unit (cm2 m2)

Special case: MULASSIS primary source surface

In case the MULASSIS-type of geometry is used, the MULASSIS geometry constructor, in addition to the layered geometry volumes definition, also pre-sets the GPS parameters for the specific selected geometry shape, to define a uniform irradiation.

The actual source position type in the MULASSIS is in fact always point-like, located at the edge of the first layer, with emission aimed into the layers. Thanks to the symmetry of the geometries this configuration mimics a uniform irradiation from the external surface of the layered structure.

Because of the point-like distribution, the area of the surface cannot be automatically obtained from GPS, and it has to be forced in GRAS based on the concept behind the individual MULASSIS cases:

  • SLAB: irradiation from one side only of the slab square surface.

Source surface set to the area of the square. - SPHERE: irradiation from the surface of external spherical layer. Source set to the external area of the sphere. - CYLINDER: irradiation from the side of the cylinder. Source set to the surface of the cylinder.

The geometry parameters needed to compute these surface areas are automatically retrieved from the MULASSIS geometry constructor.

Minor detail: the primary source vertex is not located exactly at the surface of the first layer, but rather at a small distance in front of the surface, so that the fluence of the particles entering the first layer through the first surface can be properly detected. This small correction is taken into account in the definition of the source surface area for the normalisation.

An isotropic irradiation in space can then be simulated by the GRAS user by using a cosine-law biased angular distribution.

Output units

The results are internally computed and stored in Geant4 units. However, the user can choose the unit he prefers for the result printout via a UI command. A series of appropriate units is available for each module, according to the analysis type.

Script example:

/gras/analysis/tid/doseDetector/setUnit Rad

Histogramming

For the analysis modules that produce histograms and/or tuples, GRAS uses the G4GenericAnalysisManager class to book, fill and store the analysis output.

The user can specify the stem of the name of the files used by GRAS to store the output (e.g. gras_histograms) with the command: /gras/histo/fileName while the suffix of each file is automatically appended by GRAS. The output will be produced in both GRAS CSV (variables and histograms) and ROOT (histograms and tuples) files.

Script example:

/gras/histo/fileName myfile

The user can modify some parameters of the histograms (number of bins and range) via UI commands: it is possible to select the histogram by progressive number or by name with the two UI commands /gras/histo/setHisto and /gras/histo/setHistoByName. The GRAS internal naming scheme foresees that each analysis module assigns to its histograms names composed of <moduleName>_<histogramName> (e.g. doseDetector_tid).

Script example:

/gras/histo/setHisto 1 100 0. 20.
/gras/histo/setHistoByName doseDetector_tid 100 0. 20.

Users can choose between linear (lin) and logarithmic (log) binning schemes. By default a linear binning scheme is used. The lin/log option can be specified via the two UI commands /gras/histo/setHisto and /gras/histo/setHistoByName. The log binning can only be selected for non negative bin edges.

Script example:

/gras/histo/setHisto 1 100 0. 20. MeV lin
/gras/histo/setHistoByName doseDetector_dose 100 0. 20. MeV log

In the special case of the Fluence analysis the GRAS internal naming scheme is slightly different, and names are composed of <moduleName>_<histogramName>_<particleName> (e.g. fluenceDetector_fluence_proton).

Script example:

/gras/histo/setHisto fluenceDetector_fluence_proton 100 0. 20.

The histogram and/or the tuple output can be enabled/disabled by module with the commands: /gras/analysis/<analysis_type>/<module_name>/bookHistos and /gras/analysis/<analysis_type>/<module_name>/bookTuples. Specific histograms containing results as a function of the primary particle (kinetic) energy are disabled by default and can be enabled/disabled by module with the command: /gras/analysis/<analysis_type>/<module_name>/bookHistosVsPrimary.

Script example:

/gras/analysis/tid/doseDetector/bookHistos          [true | false]
/gras/analysis/tid/doseDetector/bookHistosVsPrimary [true | false]
/gras/analysis/tid/doseDetector/bookTuples          [true | false]

Histograms are created by analysis modules at module initialisation phase, which is started at the latest at begin of run. Users can force earlier initialisation of single modules with the command: /gras/analysis/<analysis_type>/<module_name>/initialise. Initialisation of all inserted modules at once can be obtained with the UI Command: /gras/analysis/initialise. This enables modifications of the histogram parameters with the previously described UI commands /gras/histo/setHisto and /gras/histo/setHistoByName before the begin of run.

Analysis types

GRAS/trunk/r2242