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 columns, where 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", &endThe 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, &endThe 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
¶meter name = "Type", symbol = "Type", description = "Particle type", type = "string", &endNote 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.
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 ¶meter name = "PowerOfInitialBeam" description="Initial beam power", symbol = "P$b0$n", type="double" units="W" &end ¶meter 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 7000Here, 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.