NOTICE: This Legacy journal article was published in Volume 3, May 1993, and has not been updated since publication. Please use the search facility above to find regularly-updated information about this topic elsewhere on the HEASARC site.

PIMMS and Viewing: proposal preparation tools

We have created new software to help astronomers write ASCA proposals. This article summarizes the current capabilities and future plans of the two programs, as well as describing where they can be found.

1. Why PIMMS?

Technical feasibility is perhaps the second most important aspect of successful observing proposals after the scientific justification. In the most basic form, this may be reduced to: can we detect the source with x ksec of satellite y time? The real feasibility question, of course, may well be more complex, e.g., can we detect the Fe line in x ksec?

The old-fashioned way is by using hardcopy plots and tables of conversion factors, for a grid of model parameters, between intrinsic flux and expected count rate. While this is still something many astronomers would like to do first, it certainly is not an ideal way of achieving anything more than the back-of-the-envelope accuracy.

In an effort to help ease the pain, we have developed a simulation program, PIMMS (Portable, Interactive, Multi-Mission Simulator), initially tuned for ASCA but written in a general enough way as to be useful for other missions.

2. PIMMS Design Goals

The name PIMMS reflects three crucial design goal we have kept in mind:

(1) Portability -- The program must be portable enough that the majority (if not all) of astronomers can take a copy to their own home institution and run it there. At the same time, we support use of PIMMS via remote login to a central location. PIMMS is being developed in OGIP standard Fortran for this purpose. (For more information on the OGIP Fortran standard, see the article in this issue of Legacy.)

(2) Interactive design -- We anticipate that few users of PIMMS will be content to find one number at the end of a run. More likely, users will want to repeat nearly identical calculations for different parameter values (such as N_H). This is most readily accommodated in a command-driven approach, in which parameter values are preserved for successive calculations unless explicitly changed.

(3) Multi-Mission nature -- It is so often the case that one wants to predict the ASCA (for example) count rate of a source, given the known Einstein IPC (or some other experiment) count rate. Such conversion presents a problem to the users of many existing utilities, each of which typically deals with only one instrument (or at most one satellite): one has to run two separate programs, or trust somebody else's conversion to a physical flux unit. We are not suggesting fluxes in literature are unreliable, of course, merely that specific models are assumed in their derivation. One has to hunt down what these values were, and may have to use models that one does not quite agree with. By providing a single step conversion between various missions, PIMMS avoids this pitfall; it guarantees that exactly the same model was used for both instruments and asks only for the observed count rate. (PIMMS still provides flux to count rate conversion, for those of you more theoretically inclined.)

3. Current capabilities of PIMMS

The current release of PIMMS comes with the effective area (as a function of the energy) calibration for the instrument/filter combinations described in Table 1.

These are obviously representative values that are good for simulation purposes only (note in particular that ROSAT WFC effective area curve is that at the beginning of the survey, and subsequent loss of sensitivity is currently not taken into account within PIMMS). With this data in hand, PIMMS can perform flux conversion to and from count rate or count rate to count rate conversion, given a spectral model.

We have opted not to include complex spectral simulation within PIMMS; this would require a rather extensive effort, not only initially but also to keep up with the ever increasing set of theoretical models. We have limited PIMMS to 3 analytical models (blackbody, power law and Bremsstrahlung) and a limited grid of Raymond-Smith models, each with a simple cold absorber. More complex spectral model can be imported to PIMMS via an ASCII file that can be generated using XSPEC (see the Users' Guide for details) or by users' own programs.

The current version of PIMMS can also simulate simple ASCA SIS images (see Users' guide for details).

Table 1

Directory of Missions/Instruments


		Mission		Instrument	Filter


		ASCA		SIS
				GIS
		BBXRT		(A0 pixel)
		Einstein	IPC
				MPC
		EUVE		SW
				MW
				LW
		EXOSAT	LE	OPEN
						3 Lexan
						4 Lexan
						Al/P
						Boron
				ME
				GSPC
		ROSAT		HRI
				PSPC		Open
						Boron
				WFC		S1
						S2
						P1
						P2

4. ASCA-specific details in PIMMS

We have also included the following ASCA-specific details in PIMMS.

(1) Telemetry limits

Bright X-ray sources can easily overfill the telemetry, depending on the available bit rate and the instrument mode setting. Expert users of ASCA will want to specify the mode setting to optimize the scientific return while not saturating telemetry, although this can be left to the technical experts at the ASCA GOF. For this purpose, PIMMS will display, given the calculated count rate, what percentage of the telemetry will be used for source X-rays in various mode settings.

(2) Mode recommendation

PIMMS goes one step further, in fact, and makes a recommendation on what mode to use, assuming the target is a point source. This should help the user avoid settings that are clearly (under most circumstances at least) disadvantageous. We naturally cannot guarantee the absolute best settings for the science; that would require a detailed understanding of the science. Note, also, that our recommendations may change during the mission as we accumulate more experience taking and analyzing data in various modes.

(3) Detection limits

PIMMS also calculates, given a count rate, how long an observation is required for a 5-sigma detection.

5. Viewing

If you are planning a time-critical observation and need to know when ASCA (or any other satellite) can observe your target, then you might be interested in using Viewing. This stand-alone utility program calculates the sun angle constraint ( degrees in the case of ASCA) and outputs the visibility window (i.e., times of year when the satellite can point at the target). Viewing does not have any information on the up-to-date orbital elements of ASCA or any other satellite; it is therefore impossible to predict a detailed viewing pattern (Earth occultations, SAA passages etc.) or the efficiency of observation with this program. Some satellites may have additional constraints (e.g., thermal) that Viewing does not take into account.

In the case of ASCA, however, there are currently no factors that can make the observation of your target on a given date impossible, as long as the Sun angle constraint is satisfied. For other missions, consult respective mission description document.

Viewing users' guide is included as an appendix to this article.

6. How to use PIMMS and Viewing

PIMMS and Viewing are available as part of the HEASARC on-line service at NASA/GSFC. This allows these programs to be used via remote login. To use, telnet to ndadsa.gsfc.nasa.gov (TCP/IP) or set host to NDADSA (DECnet) and login as username XRAY (no password necessary). For further information on the HEASARC on-line service, refer to previous issues of Legacy or send an e-mail to request@ndadsa.gsfc.nasa.gov or NDADSA::REQUEST.

Alternatively, PIMMS and Viewing can be obtained via anonymous ftp from heasarc.gsfc.nasa.gov, under the directory asca/nra_info/pimms. This directory includes a README file and several compressed tar files. Help files and an up-to-date users' guide as well as the source code and data files are also provided via anonymous ftp.

7. Future plans

Current and future generations of X-ray satellites often produce data that consist of a list of photons with position, energy and time. We hope to be able to produce simulated photon file in OGIP standard rationalized FITS format in the near future. This will enable the simulated data to be analyzed almost as if they were real. (We have no plans to produce housekeeping or attitude files within PIMMS, however.)

We also hope to add more instruments, particularly for image simulation but also for count rate conversion. Suggestions for inclusion are sought from the community. (It will help if users could supply the necessary calibration.)

Bug reports, questions, enhancement requests, etc. should be addressed to the author.

PIMMS Users' Guide

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

1 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.
    

• 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, the user 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 units, PIMMS can accept flux in, e.g., Einstein IPC count rate.

2 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.

3 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 

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 

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 

4 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.

5 Missions

PIMMS reads the list of missions from a file called pms_mssn.lst in the data directory. For each mission (i.e., satellite), detector and filter combination, PIMMS looks for 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.

5.1 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 250 cm² at 1 keV; there are two GIS (imaging gas scintillation proportional counters) and two SIS (Solid-state Imaging Spectrometer, X-ray CCD) detectors.

5.2 BBXRT

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

5.3 Einstein

Currently only IPC and MPC effective area curves are available in PIMMS.

5.4 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Å).

5.5 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.

5.6 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 75% of the initial value by the end of the survey, followed by a steeper decline to 15-20% of the original value after The Tumble (February 1991). Non-survey (P1 and P2) filters have suffered much smaller degradation.

5.7 FLUX

PIMMS can also calculate conversion to/from flux values not folded through any instrument responses. To use flux, the unit must be specified: `ERGS' for ergs cm<sup>2</sup> sec<sup>-1</sup>, `PHOTONS' for photons cm² sec^-1, `MCRAB' for milliCrab, `MJANSKY' for microJansky. 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 N_H set to 0.0; this is useful in relating the flux to the total bolometric luminosity of the X-ray source before interstellar absorption.

6 User interface

6.1 Command interpreter

Commands can be abbreviated (as long as the abbreviation is unique) and 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 semicolon.

6.2 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 the user starts with a general introduction and pick up as many specific details as he or she likes 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 control-Z on VAX/VMS (control-D on UNIX machines).

6.3 Spawn

Enter a dollar sign `$' followed by a command to be spawned. Note that some operating systems 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 ? 

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 (from Morrison and 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, N_H 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 includes the Gaunt factor. Parameter is temperature in keV.

MODEL -- Power Law

Can be abbreviated to `PO' or `PL'. Parameter is photon index (flux in photons cm^-2 sec^-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.

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 7 pre-calculated models, for kT = 0.1, 0.2, 0.5, 1.0, 2.0, 5.0 or 10.0 keV N_H correction is applied properly). 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 (photons cm^-2 sec^-1 keV^-1) pairs. N_H correction 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, the user's current default directory is assumed first, and if not found there, 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 name and a short description are 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 the IPLOT MODEL command to plot the model. 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 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' from which the conversion is to take place. 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 ergs cm^-2 s^-1.

INSTRUMENT

Command syntax:  INSTRUMENT <mssn> [<det> [<filt>]] [<lo>-<hi>]
	or INSTRUMENT FLUX <unit> <lo>-<hi> [UNABSORBED]
Minimum abbreviation:  I

This command specifies the `instrument' to which the conversion is to take place. 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 the removal of all point sources. Position must be specified in pixels and count rate must be pre-calculated for the particular instrument (currently only ASCA SIS). 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>, GO predicts what the rate would be for the instrument specified with the INSTRUMENT command. Unit of input rate can be specified here, or 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 the 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.

DIRECTORY

Command syntax: DIRECTORY [<mission> [<detector>]]
Minimum abbreviation: D

Examples: `DIR', `DIRE EXOSAT'

This command displays to the screen the full list of missions that PIMMS recognizes. For explanations and comments, see `Missions' in this Users' Guide.

A Viewer's Guide to VIEWING

Introduction

Viewing is a stand-alone program that allows users to calculate
satellite viewing window, either in interactive or batch mode.

The following sample shows the most basic form in which viewing may be
used:

$ viewing *** VIEWING Version 1.01 run on 1993 Feb 22 ***
    for ASUKA, (allowed Sun angle range =  60.0-120.0)
    for the period 1993 Feb 22 to 1994 Feb 23
    input positions are taken to be for epoch 1950.0 
Enter RA (hh mm [ss.s] or dd.ddd) [<CR> to end] > 21 34 45.2
Enter Dec ([s]dd mm [ss.s] or [s]dd.ddd) > -43 55 46 
* Object #    1 at (21 34 45.2, -43 55 46) is:
  observable between 1993 Mar 27           and 1993 Jun 06
  observable between 1993 Sep 30           and 1993 Dec 08 
Enter RA (hh mm [ss.s] or dd.ddd) [<CR> to end] > 23 16 44 
Enter Dec ([s]dd mm [ss.s] or [s]dd.ddd) > 68 45 43 
* Object #    2 at (23 16 44.0, +68 45 43) is:
  always observable 
Enter RA (hh mm [ss.s] or dd.ddd) [<CR> to end] > 15 50 33.1
Enter Dec ([s]dd mm [ss.s] or [s]dd.ddd) > 19 5 18 
* Object #    3 at (15 50 33.1, +19 05 18) is:
  observable between 1993 Feb 22 or before and 1993 Mar 20
  observable between 1993 Jul 03           and 1993 Sep 23
  observable between 1994 Jan 01           and 1994 Feb 23 or later 
Enter RA (hh mm ss.s or dd.ddd) [<CR> to end] >

The above example includes 3 typical responses --- the object may be always observable or have 2 observing windows per year. If the object is initially (i.e., at the beginning of the period of interest) in an observing window, that is signified by the words ``or before'`; similarly for objects that ends in a viewing window. It is also possible to get the response ``never observable,'` if the allowed range and/or the period of interest is restrictive.

viewing help should return you some useful information; viewing -help and viewing ? should also work, if such special characters are not processed by the shell (or if the user cleverly provided shell-escape for the special characters). There are similar but undocumented aliases, which experienced users may be able to figure out from, e.g., the parameter file.

How to specify target positions

Viewing expects the celestial coordinates of the targets in one of the following two forms.

1. Using three numbers separated by space or comma; 12 34 56.7 will be interpreted as 12^h34^m56.^s7 for RA and +12deg.34'56."7 for Dec. Either three integers or two integers followed by a real number can be accepted. Negative Dec near the equator (e.g., -00 24 33.1) should be interpreted correctly (but it does not hurt to check).
2. Using two numbers separated by space or comma; similar interpretation will apply. Either two integers or one integer plus one real number can be used.
   
3. Using one real number to indicate decimal degrees: 320.55 would be a valid input for RA (range 0--360) and will be interpreted as 21^h22^m12^s.

Options

Options can be supplied on the command line in the form name=value, which are:

• mission=rosat to specify non-default mission. Or,
  
• range=70-110 to explicitly specify the Solar angle range.
  
• epoch=2000 to change the epoch.
  
• from=31-mar-93 to change the start date.
  
• for=2.5 to specify the duration (in year) for which calculation is to be done. Or
  
• to=31-dec-96 to specify the end date.
  
• input=file to read target information from a file rather the terminal.
  
• output=file to save the results in a specified file rather than outputting to the terminal.
  

Preparing an input file

When using an input file with viewing, each entry must consist of three lines: a target name, RA and Dec. RA and Dec can be in the same format as for interactive input. An input file can contain as many targets as is practical; these targets will be processed sequentially by viewing.

The following is a sample input file:

X1223-62 (=GX301-2) 
12 23 49.7 
-62 29 37 
Galactic Center 
265.68 
-28.93 
Cyg X-1 
19 56 28.87 
35 03 55.0 
1E2259+586 
22 59 03.4 
-3.394444 
PSR1534+12 
233.699 
12.096 
PSR1957+20 
299.3554 
20 39 59.5 
1E1740.7-2942 
17 42 42.7 
-29 42 46 

* Mission List File

Mission list file contains entries beta angle constraints of various satellites. The current version is included below:

`ASCA',60,120
`ASUKA',-60,120
`ASTROD',-60,120
`ROSAT',75,105
`EUVE',90,180
`EUVE1',130,180

Proceed to the next article

Return to the previous article

Select another article