Output Files

MULASSIS produces the following output files:

The default filename prefix for the Report and Data files is

  • mulassis if invoked interactively

  • the first macro file from the command line, e.g.
    % mulassis MyMacro.g4ml would produce MyMacro.rpt and MyMacro.csv.

The name of the output file can be specified using the /analysis/file <filenamePrefix> macro command.

Note

For batch sessions, an alias, ARGV1, is created with the value of the report and data file file name prefix.

% mulassis testing.g4mac

....

/control/listAlias
  ARGV1 : testing

Report file (.rpt)

The MULASSIS report file is intended to be a human readable text file, containing details of the simulation setup and some summary outputs.

Material Definition

The next section reports on the materials defined in the simulation, with various material properties.

-------------------------------------------------------------
Material Definition:
-------------------------------------------------------------

There are 2 materials used:
 Material:   Vacuum H1   density:  0.000 mg/cm3  RadL: 204310098.490 pc   Nucl.Int.Length: 113427284.261 pc
                       Imean:  19.200 eV   temperature:   2.73 K  pressure:   0.00 atm

   --->  Element: H (H)   Z =  1.0   N =     1   A =  1.008 g/mole
         --->  Isotope:    H1   Z =  1   N =   1   A =   1.01 g/mole   abundance: 99.989 %
         --->  Isotope:    H2   Z =  1   N =   2   A =   2.01 g/mole   abundance:  0.011 %
          ElmMassFraction: 100.00 %  ElmAbundance 100.00 %

 Material: Aluminium Al1   density:  2.700 g/cm3   RadL:   8.893 cm   Nucl.Int.Length:  38.879 cm
                       Imean: 166.000 eV   temperature: 293.15 K  pressure:   1.00 atm

   --->  Element: Al (Al)   Z = 13.0   N =    27   A = 26.980 g/mole
         --->  Isotope:  Al27   Z = 13   N =  27   A =  26.98 g/mole   abundance: 100.000 %
          ElmMassFraction: 100.00 %  ElmAbundance 100.00 %

Geometry Definition

This section provides a list of the different layers, thickness, material, and starting location in the geometry.

There are 27 physical volumes used (including the world volume which is PhysVol #1).

PhyVol#  PhyVol Name     Start      Thickness  Material
      2  Layer-1         -1 cm      50 um      Aluminium
      3  Layer-2         -9.95 mm   50 um      Aluminium
      4  Layer-3         -9.9 mm    100 um     Aluminium
      5  Layer-4         -9.8 mm    100 um     Aluminium
      6  Layer-5         -9.7 mm    100 um     Aluminium
      7  Layer-6         -9.6 mm    100 um     Aluminium
      8  Layer-7         -9.5 mm    100 um     Aluminium
      9  Layer-8         -9.4 mm    100 um     Aluminium
     10  Layer-9         -9.3 mm    100 um     Aluminium
     11  Layer-10        -9.2 mm    200 um     Aluminium
     12  Layer-11        -9 mm      500 um     Aluminium
     13  Layer-12        -8.5 mm    500 um     Aluminium
     14  Layer-13        -8 mm      500 um     Aluminium
     15  Layer-14        -7.5 mm    500 um     Aluminium
     16  Layer-15        -7 mm      1 mm       Aluminium
     17  Layer-16        -6 mm      1 mm       Aluminium
     18  Layer-17        -5 mm      1 mm       Aluminium
     19  Layer-18        -4 mm      1 mm       Aluminium
     20  Layer-19        -3 mm      1 mm       Aluminium
     21  Layer-20        -2 mm      1 mm       Aluminium
     22  Layer-21        -1 mm      1 mm       Aluminium
     23  Layer-22        -0.0017763 2 mm       Aluminium
     24  Layer-23        2 mm       2 mm       Aluminium
     25  Layer-24        4 mm       2 mm       Aluminium
     26  Layer-25        6 mm       2 mm       Aluminium
     27  Layer-26        8 mm       2 mm       Aluminium

Physics Definition

This section lists the physics simulation scenario, and production cuts set for the simulation.

-------------------------------------------------------------
Physics Definition:
-------------------------------------------------------------
Simulation scenario : hadron-em-ln
Applied default cuts: 100 um
Production Cuts By Region:
 Region: DefaultRegionForTheWorld
  GammaCutLength    : 1 m
  ElectronCutLength    : 1 m
  PositronCutLength    : 1 m
  Cuts in Energy    :
   The layers in the region are:
       World
    in Vacuum:
        gamma 990 eV     e- 990 eV     e+ 990 eV     p  10 keV
    in Aluminium:
        gamma 10 GeV    e- 1.19608 GeV    e+ 1.13347 GeV    p  10 keV
 Region: DefaultRegionForParallelWorld
  GammaCutLength    : 1 m
  ElectronCutLength    : 1 m
  PositronCutLength    : 1 m
  Cuts in Energy    :
   The layers in the region are:

Incident Particle Definition

This section provides a summary of the particle source. As the /gps system can provide multiple source configurations [R23], this summary may not be complete for any simulations other than a single particle source.

-------------------------------------------------------------
Incident Particle Definition:
-------------------------------------------------------------

The incident particle type:       proton
The incident position is:         (0.0000,0.0000,-100.0050) mm
The number of particles fired is: 1.00e+05
The incident particle fluence:    1.0000e+00 particles/cm2

Analysis Results

The remaining sections of the report file provide a summary of the various analysis modules configured for the simulation. Of these, the Fluence and Pulse Height analyses are not reported, and only have their outputs in the .csv file.

The Dose, Non-Ionising Dose, Dose Equivalent, and Solar Cell analyses have summary results provided.

Data file (.csv)

The data file produced is a comma-separated value file using the format specification of the SPENVIS system [R17].

Note

A python class to read and plot the CSV outputs is provided in the test/Mulassis.py file, with a SpenvisCSV package for reading the CSV files available in python/SpenvisCSV.

To install the SpenvisCSV package:

cd python/SpenvisCSV/SpenvisCSV
pip install .

See the tests/plot_tests.py for an example of usage.

SPENVIS Format

The SPENVIS file format is a comma-separated value file, comprising a series of blocks that consists of the following sections:

  • a header line

  • a number of comment lines

  • a meta-data section

  • a set of plot annotation lines

  • variable definition lines

  • the body section containing a table of the results data

  • an end of block indicator 'End of Block'

This file format has been selected to ensure a wide range of import compatibility with various data analysis tools while still maintaining human readability.

Header line

The header line consists of a character string and eight integers. The character string serves as a guard and start of block indicator. This character string is always set to a single asterisk enclosed in single quotes: '*'.

The integer values provide information on the size of the header and body sections:

  • nheader is the total number of lines in the header section (including the header-line).

  • ntext is the number of comment lines.

  • nmeta is the number of meta data lines.

  • nanno is the number of annotation lines

  • nvar is the number of variables in the body section.

  • ncol is the number of data columns in the body section. As variables can have more than one dimension, this number does not have to be equal to the number of columns.

  • nbody is the number of data records in the body section (set to -1 when the length of the body section is unknown).

  • npart is the number of blocks following the current block.

In the following example, there are 14 lines in the header, 4 comment lines, 4 meta-data lines, no annotation lines, 5 variables, 5 data columns, 60 data rows, and 7 following blocks.

'*',    14,     4,     4,     0,     5,     5,    60,     7

Note

Note that part of the information is redundant as nheader = 1 + ntext + nanno + nmeta + nvar.

Comment lines

The lines immediately following the header line are the comment lines. These are human-readable, free format lines intended for documenting the block. The MULASSIS comments consist of:

  • the name of the analysis results

  • “MULASSIS” with the source code configuration (trunk, tag, branch)

  • the version of Geant4

  • the file creation date

An example of the comment section.

'OMNIDIRECTIONAL FLUENCE ANALYSIS'
'MULASSIS tag ml-v01-26'
'geant4-10-01-patch-03 (5-February-2016)'
'File Created: Fri Dec  8 10:07:06 2023'

Meta-Data lines

Each line contains the information on a specific metavariable, and starts with a character string (ameta) followed by an integer (ktyp). The string ameta contains the name of the metavariable. The integer ktyp specifies the type of the metavariable. When ktyp is negative -1, the metavariable contains a character string, the value of which is set in the third element of the line (val_1). When ktyp is greater than 0, the metavariable contains a vector of ktyp real numbers, the values of which are set in the third and following elements of the line (val_1 … val_[ktyp]). The units of the meta data may be included as a final character string entry at the end of the line.

In the following example from a Fluence analysis, the meta-data in line 1, MOD_ABB identifies the block as originating from MULASSIS; the BLK_TYP meta-data identifies the block as from a fluence analysis. The FLU_BDY meta-data indicates that the analysis is from layer 5 with FLU_PAR specifying that it is an electron fluence analysis. The FLU_AMN and FLU_AMX indicate that the fluence is for particles with an angle between 90 and 180 degrees.

'MOD_ABB', -1,'MULASSIS'
'BLK_TYP', -1,'FLUENCE'
'FLU_BDY',  1, 5,' '
'FLU_PAR', -1,'e-',' '
'FLU_AMN',  1, 9.0000e+01,'deg'
'FLU_AMX',  1, 1.8000e+02,'deg'

Variable Definitions

Each line of this section includes information on a specific variable of the data set. A variable is defined as a single real number or as a vector of real numbers. Each record contains four elements:

  • aname, a character string with the name of the variable;

  • aunit, a character string with the units of the variable;

  • nelem, an integer with the number of elements of the vector (set to 1 when the variable is a single real number);

  • atitle, a character string with a title for the variable that can be used on plots, etc…

Optionally, the string atitle can be followed by a set of character strings with metavariable names (see below).

Note that the sum over the nvar records of the nelem value shall be equal to ncol from the header-line.

In the example below, 5 variables are defined, each of a single dimension.

'Elo','keV',  1,'Lower edge of energy bin'
'Eup','keV',  1,'Upper edge of energy bin'
'Emean','keV',  1,'Mean energy of bin'
'Value','particles/cm2/bin',  1,'Fluence/flux'
'Error','particles/cm2/bin',  1,'Error in fluence/flux'

Body - Data section

Each record of the body section contains the values associated to all the variables of the data set. All records of the body section have the same structure: they contain a suite of real numbers, the number of which is specified by the 7th element of the header line (ncol). For the sake of clarity, the values are usually written in fields with fixed width such that the fields from the different records are aligned in columns. In each record, the values are ordered the same way as the variable descriptions in the variable definition section.

The number of records contained in the body section is not explicitly determined. An expected value of this number is given by the 8th element of the first record of the header section (nbody).

Practically, the end of the body section is defined by the detection of the footer section.

'Elo','keV',  1,'Lower edge of energy bin'
'Eup','keV',  1,'Upper edge of energy bin'
'Emean','keV',  1,'Mean energy of bin'
'Value','particles/cm2/bin',  1,'Fluence/flux'
'Error','particles/cm2/bin',  1,'Error in fluence/flux'
 1.0000e-01, 1.2589e-01, 0.0000e+00, 0.0000e+00, 0.0000e+00
 1.2589e-01, 1.5849e-01, 0.0000e+00, 0.0000e+00, 0.0000e+00
 1.5849e-01, 1.9953e-01, 0.0000e+00, 0.0000e+00, 0.0000e+00
 1.9953e-01, 2.5119e-01, 0.0000e+00, 0.0000e+00, 0.0000e+00
 2.5119e-01, 3.1623e-01, 0.0000e+00, 0.0000e+00, 0.0000e+00
 3.1623e-01, 3.9811e-01, 0.0000e+00, 0.0000e+00, 0.0000e+00
 3.9811e-01, 5.0119e-01, 0.0000e+00, 0.0000e+00, 0.0000e+00
 5.0119e-01, 6.3096e-01, 0.0000e+00, 0.0000e+00, 0.0000e+00
 6.3096e-01, 7.9433e-01, 0.0000e+00, 0.0000e+00, 0.0000e+00

 ...

 1.0000e+05, 1.2589e+05, 1.1249e+05, 5.6547e-03, 3.8153e-04
 1.2589e+05, 1.5849e+05, 1.4211e+05, 4.5088e-03, 3.2247e-04
 1.5849e+05, 1.9953e+05, 1.7669e+05, 5.2212e-03, 4.1081e-04
 1.9953e+05, 2.5119e+05, 2.2433e+05, 3.8650e-03, 2.5657e-04
 2.5119e+05, 3.1623e+05, 2.8087e+05, 3.7066e-03, 2.3941e-04
 3.1623e+05, 3.9811e+05, 3.5177e+05, 3.0826e-03, 2.0597e-04
 3.9811e+05, 5.0119e+05, 4.3964e+05, 2.0451e-03, 1.6114e-04
 5.0119e+05, 6.3096e+05, 5.4728e+05, 7.8162e-04, 9.7811e-05
 6.3096e+05, 7.9433e+05, 6.5959e+05, 8.3694e-05, 3.1638e-05
 7.9433e+05, 1.0000e+06, 8.0200e+05, 1.1611e-05, 1.1611e-05

Sample file

This example illustrates the specifications on the UNIRAD/SPENVIS output file structure. Different record numbers have been added in order to better highlight the different parts of the structure, but do not occur in the file.

 1'*', 13, 2, 3, 4, 3, 8, -1, 0
 2'Title of this project'
 3'This is an example file'
 4'EPOCH', 1, 1995.0
 5'ENERGY', 6, 0.10, 0.50, 1.00, 2.00, 5.00, 10.00
 6'MODEL', -1,'IRI-90'
 7##########################
 8# Specific area reserved #
 9#     for future use     #
10##########################
11'AMJD ','day ', 1,'Modified Julian Day'
12'FLUX_EL ','cm-2 s-1', 6,'Integral electron flux'
13'L ','Re ', 1,'McIlwain''s shell parameter'
1417888.07465, 1.2E+06, 1.0E+06, 5.4E+05, 2.9E+05, 4.2E+04, 9.8E+03, 2.067
1517890.78901, 6.0E+05, 5.0E+05, 2.7E+05, 1.4E+05, 2.1E+04, 4.9E+03, 1.076
1617892.87572, 3.2E+05, 2.0E+05, 2.4E+05, 1.9E+05, 2.2E+04, 4.8E+03, 1.085
1717894.36543, 1.2E+04, 1.0E+04, 5.4E+03, 2.9E+03, 4.2E+02, 9.8E+01, 2.094
1817896.43453, 6.0E+05, 5.0E+05, 2.7E+05, 1.4E+05, 2.1E+04, 4.9E+03, 3.103
1917898.88785, 1.2E+06, 1.0E+06, 5.4E+05, 2.9E+05, 4.2E+04, 9.8E+03, 3.112
2017900.68776, 1.2E+04, 1.0E+04, 5.4E+03, 2.9E+03, 4.2E+02, 9.8E+01, 2.121
2117902.76786, 6.0E+05, 5.0E+05, 2.7E+05, 1.4E+05, 2.1E+04, 4.9E+03, 1.130
22'End of Block'
  • The first record indicates that

    • the header section extends from record 1 to 13;

    • the header section includes 2 text lines, 3 metavariables, 4 reserved records, and 3 variable definitions;

    • each record of the body section contains 8 elements corresponding to the total dimensions of the 3 variables;

    • the number of records of the body section was unknown when this record has been written, as indicated by the “-1”;

    • there is only a single block in the file, i.e. no following blocks, as indicated by the final “0” in the record.

  • Records 2 and 3 contain the two text lines.

  • Records 4 to 6 contain the three metavariables: EPOCH, ENERGY and MODEL. The metavariable EPOCH corresponds to a single real number while the metavariable ENERGY is a vector of 6 elements. The metavariable MODEL is a character string.

  • Records 7 to 10 correspond to an area, the format of which is not defined by the current specification.

  • Records 11, 12 and 13 contain the definition of the three variables. Both first and third variables (AMJD and L) correspond to single real numbers. The second variable (FLUX_EL) is a 6-element vector of real numbers.

  • Records 14 to 21 correpond to the body section. Each record contains 8 elements associated to the three variables AMJD, FLUX_EL and L.

  • Record 22 is the footer section.

Mulassis/ml-v02-00/r342