NAME

SAOdrat - deformed surface intercept and optional reflection

VERSION

SAOdrat Version 1.11 1998-Mar-11

PARAMETERS

SAOdrat uses an IRAF-compatible parameter interface. A template parameter file is in /proj/axaf/simul/lib/uparm/SAOdrat.par.

surf_no: surface number

This parameter specifies the surface number for the optic (normally 1 for the paraboloid of a Wolter type-I optic). This is used to specify which surface to read from the ``gi'' file.

input: input file

This parameter specifies the name of the file/stream for the input bpipe. If the filename is the string stdin, it reads UNIX standard input.

output: output file

This parameter specifies the name of the file/stream for the output bpipe. If the filename is the string stdin, it write to UNIX standard output.

logfile: log file

This parameter specifies the name of the file to contain the raytrace summary and error messages. If no logfile parameter is provided, a warning message is issued and the default value (surfn.lis, where n is the number of the current surface) will be used.

gi_filename: OSAC-style 'gi' file

This parameter specifies the name of the OSAC-style 'gi' file containing the optic prescription. The surf_no'th surface is used.

dfm_type: deformation type

This parameter specifies the type of deformation to be applied:

spline only. dfm_filename specifies a file containing transfit-generated spline deformation coefficients.
Fourier-Legendre only. dfm_filename specifies a cogen-generated Fourier-Legendre deformation file.
Combination of transfit-generated spline and cogen-generated Fourier-Legendre deformations. dfm_filename specifies the spline data and dfm2_filename specifies the Fourier-Legendre data.

dfm_filename: deformation coefficients file

This parameter specifies the name of a file containing the deformation coefficients. The file contains either Fourier-Legendre 'cogen' coefficients, or spline coefficients.

By convention, the following file suffixes are used:

.DFR: ascii file containing cogen-generated Fourier-Legendre 'cogen' coefficients.
.SPL: ascii file containing transfit-generated spline coefficients.
.BSPL: binary file containing transfit-generated spline coefficients.
.spl: binary file containing transfit-generated spline coefficients. New format incorporating precomputed rms amplitude value.

dfm2_filename: deformation coefficients file #2

This parameter specifies the name of a file containing the second set of deformation coefficients to be used in the case that dfm_type = 2. Currently the file must contain cogen-generated Fourier-Legendre coefficients.

dfm_scale: deformation scale parameter

This parameter scales the deformation (and the theta and z derivatives) by a constant. Normally it should be set to 1.0 (no scaling)

dfm2_scale: deformation scale parameter #2

This parameter scales the second set of deformations (and their theta and z derivatives) by a constant. Normally it should be set to 1.0 (no scaling)

theta0: clocking angle

This parameter specifies the reference clocking angle for the optic. theta0 is in degrees; a positive clocking rotates the optic deformation such that a fiducial mark on the +X axis (SAO raytrace coordinates) moves towards the +Y axis.

The SAO raytrace coordinates are:

Z-axis: parallel to the nominal optical axis. Z increases from the mirror towards the focal plane.
Y-axis: ``up''
X-axis: completes a right-handed coordinate system.

theta02: clocking angle #2

This parameter specifies the reference clocking angle for the 2nd set of deformation parameters in the case that dfm_type = 2. theta02 is in degrees; a positive clocking rotates the optic deformation such that a fiducial mark on the +X axis (SAO raytrace coordinates) moves towards the +Y axis.

do_osac_reflect: yes|no

Boolean flag indicating the handling of reflection from the surface.

yes

SAOdrat locates the ray-surface intercept. If the ray intercepts within the bounds of the current optic, the ray is moved to the surface intercept location on the optic and reflected: The ray direction vector is reflected and the outgoing ray polarization state is reflected using the Fresnel equations and the complex dielectric constant which was read in from the ``.gi'' file.

NOTE: this setting is incompatible with the reflect module.

no

SAOdrat locates the ray-surface intercept but does not reflect the ray. The ray position The ray will be reflected by another ray-reflection module.

NOTE: this setting is required when using the reflect module.

If the ray intercepts ahead of the surface (outside the forward boundary), the ray is considered to have a left stop error and is discarded. If the ray intercepts aft of the aft boundary the treatment of the ray depends on the setting of the onlygoodrays flag.

onlygoodrays: yes|no

Boolean flag indicating the handle of ``ghost'' rays, i.e., rays which have not reflected from one or more of the optics encountered so far.

yes: Only those rays which have reflected off each optic (so far) will be passed along the pipeline.
no: Ghost rays will also be passed. Ghost rays include nonreflected rays and rays which miss at least one optical surface. The position and direction of the ghost ray correspond to the ray position/direction just after the last successful reflection.

Rays which are marked bad by SAOdrat for other reasons (e.g., left stop errors, negative pathlength errors, ...) are not considered to be ghost rays and are not passed.

help: yes|no

Print out a simple help message and exit.

version: yes|no

Print out SAOdrat's version and exit.

debug: list

A list of debug flags. The presently supported flags are:

extend_all: increase the extent of all BPipe data fields by one; this allows a history of data values to be accumulated.

DESCRIPTION

SAOdrat reads BPipe format rays finds the intercept point of the ray with a deformed surface.

If the parameter do_osac_reflect = yes and the ray hit within the bounds of the surface, SAOdrat will also reflect the ray.

If the ray hits with Z coordinate less than the specified Z for the edge at smaller Z, the ray is absorbed (``left-stop error'').

If the parameter onlygoodrays = yes and the ray intercepts with Z greater than the Z for the edge at larger Z (i.e., the ray missed the surface), the ray is considered invalid and removed from the stream.

If the parameter onlygoodrays = no and the ray intercepts with Z greater than the Z for the edge at larger Z (i.e., the ray missed the surface), the appropriate ghost ray flag is set in the bpipe ray.

History

The SAOdrat module is built atop the OSAC (Optical Surface Analysis Code) library. OSAC was developed for Goddard Space Flight Center by the Perkin-Elmer corporation under NASA contract NAS5-25802; four revisions were developed and programmed for Goddard Space Flight Center by Paul Glenn of Bauer Associates. The current version level for OSAC is Version 7.0. A fuller description of the OSAC suite of programs is provided in the Optical Surface Analysis Code (OSAC) Version 7.0 User's Manual, 2nd edition, August 11, 1993, available from the Goddard Space Flight Center.

The SAOsac version of OSAC library is based on Version 5.0 of the OSAC suite, revised and updated to incorporate the modifications and bug fixes from Versions 6 and 7 of the OSAC suite.

The SAOdrat module is modeled in part on the drat program of OSAC. drat is a stand-alone program which performs a raytrace of a (possibly deformed) optic. In OSAC, the trace is initialized by geosac, and an invocation of drat is run for each surface to be traced. The first invocation of drat generates the rays on a ``ring and spoke'' pattern within an annulus located at plane Z = 0 in the OSAC standard coordinate system (STD). A final invocation of drat locates the focus and moves the ray to a specified plane. The separate invocations of drat communicate via ascii ray data files.

Because of the limitations OSAC, a modified version of OSAC, dubbed frSAOsac, was developed by members the Smithsonian Astrophysical Observatory AXAF Mission Support Team (SAO/MST) Simulations and Analysis group together with members SAO Central Engineering. The chief problems to be addressed by the initial version of frSAOsac were:

the maximum number of rays was limited to approximately 100000; this is too small for many simulations.
the intermediate ascii rayfiles can be enormous; the disk i/o associated with reading and writing the files imposes too much of a performance hit.
the deformations handled by OSAC (specified by Fourier-Legendre coefficients) are not capable of handling the deformations produced by the mechanical modeling of the AXAF optics.
the monolithic nature of drat made it hard to modify.

Design

It was decided to set up the raytrace system based on the UNIX filter paradigm: the drat functionality was handled by a set of programs communicating via UNIX pipes. A program reads a ray from its standard input stream, manipulates it and writes it to its standard output stream. The use of pipes avoids the necessity of reading and writing large ascii data files.

The programs are completely independent from each other, making program development as well as validation and verification much easier. Programs can be added or removed from the pipeline, greatly adding to the flexibility.

The OSAC deformed surface raytrace capability was factored into a set of programs

frRaygen: Generate rays on an input ray bundle annulus. The source can be a finite distance or at infinite (1 x 10^30) distance. Rays can be generated on a (ring and spoke) grid pattern of up to 500 rings and 500 spokes. Rays can also be generated with a random distribution within the input ray bundle annulus.
frSAOdrat: Trace rays through a (possibly deformed) optic. The frSAOdrat module was based based on drat, with modifications to communicate via binary streams read from standard input and written to standard output.
frSAOfocus: Determine the Gaussian focus; locate the best focus location and transport rays to the focal plane.

The modules were converted to use the BPipe interface and as of version 1.0, frSAOdrat was renamed to SAOdrat and frSAOfocus was renamed to SAOfocus.

See Revision List for further details.

OTHER

This version of SAOdrat makes extensive use of routines from the NASA Goddard Space Flight Center code OSAC, ``Optical Surface Analysis Code''.

This version of SAOdrat also makes use of spline evaluation routines from the Numerical Algorithms Group (NAG) library Data Approximation Subroutine Library (DASL).

AUTHORS

MDF Mark Freeman (SAO/Central Engineering)
TJG Terry Gaetz (SAO/AXAF Mission Support Team)
DMG David Grumm (SAO/AXAF Mission Support Team)

REVISION LIST

pre version 0.0: 1993: MDF: Original version.
version 0.0: 1993 Dec 16: TJG: Baselined version.
version 0.1: 1995 Jan 10: TJG: Extend precision for frSAOfocus outputs.
versions 0.2 - V0.5: 1995 Oct 12: TJG: Add OSAC V7.0 updates.
version 0.6: 1995 Oct 23: TJG: Add deformation clocking and scaling capabilities; enlarge spline deformation arrays
version 0.7: 1995 Oct 30: TJG: Clean up clocking and scaling tests. Add version parameter to frSAOfocus
version 0.8: 1995 Nov 29: TJG: Simplify and reorganize test scripts. Increase spline arrays: MX_QX = 450, MX_NTKNTS = 300. allow ray input bundle z coordinate to be -1,000,000 to 1,000,000 rather than 0 - 1,000,000.
version 0.9: 1996 Jan 25: TJG: Add in modifications to activate do_osac_reflect=no option. Rework test scripts and add frSAOdrat + reflect tests.
version 0.91: 1996 Feb 27: TJG: Add in modifications to support binary spline deformation files. Add test scripts for binary spline i/o tests.
version 0.92: 1996 May 14: TJG: Modifications to support SGI IRIX64. Fixed SAOfocus infinite loop bug. Revised test scripts.
version 0.93: 1997 June 3: DMG: Add modifications to allow single element deformations that are the sum of a spline deformation and a Fourier/Legendre deformation, and add test scripts for test cases for combination tests. Fix gi files to eliminate warning generated when last record read.
version 1.0: 1997 Dec 12: DMG: Convert drat module from fullray to BPipe format; module name changed from frSAOdrat to SAOdrat. Ensure existence of appropriate data fields. Correct handling of ghost ray flag using bit array. Add graze angle field to output stream. Install a floating point exception handler. Add debug parameter option to extend data fields.
version 1.01: 1998 Feb 10: TJG: Change SNGL to DBLE throughout saosacLib. Added help parameter. Added perl pod documentation. Revised UDF to include only most recent version of parameter descriptions.

version 1.1: 1998 Mar 10: TJG: Add support for new spline file format; add autorecognition of spline file formats. Spline arrays are now handled on the C side of the divide and the space is dynamically allocated.

version 1.11: 1998 Mar 11: TJG: Fixup for new spline format.