NAME

ascaray -- ASCA mirror ray tracing program

USAGE

        ascaray outfile

DESCRIPTION

This is a conversion of the Nagoya ray tracing program "ray2areav6_0cal" into an FTOOL. This program is being supplied as part of the ASCA Ftools package so that users can see the techniques used in determining the telescope parameters used to generate calibration files.

This program allows the same level of control over the ray tracing as the original Nagoya "ray2areav6_0cal". The physical parameters describing the mirror are set as defaults in the parameter file. In general, users should resist the desire to tune these parameters for a better fit to their observation without confirming with Nagoya and GSFC ASCA staff. Parts of parameter space have already been excluded by analysis done by members of the Nagoya and GSFC XRT teams. Any improvement in spectral or spatial fit that would be found by changing key parameters would most likely be an accident. This program is expected to be heavily modified and possibly superceded for the next release.

PARAMETERS

outfile [Output FITS result file name]

Name of the FITS output file that will contain the raytracing results. This file may already exist in which case the new ray tracing result binary extention will be inserted/appended as the 1st file extention. Extention numbers supplied in the file name are ignored. Existing extentions will be moved down to make room. The program will check to see if the FITS primary header is compatible with the ASCARAY image requirements if an output image is requested. Non-matching FITS files will be refused as output files.

xrtfile [ASCA XRT description file name]

The name of the file containing the description of the X-Ray Telescope. If this parameter is set to "DEFAULT", then the name is taken from the hidden parameter, defxrtfile.

runmode [(1=Single Energy, 2=EffectiveArea, 3=PSF)]

This parameter specifies which mode the program is to run in: 1, Single Energy mode; 2, Effective Area mode; 3, Point Spread Function mode. Single Energy mode traces a specific number of photons at a specific energy. Effective Area mode traces photons at 300 energies between 0.1 and 12 keV. The number traced is set by parameter, nea, which sets the minimum number of photons required to fall within 12 arcmin of the PSF center pixel. Point Spread Function mode traces photons at 11 energies between 1.0 and 10 keV. The number traced is set by the parameter, npsf, which sets the minimum number of photons required to fall within 12 arcmin of the PSF center pixel.

nph [ONLY IF RUNMODE=1; Number of photons to trace for SE mode]

The maximum number of photons to trace.

energy [ONLY IF RUNMODE=1; real; keV; min=0.1 max=12.0]

The exact energy of the photons that should be traced.

atomic [Atomic constants? 1:Owens 2:Old Nagoya]

Specify which set of atomic constants to assume for surface reflections. OWENS are Owens updated Henke constants (1992) as created by Keith Gendreau at GSFC. NAGOYA are the constants used by Nagoya University XRT staff in the development of the "ray2areav6_0cal" program.

goldens [ONLY IF ATOMIC=1; real; gcm**-3]

The gold density to assume for the suface of the foils. Nominal gold density is 19.3 g/cm**3 but sputtered gold has a lower density based on the AXAF mirror tests.

incang1 [real; arminutes; min=0, max=120]

The photon incident angle in the off-axis direction.

incang2 [real; degrees; min=0, max=360]

The photon incident angle in the rotation direction.

difftype [integer; 0:flat field, 1:Beta model, other:point source]

The diffuse source type for traced photons.

beta [ONLY IF DIFFTYPE=1; real; min=0.0]

BETA for Beta Model diffuse source.

diffang [ONLY IF DIFFTYPE=0 OR 1; real; min=0.0]

Diffuse radius for Flat Field (DIFFTYPE=0) model. Core radius for Beta (DIFFTYPE=1) model.

region [0:quadrant, 1:Full telescope, 2:One sector]

The region of the telescope to map photons over. This is primarily useful for simulating ground tests where only part of the telescope is present.

rough [real; min=0.0]

The foil surface micro-roughness parameter. This is generally compensated for in the built-in scattering function.

sigma1 [real; arcminutes; min=0.0]

This is the Lorentzian Gamma parameter for sectors 3-12 of a telescope quadrant. Telescope quadrants are divided into 14 sectors defined by the foil alignment bars. The original Nagoya code allows different gamma's for the center of the quadrant and its edges to compensate for foil twisting near the edges.

lalin [real; per arcminute; min=0.0]

Parameter for the inclination of the linear function.

sigma2 [real; arcminutes; min=0.0]

This is the Lorentzian Gamma parameter for sectors 2 and 13 of a telescope quadrant. Telescope quadrants are divided into 14 sectors defined by the foil alignment bars. The original Nagoya code allows different gamma's for the center of the quadrant and its edges to compensate for foil twisting near the edges.

consct [real; < 1:Do not consider; >= 1:Consider]

Whether to consider scattering or not. See the raytrace_fscat and raytrace_raycha subroutines for a full understanding of the various controls on the scatter functions.

flct [boolean]

Should foil misalignment be simulated (yes/no)? This parameter controls whether the XRT file standard radii of the foils should be randomly perturbed by a small amount. This simulates a slight misalignment in the foil radii caused by launch forces and play in the foil alignment bar teeth.

image [boolean]

Should an image of the focal plane be stored in the output FITS file (yes/no)? This parameter allows control over the focal plane PSF image. NO reduces the output FITS file size and makes the program run slightly faster. This control feature is inherited from the original Nagoya program.

xymin [ONLY IF IMAGE=YES;real; millimeters]

Sets the minimum x- and y-axis values in mm for the output image.

xymax [ONLY IF IMAGE=YES;real; millimeters]

Sets the maximum x- and y-axis values in mm for the output image.

xybins [ONLY IF IMAGE=YES;integer; min=0, max=1024]

Sets the x- and y-axis size (in bins) for the output image. Typically a power of 2 is choosen.

eefcalc [boolean]

Should the (photon-type independent) Encircled Energy Function be calculated (yes/no)? This parameter turns on and off the calculation of the EEF which is done at the focal plane using all sources of photons. NO makes the program run slightly faster. This control feature is inherited from the original Nagoya program.

(nea=500000) [ONLY IF RUNMODE=2; Minimum number of photons for EA mode]

The minimum number of photons to trace.

(npsf=10000) [ONLY IF RUNMODE=3; Minimum number of photons for PSF mode]

The minimum number of photons to trace.

(ranseed = 29075) [integer; min=1, max=2**31]

The starting integer seed for the random number generator used for determining photon locations and reflection probabilities.

(defxrtfile = "ascaxrt1_0.fits") [Default name of ASCA xrtfile]

The default name for the FITS file that contains information on the construction parameters of the x-ray telescopes.

(mask = yes) [boolean; DEFAULT TO YES]

This parameter specifies whether a mask is present over the telescope aperture. The current code always assumes the presence of a mask so this parameter has no effect. This control feature is inherited from the original Nagoya program.

(telescope = 0)

Present code assumes no difference between the four telescopes. This parameter is provided for future possible use.

(calss3 = 0.0) [real]

This parameter provides adjustment to the scattering function "raytrace_fscat". Do not attempt to set it unless you clearly understand the code in this subroutine.

(calsc3 = 0.0) [real]

This parameter provides adjustment to the scattering function "raytrace_fscat". Do not attempt to set it unless you clearly understand the code in this subroutine.

(verbose = no) [boolean]

This parameter allows control over informational messages from the program while it is running. Currently, YES will output a terminal message showing the current energy and photon traced count every 10,000 photons. This is primarily useful for long runs to keep track of the progress of the program.

(mode = "ql") [string]

System parameter to control saving/learning of parameter values from previous runs.

EXAMPLES

BUGS

SEE ALSO

CATEGORY