trace-shellz4 - ray trace a shell, hey!
trace-shellz4 options
trace-shellz4 uses an IRAF-compatible parameter interface. See the section on Setup below. 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-shellz4 configuration file is used.
Extra parameters to be passed to the source script. See the documentation for the source script for information on which parameters are available.
The are passed directly to raygen via its source_override
parameter.
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.
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 numerical value of the limit at which to stop generating rays at the telescope entrance aperture. The number of rays which reach the focal plane are typically lower than this. The limit_type parameter specifies the units for this value.
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
The ray distribution at the entrance aperture. It may be one of
random or ringspoke. Currently, ringspoke is ignored.
The number of rings to use if the ray_dist parameter is ringspoke.
The number of spokes to use if the ray_dist parameter is ringspoke.
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.
The directory containing the trace-shellz4 configuration file.
The name of the configuration file which provides the details of the
mirror configuration. If this begins with . or /, the
config_dir parameter is ignored.
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-shellz4 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-shellz4 uses a variety of programs to accomplish the
raytrace. To see the actual raytrace command pipeline, use the
debug pcomm option.
trace-shellz4 uses an IRAF compatible parameter interface. Because it calls many other programs, you will actually need to have parameter files for all of them handy.
To simplify things, there is a command (trace-shellz4_setup) which creates copies in the current directory of the all of the required parameter files.
The trace-shellz4 configuration file (specified by the config_dir and config_db parameters) describes the telescope configuration. See the ts_config documentation for more information.
trace-shellz4 produces a few intermediate files, prefixed by the value of the tag parameter:
This is a rather arcanely formatted file required by SAOdrat. It's not of much general interest.
This file contains the number and weight of the rays at the entrance aperture. It is produced by tot_wt.
This file contains the number and weight of the rays which have made it through the entire configuration. It is produced by tot_wt.
This is created during a focus run by saofocus.
trace-shellz4 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 variant
Various FITS formatted outputs may be specified. In all cases the output must be to a file.
fits or fits-std
The rays are written in the uncommon and seldom used AXAF Photon FITS standard.
fits-events
The rays are written in the much more common ``events'' format. It
differs from the AXAF FITS Photon Standard in that the binary table is
named EVENTS, the rt_ prefix is removed from the column names,
and the energy column is named energy and is in units of eV. 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
src_params parameter. The focus procedure is carred out by
saofocus which leaves its results in a file called
tag.focus.lis, (where you've specified tag). This file 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.
trace-shellz4 has a more intricate relationship with raygen than with
other executables it uses because of the complexity of specifying source
information. In particular, it passes raygen some extra information
via its override variables.
It adds a definition of shell to the source_override parameter,
setting it equal to the shell being raytraced. This implies that you
cannot pass a script file (via the @ construct) to raygen via
trace-shellz4's src_params parameter.
It adds definitions of shell and ea_db to the ea_override
parameter. See the discussion of entrance_ap_db and
entrance_ap_spec in the ts_config documentation.
The debug options that are available are:
Print out the raytrace command before executing it. This gives you some idea of which programs are running and what their inputs are.
Generate the raytrace command and any required intermediate files, but do not execute it. Most useful with the pcomm debug option.
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-shellz.
Save 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
The 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-shellz4 using the syntax $parameter or
${parameter}. For example,
debug=input-tap='frobnicator input=stdin output=$tag.frob'
The rays are in bpipe format.
The 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-shellz4 using the syntax $parameter or ${parameter}.
For example,
debug=input-filter='snackmaster input=stdin output=stdout'
The rays are in bpipe format.
Ghost rays will not be propagated through the system.
The 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-shellz4 using the syntax $parameter or
${parameter}. For example,
debug=output-tap='frobnicator input=stdin output=$tag.frob'
The rays are in bpipe format.
The 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-shellz4 using the syntax $parameter or ${parameter}.
For example,
debug=output-filter='snackmaster input=stdin output=stdout'
The rays are in bpipe format.
set the minimum scattering probability for both optics
set the maximum scattering probability for both optics
set the minimum scattering probability for the paraboloid
set the maximum scattering probability for the paraboloid
set the minimum scattering probability for the hyperboloid
set 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 1.18.3 of trace-shellz4.
Diab Jerius <djerius@cfa.harvard.edu>