Документ взят из кэша поисковой машины. Адрес оригинального документа : http://xmm.vilspa.esa.es/scisim/release/latest/help/postscript/tools.ps Дата изменения: Wed Jan 12 14:03:36 2005 Дата индексирования: Sat Dec 22 15:35:13 2007 Кодировка: Поисковые слова: http astrokuban.info astrokuban

SciSim Tools 4.0
M.W. Beijersbergen
January 12, 2005
This is a paper version of the SciSim Tools help. If possible, refer to the HTML version, which contains
images and hypertext links.
SciSim Tools is a suite of tools to process the data format that is exchanged between most of the
simulators of SciSim, the scientic simulator for the XMM-Newtonsatellite.
This document contains information specic to SciSim Tools only; for generic information about SciSim,
see the SciSim User Guide.
1

XMM-Newton Science Simulator Page: 2
Contents
1 Introduction 3
2 Installation 3
3 Usage 3
4 Tool generics 3
5 Tool specics 4
5.1 ssimimport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
5.2 ssimexport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
5.3 ssimtransform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
5.4 ssimquantize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
5.5 ssimlter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
5.6 ssimraystat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
5.7 ssimspot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
5.8 ssimdetector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
5.9 ssimspectrum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
5.10 ssimradial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
5.11 ssimrayplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
5.12 ssimaperture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
5.13 ssimcenter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
5.14 ssimascii . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
5.15 ssimevents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
5.16 ssimhisto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

XMM-Newton Science Simulator Page: 3
1 Introduction
The SciSim Tool suite provides a set of tools that can be used to exchange information with and to
analyze data from the SciSim simulators. This is especially useful for the X-ray simulators, since they
read and write a binary le format. Tools are also provided to do simple analysis. This is used in the test
scripts and can be used for simple analysis of the simulator performance. Rigorous and exible analysis
should be obtained by exporting the data to a dierent le format and analysing this le with more
advanced data analysis tools.
Note that the interface between the X-ray simulators is considered an internal interface of SciSim. If you
want to interface to an internal part of SciSim (e.g. msim), use the ssimimport and ssimexport tools,
which provide a documented and maintained external interface to the X-ray simulators.
2 Installation
See the Installation Guide.
3 Usage
The tools are not integrated in the GUI, and can therefore only be used from the command line.
All the tools operate as Unix lters, that is, they read their input from standard input and produce their
output at the standard output. The standard usage is therefore
tool [- -param value]... inputfile > outputfile
Notice that a double minus sign is needed to specify the value of a parameter.
This syntax allows the tools to be used in pipes. For example, the following command produces an ASCII
listing of the rays produces by gsim:
gsim sources.dat | ssimexport - -fields "begin x y z dx dy dz energy end"
The tools can be congured by editing the SciSim conguration le, by adding command line options or
by specifying a customised conguration le with the -c option (see the SciSim User Guide). The tools
provide usage information with the -h option.
Most of the tools have some generic parameters(Sec. 4), and some have specic parameters(Sec. 5) as
well.
4 Tool generics
The command line options implemented by the tools are identical as those of the simulators, and are
described in the SciSim User Guide.
Most of the tools process rays. They therefore share several parameters that are used by all programs
that process rays. For a description of these parameters see also SciSim User Guide:
transform

XMM-Newton Science Simulator Page: 4
rotation.x
rotation.y
rotation.z
rotation.angle
translation.x
translation.y
translation.z
scale
historyFile
5 Tool specics
5.1 ssimimport
ssimimport reads ASCII multicolumn les and tries to convert the data into rays for the SciSim X-ray
simulators. It is to be applied to an ASCII input le. Its operation is congured by the generic ray
parameters as well as the following:
elds Species the elds that can be found for each ray in the input le. Should be enclosed between
begin and end. Possible values: id source time active energy intensity x y z dx
dy dz mirrorShell mirrorProcess gratingRow grating spectralOrder gratingProcess.
Example:
ssimimport --fields "begin x y z dx dy dz energy end" rays.dat | msim
5.2 ssimexport
ssimexport produces ASCII output of the events in the input or output of a ray simulator. Its operation
is congured by the generic ray parameters as well as the following:
elds Species the elds that are to be produced in the output le for each event. (For importing rays,
see ssimimport.
labels Event selection. This is a string of characters, where each character represents an event code.
Only events with these codes are written in ASCII to the output. The rst character in the
output is the character at the same position in the replace parameter.
replace Characters to replace the event codes in the ASCII output. An underscore is used to represent
a space.

XMM-Newton Science Simulator Page: 5
For example, with labels = 'R=@;' and replace = ' ###', the ASCII output contains rays, parameter
specications, commands and comments. Lines that describe a ray start with a space. Lines with a
parameter specication, a command or a comment start with a hash sign.
The events and possible elds are listed below:
ray (R) id source time active energy intensity x y z dx dy dz mirrorShell mirrorProcess gratingRow
grating spectralOrder gratingProcess
parameter specication (=)
command (@)
comment (;)
camera info (i) i type i mode i n ccds i window X i window dX i pixelArray i pixelSize i deadSpace
frame header (h) f mode f sub mode f ccd id f ccd node f id f start f time f window X f window dX
f window bin f threshold f elevation
frame trailer (t) t pixels above threshold t valid events t nish time
camera event (e) e column e row e energy1 e energy2 e energy3 e energy4 e grade e peripheral pixels
Example:
ssimexport --fields "begin x y z dx dy dz energy time end" \
--labels "R=@;" --replace "_###" msim.ray
5.3 ssimtransform
ssimtransform reads rays into its own coordinate system and writes them in this same coordinate system.
It can be used to change the coordinate system of a ray le.
For example this command will rotate all the rays in the le msim.ray by 90 degrees around the x axis:
ssimtransform --rotation.x 1 --rotation.y 0 --rotation.z 0 \
--rotation.angle 90 msim.ray > msimrotated.ray
5.4 ssimquantize
ssimquantize reads and writes a ray le. If a ray has a relative intensity smaller than one, it is accepted
with a chance that is equal to its relative intensity. This corresponds to quantization of the rays, that is
turning classical rays into photons.
Example:
ssimquantize msim.ray > msimquantized.ray
Note that the simulators themselves can quantize the rays by setting raytraceMode 0.

XMM-Newton Science Simulator Page: 6
5.5 ssimlter
ssimfilter selects rays based on the value of their elds. By default it is transparent. It is congured
by the following parameters (the value between brackets is the value that is to be used if you do not want
to select on this eld):
id select rays with this id ( 1).
active if 1, select rays that are not yet absorbed or re ected; if 0, select rays that have been absorbed
or re ected and therefore end at a certain point. ( 1)
source select rays originating from the source with this id ( 1)
mirrorShell select rays that are re ected from this shell ( 1)
mirrorProcess select rays that have undergone this mirror process ( 1)
gratingRow select rays that were re ected from this row ( 1)
grating select rays that were re ected from this grating ( 1)
spectralOrder select rays from this spectral order (99)
gratingProcess select rays that have undergone this grating process ( 1)
If more than one eld has a selection value, only rays are passed that match all selections.
This example lters only the rays that are properly re ected in the mirror module and produces statistics
for these rays:
ssimfilter --mirrorProcess 3 msim.ray | ssimraystat
5.6 ssimraystat
ssimraystat calculates statistics of rays. It is to be applied to a ray le. It reports:
 illumination parameters
 time range
 total eective area
 eective area per mirror process (for the coding see the MSIM documentation)
 eective area per grating process (for the coding see the RSIM documentation)
 eective area per source
 geometrical area per mirror shell
 eective area per mirror shell
 eective area per grating
 eective area per grating row
 eective area per spectral order

XMM-Newton Science Simulator Page: 7
Where a third column is present, it corresponds to the number of rays.
The eective area is dened as
A e = I
I in
A illum
where I is the sum of the intensity of the rays of interest, I in is the sum of the intensities of all incident
rays, and A illum is the illuminated area.
Example:
ssimraystat msim.ray
5.7 ssimspot
ssimspot calculates spot diagrams from rays. It is to be applied to a ray le. It calculates the point of
impact in the plane x = 0 in its own coordinate system, and produces a multicolumn ASCII le with the
following columns:
 y
 z
 relative intensity
 energy (eV)
 time (s)
 serial number
Example:
ssimspot --translation.x 7500 msim.ray > spot.dat
5.8 ssimdetector
ssimdetector reads a ray le and bins the intensities of the rays on an ideal detector. The energy of the
rays is not taken into account.
The output is an ASCII le. The rst line species the width and height of the image separated by a
comma. The following lines give the intensity per bin, where the row number varies the fastest.
It is congured by the generic ray parameters as well as the following parameters:
binsize The size of the bins in mm.
yBins The nr of bins in a row. A row is centered around y=0.
zBins The nr of bins in a column. A column is centered around z=0.
This example produces an image in the plane x = 7500:

XMM-Newton Science Simulator Page: 8
ssimdetector --translation.x 7500 msim.ray > detector.dat
5.9 ssimspectrum
ssimspectrum reads a ray le, and produces a histogram of the energy of the rays, taking their intensity
into account.
The output is a two-column ASCII le. The rst column is the central energy, and the second the eective
area represented by the rays in that energy band, or the total intensity distribution if the plotIntensity
parameter is set.
The tools is congured by the following parameters:
binsize Width of a bin in the histogram in eV.
oset Oset of the bins in eV.
plotIntensity If zero, the eective area curve will be generated, otherwise the total intensity distribution.
Example:
gsim flat.dat | msim | ssimspectrum > spectrum.dat
5.10 ssimradial
ssimradial reads a ray le. It calculates the point of impact in the plane x = 0 in its own coordinate
system, and then produces a histogram of the distance to the origin. It does take the intensities of the
rays into account, but not the energy.
The output is a two-column ASCII le. The tools is congured by the following parameters:
binsize Width of a bin in the histogram in mm.
oset Oset of the bins in mm.
integrate If 0, the output is the point spread function. The rst column is the radius, the second column
the average surface brightness outside this radius. If 1, the output is the encircled energy.
The rst column is the radius, the second column is the integrated eective area enclosed
inside that radius.
normalize If non-zero, the encircled energy will be normalized to 1.
The surface brightness is dened as the intensity per unit of area in the ring divided by the brightness
per unit area at the input aperture of the telescope.
This example produces a normalized PSF:
ssimradial --integrate 0 --normalize 1 msim.ray > psf.dat

XMM-Newton Science Simulator Page: 9
This example calculates the encircled energy function:
ssimradial --integrate 1 --normalize 1 msim.ray > ee.dat
5.11 ssimrayplot
ssimrayplot produces ASCII output of the rays in the input ray le. The output is a three-column
ASCII le, which are the x; y; z coordinates of the points. Rays are separated by a line containing "&".
If this is performed both on the history output and the normal output of a ray tracer (MSIM, RSIM),
the output can be used by a plotting program (specically xmgr) to show a side view of the rays going
through the system.
Example:
gsim onaxis.dat | msim -h msim.his > msim.ray\\
cat msim.his msim.ray | ssimrayplot > plot.dat\\
xmgr -maxsets 500 plot.dat
5.12 ssimaperture
ssimaperture selects rays based on their point of impact in the plane x = 0 in the tools own coordinate
system. It selects the rays that are within the specied distance of the origin as well as within a square
around the origin of the specied size. It is congured with the generic parameters as well as the following.
The value between brackets is the value to use if the rays should not be selected on this property.
radius select rays within this distance from the origin ( 1)
ySize select rays whose distance from the line y = 0 is less than half this size ( 1)
zSize select rays whose distance from the line z = 0 is less than half this size ( 1)
This example selects rays in an o-axis circle of radius 10 mm:
ssimaperture --radius 10 --translation.y 25 temp.ray > temp1.ray
5.13 ssimcenter
ssimcenter reports the center of gravity of the rays in the plane x = 0 in its internal coordinate system.
Example:
ssimcenter --translation.x 7500 msim.ray

XMM-Newton Science Simulator Page: 10
5.14 ssimascii
ssimascii produces a complete ASCII representation of all the data on the event stream passed between
ray simulators. The format is version specic, and should not be used to interface to SciSim. It can be
used to manually inspect a ray le.
For a description of the elds in the event stream, see ssimexport.
Example:
ssimascii tempm
5.15 ssimevents
ssimevents provides a list of all the events passed between ray simulators, without showing the content
of the event. It is mainly used to manually inspect the content of a ray le.
Example:
ssimascii tempe
5.16 ssimhisto
ssimhisto operates on an ASCII le, not on a ray le. It will accumulate a histogram out of (x; y) pairs
by adding up the y values in the bin determined by the corresponding x value. It can be used to calculate
a histogram of the energies (with x the energy and y the intensity), a line spread function (with x a
position and y the intensity) etc.
x the column number for x
y the column number for y
binsize Width of a bin.
oset Oset of the rst bin.
Example:
ssimspot --translation.x 7500 msim.ray | ssimhisto --x 1 --y 3