PIMMS commands

MODEL
ABSORPTION
PLASMA
FROM
INSTRUMENT
GO
OUTPUT
SHOW
DIRECTORY
LOG

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. Starting with version 3.0, up to 8 model components can be added together to represent multi-temperature plasma, power law plus Gaussian emission line, partial-covering absorber etc. Only a limited combinations of models have been rigorously tested; users of complicated models are urged to check the composite model by using the OUTPUT command. See the Using Multi-component Models section for more details.

As components, PIMMS recognizes BLACKBODY, POWERLAW, BREMSSTRAHLUNG, GAUSSIAN and PLASMA. If the model name string does not match these, PIMMS will try to interpret the string as a file name containing a precalculated model containing energy, photon flux pairs. N_H, the equivalent neutral hydrogen column density (using Morrison & McCammon model) is expected for each component, except for GAUSSIAN and external files. N_H should be specified in full with an appropriate exponent (e.g., 2.5e21), or as a small non-zero number less than 30.0, to be intepreted as log10(N_H).

Model normalization for the built-in models do not necessarily correspond to physical quantities. Instead, PIMMS is designed to allow users to compare 2 observable quantities (count rates through specific instruments, or fluxes in specific energy bands) without having to know the model normalization.

Optionally, all components may be redshifted using a common z (in which case, all component N_H are interpreted as intrinsic absorber, with the same z) with an optional Galactic N_H.

Syntax

The Model commands takes 1--8 blocks of component specification, and a final optional block of redshift specification. Each block starts with a valid name of a component (including a valid file name), followed by a set of numerical parameters. As a special case, the plasma model takes an optional string (logt or kev, the latter being the default) specifying the unit of temperature, immediately after the numerical parameter for the temperature. For 2nd through 8th component blocks, additional parameter(s) specifying the ratio of that component to component 1, and the reference energy at which this is to be evaluated, must also be given (NB the reference energy for Gaussian is always its central energy). See the Using Multi-component Models section for more details.

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 photons/cm/cm/s is E^[-(index)]. Unlike in previous versions, a power-law photon spectrum that increases with increasing energy can be specified by entering a negative number as the index, starting from PIMMS v2.5.

A power law with high energy cutoff E^(-index) exp[(Ecut-E)/Eefold] can be specified by typing "model pl 1.5 13.5 20.0 1e22" for example; this will result in an index of 1.5, cut-off energy of 13.5 and e-folding energy of 20 keV, with an Nh of 1e22.

MODEL - Plasma

Can be abbreviated to "PLA..." PIMMS relies on grids of pre-calculated files, using the APEC (default), mekal, and Raymond-Smith codes. PIMMS v4.0 is distributed with APEC and Raymond-Smith models at 59 temperature (logT of 5.60 to 8.50 in an increment of 0.05) times 5 abundance (0.2 to 1.0 in an increment of 0.2), while mekal has a narrower temperature range starting with logT of 6.0 (51 tempertures to logT=8.50). The syntax is "model plasma " (e.g., "model plasma 3.5 0.8 3e20"). The temperature can be specified in logT by adding the word logt after the first numerical parameter, which is then taken to be logT. Starting in V4.7, APEC model files calculated using ATOMDB version 2.0.2 in XSPEC version 12.8.1g on 2013 Dec 9-11, assuming the solar abundances due to Asplund M et al. 2009, ARAA, 47, 481, are included. Between V4.0 and V4.6b, APEC files generated using ATOMDB 1.3.1 assuming Anders & Grevesse were included. Current mekal model files also assume Anders & Grevesse solar abundances, while the solar standard for the Raymond-Smith grid has become unclear due to passage of time. PIMMS will select the nearest temperature and abundance that is supported by the grid in use.

At start-up, the plasma model in use is APEC. The alternatives can be selected by issuing the PLASMA command.

MODEL - Gaussian

Can be abbreviated to "G". This model takes the central energy and physical width (in keV) as parameters, and optionally also N_H. A physical width of 0 is allowed, which is interpreted as a delta function (integrations of delta function is treated appropriately, although it may look incorrect in the differential form, which is what is saved by the OUTPUT command).

Gaussian is primarily intended as second (etc.) component in addition to a continuum model, with the same N_H as the primary component. In such cases, specify the equivalent width in eV rather than the "relative strength".

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/cm/s/keV) pairs. Nh 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, 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 available.

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

ABSORPTION

Command syntax: ABSORPTION morrison-mccammon/mm/tubingen/tb
Minimum abbreviation: A
Example: ABSORPTION MM

This command specifies the X-ray absorption model to use. The default, chosen at start-up, is Tubingen (or TB), which is an approximation of the tbabs model in xspec with the "wilm"abundances. This is meant to replace the old model which approximated Morrison-McCammon (MM). The two differ in terms of both cross sections and abundances, and can result in differences in PIMMS estimates of about 10%.

The ABSORPTION command is primarily intended to facilitate testing; in normal usage, the default (the Tubingen model) should be used.

PLASMA

Command syntax: PLASMA apec/mekal/rs
Minimum abbreviation: P
Example: PLASMA MEKAL

This command specifies the grid to use when the plasma model is specified. The default, chosen at start-up, is APEC. If a plasma model is currently in use (including as a component of a compound model), the grid is switched on the fly if at all possible. If none is being use, this command serves as a preliminary step for the next MODEL command that does include a plasma component.

FROM

Command syntax: FROM <mission> [<det> [<filt>]] [<lo>-<hi>]
             or FROM FLUX <unit> <lo>-hi> [UNABSORBED]
             or FROM NORMALIZATION
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 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/cm/s.

INSTRUMENT

Command syntax: INSTRUMENT <mission> [<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.

GO

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

This command actually tells PIMMS to execute the simulation.

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

OUTPUT

Command syntax: OUTPUT <filename> <loE> <hiE> <deltaE>'
Example: "OUT compoite 0.1 10.0 0.005"

This command produces an Ascii file containing the current spectral model, and is intended primarily as a debugging tool for complicated multi-component models. Each row consists of energy, total model flux, and flux of each component if there are more than one. The energy grid should be specified using the minimum and maximum values and the increment.

PIMMS currently forces output file names to be all lowercase.

SHOW

Command syntax: SHOW
Minimum abbreviation: SH

Presents a summary of the current defaults on the screen.

LOG

Command syntax: LOG <log-file-name> or LOG close
Minimum abbreviation: L
Example: "LOG crab"

When this command is issued, PIMMS opens a log file (default extension .log). Thereafter, screen outputs from PIMMS (except for questions/prompts) will be copied to the log file. LOG CLOSE will close the current log file; the purpose of this command would be to send further output to a separate log file. This command will indicate error if (1) a log file is already open; (2) (on UNIX systems) the specified file already exists; (3) (on VMS systems) when the specified "log file name" is also a DCL Logical; and (4) PIMMS failed to open the file for the usual reasons, including a lack of disk space and file system protection.