Input Beam File

The file for the input beam is specified in the command line. This file may be created using an editor or the SDDS toolkit, or may be an output of previous shower runs. The data may even originate from other SDDS-compliant physics simulation programs. Converting from one type of data to another is relatively easy with SDDS toolkit programs.

A short introduction to the SDDS format is given here with specific definitions required in the shower input beam file.

An SDDS-format file consists of a header and zero or more pages of data represented as follows:

SDDS1
description-command
column-command
.
.
column-command
parameter-command
.
.
parameter-command
data-command
! end of header, beginning of data page 1
parameter data
tabular data
! beginning of data page 2
parameter data
tabular data
.
.

The header contains namelist commands describing the structure of the data pages using parameter and column commands. The tabular data consists zero or more rows of $n$ columns, where $n$ is the number of columns defined in the header. Each column of data column must appear in the same order as the definitions of the header. The description command is optional. Another data type, array, is not mentioned here since it is not used in shower.

The first line of the file must be SDDS1, indicating that the file is an SDDS version 1 file. The description command follows, for example:

&description text = "Coordinates of particles entering ``concrete'' region",
 contents = "Particle coordinates", &end

The text and contents field are intended to be a general description to aid a user in identifying the file. This particular description command came from a output file created by a shower simulation with a region labeled ``concrete''. The contents field is intended to represent a formal way to identify the type of file. The quantities in the description don't have any particualr significance to shower but may be used in other SDDS toolkit programs, such as sddsplot.

In the input beam file shower recognizes the columns x, y, z, u, v, w, and Energy. The first three are the cartesian coordinates of incident particle with units of meters. The next three are direction cosines with no units. The last coordinate is the total energy (kinetic plus rest mass), in MeV. Note that only the Energy column need not be defined at all, as the rest of the coordinates default to zero (except for w which defaults to 1) when the simulation starts. Additional columns may exist in this file, but will be ignored by shower. An example of a column definition is

&column
 name = "Energy",  symbol = "Energy",  units = "MeV", description = "Energy",
 type=double,
&end

The minimum set of fields for a valid column definition in general consists of name and type. For shower, an additional requirement is the specification of the units, ``m'' for coordinates and ``MeV'' for Energy. All coordinate data types should be double. Other columns could be defined in the input file for informational purposes, but they will be ignored by shower.

Parameters are quantities assigned for each data page. For the input beam file the parameter Type indicates whether the page of data correspond to electrons, positrons or photons. The definition of parameter Type is

&parameter name = "Type", symbol = "Type", 
 description = "Particle type", type = "string",
&end

Note that while the definition of the parameter belong in the header, the actual value of the parameter appears at the start of each page. Program shower will recognize string values equal to electrons, positrons, and photons. The string data may appear in quotes.

If the parameter Type isn't defined in the input file, then shower uses the value given for the command line option -defaultParticleType. If no value was assigned to this option, then shower gives an error message, and aborts.

The parameters listed below are all optional. Most of them are generated in output files. They do not take part in the Monte-Carlo simulation themselves, but in combination of the simulation results these parameters are used to calculate absorbed doses.

• PowerOfInitialBeam -- Double. Units of W. Default value of 1 W. This is defined in the input beam file by the user. This parameter is passed to all output files. If linked shower runs are used to transport radiation through different parts of a complex simulation, this parameter serves as a mechanism to pass the information required to calculate a radiation dose in the final run.

• Generation -- Long. Default value of 0. Its value in an output beam file is one more than its value in an input beam file. For a primary beam, its value should be set to zero. Therefore, in an output beam file, its value is the number of shower runs that have been done starting from the primary beam. This parameter is involved in defining parameter TotalIncidentEnergyOfFirstRun.

• CumulativeSamples -- Long. Default value of 1. This is the cumulative number of samples that precedes the input file. In an output file, its value is multiplied by the number of samples in the current shower run. This parameter is used in the calculation of the radiation absorbed dose.

• TotalIncidentEnergyOfFirstRun -- Double. No default values. This parameter is the total energy of all particle used in the primary beam run (``generation'' zero). Its value is generated in the output files of the generation zero run. This quantity is used in calculating the radiation absorbed dose.

For the &data command, one sets mode equal to ascii, and no_row_counts flag to 1. Here is an example of a minimal input file used as the primary beam of a Monte Carlo calculation of radiation dose at the APS. The beam power at the safety envelope is 308 W.

SDDS1
&description
 text="One-particle 7000 GeV positron beam",
 contents="Particle coordinates" &end
&parameter
 name = "PowerOfInitialBeam" description="Initial beam power",
 symbol = "P$b0$n", type="double" units="W" &end
&parameter
 name = "Type" type="string"  &end
&column
 name="E" units="MeV" type=double &end
&data
 mode = "ascii" no_row_counts=1 &end
! page number 1
! Initial beam power of 308 W
308
! parameter Type
positrons
! start of tabular data
7000

Here, only the energy column is defined. The other column quantities are assumed to be zero. The parameter PowerOfInitialBeam is defined with value 308 W, which happens to be relevant for safety simulations at APS. The particle type is ``positrons''. Only one particle of 7 GeV is defined.

Note that command line option -chooseInInputfiles=particleType[,...] can be used to select particles of one or more types in the input files, and discard the particles of the unnamed types. Thus if one had -chooseInInputfiles=electrons for the input file above, then no particle would be tracked.