PIMMS Users' Guide

K. Mukai

Introduction

PIMMS (Portable, Interactive, Multi-Mission Simulator) is intended as a versatile simulation tool for X-ray astronomers.

PIMMS Terminology

PIMMS uses one command GO for actual execution, while other commands are mostly used for setting up various parameters. This approach allows users to repeat similar calculations using a slightly different parameter.

PIMMS uses the following terms:

Product: what PIMMS is supposed to create. This can be
- Count rate; or
- Image: no spectral or temporal information.
Other PRODUCTs will be added in future versions of PIMMS.
Model: spectral model to be used. PIMMS contains a small set of simple spectral models, and others can be imported.
Instrument: in addition to the instrument for which simulation is to be done, you can specify both input and output instruments for count rate calculations. The former is used for calculating normalization of the model; rather than asking for flux in cgs unit, PIMMS can ask for flux in, e.g., Einstein IPC count rate.

Simulating spectra

PIMMS does contain a few simple spectral models. However, spectral simulation is not a strength of PIMMS -- it does not output spectra as such, and even though modifications can be made to do this, it is unlikely that PIMMS can keep up with the multitude of models that are used for various X-ray emitting objects. We recommend the use of XSPEC for spectral simulation.

Sample Sessions

Example 1. Estimating ASCA count rates

*** PIMMS Version 1.0b (first release) ***
    Reading mission directory, please wait
* PIMMS simulation product is COUNT
        count rates for various instruments or intrinsic fluxes can be estimated
   <--- Use 'PRODUCT' to simulate images
* Current spectral model is BREMSSTRAHLUNG, kT=  10.0000 keV; NH =  1.000E+21
   <--- Use 'MODEL' command to change
* By default, input rate is taken to be
 Flux (  2.000- 10.000 keV) in ergs/cm/cm/s
   <--- Use 'FROM' command to change the default
* Simulation product will be
 Count rate in ASCA SIS
   <--- Use 'INSTRUMENT' command to switch to another instrument
PIMMS > go 1.2 einstein ipc
* For thermal Bremsstrahlung model with kT= 10.0000 keV; NH =  1.000E+21
  and  1.200E+00 cps in EINSTEIN IPC
  (Model normalization =  7.059E-03)
* PIMMS predicts  1.956E+00 cps with ASCA SIS
* An exposure of      12.78s is required for a 5-sigma detection

              Percent Telemtry Full
                 Faint Mode        Bright Mode   Fast Mode
               4CCD  2CCD  1CCD  4CCD  2CCD  1CCD  1CCD
Bit Rate High   12     6     3     3     2     1     0
Bit Rate Med.   98    49    24    24    12     6     3
Bit Rate Low    **    **    98    98    49    24    12
* Recommended mode (assuming a point source)
  is Bright (4-CCD) mode
  Medium bit rate is sufficient for your observation
PIMMS > quit

In this example, the default spectral model is used to estimate ASCA SIS count rate (which is the default). The only place where user did not use the default set-up was to specify conversion from Einstein IPC count rate.

Example 2. Estimating ASCA count rates II

*** PIMMS Version 1.0b (first release) ***
    Reading mission directory, please wait
* PIMMS simulation product is COUNT
        count rates for various instruments or intrinsic fluxes can be estimated
   <--- Use 'PRODUCT' to simulate images
* Current spectral model is BREMSSTRAHLUNG, kT=  10.0000 keV; NH =  1.000E+21
   <--- Use 'MODEL' command to change
* By default, input rate is taken to be
 Flux (  2.000- 10.000 keV) in ergs/cm/cm/s
   <--- Use 'FROM' command to change the default
* Simulation product will be
 Count rate in ASCA SIS
   <--- Use 'INSTRUMENT' command to switch to another instrument
PIMMS > from exosat me
PIMMS > model rs 1.0 5e19
PIMMS > go 1.0
* For Raymond Smith model with kT=  1.0000 keV; NH =  5.000E+19
  and  1.000E+00 cps in EXOSAT ME
  (Model normalization =  3.535E-02)
* PIMMS predicts  3.072E+00 cps with ASCA SIS
* An exposure of       8.14s is required for a 5-sigma detection

              Percent Telemtry Full
                 Faint Mode        Bright Mode   Fast Mode
               4CCD  2CCD  1CCD  4CCD  2CCD  1CCD  1CCD
Bit Rate High   19    10     5     5     2     1     1
Bit Rate Med.   **    77    38    38    19    10     5
Bit Rate Low    **    **    **    **    77    38    19
* Recommended mode (assuming a point source)
  is Bright (4-CCD) mode
  Medium bit rate is sufficient for your observation
PIMMS > model rs 1.0 1e20
PIMMS > go 1.0
* For Raymond Smith model with kT=  1.0000 keV; NH =  1.000E+20
  and  1.000E+00 cps in EXOSAT ME
  (Model normalization =  3.543E-02)
* PIMMS predicts  3.042E+00 cps with ASCA SIS
* An exposure of       8.22s is required for a 5-sigma detection

              Percent Telemtry Full
                 Faint Mode        Bright Mode   Fast Mode
               4CCD  2CCD  1CCD  4CCD  2CCD  1CCD  1CCD
Bit Rate High   19    10     5     5     2     1     1
Bit Rate Med.   **    76    38    38    19    10     5
Bit Rate Low    **    **    **    **    76    38    19
* Recommended mode (assuming a point source)
  is Bright (4-CCD) mode
  Medium bit rate is sufficient for your observation
PIMMS > inst asca gis
PIMMS > go 1.0
* For Raymond Smith model with kT=  1.0000 keV; NH =  1.000E+20
  and  1.000E+00 cps in EXOSAT ME
  (Model normalization =  3.543E-02)
* PIMMS predicts  1.686E+00 cps with ASCA GIS
PH mode can be used at low bit rate
  (56% of telemtry will be used with this)
PIMMS > quit

In this example, 1.0 keV Raymond-Smith model was used, with two different values of interstellar absorption. After estimating ASCA SIS count rate, the user switched to ASCA GIS count rate. Conversion was from EXOSAT ME count rate, and as this was repeated, the ``FROM'' command was used to change the default rather than explicitly specifying within the ``GO'' command.

Example 3. Simulating a simple ASCA SIS image

*** PIMMS Version 1.0b (first release) ***
    Reading mission directory, please wait
* PIMMS simulation product is COUNT
        count rates for various instruments or intrinsic fluxes can be estimated
   <--- Use 'PRODUCT' to simulate images
* Current spectral model is BREMSSTRAHLUNG, kT=  10.0000 keV; NH =  1.000E+21
   <--- Use 'MODEL' command to change
* By default, input rate is taken to be
 Flux (  2.000- 10.000 keV) in ergs/cm/cm/s
   <--- Use 'FROM' command to change the default
* Simulation product will be
 Count rate in ASCA SIS
   <--- Use 'INSTRUMENT' command to switch to another instrument
PIMMS > prod image
* Image is  849 by  859 pixels.
* 1 pixel =   1.590 arcsec.
PIMMS > point 200 300 1.0
PIMMS > point 500 876.5 0.5
PIMMS > go 40000 test.fits
@ Initializing image array
@ Now adding particle background
@ Now working on the background sources
@ Now doing point source(s)
@ Now writing out to file
Simulation successful
PIMMS > quit

This example shows how to create a simulated image file, in this case with two point sources. Point source positions are specified with the ``POINT'' command (in pixels, the ranges 1-849 for X and 1-859 for Y are in the field of view), as well as count rates. The command line parameters for the ``GO'' command indicates that the integration time is 40,000 sec and the result was saved in ``test.fits'', which is a FITS file with the simulated image as the primary array. This file can be read by SAOimage and other image display programs.

Comments on extended sources

PIMMS is written primarily for point sources. To simulate the count rate for an extended source, estimate the total counts/flux within the field of view of the target instrument and use that as the input to the ``GO'' command.

Missions

PIMMS reads the list of missions from a file called ``pms_mssn.lst'' in the data directory. It then looks, for each mission (i.e., satellite), detector and filter combination, the appropriate calibration files for the effective area, values used for image simulation etc. Since this is a run-time process, the following items may not exactly correspond to what you see. For a listing of what is currently available, use the DIRECTORY command.

ASCA

ASCA is the latest Japanese X-ray satellite launched on Feb 20th, 1993, for which US-led collaborations supplied the X-ray mirrors and the CCD detector. It has 4 co-aligned telescopes, each having an effective area of $\sim$ 250 cm² at 1 keV; there are two GIS (imaging gas scintillation proportional counters) and two SIS (Solid-state Imaging Spectrometer, X-ray CCDs) detectors.

BBXRT

BBXRT is flown on the Shuttle with the ASTRO payload in December 1990. The effective area curve is that for pixel A0.

EINSTEIN

Currently PIMMS only have IPC and MPC effective area curves.

EUVE

PIMMS currently has the effective area curves for the three channels of the spectrometer, which is used by GOs for pointed observations. Detectors are SW (70-190Å), MW (140-480Å) and LW (280-750Å)

EXOSAT

For the Low Energy telescopes, only the LE1/CMA effective area data are kept within PIMMS. Specify filter OPEN, LX3, LX4, ALP, or BRN. The ME effective area is for a half-array; GSPC area is also available.

ROSAT

For the German XRT, effective area curve with PSPC (filter OPEN or BRN) and HRI are available. For the British WFC, filters S1, S2, P1 and P2 effective area curves are available; these are appropriate for the time of launch. Note the S1 and S2 sensitivity dropped to $\sim$ 75% of initial value by the end of the survey, followed by a steeper decline to 15-20% of the original value after The Tumble. Non-survey (P1 and P2) filters have suffered much smaller degradation.

Flux

PIMMS can also calculate conversion to/from flux values not folded through any instrument responses can also be used. To use flux, the unit must be specified: ``ERGS'' for ergscm^-2s^-1, ``PHOTONS'' for photonscm^-2s^-1, ``MCRAB'' for milli Crab, ``MJANSKY'' for micro Jansky. Also necessary is the energy range of interest, to be specified in the form ``2.5-10'' (for 2.5 to 10 keV). Optional keyword ``UNABSORBED'' following the range will make PIMMS calculate flux with Nh set to 0.0; this is useful in relating the flux to the total bolometric luminosity of the X-ray source before interstellar absorption.

User interface

Command interpreter

Commands can be abbreviated (as long as it is unique), numerical and character string parameters can be passed onto the commands. Parameters are interpreted according to their positions within the command line (first string is input file name, second file name is output file name etc., although this does not happen in PIMMS). Some parameters are compulsory -- PIMMS will prompt you for them if they are not given on the command line; others are optional (default values will be used unless the user specifies them on the command line). Commands can be stringed together by using a semicolon.

Note that future versions of PIMMS may use a different interface.

On-line help

PIMMS contains a VMS-style help facility, within which information is stored in a hierarchical structure. On the top level, there are two types of topics. Those listed in ALL CAPITAL LETTERS are PIMMS command names, containing the usage of these commands. Others are of more general nature, not linked with specific commands. HELP items are arranged in many levels, so that you start with a general introduction and pick up as many specific details as you like by going down several levels.

This help is case-insensitive (i.e., it accepts both lower-case and capital letters). If you type n characters, it will be matched against the first n characters of the topic names at that level. No wild card is allowed in specifying item names.

If the topic name string supplied by the user can be matched to (parts of) two more more topic names, then information on all the matching topics will be displayed.

Type ``?'' to repeat the current level.

Type <RETURN> as the topic name to go up one level.

To exit HELP, type the EOF character (Z on VAX/VMS, D on UNIX machines).

Spawn

Enter a dollar sign ``$'' followed by a command to be spawned. Note that some operating system may not pass aliases, environment variables, logicals etc.

Appendix A. PIMMS commands

PRODUCT

Command syntax: PRODUCT <type>
Minimum abbreviation: PR
Examples: ``PROD COUN'' ``PR I''

Specifies whether ``COUNT'' (count rates) or ``IMAGE'' (images) are to be produced.

MODEL

Command syntax: MODEL <name> <par> <nh>
or MODEL <filename> [<nh>]
or MODEL ?
Minimum abbreviation: M
Examples: ``MO PL 1.7 3e21'' ``MO mymodel.dat''

Model specifies the spectral shape to be folded with the effective area curve of the instrument. Currently three simple, one-parameter models are recognized with a fixed absorption model (due to Morrison & McCammon). In particular, it does not allow for the possibility of partial absorption, interstellar plus intrinsic (potentially warm and/or red-shifted) absorption etc. N_H, the equivalent neutral hydrogen column density, is to be specified in full with the appropriate exponent (e.g., 2.5E21); however, Nh values smaller than 30.0 will be interpreted as log10(N_H). If the string parameter does not match the names of the models, PIMMS interprets it as a file name.

MODEL -- ?

MODEL command with a question mark (or no parameters) will return a short listing of available models.

MODEL -- Blackbody

Can be abbreviated to ``BL..'' or ``BB''. Parameter is temperature in keV.

MODEL -- Bremsstrahlung

Can be abbreviated to ``BR..'' or ``TB'' (short for Thermal Bremsstrahlung); the model include the Gaunt factor. Parameter is temperature in keV.

MODEL -- Power Law

Can be abbreviated to ``P..'' or ``PL''. Parameter is photon index (flux in photonscm^-2s^-1 is E ^-(index). Currently, entering a negative number as the index will PIMMS calculating E ^{(value-as-entered)}, one whereby flux increases with increasing energy will never be calculated by PIMMS.

Optionally, cut-off power law can be used, in which case the second numeric parameter should be the cutoff energy in keV (N_H becomes the third).

MODEL -- Raymond & Smith

Can be abbreviated to ``R..'' or ``RS''. At the moment, PIMMS cannot compute an arbitrary RS model but merely uses one of 12 pre-calculated models, for log T of 6.0, 6.2, 6.4, 6.6, 6.8, 7.0, 7.2., 7.4, 7.6, 7.9, 8.2 an 8.5. Plasma temperature can be specified either as logt (in which case type, e.g., ``model rs logt 6.6 3e19'') or as keV (``model rs 2.5 1e20''). Solar abundance is assumed.

MODEL -- External Models

Other, perhaps more complex, models can be imported in the form of an Ascii file containing energy (keV) vs. flux (photonscm^-2s^-1keV^-1pairs. N_Hcorrection is optional (i.e., interstellar absorption can be included when producing the file or done within PIMMS). If the full directory/file name is not specified, user's current default directory is assumed first, and if not the models directory is searched.

MODEL -- Models directory

Some external models (see help item under that name) may be kept under the MODELS subdirectory. If the file names and a short description is also included in the MODEL.IDX file, then PIMMS users will be able to see what is availabe. Currently, a series of 0.25 Solar abundance Raymond-Smith models are available from MODELS directory.

MODEL -- Importing from XSPEC

To import a model from XSPEC, start XSPEC and read, e.g., a template ASCA SIS pha file (which specifies the SIS response matrix which specifies the PHA channel boundary etc.). Create your model. Then use IPLOT MODEL command to plot the model, then from within plot use the WD <filename>command to output the model into an Ascii file. The program XSING within the MODELS directory should be used to convert the XSPEC output into a form readable by PIMMS.

FROM

Command syntax: FROM <mission> [<det> [<filt>]] [<lo>-<hi>]
FROM FLUX <unit> <lo>-<hi> [UNABSORBED]
Minimum abbreviation: F
Examples: ``FROM EINSTEIN IPC'' ```FROM FLUX PHOTONS 0.5-10''

This command specifies the default ``instrument'' that the conversion is to take place from. This default will be used in GO (in count rate simulation mode) or POINT (in image simulation mode) command if not explicitly specified. See Missions for details of the available instruments, or try DIRECTORY. Initially the default is 2.0-10.0 flux in ergscm^-2s^-1.

INSTRUMENT

Command syntax: INSTRUMENT <mssn> [<det> [<filt>]] [<lo>-<hi>]
or INSTRUMENT FLUX <unit> <lo>-<hi> [UNABSORBED]
Minimum abbreviation: I
Examples: ``INST EXOSAT LE LX3'' ``INST FLUX ERGS 1-10 U''

This command specifies the ``instrument'' that the conversion is to take place to. See Missions for details of the available instruments, or try DIRECTORY. Initially default is ASCA SIS.

POINT

Command syntax: POINT <x_pos> <y_pos> <rate> or POINT CLEAR
Minimum abbreviation: PO
Example: POINT 400 325.2 0.5

This command is operative only in image simulation mode, and specifies either a point source to be added or remove all point sources. Position must be specified in pixels and count rate must be pre-calculated for the particular instrument (right now, ASCA SIS only). Successive calls enable user to put multiple sources in the simulated image, up to a limit of 32.

GO

Minimum abbreviation: G

This command actually tells PIMMS to execute the simulation.

GO -- Count rate mode

Command syntax: GO <input_rate> [<mission> [<det> [<filt>]]] [<lo>-<hi>]
or GO <input_rate> [FLUX <unit> <lo>-<hi> [UNABSORBED]]
Examples: ``G 1.0'' ``GO 3.4 EINSTEIN IPC''

Given a source spectrum in the form specified with MODEL, which produces an input rate (count rate in the specified instruments or flux) of <input_rate>it GO predicts what the rate would be for the instrument specified with the INSTRUMENT command. Unit of input rate can be specified here, or else the default is used (see FROM).

GO -- Image mode

Command syntax: GO <exposure> <filename>
Example: ``GO 20000 myfile.fits''

Given the background level, point source locations and fluxes specified with POINT command, this simulates an image and stores it in the primary array of the FITS file whose name is specified.

SHOW

Command syntax: SHOW
Minimum abbreviation: SH

Presents a summary of the current defaults on the screen.

About this document ...

This document was generated using the LaTeX2HTML translator Version 98.1p1 release (March 2nd, 1998)

The command line arguments were:
latex2html -t PIMMS Manual -split 1 pimms.tex.

The translation was initiated by Michael Arida on 1999-01-29

Michael Arida
1999-01-29