Running Raytraces

• What is SAOsac?
• A few words about random numbers
• Basic Setup
• Sources
• Determining Focus
• Current release

What is SAOsac?

SAOsac is a generic term for modified versions of programs from the OSAC suite of optics raytracing programs. surface_intercept (which determines the intersection of rays with the optics' surfaces) is the program which we most use; it is a greatly modified form of the OSAC drat program. SAOsac has come to also refer to the complete suite of programs which we have constructed to create a full raytrace simulation.

Generally, users will use one of three front-ends to the raytrace suite; trace-shellz or trace-nest. In actual use, the program names have a major version number attached, such as trace-shellz4, or trace-nest3. See the Current release section for the names of the current supported release versions. For most purposes, trace-nest will suffice (even for a single mirror).

The programs differ from their predecessor, trace-shell5, in a number of important ways:

• The ray generator is very different. It uses a different coordinate system and a different manner of specifying the source characteristics. Incomplete documentation for the ray generator (raygen) is available. The current ray generator generates sources according to a description written in the Lua language. This makes it easy to generate complicated sources, but makes the learning curve a little steeper.
• The configuration file format has changed, removing many restrictions (such as number of mirrors).
• A more optimized version of SAOdrat (surface_intercept) is used.

Because the front ends call many other programs to perform the raytrace, documentation for a particular aspect of the raytrace is generally found under the name of the program doing that job, rather than under the name of the front end. Additionally, parameters names may be different between the front ends and these other programs. This can be confusing, but is unavoidable given the architecture of the system. The front ends are designed to hide almost all of the details, so this is normally not a problem. Essentially the only program other than the front end that the user will need to be aware of and deal with almost directly is the ray generator.

A few words about random numbers

In order to prevent aliasing between stochastic processes which use random numbers, one normally uses a single random stream for everything, sampling from the stream as necessary. It's very important to use only one stream, because numbers drawn from two streams with different seeds will not be uncorrelated. We use a random number generator with a very long cycle, so long that one needs to set two seeds (32 bits aren't enough). The stream is broken up into 1,048,576 blocks, each of which contains 1,073,741,824 random numbers. The generator allows one to easily move to the beginning of any block.

This is important because the raytracing is done with a number of separate programs, each of which must use the same random stream, but different chunks of it. We do this by ensuring that each program is given the same seeds, but different starting blocks.

You will thus find seed1, seed2, and block parameters for all of the MST programs which require random numbers. Some programs (such as any of the front ends mentioned above), actually string together a number of separate programs. They will have an additional parameter, block_inc which is the increment applied to the starting block for successive programs which use random numbers. A block_inc of 100 is pretty safe.

If you must run multiple programs in succession on a stream of rays, it is important that you always use the same random number seeds, with succeedingly larger starting blocks.

For more information on the random number library, see the documentation.

Basic Setup

1. Ensure that you've set up your environment to run the MST Simulation and analysis software.

2. Read the documentation on the front ends, trace-nest3, or trace-shellz4.

3. If you've followed the instructions to set up your environment mentioned above, and you don't already have the environmental variable PFILES defined, it will be set to

   	.:./uparm:/proj/axaf/simul/lib/uparm
   	

   Please check this by typing:

   	printenv PFILES
   	

   If the output doesn't match the above line, you will need to explicitly set the PFILES environmental variable:

   	setenv PFILES .:./uparm:/proj/axaf/simul/lib/uparm
   	

   This is a list of directories where MST programs will look for parameter files. Unlike some other IRAF compatible interfaces, you need to manually copy parameter files into one of these directories. Nominally, since /proj/axaf/simul/lib/uparm is explicitly mentioned, you don't need to do that. However, you'll want your own copy in your working directory so that you can use the pset command and not have to type all of the parameters on the command line. (Please note, specifying parameters on the command line does not change values in the parameter file.) Because of the way PFILES is set up, it's cleaner to create a sub-directory of your work directory called uparm and run one of the setup programs (trace-shellz4_setup, or trace-nest3_setup.

   For example,

   	mkdir uparm
   	cd uparm
   	trace-nest3_setup
   	cd ..
   	

4. Choose a configuration to raytrace. Make sure that you've got one that's compatible with the front end that you're using.

5. Choose a source to raytrace. This can turn into a fairly complicated thing, so please see the section on setting up sources for more information.

6. If you're going to run the output rays directly to MARX, you should specify

   	output_coord=hrma
   	output_fmt=fits
   	

Sources

By far the most complicated part of the ray trace is setting up the source. For quite a few cases, a point source will suffice. For that reason, each configuration supplies a default source which is just that; merely set the src parameter to default. Links to the default source scripts are available in the configuration file descriptions (see, for example, the default source listing in the orbit_XRCF+tilts_04 configuration).

The current configurations use point-01 which provides for tracing with a single energy, a list of energies with the same flux, a list of energies with different fluxes, a flat spectrum, or a spectrum read in from a file. (Older configurations use default monochromatic sources mono-point_01 or mono-point_02; the point-01 source is much more flexible.)

Each source provides some characteristics that may be modified, for instance its energy, position, flux, and distance. (The documentation in the source script specifies which properties are mutable.) This information is passed via the front end's src_param parameter using a keyword = value syntax. What you're actually doing is writing a little snippet of Lua code, so if there's a syntax error, you'll get an error message from Lua, which might be a bit confusing at first. Because the source descriptions are inputs to the raygen program, which has slightly different names for parameters, the documentation in the header of the source scripts may need some translation.

Here's an example. The documentation for point-01 indicates that there are a number of source characteristics that may be altered, using global variables, for example: coord, energy, z, theta, and phi. These may be specified as follows:

	trace-shellz4 \
		src=default \
		src_params="energy=1.49; theta=2; phi=3; z=-1000000"
      

Notice the C-like nature of the assignments, the fact that multiple assignments are separated by semicolons, and the fact that you can embed spaces for legibility by enclosing the set of assignments in quotes. The script documentation may refer to the override parameter or the override function; take that to mean the front end's src_params parameter. The latter three parameters are optional; they'll default to sane values for an on-axis point source at infinity. If you don't specify an energy, however, it'll complain and won't run.

If you want to go the full route, it's all in what you specify via the energy variable passed in src_params. The documentation has all of the details. The only trick is that if you're using an rdb table for the source energies and fluxes, you need to set energy to a string:

        trace-shellz4 src=default \
		src_params="energy={specfile={file='foo.rdb'}}; theta=2; phi=3"
      

The format and contents for the spectrum file are described in the documentation

The coord='msc' indicates that theta and phi are specified in the "Mirror Spherical System", the on-orbit polar coordinate system.

Notice that strings such as msc and foo.rdb must be enclosed in single quotes. Be sure that you use the correct quoting convention for whichever UNIX shell that you're using to get the single quotes in the string passed to src_params.

If you want something more than the default object, say something with a spectrum, or a non-point source, your best bet is to consult the documentation for raygen. A script for a simple point source with a spectrum may be found here. We have written some useful software (in Lua) to aid in creating more complicated software, especially if you want to simulate many sources. Please contact Diab Jerius for more information.

Something that's been glossed over until now is how you specify the position of the source. Internally the raygen uses a polar coordinate system (theta and phi) to express the position of the source. While raygen internally requires angles in radians, the source scripts generally let you use more comfortable units. The header documentation in the scripts (e.g. point_01 will inform you of the units. A diagram never hurts:

The relationship of SAOsac's coordinate system to others is shown in the figure below. Probably the most imporant system to worry about is the HRMA coordinate system, which is what is used on orbit (and by MARX). (Well, the XRCF coordinate system is probably useful, but we're trying to forget about that XRCF thing. If you really want to know what the others are, you're a masochist, and we just won't play along.)

For on-orbit raytraces, specifying the "Mirror Spherical System" (coord='msc' in src_params) is convenient. The theta and phi correspond to the theta and phi reported by the the Ciao tool dmcoords.

Determining the Focus

So you'd like your rays to be focussed, eh? If you're going to run your rays into a detector, you'll probably set the front end's z parameter to the position of the detector (this is not necessary if you're passing the rays through MARX) . The origin of the SAOsac coordinate system is the fiducial mark (datum A) on the fore side of the Central Aperture Plate (CAP).

However, if you want to bring the rays to the best focus, you'll need to determine it. Simply set the front end's focus parameter to yes. For each shell specified, as well as for the combination of shells, it will (eventually) produce a file with the extension .focus.lis, which contains a bunch of information. To extract the axial location of the best focus, use the getfocus program (no parameter file needed), which prints the value to the standard output stream:

	trace-nest tag=foo focus=yes
	getfocus foo.focus.lis
    

Because the focus determination is sensitive to scattered rays, focus runs are performed with surface micro-roughness scattering and ghost rays turned off. The source is also changed to be a point source using poin-01 (mono-point_01 or mono-point_02 in old configurations). You will need to specify an energy; see the Sources section for more information.

Current release

• trace-shellz4
• trace-nest3