The MARX User’s Guide

Michael W. Wise, John E. Davis, David P. Huenemoerder, and Chris Baluta

Version 1.0

July 15, 1997

MIT Center for Space Research AXAF Science Center 70 Vassar St. Building 37 Cambridge, MA 02139–4307 USA

CONTENTS  i

Contents

MARX User’s Guide · Version 1.0

ii  List of Figures

List of Figures

MIT Center for Space Reseach

List of Tables  1

List of Tables

MARX User’s Guide · Version 1.0

2  List of Tables

\underline{3}

Section 1

Introduction

1.1 MARX

This Guide describes the MIT MARX AXAF simulator. MARX (Model of AXAF Response to X-rays) consists of a suite of programs designed to enable the user to simulate the on-orbit performance of the AXAF satellite. It contains models for the HRMA mirror system onboard AXAF as well as the HETG and LETG gratings and all focal plane detectors. With the appropriate configuration, MARX can also be used to simulate calibration data taken at the XRCF facility in Huntsville, AL.

MARX consists of a number of UNIX executables and has been successfully built under SunOS, Solaris, Linux, HP/Unix, and NEXT systems. The package includes routines to generate simulations as well as programs to work with the simulated output. This Guide is designed to serve as an introduction, user’s guide, and definitive reference manual to the MARX simulation suite.

1.2 Purpose of MARX

MARX was originally developed to provide sample AXAF data with an exactly known instrument response in order to develop and test spectral extraction and analysis algorithms. It has since developed into an accurate and flexible model of the in–flight capabilities of AXAF and provides a fast and portable alternative to other simulation methods. Here we list some of the uses MARX simulations serve within the ASC Data System:

• Development of data analysis software MARX provides realistic data incorporating a variety of physical effects which characterize AXAF. These data are being used to develop new algorithms, such as event–based spectral extraction of HETG and LETG spectra, or deconvolution of overlapping orders in the case of the LETG. MARX simulations provide knowledge of the exact solution for comparison with the reconstructed data.

• Fitting and Data Analysis As part of the ASC Data System, a fitting application is being designed to allow comparison of models with calibration and flight data. In addition to its built–in stable of models, ASCFIT will be capable of driving MARX to produce detailed simulations for comparison to data.

• Calibration Ground calibration of AXAF utilized detailed predictions to plan the tests and as an aid to the interpretation and digestion of resulting test data. Many of these predictions were computed using MARX.

• Flight Observation planning MARX provides a realistic model of the AXAF response to cosmic X–ray sources and can be used for detailed planning of anticipated science programs. One may investigate issues related to sensitivity, spatial resolution, or spectral resolution. MARX will be released to the community as part of the proposal planning software package.

• Prototyping testbed The MARX simulator can be used as an infrastructure for testing new ideas pertaining to instrumentation. For example, the design for the Drake high–order suppression filter for the HRC–S camera was studied and refined using MARX .

1.3 Organization of this Guide

In Section ??, we provide an overview of MARX ’s functionality as well as the various assumptions and limitations inherent in the models. Section ?? reviews the reference data files used by MARX to simulate AXAF.

Users in a hurry to install MARX should proceed directly to Section ??. Instructions for obtaining and compiling the MARX suite are described there. Section ?? describes the various options and calling sequences for the different tools contained in the suite.

Detailed instructions for running MARX simulations are available in Section ??. This section also descibes the various output formats produced by MARX . Examples are also provided to assist the user in creating input spectra for MARX using XSPEC. Instructions for simulating the effects of pileup in the ACIS CCD’s are discussed separately in Section ??. Section ?? discusses some of the options users have in working with MARX output including FTOOLS and IDL routines.

In addition to MARX , the ASC has also developed an extremely high fidelity raytrace model of the HRMA onboard AXAF called SAOSAC. Using MARX in conjunction with SAOSAC is described in Section ??.

For reference, a comprehensive list of the MARX control parameters is given in Appendix ??. Appendix ?? contains examples of the typical FITS headers produced by the tools.

1.4. OBTAINING HELP AND ADDITIONAL INFORMATION  5

1.4 Obtaining help and additional information

1.4.1 marxhelp

If you encounter a problem with MARX which is not addressed by this manual, please send an email describing your problem to:

marxhelp@space.mit.edu

When sending mail to marxhelp, please be sure to include the version of MARX you are using as well as any diagnostic output or error messages produced. Bug reports and comments should also be send to this email address.

1.4.2 marxnews

Updates to the MARX software suite will be provided periodically. Annoucements about these updates will be disseminated via an email exploder. To be added to the mailing list for MARX updates, please send an email to:

listserv@space.mit.edu

In the text of the email, include the single line:

subscribe marxnews Firstname Lastname

and you will be automatically notified of future updates.

1.5 MARX home page on World Wide Web

The MIT ASC group maintains a MARX web page at:

http://space.mit.edu/ASC/MARX/marx.html

The latest version of MARX is available for downloading as well as an online version of this User’s Guide.

1.6 MARX information via FTP

In addition to Web access, the latest MARX distribution and associated routines and information can be obtained via anonymous FTP at:

ftp://space.mit.edu/pub/ASC/MARX

MARX User’s Guide · Version 1.0

6  SECTION 1. INTRODUCTION

The directory contains a README file detailing the available information.

1.7 Acknowledgements

We gratefully acknowledge the aid and support of various members of the AXAF project including the Mission Support Team, the Calibration group, and the Data Systems group.

Section 2

Overview of Functionality

2.1 Introduction

MARX provides the capability to simulate the various combinations of scientific instruments on–board the AXAF satellite and includes models of the AXAF mirrors, the low– and high–energy transmission grating assemblies (LETG and HETG), and the HRC and ACIS focal plane detectors. For several components of the system, the user may choose between several simulation modes depending on their needs. The mirrors, for example, can be simulated using a simple effective area model or via a full ray–trace if desired. A number of simple source models (extended or point–like) are supported and users may extend the capabilities by incorporating their own models. Sources may have arbitrary spectral energy distributions which are specified via an input ASCII file. MARX also provides support for simulations of ground–based calibration tests at XRCF. The HRMA shutter assembly is modelled as well sources at a finite distance. The purpose of this section is to provide technical information about the implementation of the various subsystems of MARX .

2.2 Simulation Control

[To be added]

2.3 Source Models

MARX provides support for both extended and point sources, which can be either on or off-axis. The sources can have a flat energy spectrum or they can use an energy spectrum supplied by the user. For even more flexibility, MARX has the ability to dynamically link to user-defined source models. Finally, the marxcat program may be used to merge simulations to form a composite simulation of multiple sources.

MARX supports the following source types:

   • POINT

This is simply a point source.

   • LINE

This source is mainly used for diagnostic purposes.

   • GAUSS

This is an extended source that has a Gaussian spatial profile.

   • BETA

This source represents the so-called beta model that is used for modeling galaxy clusters.

   • RAYFILE

This is a special source that represents partially processed rays.

   • DISK

This source is useful for modeling extended objects such as a supernova.

   • USER

This source refers to a user-defined source that is dynamically loaded.

These sources will be discussed in detail later. First, it is important to have an understanding of what a source means in the context of MARX . It is particularly important to understand how MARX interacts with a source model for the proper implementation of a user-defined source.

As far as MARX is concerned, a source is characterized by the distribution of rays in energy, time, and direction that it produces at the entrance aperture of the telescope. Implicit in this characterization is the assumption that the source is sufficiently far away that the flux does not vary with position across the telescope.

To be more precise, let

F (t, E, p̂, x⃗)(p̂ · dA⃗ )dΩ dE dt  (2.1)

denote the number of rays with energy between E and E + dE, and whose directions lie in a solid angle dΩ about the direction p̂, crossing an area element dA⃗ at x⃗ during the time dt. That is, F (t, E, p̂, x⃗) is a space-time dependent flux density. If the source is very far away, as is the case for objects of astrophysical interest, the spatial dependence of the flux density may be ignored when x⃗ refers to points near the telescope. For this reason, F will be assumed to be independent of x⃗. Similarly, since the angular acceptance of the telescope is very small (on the order of arc-minutes), to first order we need only consider area elements dA⃗ whose normals are in the direction of the source. Hence, p̂ · dA⃗ will simply be written as dA .

We can consider various classes of source models according to whether or not F factors. For example, all MARX sources with the exception of the USER source produce fluxes that are time-independent with an energy spectrum that is uncorrelated with the direction of the flux (see section ?? for more information about the USER source). For the rest of this section, we will only consider the class of models for which F can be written

F (t, E, p̂) = f(t) · f_{E}(E) · f_{p}(p̂).  (2.2)

When such a factorization is possible, it will be assumed that f_{E}(E) and f_{p}(p̂) are normalized, i.e.,

1 = ∫_{Ω} dΩ f_{p}(p̂),  (2.3)

and

1 = ∫ dE f_{E}(E).  (2.4)

With this normalization,

f(t) = ∫ dE ∫_{Ω} dΩ F (t, E, p̂)  (2.5)

is simply the total flux, which can depend upon time. In the following, we shall call f_{E} the energy spectrum, and f_{p} the angular distribution of the source.

2.3.1 Source Spectral Models

2.3.1.1 General

2.3.1.2 Flat

2.3.1.3 User Supplied

In the MARX parameter file, marx.par, the parameter SpectrumType is used to specify the function f_{E}. Currently, f_{E} can only be a FLAT spectrum or a FILE spectrum. Similarly, when f(t) is time-independent, as it for all MARX sources in this class, then its value is specified by the SourceFlux parameter. See section ?? for more information about these parameters.

2.3.2 Source Spatial Models

The distribution function f_{p}(p̂) characterizes the angular distribution of the flux and, hence, the angular distribution of the source. MARX assumes that this distribution function specifies an on-axis source and that the source can be moved off-axis via the SourceElevation and SourceAzimuth parameters.

By convention, f_{p}(p̂) is assumed to be normalized to unity, i.e.,

1 = ∫_{0}^{π} sin θdθ ∫_{0}^{2π} dϕf_{p}(θ, ϕ),  (2.6)

where p̂ has been expressed in spherical coordinates. For an azimuthally symmetric source, f_{p} is independent of ϕ and the normalization condition reduces to

1 = 2π ∫_{0}^{π} dθ sin θf_{p}(θ).  (2.7)

2.3.2.1 POINT Source

The POINT source corresponds to an angular distribution function given by

f_{p}(θ, ϕ) = \frac{1}{2π} δ(ϕ)δ(1 − cos θ)  (2.8)

2.3.2.2 LINE Source

The LINE source corresponds to a to an angular distribution function given by

f_{p}(θ, ϕ) = \frac{1}{θ_{0}θ} · \frac{1}{2}[δ(ϕ − ϕ_{0}) + δ(ϕ − ϕ_{0} − π)]  (2.9)

for θ < θ_{0} and zero otherwise. Here θ_{0} may be set via the S-LineTheta parameter and the S-LinePhi controls the value of ϕ_{0}.

2.3.2.3 GAUSS Source

The GAUSS source corresponds to a to an angular distribution function given by

f_{p}(θ, ϕ) = \frac{1}{π} e^{−θ^{2}/θ_{0}^{2}}  (2.10)

where θ_{0} determines the width of the Gaussian distribution. This value may be set via the

S-GaussSigma parameter.

2.3.2.4 BETA Source

The source corresponds to a to an angular distribution function given by

f_{p}(θ, ϕ) = \frac{1}{2π} · \frac{6}{θ_{c}} (β − \frac{1}{2})[1 + (\frac{θ}{θ_{c}})^{2}]^{−3β+ \frac{1}{2}} .  (2.11)

The core radius, θ_{c} is specified by the S-BetaCoreRadius parameter, while S-BetaBeta controls the value of β. This distribution is used to model galaxy clusters.

2.3.2.5 DISK Source

The DISK source corresponds to a to an angular distribution function given by

f_{p}(θ, ϕ) = \frac{1}{2π} · \frac{2}{θ_{1}^{2} − θ_{0}^{2}}  (2.12)

for θ_{0} <= θ < θ_{1}. Outside this region, it is zero. The values θ_{0} and θ_{1} correspond to the parameter file parameters S-DiskTheta0 and S-DiskTheta1, respectively. This source actually generates a ring structure and is useful for modeling a supernova remnant.

2.3.3 USER Source

The USER source is the most versatile of the MARX sources. This is because it is a user-defined source where each ray may be given an independent energy, time, and direction. This means that one does not need to demand that the flux density factorize as was assumed for the other MARX sources. This permits one to simulate sources whose spectrum changes with time, complex extended objects, etc.

A user-defined source model must be created by the user using a language such as C and then compiled as a shared object. During run-time, MARX will dynamically link to this shared object and use it to generate rays. To use this source, first and foremost, the underlying operating system must support dynamic linking. Operating systems such as Linux and Solaris support dynamic linking while others such as NeXT do not. It is important to understand that creating a user-defined source does not mean that MARX must be recompiled. If that were the case, then there would be no value to a user-defined source.

Creating a such a source is relatively simple and is best accomplished using the C programming language. The C source file must define three functions that MARX will call during run-time:

   user_open_source
   user_close_source
   user_create_ray

The user_open_source function will be called by MARX before any rays are generated. The purpose of this function is to initialize any data structures required by the user_create_ray function. The user_create_ray function will be called one time for each ray generated. The purpose of this routine is to assign an energy, time, and direction to a ray. Finally, the user_close_source function will be called when MARX has finished processing rays. Each of these functions are described in more detail below.

2.3.3.1 user open source

The user_open_source function has the prototype:

  int user_open_source (char *str,
                        double area,
                        double cosx,
                        double cosy,
                        double cosz);

Here the character string str will refer to the string value of the marx.par parameter UserSourceArgs. The actual meaning of the contents of this parameter will depend upon the details of the user-defined source. For example, if the user-defined source needs to read an external data file, the parameter can represent the name of the data file.

The area parameter specifies the area in cm^{2} of the entrance aperture of the mirror. Knowledge of this value is necessary to compute the time interval between rays since the incoming flux must be multiplied by this value to generate the total incoming photon rate.

The other three parameters cosx, cosy, and cosz are the direction cosines of a ray from a reference point on the source to the origin of the MARX coordinate system. These numbers are derived from the MARX parameter file SourceElevation and SourceAzimuth parameters. For an on axis source, cosy and cosz will be set to zero, but cosx will be set to -1. If the reference point of the user defined source is always on axis, these parameters may be ignored and the actual parameter values for SourceAzimuth and SourceElevation will have no affect on the rays generated by source. However, if one would like to position the source off-axis via the SourceElevation and SourceAzimuth parameters, the values of the direction cosines will need to be taken into account. An example of this is presented below.

Upon success, user_open_source must return 0. If for any reason it fails, e.g, unable to open a file, it must return -1.

The simplest example of user_open_source is one which does nothing:

  int user_open_source (char *str,
                        double cosx,
                        double cosy,
                        double cosz)
  {
     return 0;   /* Success */
  }

2.3.3.2 user close source

The user_close_source function has the prototype:

   void user_close_source (void);

Its purpose is to free up any resources acquired by the source. For example, if the source dynamically allocated memory, user_close_source should deallocate it.

2.3.3.3 user create ray

The user_create_ray function is the function that actually defines the source by endowing each ray with a direction, energy, and time. It has the following prototype:

   int user_create_ray (double *delta_t, double *energy,
                        double *cosx, double *cosy, double *cosz);

Since the purpose of this routine is to assign a ray an energy, time, and direction, the parameters are actually pointer types and the requested information is passed back to the calling routine via the parameter list. It is important to note that the ray is completely undefined prior to calling this function.

The delta_t parameter is used to give the ray a time-stamp. Actually it does not refer directly to the absolute time of the ray; rather, its value should refer to the time since the last ray was generated. For example, if a ray is generated every second,

   *delta_t = 1.0;

should be used. If *delta_t is set to -1.0, then MARX will generate the time based on the SourceFlux parameter. Otherwise, the value should be set in a manner consistent with the flux and the geometric area of the mirror.

The meaning of the other parameters that specify the energy and direction cosines should be rather clear. If energy is set to -1.0, then MARX will use the setting of the SpectrumType parameter to assign an energy to the ray.

2.3.3.4 Compiling a User-Defined Source

The procedure for compiling a user-defined source as a shared object will depend upon the operating system. For details, consult you compiler and linker manual. For the purposes of this section, it is assumed that the file containing the code for the user-defined source is called mysource.c. This may be compiled as a shared object under Linux using gcc via the command:

    gcc -shared mysource.c -o mysource.so

If mysource.c requires other libraries, they should also be included on the command line. The syntax is slightly different under Solaris:

    cc -G mysource.c -o mysource.so

To actually use the source in MARX , set the marx.par parameter SourceType to USER and also set the parameter UserSourceFile to point to the full absolute filename for mysource.so. It is usually necessary to use an absolute filename because of the way the dynamic linker searches for shared objects. Finally, set the parameter UserSourceArgs to a value that is appropriate to your source.

If running marx using your dynamically linked source causes it to crash, do not assume that the bug is in MARX . Rather, it is most likely a bug in your code. Make sure that the interface routines are properly prototyped and that the routines return the proper values to MARX . If you use dynamic memory allocation, check the return status of routines such as malloc. Finally, look at the examples provided with the MARX distribution and try to run those.

2.3.3.5 Examples of User-Defined Sources

The simplest source is that of a point source. Although MARX already provides built-in support for this source, it is instructive to write it as a user-defined source. Here is the complete C code for such a source:

#include <stdio.h>
static double Source_CosX;
static double Source_CosY;
static double Source_CosZ;
int user_open_source (char *cmd_args, double area,
                      double cosx, double cosy, double cosz)
{
   Source_CosX = cosx;
   Source_CosY = cosy;
   Source_CosZ = cosz;
   return 0;
}
void user_close_source (void)

{
}

int user_create_ray (double *delta_t, double *energy,
                     double *cosx, double *cosy, double *cosz)
{
   *cosx = Source_CosX;
   *cosy = Source_CosY;
   *cosz = Source_CosZ;
   *delta_t = -1.0;
   *energy = -1.0;
   return 0;
}

First of all, note that energy and delta_t have been set equal to -1.0 in user_create_ray. This indicates to MARX that it should compute the time and energy of the ray via the SpectrumType and SourceFlux parameters. For this reason, the area parameter was not used by user_open_source. Since the direction cosines passed to user_open_source refers to the vector from the position of the source to the origin where the telescope is located, those values were saved and used in user_create_ray.

For more complex examples, look at the files under marx/doc/examples in the MARX distribution.

2.3.4 Source Temporal Models

This functionality has not been implemented yet.

2.4 HRMA model

MARX implements two types of mirror modules. Either may be selected via the MirrorType parameter. The EA-Mirror is considered to be obsolete may eventually be phased out. Unlike the EA-Mirror, the HRMA mirror is a ray-traced mirror module that permits may be used with off-axis and extended sources. The EA-Mirror is only limited to on-axis point sources. For these reasons, the discussion will be confined to the HRMA mirror.

The HRMA mirror geometry is that of four Wolter Type I mirrors. Each shell consists of a paraboloid at the front and a hyperboloid at the back. The ray trace involves reflecting a ray off of the front paraboloid mirror and off of the back hyperboloid mirror. The mirror shells are assumed to coated with iridium and the iridium optical constants as provided by the 1995 Henke Tables are used to compute the reflectivity of the ray.

The PSF of the mirror is modeled as follows: The direction of a ray after reflection from the mirror surface is determined by the orientation of the surface normal at the point of reflection. We make the assumption that the direction of the normal can vary from its ideal direction according to a gaussian probability distribution whose standard deviation is given by the HRMABlur parameter. Unfortunately, this model produces a crude approximation to the measured PSF of the mirror. In particular, the energy-dependence of the PSF is not modeled and it fails to produce the long scattering tails of the PSF. On the other hand, these differences do not appear to be very important for off-axis sources since most of the off-axis mirror PSF is due to the geometry, which MARX does handle.

MARX does have the ability to read and process wfold scattering tables to produce a PSF that has the correct energy-dependence and scatter tails. Unfortunately, at this time we do not have the proper wfold data files to distribute with MARX .

2.5 Grating Modules

AXAF contains two distinct grating assemblies called the HETG and the LETG. The HETG is meant to be used for high energy xrays and the LETG is optimized for low energy xrays. Actually, the HETG consists of two types of gratings: MEG for medium energy rays, and HEG for high energy rays. The LETG consists entirely of LEG type gratings. Each grating facet is arranged such that its geometric center lies on a Rowland Torus. The MEG torus is rotated by −5 degrees with respect to the LEG torus, and the HEG torus is rotated by +5 degrees with respect to the LEG torus.

After a ray leaves the mirror it travels towards the detector. If the gratings are being used, the ray will intersect the grating and undergo a diffraction process. Actually, a certain percentage of the rays will not strike a grating facet; instead some will be absorbed by the grating assembly. The percentage of rays that intersect with a facet is specified by the appropriate vignetting parameter, LETGVig if the LETG is being used, or HETGVig if the HETG is used.

MARX currently knows very little about the actual location of individual grating facets. The assumption is that the HRMA and the grating assembly is aligned such that the probability of a ray striking a facet is maximized, and the percentage that miss is controlled by the vignetting factor.

2.5.1 Intersection with the Rowland Torus

The Rowland torus is defined by the equation

(x^{2} + y^{2} + z^{2})^{2} = 4R^{2}(x^{2} + z^{2})  (2.13)

where R is the Rowland radius. To determine the intersection of a ray with the torus, (??) is substituted into the equation for the torus. This yields the fourth order equation for t

\begin{aligned}0 = t^{4} & + 4(p̂ · x⃗_{0})t^{3} \\ & + 2t^{2}(|x⃗|^{2} + 2(p̂ · x⃗_{0})^{2} − 2R^{2}(p_{x}^{2} + p_{z}^{2})) \\ & + 4t(|x⃗_{0}|^{2}(p̂ · x⃗_{0}) − 2R^{2}(p_{x}x_{0} + p_{z}z_{0})) \\ & + |x⃗_{0}|^{4} − 4R^{2}(x_{0}^{2} + z_{0}^{2}) \end{aligned}  (2.14)

where the vector x⃗_{0} has components (x_{0}, y_{0}, z_{0}). The four roots of this equation are a manifestation of the fact that a line can intersect the torus at four different places.

An important case is when x⃗_{0} = 0 where an enormous simplification occurs and the equation reduces to

0 = t^{4} − 4R^{2}t^{2}(p_{x}^{2} + p_{z}^{2}).  (2.15)

This equation has a double root at 0 and non-zero roots at

t = ±2R\sqrt{p_{x}^{2} + p_{z}^{2}}.  (2.16)

In the coordinate employed by MARX , rays travel in the negative x direction from the HRMA to the torus. This means that the solution of interest is the most negative root of (??). Such a root corresponds to the first intersection point of the ray with the torus.

Even if x⃗_{0} is non-zero, one can always project the ray to the x = 0 plane to make the component x_{0} = 0. One can then argue that the remaining two components z_{0} and y_{0} will be small (i.e., z_{0} << R) since the rays from the HRMA will be converging to the focal point located at the center of the torus. The upshot is that (??) is a good zeroth order approximation to the exact solution and that one can use this value as the starting point in an iterative solution^{1} to (??).

Let t be the solution to the equation 0 = f(t) and let t_{0} represent an approximate root. If δt = t − t_{0}, then a taylor expansion yields

0 = f(t)
= f(t_{0} + δt)
= f(t_{0}) + δtf′(t_{0}) + ⋯

or

t = t_{0} − \frac{f(t_{0})}{f′(t_{0})} + · · · .  (2.17)

Newton’s method follows from the last expression as an iterative solution of the form

t_{k+1} = t_{k} − \frac{f(t_{k})}{f′(t_{k})}.  (2.18)

For the quartic equation

0 = t^{4} + at^{3} + bt^{2} + ct + d,  (2.19)

Newton’s method yields the iterative scheme

t_{k+1} = \frac{(3t_{k}^{2} + 2at_{k} + b)t_{k}^{2} − d}{(4t_{k} + 3a)t_{k}^{2} + 2bt_{k} + c}  (2.20)

From (??), it follows that

\begin{aligned}a & = 4p̂ · x⃗_{0} \\ b & = 2|x⃗|^{2} + 4(p̂ · x⃗_{0})^{2} − 4R^{2}(p_{x}^{2} + p_{z}^{2}) \\ c & = 4|x⃗_{0}|^{2}p̂ · x⃗_{0} − 8R^{2}p_{z}z_{0} \\ d & = |x⃗_{0}|^{4} − 4R^{2}z_{0}^{2} \end{aligned}  (2.21)

1Although a closed form solution exists for the quartic equation, Newton’s method is used by MARX.

MIT Center for Space Reseach

where x_{0} has been set to zero in accordance with the understanding that the ray has been projected to the x = 0 plane. This means that

t_{0} = −2R\sqrt{p_{x}^{2} + p_{z}^{2}}  (2.22)

should be used to seed (??).

The previous analysis is appropriate for any torus whose symmetry axis is aligned with the MARX y axis. This is the case for the LETG; however the tori that make up the HETG differ from the LETG torus by a rotation. In particular, the MEG torus differs from the LEG torus by a rotation of −5 degrees about the x axis. Similarly, the HEG torus is rotated by +5 degrees the other direction. In the following, we consider the more general case of a torus that is rotated by an angle θ about the x axis.

Let R(θ) represent a rotation about the x axis by an angle theta. It takes a vector v⃗ and transforms it into a new vector v⃗′ via

v′ = R(θ)v⃗  (2.23)

where the components of v′ satisfy

v′_{x} = v_{x}
v′_{y} = v_{y} cos θ + v_{z} sin θ  (2.24)
v′_{z} = −v_{y} sin θ + v_{z} cos θ.  (2.25)

At this point (??) could be applied to points on the torus to obtain a rotated version of (??) and the preceeding analysis repeated with the new, more complicated, equation. However, it is easier to work in a rotated coordinate system where the equation of the torus retains its form given in (??). So, the prescription for computing the intersection with a rotated torus looks like this:

1. After projecting x⃗_{0} to the x = 0 plane, rotate x⃗_{0} and p̂ via R(−θ).

2. Perform the intersection calculation outlined above using the rotated values of x⃗_{0} and p̂. This calculation will result in the intersection point x⃗ with components expressed in the rotated frame.

3. Rotate all vectors back using R(θ). The result will be that the intersection point x⃗ will be expressed in the unrotated frame.

To illustrate this procedure, consider the special case of x⃗_{0} = 0. In the unrotated case, we found (??) as the solution. For a rotation by an angle θ, the solution in the rotated frame will be

x′ = p̂′t_{0}
= −2Rp̂′\sqrt{p_{x}^{2} + (p_{z} cos θ + p_{y} sin θ)^{2}}

(2.26)

which when rotated back to the original frame yields

x⃗ = −2Rp̂\sqrt{p_{x}^{2} + (p_{z} cos θ − p_{y} sin θ)^{2}}.

MARX User’s Guide · Version 1.0

Figure 2.1: Figure showing the orthogonal coordinate system local to an individual gratig facet. The vector n̂ is normal to the facet and l̂ is in the direction of the grating lines. The vector d̂ is in the dispersion direction. The incident ray is given by p̂ and the diffracted ray is p̂′.

2.5.2 Diffraction of the Ray

Consider a ray with wavelength λ and direction p̂ incident upon a diffraction grating of period d located at position x⃗ and normal n̂. The grating lines are assumed to oriented in the direction l̂. See Figure ??. It can be shown that a ray diffracting into order m will move in a direction p̂′ determined by the conditions^{2}

p̂′ · l̂= p̂ · l̂  (2.27)
p̂′ · d̂= p̂ · d̂+ \frac{mλ}{d}  (2.28)

where

d̂= n̂ × l̂.  (2.29)

Since n̂, l̂, and d̂ form a right-handed orthonormal coordinate system, it trivially follows that

p̂′ = (p̂ · l̂)l̂+ (p̂ · d̂+ \frac{mλ}{d})d̂+ n̂\sqrt{1 − (p̂ · l̂)^{2} − (p̂ · d̂+ \frac{mλ}{d})^{2}}.  (2.30)

After diffraction, the ray will travel along the trajectory

x⃗(t) = x⃗ + p̂′t.  (2.31)

Note that (??) may be put into a more familiar form as follows. Since the component of the ray in the l̂ direction is not changed by the grating, the effect of the diffraction is simply a rotation of p̂ about the l̂ axis by some angle. Let p⃗_{⊥} denote the projection of p̂ onto the (d̂, n̂) plane, and let θ be the angle between p⃗_{⊥} and n̂. Define p⃗_{⊥}′ and θ′ in a similar fashion (see Figure ??). It follows from (??) that

p_{⊥} sin θ′ = p_{⊥} sin θ − \frac{mλ}{d},  (2.32)

where p_{⊥} = |p⃗_{⊥}| = |p⃗_{⊥}′|. In fact, the previous equation reduces to the well known diffraction equation when p̂ has no component in the l̂ direction. Using these definitions, one can write Figure 2.2: Diffraction in the (n, d) plane. Here θ is the angle the projection of the incoming ray onto the (d̂n̂ makes with respect to the normal, and θ′ is the angle between the normal and the projection of the outgoing ray.

2These equations are consistent with the vector equation p̂′ × n̂ = p̂ × n̂ + (mλ/d)l̂. The first equation is a simple result of taking the cross product of this equation with l̂. The second one follows from taking the dot product of the equation with l̂.

MIT Center for Space Reseach

(??) in the form

p̂′ = (p̂ · l̂)l̂− (p_{⊥} sin θ′)d̂+ (p_{⊥} cos θ′)n̂.  (2.33)

In general, n̂ and l̂ are complicated functions of the position of the grating. However, for gratings of infinitesimal size^{3} positioned on the surface of the Rowland torus, n̂ will be directed towards the origin, i.e.,

n̂ = −\frac{x⃗}{|x⃗|}  (2.34)

Similarly, l̂ may be determined from the condition that the facets are arranged such that l̂ has no y component^{4} and that it is normal to n̂. That is,

\begin{aligned}0 & = l̂· ŷ \\ 0 & = l̂· n̂ \\ 1 & = |l̂| \end{aligned}

from which it follows that

l̂= \frac{1}{\sqrt{n_{x}^{2} + n_{z}^{2}}} (\begin{matrix}n_{z} \\ 0 \\ −n_{x} \end{matrix}) .  (2.35)

Since the LETG gratings have a support structure that also acts as a diffraction grating, we need to consider a more general orientation of the l̂ axis that consists of a rotation about the n̂ axis by some angle θ. This means that the rotated vectors,

l̂_{θ} = l̂cos θ + d̂sin θ  (2.36)
d̂_{θ} = −l̂sin θ + d̂cos θ,  (2.37)

should be used in (??) to yield

p̂′ = (p̂ · l̂_{θ})l̂_{θ} + (p̂ · d̂_{θ} + \frac{mλ}{d})d̂_{θ} + n̂\sqrt{1 − (p̂ · l̂_{θ})^{2} − (p̂ · d̂_{θ} + \frac{mλ}{d})^{2}}.  (2.38)

the HETG.

3For finite size facets, the grating normal will have to be looked up in a facet database.

4We are working in the natural coordinate system of the torus. Thus these equations hold for the LETG and

MARX User’s Guide · Version 1.0

2.5.3 Grating Efficiency

The grating efficiency is a function of many quantities such as the geometrical paramters that specifiy the bar shape, the chemical composition and thickness of the layers that make up the plating base of the grating, etc. An extensive effort has been made to quantitatively understand the relationship of these quantities to the grating efficiency.

The current implementation of MARX assumes a simple rectangular bar shape for the gratings. In addition, the plating base is assumed to consist of several uniform layers Gold, Chromium, Nickel, and Polyimide. An updated version of the 1995 Henke tables have been used to compute the optical constants.

For the HEG, The rectangular bar geometry is specified by the hegBarWidth and hegBarHeight paramters. The period is controlled by the hegPeriod paramter. The thickness of the layers that make up the plating base are specified by the parameters: hegGold, hegChromium, hegNickel, and hegPolyimide. Parameters with similar names apply to the MEG and LEG gratings.

We have concluded from modeling of the grating efficiency as determined by synchrotron measurements, that the assumption of a rectangular bar shape does not meet our calibration goal of 1%. A future version of marx will employ a more sophisticated model for more complex geometrical bar shapes. Nevertheless, the assumption of rectangular bar shapes appears to adequate for the moment.

2.5.4 Grating Blur and Alignment Errors

There are several sources of grating blur. A grating assembly is made up of many individual grating facets. The position and orientation of each of these facets will differ from the ideal value. A rotation of a grating facet from its ideal value will produce a cross-dispersion blur. There will also be a blur associated with the finite size of an individual grating facet. Similarly, period variations in the grating bar shapes produce a blur in the dispersion direction.

In the current implementation of marx, these blurs are taken into account in a statistical manner, assuming a gaussian distribution of periods and orientation angles. In a future version, we hope to have more detailed information about individual grating facets.

The standard deviation in the rotation angle of a grating about its normal is specified by a MARX parameters for each grating type: legdTheta, megdTheta, hegdTheta. The period variations are specified by the parameters legdPoverP, megdPoverP, and hegdPoverP.

Currently, finite facet size effects are not taken into account by MARX .

2.6 Shutters

[To be added]

2.7. DRAKE FLAT  21

2.6.1 XRCF 2.6.2 HRC

2.7 Drake Flat

[To be added]

2.8 Detector Models

[To be added]

2.8.1 ACIS-I 2.8.2 ACIS-S 2.8.3 HRC-I 2.8.4 HRC-S

2.9 Pileup Simulations

[To be added]

2.10 Future Development

The following enhancements are planned to the various MARX subsystems.

• Improvements to HRMA model – Individual HRMA Shell misalignments

– Individual shell Gaussian cores

– Incorporate in and out of plane scattering using Leon’s scattering tables • HRC module improvements

– Incidence angle dependence of QE

– Focal plane Gaussian blurring

– Flat field maps (spatial variations in QE)

MARX User’s Guide · Version 1.0

• Grating Misalignment Terms

• Incorporate Aspect and Dither

Section 3

MARX Calibration

3.1 Overview

3.2 MARX Data Files

3.2.1 MirrorType=EA-MIRROR data files:

Mirror EE.dat This file contains data for the EA-MIRROR blur. It was generated by Dave via Leon’s fold program. mirr-ee.dat This file is created when marx is compiled. It contains the same data as Mirror EE.dat but arranged in a format more suitable to marx (see ../src/fix ee.c). Ae s1346.tbl This is an ascii file containing the energy dependent effective are curves for the four shells of the HRMA.

3.2.2 MirrorType=HRMA data files:

carbon.dat carbon.xray gold.dat gold.xray iridium.dat iridium.xray The *.dat files were produced by Mark Schattenburg’s xray program. The *.xray files are the script files that the xray program uses. The *.dat files consist of the energy dependent optical constants (beta, delta) that are used when computing the reflectivity.

MARX User’s Guide · Version 1.0

24  SECTION 3. MARX CALIBRATION

3.2.3 Grating Data Files:

optical-constants.dat optical-constants.xray The .xray file was fed into Mark Schattenburg’s xray program to produce the .dat file. The .dat file contains optical constants for nickel, polyimide, gold, and chromium.

3.2.4 ACIS-S Data Files:

ACIS QE FI.tbl This is an ascii file that contains the quantum efficiency curves for an ACIS front-illuminated CCD. ACIS QE BI.tbl This is an ascii file that contains the quantum efficiency curves for an ACIS front-illuminated CCD.

3.2.5 HRC-S Data Files:

qe hrcs p2000 al2000.dat qe hrcs p2000 al300.dat qe hrcs p2500 al1000.dat qe hrcs p2500 al300.dat These files are the QE curves for the 4 regions of the HRC-S detector. Mike Wise generated these. qe hrci p5000 al700 c200.dat This file is for the HRC-I detector. It contains a QE curve.

3.3 Comparison to XRCF

3.4 Updates

Section 4

Installing MARX

4.1 Introduction

This section describes the complete procedure for obtaining, compiling, and testing the MARX simulation suite. In brief, the process consists of the following:

• Download the distribution TAR file

• Uncompress and unpack the TAR file

• Change directories into the resulting source directory

• Type “./configure”

• Type “make”

4.2 Obtaining MARX

The MARX suite is distributed as a compressed, UNIX TAR file containing all the necessary source code and data files to produce a functioning set of executables. As mentioned in Section ??, the latest distribution is available online via the WWW or via anonymous FTP at:

WWW:   http://space.mit.edu/ASC/MARX/marx.html
FTP:   ftp://space.mit.edu/pub/ASC/MARX

For anonymous FTP access, a symbolic link is maintained which points to the current version. The following is an example of obtaining the latest version of MARX via anonymous FTP:

unix% ftp space.mit.edu
Connected to space.
220 space FTP server (SunOS 4.1) ready.
Name (space.mit.edu:wise): anonymous

331 Guest login ok, send ident as password.
Password:
230 Guest login ok, access restrictions apply.
ftp> cd pub/ASC/MARX
250 CWD command successful.
ftp> binary
200 Type set to I.
ftp> ls -l
200 PORT command successful.
150 ASCII data connection for /bin/ls (18.75.0.85,60817) (0 bytes).
total 3843
-rw-r--r--  1 wise         1187 Jun 10 19:52 00-README
-rw-r--r--  1 wise      1175088 Jan 24 20:29 marx_1.09-dist.tar.gz
-rw-r--r--  1 wise      1207413 Apr  9 23:32 marx_1.10-dist.tar.gz
-rw-r--r--  1 wise      1241336 Jun 11 22:02 marx_1.20-dist.tar.gz
lrwxrwxrwx  1 wise           21 Jun 10 19:51 marx_current.tar.gz -> \
 marx_1.20-dist.tar.gz
-rw-r--r--  1 wise       107916 May  2 21:32 marx_sims.ps.gz
-rw-r--r--  1 wise       135537 Jun 14  1996 pimms_axaf.tar.gz
226 ASCII Transfer complete.
remote: -l
489 bytes received in 0.057 seconds (8.4 Kbytes/s)
ftp> get marx_current.tar.gz
200 PORT command successful.
150 Binary data connection for marx_current.tar.gz (18.75.0.85,37817) \
 (1241336 bytes).
226 Binary Transfer complete.
local: marx_current.tar.gz remote: marx_current.tar.gz
1241336 bytes received in 1.6 seconds (7.5e+02 Kbytes/s)
ftp> bye
221 Goodbye.
unix%

Note, as of this writing, the current compressed MARX TAR file is approximately 1.3 Mbytes. The uncompressed file requires on the order of 5 Mbytes while the full distribution including executables takes 13 Mbytes. Users should make sure they have sufficient space available before beginning the installation process.

Once the compressed distribution TAR file has been downloaded to the user’s local machine, it must be uncompressed and unpacked before compiling. Move the TAR file to the area where you intend to install MARX . The following commands will uncompress and unpack the source code:

unix% gunzip marx_current.tar.gz
unix% tar xvf marx_current.tar

Untarring the distribution will create a directory entitled marx X.XX–dist, where X.XX is a number like 1.21 corresponding to the current version number.

unix% cd marx_1.21-dist/
unix% ls
INSTALL         bin/            configure*      lib/            pfile/

Makefile        config.cache    include/        marx/
acis.par        config.log      jdfits/         marx.par
autoconf/       config.status*  jdmath/         marxrsp/
unix%

After changing directories into the resulting source directory, you are ready to compile the distribution.

4.3 Compiling MARX

4.3.1 Building the main suite

To compile MARX , you will need an ANSI compatable C compiler, e.g., gcc. The C compiler bundled with the SunOS, “cc”, is NOT ANSI compliant although the C compiler included with the SparcWorks package under Solaris is apparently compliant.

The compilation process for the majority of the suite is relatively straightforward. MARX uses the GNU autoconfig package to configure itself. Starting from the source directory, type:

unix% ./configure
unix% make

The configuration script will check the system setup for any files it needs to compile MARX . If there are any problems during the installation, the output from this stage should be saved for daignostic purposes. As part of the build, the script will place the executables in the “bin” directory and copy the marx.par file to the main source directory. The suite is now ready to run simulations.

4.3.2 Building marxrsp

The above procedure will compile the majority of the programs in the MARX suite. The exception is the marxrsp tool which allows users to fold the results of a MARX simulation through a user provided FITS response matrix file (RMF). This tool is described in more detail in Section ??. In order to compile marxrsp, you will need to obtain and install the CFITSIO library if you do not already have it installed on your system. The library can be obtained from the HEASARC web page at:

http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html

Instructions for installing the library are included with the source code and will not be discussed here.

After installing the CFITSIO library, you must edit the Makefile in the “marxrsp” directory to point to the library. If you have the HEASARC FTOOLS package installed, chances are that you have the CFITSIO library already. The following excerpt from the marxrsp Makefile shows a link to the FTOOLS version of CFITSIO installed on a machine running Linux.

#  -*- sh -*-
JDSRC_ROOT = ..
OBJDIR = $(ARCH)objs
ASC_ROOT = /usr/local/src/ftools/Linux_2.0_i586
CFITSIO_LIB = $(ASC_ROOT)/lib
CFITSIO_INC = $(ASC_ROOT)/include
INSTALL_DIR = ../bin/$(ARCH)
CFITSIO = cfitsio
.
.
.

With the appropriate modifications to the marxrsp Makefile completed, the tool can now be built. Execute the following commands in the “marxrsp” source directory to build the executables and move them to the “bin” directory with the other tools in the suite.

unix% make
unix% mv ./objs/marxrsp ../bin
unix% mv ./objs/rspdump ../bin

Note, you do not need marxrsp to run MARX .

4.3.3 Compiling USER Source Models

To be added.

4.4 Running MARX

At this point, you should have a complete set of MARX executables for your system. To begin running simulations, you now need to:

• Add the MARX binary directory to your path. This addition can be accomplished under the UNIX csh with a command of the form:

     unix% set path = ($path /usr/local/src/marx_1.21-dist/bin)

In this example, the MARX 1.21 version of the distribution was compiled in the “/usr/local/src” directory. These paths should be adjusted for the specific installation location on your system.

• Set the MARX DATA DIR environment variable to point to the data file directory in the installation. Following the example above, this definition would look like:

     unix% setenv MARX_DATA_DIR /usr/local/src/marx_1.21-dist/marx/data

Alternatively, the DataDirectory parameter in the MARX parameter file may be set to the appropriate path; however, the environment variable provides a more convenient way to establish the location of this directory.

• Make sure you have a copy of the MARX parameter file (marx.par) in the directory in which you wish to run the simulation. This file can be found in the top level of the MARX source distribution directory.

MARX should now be ready to run.

4.5 Testing your Distribution

The simplest way to test whether the installation process was successful is to run a simulation. Detailed instructions for running simulations is given in Section ??. However, a couple of simple tests should verify that MARX was compiled and is ready to run. First, insure that the MARX tools are indeed in your path by typing:

unix% which marx
/usr/local/src/marx_1.21/bin/marx

The output shown above again assumes MARX was installed in “/usr/local/src”. Next, verify that MARX knows where the data files it needs to run are located with the following:

unix% printenv MARX_DATA_DIR
/usr/local/src/marx_1.21/marx/data

Finally, ensure that the executable is functioning with:

unix% marx --version
MARX version: 1.21 # Jun 28 1997 12:01:02
JDMATH library version: 1.30
PFILE library version: 1.11
Supported Sources: POINT, GAUSS, LINE, BETA, RAYFILE, DISK, USER
Supported Detectors: ACIS-S, ACIS-I, HRC-S, HRC-I
Other Features:
      HRMA Pitch/Yaw : yes
    Wfold Scattering : no
          Drake Flat : yes
     Dynamic Linking : yes
unix%

The output shown above may be slightly different depending on the user’s specific configuration and installation. If all three tests were successful, you should be ready to begin running MARX simulations.

[Note – Add discussion of EA/PSF comparison scripts]

Table 4.1: Tested Systems

Machine  Operating System
Sun Sparc  Solaris 2.5
Sun Sparc  SunOs 4.1.3, 4.1.4
HP9000/735  HP/UX A.09.01
SGI  IRIX 5.2, 5.3, 6.2
DEC Alpha  OSF1 4.0
Micron P5-90  Slackware Linux 2.0.30
WinBook FX P5-166  RedHat 4.2 Linux 2.0.30
Power Macintosh 7500  MkLinux DR2.1

4.6 Portability

MARX have been successfully tested on a variety of machines and operating systems. Table ?? lists the current set. In principle, MARX should compile and run on any UNIX system with an ANSI compliant compiler.

4.7 Speed

[Note – Add timing test results]

4.8 Known Bugs and Limitations

For some reason, rfl refuses to compile under NeXT. The current suspect is a bug in the linker on this system. If a problem occurs, edit the Makefile in the main source directory to skip building rfl. The build will still create a functioning version of MARX .

Section 5

The MARX Tool Suite

5.1 Introduction

In this section, we describe the purpose and calling sequences for the various component tools in the MARX suite. A list of the tools in the suite along with a brief description of their functions is presented in Table ??. Detailed descriptions for individual tools follow in alphabetical order. Brief usage instructions can be obtained for any tool in the suite simply by typing the name of the tool followed by return. Optional parameters are enclosed in “[]”.

5.2 Alphabetical List of Routines

5.2.1 bestfocus

Description

The bestfocus tool reads the contents of a MARX output directory and calculates the best focus position for the rays. It reports the current setting of the DetOffsetX parameter as well as the recommended setting in order to achieve the best focus for the current simulation. For grating simulations, individual orders can be specified to optimize the focus for a given spectral order.

Calling Sequence

Usage: bestfocus --dir MARX-DATA-DIR [--par parfile] [--order ORDER]

Arguments

MARX-DATA-DIR  Path to MARX simulation directory
parfile  Name of an alternate parameter file to use
order  Spectral order to isolate: 0, -1, +1, etc...

Table 5.1: Tools in the MARX Suite

bestfocus  Determines the best focus for a set of rays
dumpwfold  Prints the contents of WFOLD scattering file
fitsdump  Prints the contents of a FITS file
geff  Calculates grating efficiency curves
marx  Performs the AXAF raytrace simulation
marx2dpde  Converts MARX output to SAOSAC DPDE format
marx2fits  Converts MARX output to FITS events list
marx2img  Converts MARX output to FITS image
marxcat  Concatenates the results of multiple MARX simulations
marxrsp  Folds a MARX simulation through a FITS RMF file
pileup  Simulates the effect of pileup in ACIS CCD’s
plist  Prints out parameter files in a readable format
pset  Sets parameter values in a parameter file
pwhich  Prints the current search path for parameter files
rfl  Computes optical reflectivities
rspdump  Prints the contents of a FITS RMF file

Examples

unix% bestfocus --dir marx-out/
24110 rays read.
Best focus position [mm]: (0.004071, 0.000153, 0.000143)
At that position, that mean radius of the spot will be 0.027373 mm
(about 1.140556 ACIS Pixels)
Current DetOffsetX value: 0.010000
Suggested DetOffsetX value: 0.006476
unix%
5.2.2 dumpwfold

Description The dumpfold tool reads the contents of one Leon VanSpeybroeck’s WFOLD output scattering files and prints the contents to standard out. Calling Sequence

Usage: dumpwfold FILENAME

Arguments

FILENAME  Name of WFOLD scattering file to print

MIT Center for Space Reseach

Examples

unix% dumpwfold scat_h1_M > scat_h1_M.out

5.2.3 fitsdump

Description

The fitsdump tool can be used to examine the contents of a specified FITS file or to test the integrity of a given FITS file. The entire file can be printed out or just a particular extension.

Calling Sequence

Usage: fitsdump [Options] [-e <extension name>] <fitsfile>
 Options:
  -t                    test fits file integrity
  -r                    dump raw data, do not scale
  -s                    apply full scaling
  -h                    dump headers
  -H                    dump only headers
  -e <extension name>   dump out a particular extension.
                        The default is all.

Arguments

fitsfile  Name of the FITS file to examine
extension  String specifying the extension to be printed, i.e. “EVENTS”

Examples

unix% fitsdump test.fits > outfile

5.2.4 geff

Description

The geff tool calculates grating transmission efficiency curves using the current MIT rectangular grating bar model. It takes as input a parameter file containing the necessary grating bar parameters, quantities which specify the energy grid, and the range of orders to include in the calculation.

Calling Sequence

Usage: geff PFILE min-energy max-energy num-energies min-order max-order
where: min-energy >= 0.03, max-energy < 10.0

Arguments

PFILE  Name of the grating parameter file to use
min-energy  Minimum energy of the grid in keV
max-energy  Maximum energy of the grid in keV
num-energies  Number of energy bins in the grid
min-order  Minimum order to include in calculation
max-order  Maximum order to include in calculation

Examples

unix% geff meg.par 0.1 9.0 100 -1 1 > meg.dat

5.2.5 marx

Description

The marx tool comprises the central engine of the suite and actually performs the ray trace through the various components of the AXAF system. marx reads its inputs from an IRAF–style parameter file marx.par. Alternatively, it can accept values for any of its parameters on the call line. Detailed instructions for running marx are presented in Section ??.

Calling Sequence

marx usage forms:
   marx [parameters]    Runs a simulation with the specified parameters
   marx --dump file     Prints the contents of a MARX binary vector
   marx --raydump file  Prints the contents of a MARX rayfile
   marx --version       Prints version information
   marx --help          Prints brief help information

Arguments

parameters  Any MARX parameter, i.e. GratingType=’HETG’
file  For dump options; filename to print

Examples

5.2.5.1 Example 1

Obtaining brief help information:

unix% marx --help
This program uses an IRAF-style parameter file interface.  It searches for
the parameter file in the PFILES and UPARM directories.  If one is not
found, it will look in the current directory.
The name of the parameter file that this program uses is marx.par.

An alternative parameter file may be specified by prefixing the file name
with "@@" and using the resulting expression as the first command line
argument, e.g., program-name @@parameter-file-name.
Parameters may be set on the command line via the syntax:
     PARAMETER-NAME=VALUE PARAMETER-NAME=VALUE ...
The program will prompt for a parameter's value if VALUE is not specified,
e.g., "PARAMETER-NAME=".  Note that there must be no whitespace surrounding
the '=' sign.
See your program's user manual for more information.
pfile library version: 1.11
marx usage forms:
   marx [parameters]
   marx --dump file...
   marx --raydump file
   marx --version
   marx --help
unix%

5.2.5.2 Example 2

Checking the version of your MARX installation:

unix% marx --version
MARX version: 1.21 # Jun 26 1997 15:45:02
JDMATH library version: 1.30
PFILE library version: 1.11
Supported Sources: POINT, GAUSS, LINE, BETA, RAYFILE, DISK, USER
Supported Detectors: ACIS-S, ACIS-I, HRC-S, HRC-I
Other Features:
      HRMA Pitch/Yaw : yes
    Wfold Scattering : no
          Drake Flat : yes
     Dynamic Linking : yes
unix%

5.2.5.3 Example 3

Creating an ASCII file from the photon energy list for a given simulation:

unix% marx --dump ./ngc1068/energy.dat > energy.out

5.2.5.4 Example 4

Running a simulation with a parameter file located elsewhere on your system:

unix% marx @@/home/wise/simulations/clusters/marx.par

5.2.5.5 Example 5

An example of setting parameters on the call line. This example runs a 50 ksec simulation of a point source as observed with the HETG and ACIS–S instruments:

unix% marx ExposureTime=50000 GratingType='HETG'     \
              DetectorType='ACIS-S' SourceType='POINT'

5.2.6 marx2dpde

Description

The marx2dpde tool converts the contents of a MARX simulation output directory into a Mission Support Team DPDE format, SAOSAC compatible rayfile. The DPDE format is described in the MST SAOSAC documentation available online at:

http://hea-www.harvard.edu/MST/simul/simuldocs/index.html

Using marx2dpde, users can create rayfiles capable of being processed by the MST’s SAOSAC raytrace model. Note, MARX can also read DPDE format files. The connections between SAOSAC and MARX are described in more detail in Section ??. Alternatively, the “-dump” option may be used with marx2dpde to print out the contents of a DPDE file.

Calling Sequence

Usage: marx2dpde MARX-OUTPUT-DIR OUTPUT-FILE-NAME
   or: marx2dpde -dump DPDE-FILE-NAME

Arguments

MARX-OUTPUT-DIR  Path to MARX simulation directory
OUPUT-FILE-NAME  Name of the DPDE file to create
DPDE-FILE-NAME  Name of the DPDE file to print

Examples

5.2.6.1 Example 1

Creating a DPDE format rayfile for further processing with SAOSAC:

unix% marx2dpde ./ngc1068 > ngc1068.dpde

5.2.6.2 Example 2

Dumping the contents of a binary DPDE format file to an ASCII file for examination:

unix% marx -dump AlShell1_B_focus.dpde > AlShell1_B_focus.out

5.2.7 marx2fits

Description

The marx2fits tool converts the contents of a MARX simulation output directory into a FITS events binary table. Information about the simulation is written into the header. The current format of the events file is defined by the ACIS EVT 3.0 specification. Other detector event formats, most notably that for the HRC instruments, will be supported when they become available. In the meantime, the “–force” flag can be used to write an events file for non–ACIS simulations.

Calling Sequence

Usage: marx2fits [--force] marx-dir fitsfile
 --force will allow non-ACIS detectors to be used.

Arguments

marx-dir  Path to MARX simulation directory
fitsfile  Name of the FITS events file to create

Examples

unix% marx2fits ./ngc1068 > ngc1068_evt.fits

5.2.8 marx2img

Description

The marx2img tool converts the contents of a MARX simulation output directory into a FITS image. By default, marx2img will use all detected photons to create the FITS image. Alternatively, users may screen the events used in the image by a set of option flags. Events may currently be screened on the basis of spatial position, photon energy, or time. The “–chip” option may be used to generate an image of a single chip. Pixel coordinates to marx2img are specified in “tiled detector” coordinates. Energy selections are specified in keV and time selection in seconds. The chip numbering scheme for the ACIS flight focal plane is shown in Figure ??.

Figure 5.1: The chip numbering scheme used by marx2img for the chips in the ACIS flight focal plane. Note, the ACIS–I nominal aimpoint falls on chip 3 while the aimpoint for the ACIS–S array corresponds to chip 7.

Calling Sequence

Usage: marx2img [options] <MARXDIR> <FITSFILE>
Options include:
        --bbox          Find bounding box.
        --minX          <MIN_X_PIXEL>
        --maxX          <MAX_X_PIXEL>
        --minY          <MIN_Y_PIXEL>
        --maxY          <MAX_Y_PIXEL>
        --minE          <MIN_ENERGY> (KeV)
        --maxE          <MAX_ENERGY> (KeV)
        --minT          <MIN_TIME> (sec)
        --maxT          <MAX_TIME> (sec)
        --chip          <CHIP_NUMBER>
Unsupported detectors may require use of the --chip parameter.

Arguments

MARXDIR  Path to MARX simulation directory
FITSFILE  Name of the FITS image file to create

Examples

5.2.8.1 Example 1

Creating a FITS image containing all detected photons for an ACIS–S simulation:

unix% marx2img ./ngc1068 > ngc1068_img.fits
DetectorType: ACIS-S
Num X Pixels: 1024 (per chip)
Num Y Pixels: 1024 (per chip)
Num Chips: 6
First Chip Id: 4
Min X Pixel: 0
Max X Pixel: 6144
Min Y Pixel: 0
Max Y Pixel: 1024
Estimated Image size: 25165824
48947 counts written to the fits file.

5.2.8.2 Example 2

Creating a FITS image of all events between 0.5 and 1.0 keV for an ACIS–S simulation:

unix% marx2img --minE 0.5 --maxE 1.0 ./ngc1399 > ngc1399_img_FeL.fits
DetectorType: ACIS-S

Num X Pixels: 1024 (per chip)
Num Y Pixels: 1024 (per chip)
Num Chips: 6
First Chip Id: 4
Min X Pixel: 0
Max X Pixel: 6144
Min Y Pixel: 0
Max Y Pixel: 1024
Min Energy: 0.500000
Max Energy: 1.000000
Estimated Image size: 25165824
17906 counts written to the fits file.

5.2.8.3 Example 3

Creating a FITS image of the S3 backside chip in the ACIS–S array:

unix% marx2img --chip 7 ./ngc1399 > ngc1399_img_S3.fits
DetectorType: ACIS-S
Num X Pixels: 1024 (per chip)
Num Y Pixels: 1024 (per chip)
Num Chips: 1
First Chip Id: 7
Min X Pixel: 0
Max X Pixel: 1024
Min Y Pixel: 0
Max Y Pixel: 1024
Estimated Image size: 4194304
27067 counts written to the fits file.

5.2.9 marxcat

Description

The marxcat tool concatenates mutiple MARX simulation directories into one. In this manner, users may build arbitrarily complex simulations, one component at a time and then merge them together to produce the final result. Note, marxcat will overwrite the contents of the target directory if it already exists. If the directory does not exist, marxcat will create it.

Calling Sequence

Usage: marxcat [--help] DIR1 [DIR2 [DIR3 ...]] NEWDIR

Arguments

DIR1...DIRN  Input simulation directories to merge
NEWDIR  Destination directory for the merged simulation

Examples

unix% marxcat ./a2029_clust ./a2029_cflow ./a2029
Examining files in ./a2029_clust
Examining files in ./a2029_cflow
Merging directories...
Creating ./a2029/time.dat
Creating ./a2029/energy.dat
Creating ./a2029/xpos.dat
Creating ./a2029/ypos.dat
Creating ./a2029/zpos.dat
Creating ./a2029/xcos.dat
Creating ./a2029/ycos.dat
Creating ./a2029/zcos.dat
Creating ./a2029/pha.dat
Creating ./a2029/detector.dat
Creating ./a2029/xpixel.dat
Creating ./a2029/ypixel.dat
Creating ./a2029/mirror.dat
Creating ./a2029/order.dat

5.2.10 marxrsp

Description

The marxrsp tool allows the user to fold the results of the a MARX simulation through a FITS response matrix file (RMF). Traditionally, RMF files are used to describe the response of a given detector such as a ACIS CCD. The RMF file, also known as a redistribution matrix file, describes the mapping of photon energy into detected pulse height. marxrsp reads the energy vector for a group simulated events and uses the specified RMF file to calculate the appropriate pulse height values. By default, MARX calculates a pulse height array for ACIS simulations using an approximate, built–in redistribution function. marxrsp will overwrite this default pulse height file.

Calling Sequence

usage: marxrsp --rmf rmf-file --marx marx-dir

Arguments

rmf-file  FITS RMF file to read
marx-dir  Path to MARX simulation directory

Examples

unix% marxrsp --rmf acis.rmf ./ngc1399

42  SECTION 5. THE MARX TOOL SUITE

5.2.11 pileup

Description The pileup tool simulates the effects of photon pileup in the ACIS CCD’s. Like marx, pileup reads its inputs from an IRAF–style parameter file acis.par. Currently, only front illuminated CCD’s are simulated. Needs revision. Calling Sequence

usage: pileup

Arguments None Examples

unix% pileup

5.2.12 plist

Description The plist tool lists parameters from one or more IRAF–style parameter files. Calling Sequence

Usage: plist [ paramfile1...  ] [ paramfile2...  ] [ paramfileN...  ]

Arguments

paramfile1  Name of an IRAF–style parameter file

Examples

unix% plist acis.par marx.par

5.2.13 pset

Description The pset tool sets one or more parameters in an IRAF–style parameter file. Calling Sequence

MIT Center for Space Reseach

Usage: pset paramfile [ passign1...  ]

Arguments

paramfile  Name of an IRAF–style parameter file
passign1  Parameter assignment statement, i.e. PixelSize=24

Examples

unix% pset acis.par PixelSize=24

5.2.14 pwhich

Description

The pwhich tool allows the user to track the search path MARX will use in obtaining the marx.par parameter file. The output paths from pwhich will apply to any program using IRAF–style parameter files, i.e. FTOOLS.

Calling Sequence

Usage: pwhich [--verbose] pfile

Arguments

pfile  Name of an IRAF–style parameter file

Examples

unix% pwhich --verbose acis.par
Trying /home/wise/pfiles/acis.par.par
Trying ./acis.par.par
Trying /home/wise/pfiles/acis.par
Trying ./acis.par
Input: ./acis.par
Output: ./acis.par
unix%

5.2.15 rfl

Description

The rfl tool calculates optical reflectivities.

Calling Sequence

rfl: usage:

        rfl opt-const-file energy(KeV)
or      rfl opt-const-file -max-graxing-angle(degrees)

Arguments

opt-const-file  Path to MARX simulation directory

energy grating-angle

Examples

5.2.16 rspdump

Description

The rspdump tool is a multi–function program for examining FITS response matrix files (RMFs). If no parameters are specified, rspdump will print the entire contents of the file. The “–integrate” flag can be specified to check the normalization of the file. The energy range or channel range can be limited with the “–energy” or “–min-chan”, “–max-chan” flags.

Calling Sequence

Usage:
rspdump [--integrate] [--energy E] [--min-chan f] [--max-chan l] rsp-file
        --integrate             Integrate across channels
        --energy                Specifies energy of channel to dump
        --min-chan              Specifies minimum channel
        --max-chan              Specifies maximum channel

Arguments

rsp-file  Name of the FITS RMF file to examine

Examples

unix% rspdump acis.rmf > acis.out

5.3 IDL Routines

In addition to the UNIX executables themselves, a set of IDL scripts are also included to facilitate working with MARX output. Table ?? lists the routines and a brief description of their functions.

Table 5.2: MARX related IDL Routines

get hetg spect  Extract exact HETG spectra for a given simulation
get letg spect  Extract exact LETG spectra for a given simulation
make image  Make an image from simulation variables
read marx file  Read MARX binary vectors into IDL variables
tg extract  Extract HETG/LETG spectra for a given simulation

5.3.1 get hetg spect

Description

The get hetg spect routine uses a number of simulation variables computed by MARX to extract the specified HEG and MEG spectral order for a given simulation. Optionally, the ACIS pulse height spectrum can be returned as well.

Calling Sequence

IDL>get_hetg_spect
CALLING SEQUENCE: get_hetg_spect,path,order,rm,[xm,ym,rh,xh,yh,p,xp,yp]
IDL>

Arguments

path  String containing path to MARX simulation directory
order  Spectral order to extract
rm  Array of MEG photon disperison distances [mm]
xm  Energy array for binned MEG photons [keV]
ym  Counts per pixel for the MEG spectrum [counts]
rh  Array of HEG photon disperison distances [mm]
xh  Energy array for binned HEG photons [keV]
yh  Counts per pixel for the HEG spectrum [counts]
p  Array of photon pulse heights [pha]
xp  Energy array for binned PHA spectrum [keV]
yp  Counts per channel for the binned PHA spectrum [counts]

Examples

IDL> get_hetg_spect,'./ngc1399',1,rm,xm,ym,rh,xh,yh,p,xp,yp

5.3.2 get letg spect

Description

The get letg spect routine uses a number of simulation variables computed by MARX to extract the specified LETG spectral order for a given simulation.

Calling Sequence

IDL>get_letg_spect
CALLING SEQUENCE: get_letg_spect,path,order,rl,[xl,yl]
IDL>

Arguments

path  String containing path to MARX simulation directory
order  Spectral order to extract
rl  Array of LEG photon disperison distances [mm]
xl  Energy array for binned LEG photons [keV]
yl  Counts per pixel for the binned LEG spectrum [counts]

Examples

IDL> get_letg_spect,'./ngc1399',1,rl,xl,yl

5.3.3 make image

Description

The make image routine returns the a dimensional histogram of two variables. The two dimensional density function of the two variables, a longword array of dimensions (MAX(v1)+1, MAX(v2)+1). Result(i,j) is equal to the number of simultaneous occurences of V1=i, and V2=j, at the same element. This routine is useful for creating images from MARX position vectors.

Calling Sequence

IDL>im=make_image()
% Compiled module: MAKE_IMAGE.
% MAKE_IMAGE: USAGE: Result = make_image(vx, vy, XRANGE=[xmin,xmax],
  XAXIS=xax,YRANGE=[ymin,ymax], XBINSIZE=xbin, YBINSIZE=ybin,
  YAXIS=yax,INDEX_LIST=idx, REVERSE_INDICES=revidx)
IDL>

Arguments

vx  Input X variable for density histogram
vy  Input Y variable for density histogram

Keyword Parameters

XRANGE = [xmin,xmax]  Range in X input array to make into image
YRANGE = [ymin,ymax]  Range in Y input array to make into image
XBINSIZE = xbin  Binsize for image X
YBINSIZE = ybin  Binsize for image Y
XAXIS = xax  Output X–coordinate vector

xax(i) is the LEFT EDGE of bin i

YAXIS = yax  Output Y–coordinate vector

yax(i) is the LEFT EDGE of bin i

INDEX LIST = idx  Output vector of array indices of array elements

used from vx, vy

REVERSE INDICES = revidx  output reverse–index vector, but only of the

sub–array actually specified by XRANGE, YRANGE

Examples

IDL> ypos=read_marx_file('./ngc1399/ypos.dat')
IDL> zpos=read_marx_file('./ngc1399/zpos.dat')
IDL> im=make_image(ypos,zpos,XBINSIZE=0.024,YBINSIZE=0.024)

5.3.4 read marx file

Description

The read marx file routine returns the contents of a binary output file from the MARX simulator.

Calling Sequence

IDL>y=read_marx_file()
% Compiled module: READ_MARX_FILE.
CALLING SEQUENCE:
array=read_marx_file(inpfile[,type,name,rlen,clen,reserv,magic]
IDL>

Arguments

inpfile  String containing name of the vector to read

Examples

IDL> ypos=read_marx_file('./ngc1399/ypos.dat')

5.3.5 tg extract

Description

The tg extract routine extracts all photons along the spectral dispersion axis within a

Table 5.3: MARX related Shell Scripts

check marx effarea  Tests MARX effective area calculations
check marx psf  Tests MARX PSF calculations
xspec2marx  Convert XSPEC ASCII files to MARX format

specified spatial window. It returns the dispersion distance for each photon. Unlike, get hetg spect and get letg spect which use simulation variables to determine the exact spectrum for a given order, tg extract emulates a realistic analysis scenario using a spatial window.

Calling Sequence

IDL>tg_extract
% Compiled module: TG_EXTRACT.
tg_extract, hml, maxdist, y, z, y0, z0, dd, dxd, [list_selected]
IDL>

Arguments

hml  String to specify which arm of the ’X’ to use for

distance from dispersion line calculation.

Can be: ’h’ or ’m’ or ’l’ = HEG or MEG or LEG

maxdist  Maximum photon distance from dispersion line

to allow [mm]

y  Array of Y axis photon positions in focal plane [mm]
z  Array of Z axis photon positions in focal plane [mm]
y0  Y coordinate of 0th order [mm]
z0  Z coordinate of 0th order [mm]
dd  Output vector of photon distances from zero order

parallel to dispersion axis [mm]

dxd  Output vector of photon distances from dispersion

line in perpendicular direction [mm]

list selected  Optional output vector of indices within input

vectors of selected photons

5.4 Scripts

A number of UNIX shell scripts are also included with the MARX suite to simplify testing the distribution as well interface with XSPEC. Table ?? lists these scripts and a brief description of their functions.

5.4.1 check marx effarea

This script is not yet available.

\underline{5.4. SCRIPTS 49}

5.4.2 check marx psf

This script is not yet available.

5.4.3 xspec2marx

Description The xspec2marx converts an ASCII file generated with XSPEC into a two column format suitable for ingestion by MARX . This script simply strips out the energy array and the column containing the total flux and writes these arrays to a new file. Calling Sequence

unix% xspec2marx inputfile outputfile

Arguments

inputfile  Name of ASCII file produced by XSPEC
outputfile  Two column ASCII file readable by MARX .

Examples

unix% xspec2marx plaw.out plaw.dat

Section 6

Running MARX Simulations

6.1 Introduction

Once the MARX suite has been compiled, the process of running simulations is fairly straightforward. The basic steps consist of:

• Add the MARX tools to your path

• Set the MARX DATA DIR environment variable

• Set up the simulation using the marx.par parameter file

• Type “marx”

However, AXAF is a complicated observatory and by necessity MARX has many potentially bewildering options to mimic this complexity. In this section, we will describe this procedure in detail including a description of MARX ’s input requirements and output products. Some specific examples ranging from simple to complex are also provided as a guide.

6.2 System Setup

If the compilation process was successful (see Section ??), then configuring your system to run simulations is essentially a two step process. First, you should modify your path to include the path to the executables in the MARX suite. (This step is not required. You can always type the full path to a given executable.) The MARX source directory will contain a “bin” subdirectory which contains the executables. You can add this directory to your path with a command of the form:

unix% set path = ($path /usr/local/src/marx_1.21-dist/bin)

for CSH users. In this example, the MARX suite was installed in “/usr/local/src”. Note, you may have to type “rehash” for the current shell to recognize this addition.

Next, one must set the environment variable MARX DATA DIR to point to the location of the data files distributed as part of the installation. For the example build described above, the following CSH command:

unix% setenv MARX_DATA_DIR /usr/local/src/marx_1.21-dist/marx/data

would be sufficient. If you have something against UNIX environment variables, the MARX parameter DataDirectory can be defined to point to the data files. By default, this parameter is set to the contents of MARX DATA DIR. At this point, your system is ready to run simulations.

6.3 The MARX Parameter File

The details of a given simulation are controlled by the MARX parameter file marx.par. This file currently contains 164 different parameters which determine everything from the exposure time to the the physcial shape of the HRMA parabolas and hyperbolas. Fortunately, only about 35 of these parameters need ever be (or in fact should ever be) modified under most conceivable circumstances. In practice, most typical science simulations can be defined and controlled with less than 10. Template MARX parameter files are included as part of the distribution and can be found in the top level of the source directory. Appendix ?? reproduces the user configurable portion of a typical MARX parameter file. The tool plist can be used to print the contents of marx.par in a more readable format (see Section ??).

MARX utilizes an IRAF–style parameter interface. By default, MARX will search for marx.par in the directories specified by the PFILES and UPARM environment variables. The first version of marx.par found will be used. If a valid parameter file is not found in either of these locations, the current directory will be searched. The tool pwhich can be used to check the current parameter file search path (see Section ??).

MARX will also assume that the relevant parameter file is named “marx.par”. An alternative parameter file may be specified by prefixing the file name with “@@” and using the resulting expression as argument on the command line, e.g.,

unix% marx  @@/home/wise/simulations/marx_a2029.par

Any of MARX ’s parameters may be set on the command line via the syntax:

unix% marx PARAMETER-NAME=VALUE PARAMETER-NAME=VALUE ...

The program will prompt for a parameter’s value if VALUE is not specified, e.g.,

unix% marx DetectorType=
Reading HRMA optical constants:
        /usr/local/src/marx_1.21-dist/marx/data/iridium.dat
Range error occured while looking at parameter DetectorType.
Select detector type (HRC-S|ACIS-S|HRC-I|ACIS-I|NONE)[]:

Note that there must be no whitespace surrounding the “=” sign. In the next few sections, we will discuss the various essential parameters the user must adjust to produce a MARX simulation.

6.4 Simulation Control

By “simulation control”, we specifically refer to any necessary parameter choices which define the execution of the simulation and are not instrument or source related. These include such things as length of exposure, timed versus ray generation execution, and output location and format.

6.4.1 Exposure Time

MARX simulations can be run in either ray generation mode or in timed exposure mode. Timed exposure mode is probably the simulation method most users will employ most of the time. The ExposureTime parameter is used to specify the total integration time in seconds. Thus,

unix% marx ExposureTime=10000 ...

would generate a 10 ksec simulation. MARX will accumulate photons until the indicated integration time is reached. This mode takes precedence over ray generation mode. If the ExposureTime parameter is set to any positive, non–zero value, the simulation will be run in timed exposure mode. Uers wishing to run simulations in ray generation mode, should set

ExposureTime=0.

In ray generation mode, the exact number of rays to run through the simulator is specified using the NumRays parameter. Note, that this value is not the number of “detected” rays which will be produced. This parameter specifies the number of input rays. The parameter dNumRays determines the number of rays per iteration which will be used. Experience has shown that for systems with 32 Mbytes or more of memory, dNumRays can be set to a fairly large value such as 50,000 and ignored.

6.4.2 Output Directory

The output from a MARX simulation is written to an output directory specified by the OutputDir parameter. If the directory specfied does not exist, MARX will create it. Alternatively, if the specified directory does exist, its contents will be overwritten. In addition to the output photon vectors, MARX also copies the current version of the marx.par parameter file to the output directory.

6.4.3 Output Vectors

Depending on the particular instrument configuration chosen, MARX will produce 13, 14, or 18 binary output data files. Each of these data files contains information on a given photon property (arrival time, energy, etc.) and each is N elements long where N is the number of detected photons. The user has the option of suppressing the output of any one or all of these output files. The list of which files will be written is contained in the OutputVectors parameter. This parameter is set to a string where each desired output file is represented as a string. Table ?? lists the various output files and their single character designation. By default, all possible data files are produced.

6.5 Instrument Configuration

These parameters control the science instruments which are to be used in the simulation as well as which of MARX ’s two built–in mirror models to use.

6.5.1 Mirror Choice

MARX has two built–in mirror modules. One model is a full raytrace using an accurate physical model of the HRMA’s parabolic and hyperbolic components. The other is a simpler model based on a thin–lens approximation and using tabulated effective area data to determine which photons are reflected or absorbed. The MirrorType parameter controls which of these models is used in the simulation. A setting of “HRMA” yields the full raytrace model, while “EA–MIRROR” selects the simpler model. Off–axis sources cannot be simulated using the EA–MIRROR model and this model will eventually be phased out. Users are recommended to leave the MirrorType parameter set to the default value of “HRMA”.

6.5.2 Grating Choice

AXAF carries two sets of diffraction gratings: the Low Energy Transmission Grating (LETG) and the High Energy Transmission Grating (HETG). The performance of either instrument can be simulated using the GratingType parameter. Imaging observations can be simulated by

setting GratingType=NONE.

6.5.3 Detector Choice

Similarly, the user has the choice of all four AXAF focal plane detectors including the ACIS–I, ACIS–S, HRC–I and HRC–S. Which detector is used is controlled by the DetectorType parameter. If the HRC–S detector is selected, users have the option of including a model of the Drake Flat high energy suppression filter. Setting the parameter HRCDrake=yes includes the Drake Flat.

DetectorType can also be set to “NONE”. In this case, MARX does not project the rays to the focal plane but stops at the last simulated element, either the HRMA or the gratings if included. This option is useful for producing rayfiles which can be run through MARX again using different detectors or the same detector model with varying parameters. Alternately, the quantum efficiency of the specified detector can be suppressed using the DetIdeal parameter. If DetIdeal=yes, the focal plane geometry of the selected detector is preserved, but the efficiency is assumed to be unity.

6.5.4 Focus Position

The focal plane science instruments on AXAF are mounted on a movable platform called the Science Instrument Module (SIM) to allow the different detectors to be selected. Movement along the optical axis is also possible to adjust the focus. MARX simulates the SIM movement with three parameters: DetOffsetX, DetOffsetY, and DetOffsetZ. These parameters apply an offset measured in millimeters to the nominal on–axis, in–focus SIM position and have values of 0 by default. In the MARX coordinate system (which is the same as the XRCF coordinate system), the X axis corresponds to the optical axis. Therefore, the DetOffsetX parameter can be used to simulate defocussed AXAF observations. This functionality is useful for studying the pileup effect in the ACIS CCD’s. Defocussing is one possible means of minimizing this effect for a given observation.

The DetOffsetZ parameter can be used to translate the SIM in the direction perpendicular to the grating dispersion. If the Drake Flat is to be used, the DetOffsetZ parameter should be set to a value of -5.471 mm.

6.6 Source Definition

Specifying sources in MARX is equivalent to choosing a spectral energy distribution and a spatial distribution for the incoming photons. A number of simple options for these two source characteristics are built into MARX or users may write their own custom source models and link them into MARX dynamically.

6.6.1 Source Position

Source position refers to the location of the source relative to the optical axis or nominal aimpoint. Users may specify the off–axis location of a source using the parameters SourceElevation and SourceAzimuth. Despite the familiar nomenclature, “Elevation” and “Azimuth” do not carry their standard astronomical connotations in this situation. SourceAzimuth refers to the off–axis angle of the source measured along the dispersion or y–axis. Coversely, SourceElevation determines the off–axis angle in the cross-disperison or z–axis direction. Both parameters are measured in units of arcminutes.

MARX can also simulate photons from a source at a finite distance. This functionality is useful for XRCF simulations where the X–ray source was not at infinity. Non–astronomical sources can be specified using the SourceDistance parameter which sets the distance between the source and the front aperture of the HRMA in meters. If SourceDistance is set to 0, the source is assumed to be at infinite distance.

6.6.2 Source Spectrum

Users have two options for specifying the spectral energy distribution of source photons: a built–in FLAT spectrum model which produces uniform flux over the specified energy range, or a FILE mode which reads the spectrum from an external ASCII file. The SpectrumType parameter selects between these two options. If the FLAT spectrum is selected, the SourceFlux parameter is used to determine the overall normalization of the spectrum in photons sec^{−1} cm^{−2}. The MinEnergy and MaxEnergy energy parameters determine the energy range over which photons will be generated for the FLAT spectral model. Both parameters may be set to the same value to generate a monochromatic source.

If the FILE mode is selected, the user must specify the name of the input ASCII file containing the spectral energy distribution using the SpectrumFile parameter. The input ASCII file should contain two columns separated by at least one space where the first column gives the energy grid in keV and the second column gives the flux density at that energy in units of photons sec^{−1} cm^{−2} keV^{−1}. No limits are placed on the number of points in the input file. Directions for creating MARX ASCII spectral input files using XSPEC are given in Section ??

In FILE mode, the SourceFlux parameter can be used to set the overall normalization of the input spectral energy distribution. Setting SourceFlux to a positive, non–zero value will cause MARX to renormalize the spectrum read from the ASCII file to the specified total flux. If SourceFlux=-1 (or any number less than 0), MARX will use the normalization inherent in the input spectrum. In this manner, several sources with a consistent spectral “shape” but varying total flux can be simulated using a single input spectrum file.

6.6.3 Source Spatial Distribution

The spatial distribution of source photons in MARX is determined by the choice of the SourceType parameter. There are currently seven spatial models included:

POINT  Point source
GAUSS  Radially symmetric Gaussian
LINE  One–dimensional line
BETA  Cluster Beta model
RAYFILE  Input from a previously run MARX rayfile
DISK  Uniform disk or annulus
USER  Dynamically linked user–supplied model

The GAUSS, LINE, BETA, and DISK models all have additional, individual parameters which may be adjusted. If SourceType=``RAYFILE'', the name of the rayfile to be used is specified with the RayFile parameter.

The USER source model requires two additional parameters. UserSourceFile specifies the path to the dynamically linked source file and should be the full, absolute pathname due to peculiarities in the manner in which the dynamic linker locates modules. The value of the parameter UserSourceArgs will depend on the specifics of the user model being linked. Section ?? discusses USER models in more detail.

6.7 Running the Simulation

Once your system has been configured appropriately and any desired modifications have been made to the marx.par parameter file, the simulation is ready to run. If the parameters in the marx.par file are already set appropriately, the simulation can be lauched simply by typing “marx” at the prompt. MARX will print out a number of diagnostic messages as the simulation proceeds indicating which configuration is being used as well as which data files were accessed. Some output from an example simulation using the LETG/HRC–S combination is shown here:

unix% marx
Reading HRMA optical constants:
/usr/local/src/marx_1.21-dist/marx/data/iridium.dat
Initializing LETG...
/usr/local/src/marx_1.21-dist/marx/data/optical-constants.dat
Initializing HRC-S detector...
Reading HRC-S QE data files:
/usr/local/src/marx_1.21-dist/marx/data/qe_hrcs_p2500_al1000.dat
/usr/local/src/marx_1.21-dist/marx/data/qe_hrcs_p2500_al300.dat
/usr/local/src/marx_1.21-dist/marx/data/qe_hrcs_p2000_al2000.dat
/usr/local/src/marx_1.21-dist/marx/data/qe_hrcs_p2000_al300.dat
Initializing Drake flat...
Reading Drake QE data files:
/usr/local/src/marx_1.21-dist/marx/data/carbon.dat
/usr/local/src/marx_1.21-dist/marx/data/chromium.dat
Initializing source type POINT...
System initialized.
Starting simulation.  Exposure Time set to 1.000000e+01 seconds
Collecting 10000 photons...
10000 collected.
Reflecting from HRMA
Diffracting from LETG.
Detecting with HRC-S
Writing output to directory 'letg' ...
Total photons: 10000, Total Photons detected: 195, (efficiency: 0.019500)
  (efficiency this iteration  0.019500)  Total time: 0.893824
Collecting 10000 photons...
10000 collected.
Reflecting from HRMA
Diffracting from LETG.
Detecting with HRC-S
Writing output to directory 'letg' ...
Total photons: 20000, Total Photons detected: 389, (efficiency: 0.019450)
  (efficiency this iteration  0.019400)  Total time: 1.768704

...

Once the initialization is complete, MARX will begin processing groups of rays (the size of this group is determined by the dNumRays parameter). Again, diagnostic messages will be generated which track the simulation’s progress, i.e. “Collecting...”, “Reflecting...”, etc. A short synopsis will also be printed at the end of each group of rays indicating the number of rays processed, the number actually “detected”, the efficiency for this iteration, and the total integration time incurred so far. When the number of rays specified have been processed or the indicated integration time has been reached, the simulation will terminate.

Table 6.1: MARX Output Files

Filename  Code  Description
detector.dat  D  Chip ID (CCD for ACIS or MCP for HRC)
energy.dat  E  The true photon energy [keV]
marx.par  −  Updated MARX parameter file
marx2fits.info  −  Information summary for FITS header
mirror.dat  M  Reflection shell of the HRMA
pha.dat  P  The pulse height of the detected photon [PHA]
time.dat  T  Photon arrival time [sec]
xcos.dat  1  The X–axis direction cosine of the photon
xpixel.dat  x  The X–axis detection pixel
xpos.dat  X  The X–axis position of the photon [mm]
ycos.dat  2  The Y–axis direction cosine of the photon
ypixel.dat  y  The Y–axis detection pixel
ypos.dat  Y  The Y–axis position of the photon [mm]
zcos.dat  3  The Z–axis direction cosine of the photon
zpos.dat  Z  The Z–axis position of the photon [mm]

Additional HETG specific files

order.dat  O  The diffraction order of the photon

Additional LETG specific files

ocoarse1.dat d The order of a photon diffracted by the coarse

wire support structure of the LETG

ocoarse2.dat c The order of a photon diffracted by the coarse

wire support structure of the LETG

ocoarse3.dat b The order of a photon diffracted by the coarse

wire support structure of the LETG

ofine.dat a The order of a photon diffracted by the fine

wire support structure of the LETG

order.dat  O  The primary diffraction order of the photon

6.8 MARX Output files

Depending on the values of the OutputDir and OutputVectors parameters, MARX will by default create a directory containing a number of binary output files. The contents of this directory can be translated into other formats (FITS events files, FITS image files, SAOSAC DPDE files, etc..) using the tools described in Section ??.

6.8.1 Binary Output Vectors

The exact number of files which MARX writes out will depend on the instrument configuration being simulated and the value of the OutputVectors parameter. Table ?? lists the various possible output files along with their single letter designations in the

Table 6.2: MARX Binary Output File Format

Offset  Length  Interpretation
(bytes) (bytes)
0  4  Magic number: 0x83 0x13 0x89 0x8D
4  1  Data type:

“A” − 8 bit signed integer (character)

“I” − 16 bit signed integer “J” − 32 bit signed integer “E” − 32 bit float “D” − 64 bit float

5 15 Data column name. If the length of the name is less

than 15 characters, it will be padded with 0. If the name is 15 characters, there will be no padding.

20  4  Number of Rows
24  4  Number of Columns, if 0 it is a vector
28  4  Reserved
32  N  Data

OutputVectors parameter string. Each file is a simple binary vector describing a given photon characteristic and containing a 32 byte header followed by one entry for each detected photon. The format of the header for these files is described in Table ??. The contents of a given binary output file can be examined using:

unix% marx -dump FILENAME > output.log

which prints the contents of the specified binary file to the standard output device (here redirected into a log file). Alternatively, the IDL routine READ MARX FILE may be used to read MARX binary output files (see Section ??).

6.8.2 FITS Events Files

The contents of a MARX simulation output directory may be recast in a standard binary FITS events file using the marx2fits tool (see Section ??). Events files created in this way contain the standard event quantitites for “detected” photons (pixel position, pulse height, time, etc.). In addition, table entries are included for a number of useful simulation variables (true photon energy, dispered order, mirror reflection shell, etc.). marx2fits currently writes files using the prototype ACIS event file format ACIS EVT 3.0. HRC specific formats are not currently supported since they are still in development. As they become available, these additional formats will be included. Sample FITS headers are reproduced in Appendix ??.

6.8.3 FITS Images

The marx2img tool can be used to create standard FITS images from the contents of a MARX simulation output directory. The dimensions of the constructed image will depend on the specified selection region. See Section ?? for the various options to this tool.

6.8.4 MARX Rayfiles

[To be added]

6.9 Creating Input Spectra in XSPEC

As we discussed in Section ??, MARX can read a user–provided ASCII file to specify the spectral energy distribution of source photons. How does one create such a file? There a number of ways to create such a spectrum, but for most users, XSPEC will be the simplest means. Users should, however, note that the built–in models in XSPEC are probably not sufficient for generating high resolution spectra as input to HETGS or LETGS simulations.

The basic process to create an ASCII output file within XSPEC consists of:

• Define model

• Define model energy grid

• Write model to ASCII data file

The reader is referred the voluminous XSPEC 10.0 documentation for guidance, but for the simple example of a power-law model with Galactic absorption, the process might go something like:

   XSPEC> model wabs powerl
   XSPEC> dummyrsp 0.03 30.0 1000 log
   XSPEC> plo model
   XSPEC> iplo
   PLT> wdata plaw.out
   PLT> quit
   XSPEC> quit

Note that you will need to answer various prompts to set the values of the model parameters. In particular, you will need to make sure that your spectrum is normalized appropriately for the source in question. Alternatively, you can ignore the normalization within XSPEC and use the MARX SourceFlux parameter to control the normalization.

At this point, you have an input spectrum and are almost ready to run MARX to produce the desired simulation. The default output format of XSPEC ASCII data files, however, is not transparently digestible by MARX . MARX expects as input a two column ASCII file containing the energy in keV in the first column and the flux in phot s^{−1} cm^{−2} keV^{−1} in the second. XSPEC’s ASCII output contains additional columns and header information. So before running the input spectrum through MARX , one must simplify the XSPEC output file. The MARX suite includes a shell script for making such simplications called xspec2marx (see Section ??). Simply type the following (assuming xspec2marx is in your path):

unix% xspec2marx plaw.out plaw.dat

The new data file, plaw.dat, will contain the input spectrum in a format ready for input into MARX . In future versions of MARX , support for reading XSPEC PHA files directly will be incorporated.

6.10 Sample Sessions

6.10.1 An Off–axis Point Source

Section 7

Simulating Pileup

Section 8

Working with Simulated Data

8.1 Using FTOOLS 8.2 Using IDL

Section 9

Using MARX with SAOSAC

9.1 Overview 9.2 Using SAOSAC Rayfiles in MARX 9.3 Using MARX Rayfiles in SAOSAC

Appendix A

MARX Parameters

A.1 Parameter List by Module

A.1.1 Simulation Control

NumRays  1000000  TOTAL number of rays to generate
dNumRays  100000  number of rays per iteration
ExposureTime  10000.0  exposure time (0.0 for none)
OutputDir  marx-out  output directory name
MirrorType  HRMA  Select mirror type
GratingType  HETG  Select grating type
DetectorType  ACIS-S  Select detector type
(DataDirectory  $MARX DATA DIR)  Directory for input data
OutputVectors  ETXYZ123DxyMPOabcd Output data columns (one or more of ETXYZ123DxyMPOabcd)
RandomSeed 0 Random number seed (-1 means use current time)
(DumpToRayFile no)  Output in marx rayfile format?
RayFile  marx.output  Marx input source/output ray filename
DetOffsetX  0.0  Detector X offset from nominal (mm)
DetOffsetY  0  Detector Y offset from nominal (mm)
DetOffsetZ  0  Detector Z offset from nominal (mm)
DetIdeal  no  Is Detector perfect (QE=1)?
(mode  hl)  Mode for parameter file

MARX User’s Guide · Version 1.0

70  APPENDIX A. MARX PARAMETERS

A.1.2 Source

SourceFlux  1.0  Incoming ray flux (photons/sec/cm^{2})
SpectrumType  FLAT  Select spectrum type
SpectrumFile  spect.dat  Input spectrum filename
MinEnergy  0.03  MIN ray energy
MaxEnergy  10.0  MAX ray energy
SourceType  POINT  Source type
SourceDistance  0  Source distance (meters) (0 if infinite)
SourceElevation  0  Source elevation (ARC Minutes)
SourceAzimuth  0  Source azimuth (ARC Minutes)
S-GaussSigma  50  Gauss source sigma (ARC seconds)
S-LineAngle  45  Line source orientation angle (degrees)
S-LineLength  120  Line source length (arc-secs)
S-BetaCoreRadius 2.5  Core radius (ARC SECONDS)
S-BetaBeta  0.7  BETA value
S-DiskTheta0  0  Min disk theta in arc-sec
S-DiskTheta1  60  Max disk theta in arc-sec
UserSourceFile  ../doc/examples/grayscale.so Dynamically linked source filename
UserSourceArgs  /tmp/casa.8bit  User source parameter

A.1.3 Mirror

Shutters1  0000  mirror 1 shutter bitmap (0 == open, 1 == closed)
Shutters3  0000  mirror 3 shutter bitmap (0 == open, 1 == closed)
Shutters4  0000  mirror 4 shutter bitmap (0 == open, 1 == closed)
Shutters6  0000  mirror 6 shutter bitmap (0 == open, 1 == closed)
(WFold P1 File  scat p1 M)  wfold filename for HRMA
(WFold H1 File  scat p1 M)  wfold filename for HRMA
(WFold P3 File  scat p3 M)  wfold filename for HRMA
(WFold H3 File  scat p3 M)  wfold filename for HRMA
(WFold P4 File  scat p4 M)  wfold filename for HRMA
(WFold H4 File  scat p4 M)  wfold filename for HRMA
(WFold P6 File  scat p6 M)  wfold filename for HRMA
(WFold H6 File  scat p6 M)  wfold filename for HRMA
(HRMAOptConst  iridium.dat) optical const filename for HRMA
(HRMAOptConstScale 1.0)  Scale factor for HRMA opt constants
(HRMAVig  0.9)  HRMA Vignetting factor
(HRMABlur  0.287)  HRMA Blur angle (arc seconds)
(HRMAXOffset  0.0)  HRMA XOffset (mm)
(HRMA Pitch  0.0)  HRMA Pitch (arc-minutes)
(HRMA Yaw  0.0)  HRMA Yaw (arc-minutes)
HRMA Locked  yes  Does the HRMA rotate with the gratings?
(HRMA X H Back  9179.8)  HRMA Hyperboloid back distance
(HRMA X H Front  10018.0)  HRMA Hyperboloid front distance
(HRMA X P Back  10098.8)  HRMA Paraboloid back distance
(HRMA X P Front  10937.0)  HRMA Paraboloid front distance

A.1. PARAMETER LIST BY MODULE  71

(HRMA R H1 Back 560.86506)  H1 back radius
(HRMA R H3 Back 451.45717)  H3 back radius
(HRMA R H4 Back 398.51324)  H4 back radius
(HRMA R H6 Back 296.13584)  H6 back radius
(HRMA R H1 Front 598.52343)  H1 front radius
(HRMA R H3 Front 481.77216)  H3 front radius
(HRMA R H4 Front 425.27403)  H4 front radius
(HRMA R H6 Front 316.02294)  H6 front radius
(HRMA R P1 Back 600.34506)  P1 back radius
(HRMA R P3 Back 483.46567)  P3 back radius
(HRMA R P4 Back 426.85049)  P4 back radius
(HRMA R P6 Back 317.29022)  P6 back radius
(HRMA R P1 Front 612.69078)  P1 front radius
(HRMA R P3 Front 493.40861)  P3 front radius
(HRMA R P4 Front 435.62935)  P4 front radius
(HRMA R P6 Front 323.81612)  P6 front radius
(MirrorF  10.0692)  HRMA focal length (meters)
(MirrorRadius1  600)  Mirror 1 radius (mm)
(MirrorRadius3  480)  Mirror 3 radius (mm)
(MirrorRadius4  425)  Mirror 4 radius (mm)
(MirrorRadius6  310)  Mirror 6 radius (mm)
(MirrorVig  0.9)  HRMA Vignetting factor
MirrorUseEA  yes Use effective area for HRMA?
(MirrorEAFile Ae s1346.tbl) mirror effective filename
MirrorBlur  yes Perform mirror blur?
(MirrorBlurFile  mirr-ee.dat)  mirror blur filename

A.1.4 HETG

(RowlandDiameter 8634)  Rowland Torus Diameter (mm)
(GratingOptConsts optical-constants.dat) optical constants filename
(LETGVig  0.73)  Grating Vignetting Factor
(HETGVig  0.93)  Grating Vignetting Factor
(hegGold  0.02)  HEG gold thickness (microns)
(hegChromium  0)  HEG chromium thickness (microns)
(hegNickel  0)  HEG nickel thickness (microns)
(hegPolyimide  1)  HEG polyimide thickness (microns)
(hegPeriod  0.2002)  HEG period (microns)
(hegdPoverP  2.2e-4)  HEG dP/P
(hegBarHeight  0.55)  HEG bar height (microns)
(hegBarWidth  0.1201)  HEG bar width (microns)
(hegNumOrders  23)  HEG num orders (2n+1)
(hegTheta  -5.0)  HEG dispersion angle
(hegdTheta  0.46)  HEG alignment error (sigma arc min)
(megGold  0.02)  MEG gold thickness (microns)
(megChromium  0)  MEG chromium thickness (microns)
(megNickel  0)  MEG nickel thickness (microns)
(megPolyimide  0.5)  MEG polyimide thickness (microns)
(megPeriod  0.4001)  MEG period (microns)
(megdPoverP  1.6e-4)  MEG dP/P
(megBarHeight  0.38)  MEG bar height (microns)
(megBarWidth  0.2080)  MEG bar width (microns)
(megNumOrders  23)  MEG num orders (2n+1)
(megTheta  5.0)  MEG dispersion angle
(megdTheta  0.36)  MEG alignment error (sigma arc min)

A.1.5 LETG

(legGold  0.0)  LEG gold thickness (microns)
(legChromium  0)  LEG chromium thickness (microns)
(legNickel  0)  LEG nickel thickness (microns)
(legPolyimide  0.0)  LEG polyimide thickness (microns)
(legPeriod  0.991249)  LEG period (microns)
(legdPoverP  8.67592e-05) LEG dP/P
(legBarHeight  0.4758)  LEG bar height (microns)
(legBarWidth  0.5154)  LEG bar width (microns)
(legTheta  0.0)  LEG dispersion angle
(legdTheta  0.0)  LEG alignment error (sigma arc min)
(legNumOrders  41)  LEG num orders (2n+1)
(legFineNumOrders  11)  LETG Fine Grating num orders (2n+1)
(legCoarseNumOrders 11)  LETG Coarse Grating num orders (2n+1)

A.1.6 ACIS

(ACISPixelsX  1024)  ACIS-S number of pixels in X Direction
(ACISPixelsY  1024)  ACIS-S number of pixels in Y Direction
(ACISPixelSize  0.024)  ACIS-S pixel size (mm)
(ACISFanoFactor  0.115)  ACIS-S fano factor
(ACISReadoutTime  2.7)  ACIS-S readout time (sec)
(ACIS-S-FsBsConf  fbfbff)  ACIS-S fs/bs configuration
(ACIS-S-FsReadNoise  4.0)  ACIS-S FS read noise
(ACIS-S-FsEnergyGain 0.00368)  ACIS-S FS energy gain (KeV/electron)
(ACIS-S-FsQEFile  ACIS QE FI.tbl) ACIS-S FS QE filename
(ACIS-S-BsReadNoise 4.0) ACIS-S BS read noise
(ACIS-S-BsEnergyGain 0.00368)  ACIS-S BS energy gain (KeV/electron)
(ACIS-S-BsQEFile  ACIS QE BI.tbl) ACIS-S BS QE filename
(ACIS-I-QEFile  ACIS QE FI.tbl) ACIS-I QE filename

A.1.7 HRC

(HRC-IPixelSize 6.4e-3)  HRC Pixel size (mm)
(HRC-IQEFile  qe hrcs p2500 al1000.dat) HRC QE File 0
(HRCPixelSize 6.4e-3) HRC Pixel size (mm)
(HRCQEFile0  qe hrcs p2500 al1000.dat) HRC QE File 0
(HRCQEFile1 qe hrcs p2500 al300.dat) HRC QE File 1
(HRCQEFile2  qe hrcs p2000 al2000.dat) HRC QE File 2
(HRCQEFile3 qe hrcs p2000 al300.dat) HRC QE File 3
(HRCIonOffsetT 4)  Top Ion Shield Offset (mm)
(HRCIonOffsetL 19.7)  Left Ion Shield Offset (mm)
(HRCIonOffsetR 11.7)  Right Ion Shield Offset (mm)

A.2. SAMPLE PARAMETER FILE  73

A.1.8 Drake Flat

HRCDrake  yes Use Drake flat (yes/no)
DrakeOffsetX  28.3  the Drake X offset of lower plate (mm)
DrakeOffsetZ  5.0  the Drake Z offset of lower plate (mm)
DrakeGapY1  28.7  the Drake Gap Offset Y1
DrakeGapY2  36.7  the Drake Gap Offset Y2
DrakeN  2  the number of Drake facets
DrakeLength  100  length of Drake plate
DrakeOptConstCr chromium.dat  the Chromium Optical constant filename for the Drake
DrakeOptConstC carbon.dat  the Carbon Optical constant filename for the Drake
DrakeHeight1  25.3  the height of drake flat 1 (mm)
DrakeTheta1  4.5  the angle of drake flat 1 (degrees)
DrakeHeight2  34.4  the height of drake flat 2 (mm)
DrakeTheta2  7  the angle of drake flat 2 (degrees)
DrakeHeight3  0  the height of drake flat 3 (mm)
DrakeTheta3  0  the angle of drake flat 3 (degrees)
DrakeHeight4  0  the height of drake flat 4 (mm)
DrakeTheta4  0  the angle of drake flat 4 (degrees)

A.2 Sample Parameter File

# -*-sh-*--------------------------------------------------------------------
#
#
# MIT MARX Simulator Parameter file                 version 1.21 (06-30-97)
#
#
#----------------------------------------------------------------------------
#
# Simulation setup and control
#
#----------------------------------------------------------------------------
NumRays,i,a,100000,1,,"Enter TOTAL number of rays to generate"
dNumRays,i,a,10000,1,100000,"Enter number of rays per iteration"
ExposureTime,r,a,10,,,"Enter exposure time (0.0 for none)"
OutputDir,f,a,"letg",,,"Enter output directory name"
MirrorType,s,a,"HRMA","HRMA|EA-MIRROR",,"Select mirror type"
GratingType,s,a,"LETG","HETG|LETG|NONE",,"Select grating type"
DetectorType,s,a,"HRC-S","HRC-S|ACIS-S|HRC-I|ACIS-I|NONE",,"Select detector type"
DataDirectory,s,h,"$MARX_DATA_DIR",,,"Enter directory for input data"
OutputVectors,s,a,"ETXYZ123DxyMPOabcd",,,"Enter output data columns (one or \
  more of ETXYZ123DxyMPOabcd)"
RandomSeed,i,a,0,,,"Enter random number seed (-1 means use current time)"
DumpToRayFile,b,h,no,,,"Output in marx rayfile format?"
RayFile,s,a,"marx.output",,,"Enter marx input source/output ray filename"
#---------------------------------------------------------------------------
#
# Source spectral parameters
#
#---------------------------------------------------------------------------
SourceFlux,r,a,1.0,,,"Enter incoming ray flux (photons/sec/cm^2)"
SpectrumType,s,a,"FLAT","FLAT|FILE",,"Select spectrum type"
SpectrumFile,f,a,"spect_n1399.dat",,,"Enter input spectrum filename"
#
#  Energy limits  (for flat spectrum model)

#
MinEnergy,r,a,0.03,0.03,10.0,"Enter MIN ray energy"
MaxEnergy,r,a,10.0,0.03,10.0,"Enter MAX ray energy"
#---------------------------------------------------------------------------
#
# Source spatial parameters
#
#---------------------------------------------------------------------------
#
# Source spatial model
#
SourceType,s,a,"POINT","POINT|GAUSS|LINE|BETA|RAYFILE|DISK|USER",,"Select source"
#
# Source position (center of source)
#
SourceDistance,r,a,0,,,"Enter Source distance (meters) (0 if infinite)"
SourceElevation,r,a,0,,,"Enter source elevation (ARC Minutes)"
SourceAzimuth,r,a,0,,,"Enter source azimuth (ARC Minutes)"
#
# Gaussian source parameters
#
S-GaussSigma,r,a,50,0.0,14000.0,"Enter gauss source sigma (ARC seconds)"
#
# LINE source parms
#
S-LinePhi,r,a,0,,,"Enter line source orientation angle (degrees)"
S-LineTheta,r,a,5,,,"Enter line source length (arc-secs)"
#
# BETA source parms
#
S-BetaCoreRadius,r,a,2.5,,,"Enter core radius (ARC SECONDS)"
S-BetaBeta,r,a,0.7,0.5001,,"Enter BETA value"
#
# DISK source parms
#
S-DiskTheta0,r,a,0,,,"Enter min disk theta in arc-sec"
S-DiskTheta1,r,a,60,,,"Enter max disk theta in arc-sec"
#
# USER Source type.
#
#      This is for use by a dynamically linked user-defined source.
#      On most systems, this should be an absolute path.
#
UserSourceFile,f,a,"../doc/examples/grayscale.so",,,"Enter dynamically linked \
  source filename"
UserSourceArgs,s,a,"/tmp/casa.dat",,,"Enter user source parameter"
#---------------------------------------------------------------------------
#
# Detector Setup for HRC-S/I, ACIS-S/I, ....
#
#---------------------------------------------------------------------------
DetOffsetX,r,a,0.0,,,"Enter Detector X offset from nominal (mm)"
DetOffsetY,r,a,0,,,"Enter Detector Y offset from nominal (mm)"
DetOffsetZ,r,a,0,,,"Enter Detector Z offset from nominal (mm)"
DetIdeal,b,a,no,,,"Is Detector perfect (QE=1)?"
#
#  Note:  If the drake flat is used, set DetOffsetZ to -5.471

A.2. SAMPLE PARAMETER FILE  75

#
#DetOffsetZ,r,a,-5.741,,,"Enter Detector Z offset from nominal (mm)"
#
#---------------------------------------------------------------------------
#
#        PARAMETERS BEYOND THIS POINT SHOULD NOT BE MODIFIED
#               UNLESS YOU KNOW WHAT YOU ARE DOING.
#
#---------------------------------------------------------------------------

...

Appendix B

Sample FITS Headers

B.1 Primary Header

SIMPLE  =                   T /FITS STANDARD
BITPIX  =                   8 /Binary Data
NAXIS   =                   0 /No DATA image array present
EXTEND  =                   T /There MAY be standard extensions
COMMENT
COMMENT  AXAF FITS Event File: ACIS
COMMENT
CONTENT = 'BASIC   ' /File contains GTIs and events
MISSION = 'AXAF    ' /Advanced X-ray Astrophysics Facility
TELESCOP= 'AXAF    ' /Telescope used
INSTRUME= 'ACIS    ' /AXAF CCD Imaging Spectrometer
OBJECT  = 'POINT   ' /Title of Observation
OBS_ID  = '0       ' /Observation ID (*)
GRATING = 'NONE    ' /Grating type used
SIM_X   =                  10 /SIM offset, mm
SIM_Y   =                   0 /SIM offset, mm
SIM_Z   =                   0 /SIM offset, mm
AEID    = 'ACIS1   ' /ACIS electronics ID
OBSERVER= 'wise    ' /Observer or PI
OBS_MODE= 'POINTING' /Observation mode
READMODE= 'TIMED   ' /CCD exposure mode
DATAMODE= 'FAINT   ' /CCD telemetry mode
SCI_MODE= 'PHOTON_COUNT' /Event detection mode
INSTMODE= 'FPI     ' /Telemetry type
RA_NOM  =                   0 /Nominal RA in degrees
DEC_NOM =                   0 /Nominal Dec in degrees
ROLL_NOM=                   0 /Nominal Roll in degrees
DATE-OBS= '02/07/1997' /Date of observation start (GMT)
TIME-OBS= '23:40:19' /Time of observation start (GMT)
DATE-END= '02/07/1997' /Date of observation end (GMT)
TIME-END= '23:40:49' /Time of observation end (GMT)

MJD-OBS =             50632.5 /MJD of observation start
ONTIME  =             30.0003 /Ontime in seconds
EXPOSURE=             30.0003 /Livetime in seconds
DTCOR   =                   1 /Dead time correction factor
CREATOR = 'marx2fits v1.0' /Program creating this file
ASCVER  = 'ACIS_EVT_3.0' /Format spec for this file
ORIGIN  = 'ASC     ' /Organization creating file.
DATE    = '14/07/97' /Date file was created
REVISION=                   0 /Processing revision
EVENT   = 'EVENTS  ' /PROS: Name of extension with events
DATACLAS= 'SIMULATED' /File contains simulated data produce by MARX
COMMENT
COMMENT  HEASARC timing keywords
COMMENT
MJDREF  =             49353.5 /MJD of clock start
TSTART  =         1.10504e+08 /Observation start time, seconds
TSTOP   =         1.10504e+08 /Observation stop time, seconds
TELAPSE =             30.0003 /Elapsed time, seconds
TIMEUNIT= 's       ' /HEASARC: time unit
TIMESYS = '1994.0  ' /HEASARC: time system
TIMEDEL =                 0.2 /Smallest meaningful time increment, s
TIMEREF = 'LOCAL   ' /Time is local for data
TIMVERSN= 'OGIP/93-003a' /OGIP time convention
TASSIGN = 'SATELLITE' /Source of time assignment
COMMENT
COMMENT  ACIS event processing information
COMMENT
NFRAMES =                   0 /Number of ACIS Frames
LABROT  =                   1 /WHAT IS THIS?
RASTER1 =                1360 /Number of READ X pixels
RASTER2 =                1030 /Number of READ Y pixels
IAMINCOL=                   5 /Node A first column
IAMAXCOL=                 260 /Node A last column
IAMINROW=                   1 /Node A first row
IAMAXROW=                1026 /Node A last row
IBMINCOL=                 345 /Node B first column
IBMAXCOL=                 600 /Node B last column
IBMINROW=                   1 /Node B first row
IBMAXROW=                1026 /Node B last row
ICMINCOL=                 685 /Node C first column
ICMAXCOL=                 940 /Node C last column
ICMINROW=                   1 /Node C first row
ICMAXROW=                1026 /Node C last row
IDMINCOL=                1025 /Node D first column
IDMAXCOL=                1280 /Node D last column
IDMINROW=                   1 /Node D first row
IDMAXROW=                1026 /Node D last row
GRD_SCHM= 'ASCA    ' /Grading scheme
EVTIMODE=                   9 /Event island size
WINSIZE =                 114 /Window size
COMMENT  MARX VERSION: 1.21 # Jun 28 1997 12:01:02

B.2 Good Time Interval Extension Header

XTENSION= 'BINTABLE' /FITS BINARY TABLE
BITPIX  =                   8 /Binary data
NAXIS   =                   2 /Table is a matrix
NAXIS1  =                  16 /Width of table in bytes
NAXIS2  =                   1 /Number of entries in table
PCOUNT  =                   0 /Random parameter count
GCOUNT  =                   1 /Group count
TFIELDS =                   2 /Number of fields in each row
TFORM1  = '1D      ' /Data type for field
TTYPE1  = 'START   ' /Label for field
TUNIT1  = 's       ' /Physical units for field
TFORM2  = '1D      ' /Data type for field
TTYPE2  = 'STOP    ' /Label for field
TUNIT2  = 's       ' /Physical units for field
EXTNAME = 'GTI     ' /Table name
HDUCLASS= 'OGIP    ' /Convention for HDUCLASS
HDUCLAS1= 'GTI     ' /File contains good time intervals
HDUCLAS2= 'STANDARD' /File contains standard good time intervals
COMMENT
COMMENT  Data model support keywords
CFIELDS =                   1 /Number of ASC Table Columns
CNAM1   = 'TIME    ' /Time
CNC1    =                   2 /Number of FITS cols for ASC col 1
CETYP1  = 'R       ' /Data is an interval
CITYP1  = '[)      ' /Interval is semi-open
TDISP1  = 'F20.6   ' /Display format for FITS col 1
TDISP2  = 'F20.6   ' /Display format for FITS col 1

B.3 Events Binary Table Extension Header

XTENSION= 'BINTABLE' /FITS BINARY TABLE
BITPIX  =                   8 /Binary data
NAXIS   =                   2 /Table is a matrix
NAXIS1  =                  64 /Width of table in bytes
NAXIS2  =               81963 /Number of entries in table
PCOUNT  =                   0 /Random parameter count
GCOUNT  =                   1 /Group count
TFIELDS =                  22 /Number of fields in each row
TFORM1  = 'D       ' /Data type for field
TTYPE1  = 'TIME    ' /time since observation start
TUNIT1  = 's       ' /Physical units for field
TFORM2  = 'J       ' /Data type for field
TTYPE2  = 'EXPNO   ' /Exposure number
TUNIT2  = '        ' /Physical units for field
TFORM3  = 'I       ' /Data type for field
TTYPE3  = 'FRAME   ' /Frame number
TUNIT3  = '        ' /Physical units for field

TFORM4  = 'I       ' /Data type for field
TTYPE4  = 'CHIPX   ' /CHIP X
TUNIT4  = 'pixel   ' /Physical units for field
TFORM5  = 'I       ' /Data type for field
TTYPE5  = 'CHIPY   ' /CHIP Y
TUNIT5  = 'pixel   ' /Physical units for field
TFORM6  = 'I       ' /Data type for field
TTYPE6  = 'TDETX   ' /Detector X
TUNIT6  = 'pixel   ' /Physical units for field
TFORM7  = 'I       ' /Data type for field
TTYPE7  = 'TDETY   ' /Detector Y
TUNIT7  = 'pixel   ' /Physical units for field
TFORM8  = 'I       ' /Data type for field
TTYPE8  = 'DETX    ' /Tangent Plane X
TUNIT8  = 'pixel   ' /Physical units for field
TFORM9  = 'I       ' /Data type for field
TTYPE9  = 'DETY    ' /Tangent Plane Y
TUNIT9  = 'pixel   ' /Physical units for field
TFORM10 = 'I       ' /Data type for field
TTYPE10 = 'X       ' /RA sky pixel
TUNIT10 = 'pixel   ' /Physical units for field
TFORM11 = 'I       ' /Data type for field
TTYPE11 = 'Y       ' /Dec sky pixel
TUNIT11 = 'pixel   ' /Physical units for field
TFORM12 = '0I      ' /Data type for field
TTYPE12 = 'PHAS    ' /Event island phas
TUNIT12 = 'channel ' /Physical units for field
TFORM13 = 'I       ' /Data type for field
TTYPE13 = 'CCDID   ' /CCD id number
TUNIT13 = '        ' /Physical units for field
TFORM14 = 'I       ' /Data type for field
TTYPE14 = 'PHA     ' /Total PHA for event
TUNIT14 = 'channel ' /Physical units for field
TFORM15 = 'I       ' /Data type for field
TTYPE15 = 'GRADE   ' /grade code
TUNIT15 = '        ' /Physical units for field
TFORM16 = 'E       ' /Data type for field
TTYPE16 = 'ENERGY  ' /Energy of ray
TUNIT16 = 'kev     ' /Physical units for field
TFORM17 = 'E       ' /Data type for field
TTYPE17 = 'XPOS    ' /X position in MARX coord system
TUNIT17 = 'mm      ' /Physical units for field
TFORM18 = 'E       ' /Data type for field
TTYPE18 = 'YPOS    ' /Y position in MARX coord system
TUNIT18 = 'mm      ' /Physical units for field
TFORM19 = 'E       ' /Data type for field
TTYPE19 = 'ZPOS    ' /Z position in MARX coords
TUNIT19 = 'mm      ' /Physical units for field
TFORM20 = 'E       ' /Data type for field
TTYPE20 = 'XCOS    ' /X direction cosine
TUNIT20 = '        ' /Physical units for field
TFORM21 = 'E       ' /Data type for field

TTYPE21 = 'YCOS    ' /Y direction cosine
TUNIT21 = '        ' /Physical units for field
TFORM22 = 'E       ' /Data type for field
TTYPE22 = 'ZCOS    ' /Z direction cosine
TUNIT22 = '        ' /Physical units for field
EXTNAME = 'EVENTS  ' /Table name
COMMENT
COMMENT  AXAF ACIS Events
COMMENT
MISSION = 'AXAF    ' /Advanced X-ray Astrophysics Facility
TELESCOP= 'AXAF    ' /Telescope used
INSTRUME= 'ACIS    ' /AXAF CCD Imaging Spectrometer
OBJECT  = 'POINT   ' /Title of Observation
TITLE   = 'POINT   ' /Title of Observation
OBS_ID  = '0       ' /Observation ID (*)
GRATING = 'NONE    ' /Grating type used
OBSERVER= 'wise    ' /Observer or PI
OBS_MODE= 'POINTING' /Observation mode
READMODE= 'TIMED   ' /CCD exposure mode
DATAMODE= 'FAINT   ' /CCD telemetry mode
DANAM1  = 'EQPOS_NOM' /Nominal Pointing
DEDIM1  =                   2 /EQPOS is 2D
1DCPT1  = 'RA_NOM  ' /EQPOS[1] = RA_NOM
1DCPT2  = 'DEC_NOM ' /EQPOS[2] = DEC_NOM
DAUNI1  = 'deg     ' /Unit of DANAM1
RA_NOM  =                   0 /Nominal RA in degrees
DEC_NOM =                   0 /Nominal Dec in degrees
ROLL_NOM=                   0 /Nominal Roll in degrees
RADECSYS= 'FK5     ' /WCS system
EQUINOX =                2000
DATE-OBS= '02/07/1997' /Date of observation start (GMT)
TIME-OBS= '23:40:19' /Time of observation start (GMT)
DATE-END= '02/07/1997' /Date of observation end (GMT)
TIME-END= '23:40:49' /Time of observation end (GMT)
MJD-OBS =             50632.5 /MJD of observation start
ONTIME  =             30.0003 /Ontime in seconds
DANAM2  = 'EXPOSURE' /Exposure time
DAUNI2  = 's       ' /Unit of DANAM2
EXPOSURE=             30.0003 /Livetime in seconds
DTCOR   =                   1 /Dead time correction factor
HDUCLASS= 'OGIP    ' /Convention for HDUCLAS
HDUCLAS1= 'EVENTS  ' /This is an events file
ORIGIN  = 'SAO     ' /Organization where data processed
COMMENT
COMMENT  Spacecraft configuration
COMMENT
DANAM3  = 'FC      ' /Focal coords
DAUNI3  = 'mm      ' /Unit of DANAM3
DEDIM3  =                   3 /Dimensionality of DANAM3
1DCPT3  = 'FC_X    ' /Component 1 of DANAM3
2DCPT3  = 'FC_Y    ' /Component 2 of DANAM3
3DCPT3  = 'FC_Z    ' /Component 3 of DANAM3

FC_X    =                   0 /Focus
FC_Y    =                   0 /Aimpoint Y shift
FC_Z    =                   0 /Aimpoint Z shift
FOCLEN  =             10258.3 /Nominal focal length, mm
COMMENT
COMMENT  HEASARC timing keywords
COMMENT
MJDREF  =             49353.5 /MJD of clock start
TSTART  =         1.10504e+08 /Observation start time, seconds
TSTOP   =         1.10504e+08 /Observation stop time, seconds
TELAPSE =             30.0003 /Elapsed time, seconds
TIMEUNIT= 's       ' /HEASARC: time unit
TIMESYS = '1994.0  ' /HEASARC: time system
TIMEDEL =                 0.2 /Smallest meaningful time increment, s
TIMEREF = 'LOCAL   ' /Time is local for data
TIMVERSN= 'OGIP/93-003a' /OGIP time convention
TASSIGN = 'SATELLITE' /Source of time assignment
COMMENT  HEASARC PHA keywords for back compatibility
CHANMIN =                   0 /Minimum PHA value
CHANMAX =                4096 /Maximum PHA value
CHANTYPE= 'PHA     ' /PHA type
COMMENT  MARX VERSION: 1.21 # Jun 28 1997 12:01:02

B.4 Parameter File Extension Header

XTENSION= 'BINTABLE' /FITS BINARY TABLE
BITPIX  =                   8 /Binary data
NAXIS   =                   2 /Table is a matrix
NAXIS1  =                 105 /Width of table in bytes
NAXIS2  =                 296 /Number of entries in table
PCOUNT  =                   0 /Random parameter count
GCOUNT  =                   1 /Group count
TFIELDS =                   1 /Number of fields in each row
TFORM1  = '105A    ' /Data type for field
TTYPE1  = 'MARXPAR_LINE' /Label for field
EXTNAME = 'MARX_PAR' /Table name

Appendix C

Acronyms

ACIS  AXAF CCD Imaging Spectrometer
ACIS-I  ACIS Imaging array
ACIS-S  ACIS Spectroscopic array
CCD  Charge Coupled Device
CSIM  C-Simulator
ETE  End-To-End
FITS  Flexible Image Transport System
HEG  High Energy Grating
HETG  High Energy Transmission Grating
HRMA  High Resolution Mirror Assembly
HRC  High Resolution Camera
HRC-S  HRC Spectroscopic array
IRAF  Image Reduction and Analysis Facility
LEG  Low Energy Grating
LETG  Low Energy Transmission Grating
MARX  Model of AXAF Response to X-rays
MEG  Medium Energy Grating
SAO  Smithsonian Astrophysical Observatory
WIRM  What It Really Means
XRCF  X-Ray Calibration Facility