Generic factors analysis

Module type name (to be used for the module commands): generic_factors

Description

The Generic factors module is an analysis module that can read a user defined file with factors/curves and accordingly calculate some variable.

From an input file a curve can be read (conversion coefficients), while multiple weighting factors can be read associated to the curve.

Input file

The input file has to be in the Spenvis CSV format. It needs an information block with general information for the curve to be read and multiple blocks, each including the curve or weighting factors per particle.

Files distributed with GRAS are installed in <GRAS_INSTALL_PREFIX>/share/data/ for reference.

Information block

The Input file needs an Information block, where details of the curve/factors to be read are set. The information block is identified by a starting comment line Curve Info. Additionally, the following information are read in the form of !MetaVariables:

MetaVariable name	Format	Available options	Notes
Curve Name	G4String		The name of the curve to be read
Curve Description	G4String		Description of the curve to be read (optional)
Curve Reference	G4string		Reference for the curve (optional)
Curve Effective At	G4String	Volume, Interface or Volume-Interface	Specifies if the calculation will take place for steps inside a Volume, on a Volume interface, or for steps inside a volume but get attributed to the particle crossing an interface (with the factor of the particle on the interface)
Curve Specifiers Name	G4String	Material, Tissue, …	Name/type of specifiers
Curve Specifiers Values	G4String	G4_Si, Male Red bone marrow, …	Name of the available specifiers
Particles	G4string	Geant4 particle names, all (for all particles), rest (for remaining particles if at least one specific one is given)	Particle names for which the curve/factors are applicable
Weighting Factors	G4String		Name of Weighting factors to be read if more than one (e.g. ICRP60, NASA, …)
Normalisation Quantity	G4String	Surface, Volume, Mass, None	Value to which the result will be normalized if needed
Multiplication Quantity	G4String	Energy Deposition, Step Length, None	Value that will multiply the result

Curve block

Each curve block will have the conversion coefficients for a specific particle. In order to identify a curve block a starting comment line Data is needed. Additionally the following information is given in the form of Metavariables.

MetaVariable name	Format	Available options	Notes
Particle	G4String	One of the particles from the information block	The name of particle for the data to be read
Data type	G4String	Curve, Step	Type of data. Curve for data points to be spline interpolated, step for step function data

For the data of the curve the following variables are defined and read.

Dependency Quantity	G4String, Unit and Dimension	Kinetic Energy, MidStep Kinetic Energy, Energy Deposition/Step Length	The value on which the curve is dependent on with its unit and its dimension (1 for curve type, 2 for step)
Quantity	G4String, Unit and Dimension		Output quantity name of the curve with its units and its dimension (it has to be the same as the Nb of specifiers of the Information block)

The data lines are read per point and have the format:

Data Type: Curve

<Dependency Quantity value>, <Quantity Dimension> Column of <Dependency Quantity Value>

Data Type: Step

<Min Dependency Quantity value>, <Max Dependency Quantity value>, <Quantity Dimension> Columns of <Dependency Quantity Value>

Weighting factors block

The Weighting factors block is similar to the curve block with the differences that the Weighting Factors Data comment should be present instead of Data and that an additional !MetaVariable is needed to specify the name of the weighting factor that is read (in case multiple exist).

MetaVariable name	Format	Available options	Notes
Weighting Factor	G4String	One of the weighting factors declared in the information block	The name of weighting factors to be read

The data have also a similar format as in the curve block, with the difference that the Quantity variable is named Weighting Factors Quantity.

Available Units

The module accepts as units all the G4 units.

Specific Module commands

In the following commands the <moduleType> can be generic_factors (for the generic analysis module), or any of the other Module type name for the modules that are based on this one (e.g. dose_equivalent, tnid, …).

/gras/analysis/generic_factors/<moduleName>/readCurveSetFile <fileName>

Specify a SpenvisCSV file to read the factors

/gras/analysis/<moduleType>/<moduleName>/setCurveSet <curveName>

Specify the curve name to be used, in case more than one files are read (e.g. Summers, ROSE, …)

/gras/analysis/<moduleType>/<moduleName>/setCurve <curveName>

Specify the curve name to be used, in case more than one files are read (e.g. Summers, ROSE, …)

/gras/analysis/<moduleType>/<moduleName>/setSpecifier <specifierName>

Specify the specifier name to be used for the user defined volumes, in case more than one is available (e.g. G4_Si, InP, Male Red bone marrow, …)

/gras/analysis/<moduleType>/<moduleName>/tallyIndividualSpecifiers [true || false]

Specifies if separate tallies are created for each of the different specifiers

/gras/analysis/<moduleType>/<moduleName>/setWF <weightingFactorsName>

Specifies the weighting factors name to be used for the user defined volumes, in case more than one is available (e.g. NASA, ICRP60, …)

/gras/analysis/<moduleType>/<moduleName>/tallyIndividualVolumes [true || false]

Specifies if separate tallies are created for each of the added volumes

/gras/analysis/<moduleType>/<moduleName>/tallyIndividualParticles [true || false]

Specifies if separate tallies are created for each of the different particles

/gras/analysis/<moduleType>/<moduleName>/additionalTuple [true || false]

If true, more information is recorded into an additional tuple

/gras/analysis/<moduleType>/<moduleName>/alongStepInfo [true || false]

If true, more information is recorded into the step filled tuple

Output

In the following sections for the generic case GFMtype is GenericFactors. In the other analysis modules that are based on this one the specific GFMtype is mentioned.

Scalars (only in CSV file)

<GFMtype> IN <specifierName>

• average <GFMtype> value in the user specified volumes or on the user specified interfaces treated as <specifierName> set by the setSpecifier command

• Always active

• Precision Calculations This variable is registered for precision calculations if activated

<GFMtype> IN <specifierType>

• average <GFMtype> value in the user specified volumes or on the user specified interfaces treated as <specifierName> for all the specifier names available

• Activated by the tallyIndividualSpecifiers command

<GFMtype> PER PARTICLE SPECIES IN <specifierName>

• average <GFMtype> value per particle in the user specified volumes or on the user specified interfaces treated as <specifierName> set by the setSpecifier command

• Activated by the tallyIndividualParticles command

<GFMtype> PER PARTICLE SPECIES IN <specifierType>

• average <GFMtype> value per particle in the user specified volumes or on the user specified interfaces treated as <specifierName> for all the specifier names available

• Activated by the tallyIndividualParticles and tallyIndividualSpecifiers command

<GFMtype> FOR INDIVIDUAL VOLUMES IN <specifierName>

• average <GFMtype> value per particle in the user specified volumes or on the user specified interfaces treated as <specifierName> set by the setSpecifier command

• Activated by the tallyIndividualVolumes command

<GFMtype> FOR INDIVIDUAL VOLUMES IN <specifierType>

• average <GFMtype> value per particle in the user specified volumes or on the user specified interfaces treated as <specifierName> for all the specifier names available

• Activated by the tallyIndividualVolumes and tallyIndividualSpecifiers command

Histograms (in CSV and ROOT files)

Controlled by the bookHisto command (default is active).

<GFMtype> SPECTRUM

• Name (for the setHistoByName command): <moduleName>_<moduleType>

• Spectrum of the <GFMtype> value per event in all the specified volumes or on all the specified volume interfaces treated as <specifierName> set by the setSpecifier command

• Always active

<GFMtype> SPECTRUM IN VOLUME <volumeName>

• Name (for the setHistoByName command): <moduleName>_<moduleType>_perVolume_<volumeName>

• Spectrum of the <GFMtype> value per event per specified volume or volume interface treated as <specifierName> set by the setSpecifier command

• Activated by the tallyIndividualVolumes command

<GFMtype> VS PRIMARY KINETIC ENERGY

• Name (for the setHistoByName command): <moduleName>_<moduleType>_vs_primary_kine

• Spectrum of the <GFMtype> value of event in all the specified volumes or on all the specified volume interfaces per primary kinetic energy- Always active

<GFMtype> SPECTRUM VS PRIMARY KINETIC ENERGY

• Name (for the setHistoByName command): <moduleName>_<moduleType>_spectrum_vs_primary_kine

• 2D Spectrum of the <GFMtype> value of event in all the specified volumes or on all the specified volume interfaces VS the primary kinetic energy

• Activated by the book2DHistoVsPrimary command (or the obsolete bookHistosVsPrimary command)

Tuples (only in ROOT file)

Controlled by the bookTuples (default is active). brBy default for curves Effective At Interface the step tuple is active, while the event tuple is inactive. For curves Effective At Volume and Effective At Volume-Interface the step tuple is inactive and the event tuple is active. To activate the inactive tuple the additionalTuple command has to be issued.

Event_<moduleName>

• Name: <moduleName>_EventTuple_<GFMtype>

• Information by event

• Columns:

  • EventID: event ID

  • primarykine: primary kinetic energy of the event

  • <moduleType>: cumulative value of <moduleType> of the event

  • weight: weight of the event

• By issuing the detailedTuples command the following columns are also available

  • primaryx: x of the primary vertex

  • primaryy: y of the primary vertex

  • primaryz: z of the primary vertex

  • primarymomx: x component of the momentum of the primary particle

  • primarymomy: y component of the momentum of the primary particle

  • primarymomz: z component of the momentum of the primary particle

• Always active for curves Effective At Volume and Effective At Volume-Interface Otherwise activated by the additionalTuple command

Step_<moduleName>

• Name: <moduleName>_StepTuple_<GFMtype>

• Information by step

• Columns:

  • EventID: event ID

  • pdg: pdg of particle

  • theta: theta to normal of the particle on the interface (available only for curves ``Effective At Interface``)

  • <moduleType>: value of <moduleType> of the step

  • weight: weight of the event

  • primarykine: primary kinetic energy of the event

• By issuing the detailedTuples command the following columns are also available

  • kine: kinetic energy of particle

  • x: local x position

  • y: local y position

  • z: local z position

  • <moduleType>WF: The correction factor (curve*WF if both exist) as calculated for the current step

  • weight: weight of the event

  • primarykine: kinetic energy of the primary particle

  • primaryx: x position of the primary particle

  • primaryy: y position of the primary particle

  • primaryz: z position of the primary particle

  • primaryphi: phi of the primary particle

  • primarytheta: theta of the primary particle

  • primarymomx: momentum projection on x of the primary particle

  • primarymomy: momentum projection on y of the primary particle

  • primarymomz: momentum projection on z of the primary particle

• Only for curves Effective At Volume and Effective At  Volume-Interface the following columns are also available

  • InterfacePDG: pdg of particle that crossed the interface

  • InterfaceKine: kinetic energy of particle on the interface

  • InterfaceX: local x position of particle on the interface

  • InterfaceY: local y position of particle on the interface

  • InterfaceZ: local z position of particle on the interface

  • InterfaceTheta: theta to normal of particle on the interface

• By issuing the alongStepInfo command the following columns are also available

  • isadj: 10 for forward and 1 for adjoint step (the latter is not implemented at the moment)

  • stepnb: current step number

  • z: atomic number of particle

  • a: atomic mass of particle

  • trackid: track ID

  • parentid: parent particle ID

  • primarypdg: pdg of the primary particle

  • truelength: length of the current step

  • geolength: geometric distance between the Pre and Post step points

  • PreStepKine: kinetic energy at the Pre step point

  • edep: energy deposition of the current step

  • PreStepX: local x of the Pre step point

  • PreStepY: local y of the Pre step point

  • PreStepZ: local z of the Pre step point

  • costh: cosine of theta, where theta is the angle between the momentums at Pre and Post step points

  • w: weight of the current track

• Always active for curves Effective At Interface. Otherwise activated by the additionalTuple command

---

GRAS/trunk/r2242