trace-nest - ray trace a nest of shells, hey!
trace-nest options
trace-nest 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-nest 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. script accepts
These are passed directly to raygen via the source_override
parameter.
The shells that should be raytraced and merged. The value may be take one of the following values:
all
All of the shells defined in the mirror geometry database will be raytraced.
active
All of the shells defined in the mirror geometry database which are
marked as active
will be raytraced. If the geometry database does not
provide the active
attribute, all of the shells are raytraced.
A comma delimited list of individual shell ids or ranges (min-max). For example:
shells=1-10,23,45
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
, bp
, 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 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 to start at. 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.
limit may be either a floating point number, in which it is used for all shells, or the name of a file containing limit values for all shells. The file must be an RDB formatted file with columns shell and limit.
The units of the limit at which to stop generating rays.
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. This is in the OSAC coordinate system.
z may be either a floating point number, in which it is used for
all shells, or the name of a file containing Z values for all
shells. The file must be an RDB formatted file with columns
shell and z. The Z value for the combined shells should have
a shell value of 99999
.
If non-zero, a tally of rays 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 nest, after all of the post-optic
apertures.
If non-zero, this specifies the number of rays which should be output after the shells are merged. Rays are first eliminated based upon their probability of reflection, and then only the requested number are passed through through (provided enough are available). The number may be varied in a Poisson fashion by setting throttle_poisson.
If negative, rays will be eliminated by their probability of reflection, but no total limit to their number will be set.
A side effect of this option is that all rays will have a weight of one.
If true, and if throttle is non-zero, then the number specified by throttle is treated as the mean of a Poisson distribution, and the number of rays actually output will be drawn from that distribution.
Which intermediate files to delete. It may be none
, in which case
nothing is removed, rays
in which case intermediate ray files are
removed, or all
in which everything is removed.
The directory containing the trace-nest configuration file.
The name of the configuration file which provides the details of the HRMA configuration. See the Configuration File section below.
Print out the version information and exit.
Print out this message and exit.
A comma separated list of debugging options. See the Debugging section for more information.
trace-nest raytraces a nest of Wolter type I X-ray telescope shells with various apertures and baffles. It was designed around the AXAF HRMA, but may be used for other systems. It works by using trace-shell to raytrace each shell, finally merging them into a single file. It traces each shell sequentially, storing each shells' rays on disk; it ends up using twice as much disk space as you think. It'll clean up after itself, though (see the clean parameter).
trace-nest uses a variety of programs to accomplish the raytrace.
To see the actual raytrace command pipeline, use the debug pcomm
option.
trace-nest 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-nest_setup) which creates copies in the current directory of the all of the required parameter files.
The trace-nest configuration file (specified by the config_dir
and config_db parameters) describes the telescope
configuration. Before you create your own, look at
/proj/axaf/simul/databases/ts_config/00Index.html and see if
there's one to suit your fancy. Also, note that trace-nest can
only use configuration files with a .cnf
suffix. For more
information on raytrace configuration files, etc. see ts_config.
trace-nest produces a few intermediate files. Each file is given a
prefix which consists of the value of the tag parameter followed
the shell number. For the final set of merged rays, the shell number
is left off. For example, if tag is foo
, you'll get files of
foo_1.totwt-in foo_2.totwt-in
and
foo.totwt_in
If trace-nest is only tracing one shell, it doesn't include the shell number in the file name.
The rays for the particular shell, in bpipe format.
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 file contains the number and weight of the rays which have made it through the entire configuration, after getting throttled. It is produced by tot_wt.
This is created during a focus run by saofocus.
trace-nest outputs 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.
bp
or 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
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
. However,
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. Additionally, the source is
forced to be the default source specified by the configuration file,
which should be a point source. The default source requires at least
one parameter, namely energy
. The focus procedure is carried 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
UNIX standard output stream. Note that you'll get the focus of all of
the individual shells as well as the nest (unless you set clean to
all
).
All of the shells' focal distances, including the focal distance
for the combined shells, is written to the file tag.focus.rdb
.
The combined shells are assigned a shell number of 99999
.
There are several debug options available:
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.
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-nest.
noghosts
Ghost rays will not be propagated through the system.
saveblock
The next unused random number block is written to tag.block.
trace-shell, ts_config
This software is Copyright The Smithsonian Astrophysical Observatory and is released under the GNU General Public License. You may find a copy at: http://www.fsf.org/copyleft/gpl.html
Diab Jerius ( djerius@cfa.harvard.edu )