trace-shell - ray trace a shell, hey!
trace-shell options
trace-shell uses an IRAF-compatible parameter interface. The available parameters are:
A prefix to be used on all intermediate files created. There are lots of intermediate files; see the section on Intermediate Files.
The location of a raygen compatible source script. If it is the
string default
, the value of the source_spec
keyword in the
trace-shell configuration file is used.
Extra parameters to be passed to the source script. If it ends in
.lua
it is interpreted as being the name of a Lua script. See the
documentation for the source script for information on which
parameters are available.
The output stream to which to write the rays. It may be a filename,
or the string stdout
, in which case rays will be written to the
standard output stream. If it is the string default
, a file name
will be created by appending the output_fmt to the tag (with an
intervening period).
The output format of the rays. May be one of fr
, bpipe
, rdb
,
or a fits
variant. See Output Formats for more information.
The output coordinate system of the rays. May be one of osac
,
hrma
, xrcf
.
Which data fields to output for each ray. The value may be one of
all
A rather large amount of information.
A comma delimited list of field names to output. Field names may be
prefixed with -
, indicating that they are to be removed from the
list of output fields. If the only fields specified are those to be
removed, the initial output list contains all of the fields in the data.
The field name min
is an alias for specifying the following fields:
position direction weight energy time
The order of additive and subtractive fields is unimportant; all additive fields are inserted into the list before the subtractive fields are removed.
The shell to raytrace.
The first seed for the random number generator. It must be in the range [1,2147483562].
The second seed for the random number generator. It must be in the range [1,214748339]
The random number block at which to start. It must be in the range [0,1048575].
The spacing between random number blocks for each random process. 100 is a good number.
The start time of the observation in seconds. If less than zero and jitter is turned on, the start of the valid jitter time range is used.
The quantity of whatever limit_type
specifies that raygen must
generate. If limit_type
is a unit of time, this is added to the
start time (see tstart
) to determine the stop time of the
simulation. If jitter is on and this is set to 0
, then the stop
time is set equal to the end of the valid jitter time range.
The units of the limit at which to stop generating rays.
ksec
kiloseconds of observation time
sec
seconds of observation time
Mrays
millions of rays at the entrance aperture
krays
thousands of rays at the entrance aperture
rays
rays at the entrance aperture
r/mm2
a ray density at the entrance aperture in rays / mm^2
r/cm2
a ray density at the entrance aperture in rays / cm^2
A boolean parameter indicating that the focus of the system is to be determined. See the Focus section for more details.
The position along the Z (optical) axis at which to leave the rays.
If non-zero, a tally of photons will be written to the standard
error stream every tally
rays. This is useful if you're wondering
why it's taking so long to run the raytrace. This tallies the number
of rays which make it out of the shell, after all of the post-optic
apertures.
trace-shell will change into this directory before reading the configuration file. This allows relative includes within standard configuration files to work.
The name of the configuration file which provides the details of the
mirror configuration. If this begins with .
or /
, the
configuration file in the specified directory will be used. Note that
trace-shell will still change directory to config_dir before
reading the configuration file.
Print out the version information and exit.
Print out this message and exit.
A comma separated list of debugging options. See Debugging for more information.
trace-shell raytraces a single Wolter type I X-ray telescope shell with various apertures and baffles. It was designed around the AXAF HRMA, but may be used for other systems. In order to isolate the source specification from the specification of the optics, it uses a separate optics configuration file (see Configuration File).
trace-shell uses a variety of programs to accomplish the
raytrace. To see the actual raytrace command pipeline, use the
debug pcomm
option.
The trace-shell configuration file (specified by the config_dir and config_db parameters) describes the telescope configuration. See the ts_config documentation for more information.
trace-shell produces a few intermediate files, prefixed by the value of the tag parameter:
tag.gi
This is a rather arcanely formatted file required by SAOdrat. It's not of much general interest.
tag.totwt-in
This file contains the number and weight of the rays at the entrance aperture. It is produced by tot_wt.
tag.totwt-out
This file contains the number and weight of the rays which have made it through the entire configuration. It is produced by tot_wt.
tag.focus.lis
This is an arcanely formatted file created during a focus run by saofocus.
tag.summary.rdb
This summarizes the tag.totwt-in
, tag.totwt-out
, and tag.focus.lis
files.
trace-shell produces output in one of the following formats, specified by the output_fmt parameter:
fr
The fr
format has no header. Each ray is in a fullray
structure.
See /proj/axaf/simul/include/fullray.h for the formats of the ray
structure.
bpipe
The rays are in bpipe
format. See the bpipe documentation for
more information on this.
rdb
The rays are written as an RDB table.
fits
variantVarious FITS formatted outputs may be specified. In all cases the output must be to a file.
fits-axaf
The rays are written according to the AXAF FITS Photon standard.
fits-events
The rays are written in the common astronomical X-ray "events" format. Most X-ray Astronomy software uses this convention.
If you wish to determine where the focal point for a given
configuration is, set the focus parameter to yes
. Because of
bad interactions between the focus algorithm and wildly scattered
rays, micro-roughness induced ray scattering and ghost-ray tracking is
turned off when focussing. You should nominally only focus with a
point source. If the src parameter is set to default
, the
default focus source (as specified in the configuration file) will be
used. You may need to specify arguments for the focus source via the
srcpars parameter. The focus procedure is carred out by
saofocus which leaves its results in files called tag.focus.lis
and tag.focus.rdb
(where you've specified tag). The first file's
format is pretty arcane; generally to extract the focus from there, run the
script getfocus on it:
getfocus tag.focus.lis
which will write out the focal position (in OSAC coordinates) to the
standard output stream. The second file (tag.focus.rdb
) contains
the three-dimensional position of the Global Optimal Focus.
The debug options that are available are:
pcomm
Print out the raytrace command before executing it. This gives you some idea of which programs are running and what their inputs are.
noexec
Generate the raytrace command and any required intermediate files, but
do not execute it. Most useful with the pcomm
debug option.
reuse
Reuse the raytrace output from a previous identical run to
regenerate the summary information. noexec
must not be
specified simultaneously. The raytrace parameters should be
identical except for the addition of this flag.
normalize_limit
If specified and the limit_type
parameter is density related, the
output ray weights will be scaled so that the input photon density is
1. This allows specifying different photon densities for each shell
to provide a uniform statistical errors while retaining the ability to
easily coadd the raytraces for different shells.
noproject
Do not project the rays to the value specified by the z
parameter.
This is a temporary kludge, and will probably not survive into the
next version of trace-shell.
save_rays_
whereSave intermediate rays. Rays are saved in bpipe
format to the file
${tag}-where.bp. where is one of
Rays coming out of the ray generator
Rays before they are intercepted with the optic.
Rays before they are reflected at the optic.
Rays before they are scattered off of the optic
Rays after they are scattered off of the optic
input-tap
=commandThe rays exiting the ray generator (before they hit the shells) will
be copied to the standard input stream of the specified command (thus
the name input-tap
). The command may refer to any of the
parameters given to trace-shell using the syntax $parameter
or
${parameter}
. For example,
debug=input-tap='frobnicator input=stdin output=$tag.frob'
The rays are in bpipe format.
input-filter
=commandThe rays exiting the ray generator are passed through the provided
command before being sent to the shells. The command must read the
rays from its standard input and write the modified rays to its
standard output. The command may refer to any of the parameters given
to trace-shell using the syntax $parameter
or ${parameter}
.
For example,
debug=input-filter='snackmaster input=stdin output=stdout'
The rays are in bpipe format.
noghosts
Ghost rays will not be propagated through the system.
output-tap
=commandThe rays exiting the optics (after projecting to the final
requested position, but before any coordinate conversions) will
be copied to the standard input stream of the specified command (thus
the name output-tap
). The command may refer to any of the
parameters given to trace-shell using the syntax $parameter
or
${parameter}
. For example,
debug=output-tap='frobnicator input=stdin output=$tag.frob'
The rays are in bpipe format.
output-filter
=commandThe rays exiting the optics (after projecting to the final requested
position, but before any coordinate conversions) are passed through
the provided command before being tallied and finally written to the
requested destination. The command must read the rays from its
standard input and write the modified rays to its standard output.
The command may refer to any of the parameters given to
trace-shell using the syntax $parameter
or ${parameter}
.
For example,
debug=output-filter='snackmaster input=stdin output=stdout'
The rays are in bpipe format.
scat_min_prob
=fractional probabilityset the minimum scattering probability for both optics
scat_max_prob
=fractional probabilityset the maximum scattering probability for both optics
scat_p_min_prob
=fractional probabilityset the minimum scattering probability for the paraboloid
scat_p_max_prob
=fractional probabilityset the maximum scattering probability for the paraboloid
scat_h_min_prob
=fractional probabilityset the minimum scattering probability for the hyperboloid
scat_h_max_prob
=fractional probabilityset the maximum scattering probability for the hyperboloid
trace-nest3, ts_config
Copyright 2006 The Smithsonian Astrophysical Observatory
This software is released under the GNU General Public License. You may find a copy at: http://www.fsf.org/copyleft/gpl.html
This documents version 2.2.2 of trace-shell.
Diab Jerius <djerius@cfa.harvard.edu>