back to V3D page 16 May 2007,
6 June 2007.

isis-3D: Using v3d routines in a custom isis model


For slitless dispersive spectrometers like Chandra's HETG or XMM-Newton's RGS, the dispersed spectrum from an extended (resolved) source will show "line shapes" that depend on both the spatial and spectral properties of the source.

The versatility of the ISIS model definition allows the user to create custom spectral models for use in the arf-rmf-pha spectral analysis paradigm. Here, a simple spatial-spectral line-shape model is created using the S-Lang-written "v3d" (3D volumetric) routines to model the emitting volume and its velocity (Doppler) properties.

An Example Model

The demonstration model used here is fully defined in the file: see comments in this file for some further implementation details.

By ".load'ing" this file in isis, the user defines a new fit function in isis. For this example case, the geometry implemented is the intersection (product) of a sphere and a cylinder. The inner and outer radii of the sphere and cylinder as well as the cylinder's length are specified in units of arc seconds. The axis of the cylinder is specified by two angles: theta (longitude in the v3d coordinate system, 0 degrees is in the W direction, 90 degrees is in the Away direction) and phi (lattitude, 0 degrees is in the E-W Toward-Away plane, +90 degrees is in the N direction.)

The velocity property of the model can be specified as (0) constant v in the r^hat direction, (1) proportional-to-radius (Hubble-like expansion), (2) rigid-body rotation, about the cylinder axis, or (4) Keplerian rotation about the cylinder axis. A velocity value appropriate to the type, e.g., "km/s per arc second" for velocity type 1, is set as well.

Hers's a listing of the parameters for this model as seen by an isis user, the values are for the case of the "Fat Ring" example below:

isis> list_par;
 idx  param                   tie-to  freeze         value         min         max
  1  sphxcyl_line(1).norm         0     0            0.001           0     1000000  ph/cm^2/s
  2  sphxcyl_line(1).lam_center   0     0               12           0         150  A
  3  sphxcyl_line(1).vel_scale    0     1                0           0          20  factor
  4  sphxcyl_line(1).xyz_scale    0     1                1           0          20  factor
  5  sphxcyl_line(1).sph_rin      0     1                2           0        1000  arcsec
  6  sphxcyl_line(1).sph_rout     0     1                3           0        1000  arcsec
  7  sphxcyl_line(1).cyl_rin      0     1                0           0        1000  arcsec
  8  sphxcyl_line(1).cyl_rout     0     1              3.2           0        1000  arcsec
  9  sphxcyl_line(1).cyl_len      0     1              2.5           0        1000  arcsec
 10  sphxcyl_line(1).theta        0     1              225        -360         360  deg,W-to-Away
 11  sphxcyl_line(1).phi          0     1              -10         -90          90  deg,Equat-to-Npole
 12  sphxcyl_line(1).vel_type     0     1                1           0         3.5  0-r^; 1-r; 2-rot, 3-Kep
 13  sphxcyl_line(1).vel_val      0     1         833.3333           0      100000  v; v/r; v/r; v*sqrt(r)
Besides the parameters described above, there are 4 additional ones in this list: norm, lam_center, vel_scale, and xyz_scale. The two parameters norm and lam_center are as one would expect. The two scale parameters are very useful and require some explanation. These two parameters can be used to scale the velocity (vel_scale) and spatial (xyz_scale) properties of the defined geometry; these are implemented (along with norm and lam_center) without a need for a re-calculation of the geometry and Monte Carlo simulation. Thus, these first four parameters can be fit with reasonable speed.

Need for ROLL_NOM value(s)

The model also depends on the type of data set that it is being evaluated for; that is, if it is an MEG or HEG spectrum (the ``part'') or plus or minus order. These values are already available for the data sets that have been loaded into isis and the model evaluation takes this into account.

One parameter of the data that is not available from isis but is needed for this model evaluation is the roll angle at which the data were taken, specifically the ROLL_NOM value. The roll is needed to determine the dispersion direction in the model (sky) coordinates for the data set. Isis allows the user to add additional ``meta data'' to each data set. This can be done at the time of loading in the data with commands something like:

% Set the required meta data for hist index 1 :
variable data_meta = struct { roll };
data_meta.roll =  37.123;   % ROLL_NOM in degrees
set_dataset_metadata ( 1, data_meta);
Note that the default roll for this routine is 0.0 degrees which has the dispersion axes going roughly E-W.

Examples Using the sphxcyl_line model

Below are outputs from running demonstrations of the model. The images shown are made by the model when it calculates a new geometry (i.e., if a parameter other than the first four changes). The set of four line shapes at right is made by the routine:

which plots MEG minus and MEG plus line shapes (fluxes before the arf and rmf are applied) in the top row (l to r) and HEG minus and HEG plus in the bottom row. The individual curves shown are made from different combinations of spatial and velocity effects: These plots clearly demonstrate that: i) the higher-resolution HEG sees a spatial lineshape (red) that is 1/2 the wavelength-equivalent of the MEG; ii) the MEG and HEG see the same velocity lineshape (blue); iii) when spatial and velocity effects are combined the lineshape can be dramatically different for minus and plus orders.

For these examples, the roll is at 0 degrees so that the dispersion direction is roughly left-right (E-W) with the minus order to the left.

Fat Ring

Hubble-like expansion, v = const * r

Spherical Shell

Hubble-like expansion, v = const * r

Rotating Disk

Rigid-body rotation, |v| = const * |r_offaxis|

Keplerian Disk

Keplerian rotation, |v| = const/sqrt(|r_offaxis|)

Simple Cylinder

Hubble-like expansion, v = const * r

Anatomy of the Example

The example code above,, can be roughly diagrammed as:


  check the previous geom values, if changed:
    evaluate the geometric model
    generate MC points from model
    assign Doppler correction to each MC point
  instrument simulation based on observation parameters
    ( MC sky x,y,lambda  -->  events x,y,E )

  form desired model output (1D spectrum)
With this overview as a guide, the comments in the code should give insight into the details.

It is hoped that an adventerous user can modify this example and use the suite of v3d routines to define a routine implementing the geometry and parameters of their own choice.

Please send comments etc. to