back to V3D page 15 February 2007.

MARX - S-Lang - User Model with v3d routines

This page describes software that allows users of the MARX Chandra observation simulator to conveniently create, in S-Lang, user-defined source models. The specific example here allows the use of v3d geometric routines to define the source geometry and velocity properties which are then used with a spectrum file to define the incident photons spatial and spectral properties.

The simple example here uses a single rest-frame emission spectrum. Sources which have components with different rest-frame spectra can be simulated on a per-compnent basis and then combined with marxcat to create a complete observation. For example, the gas in a cluster of galaxies might be descried as a set of radial shells of different spectral properties and a supernova remnant may be the sum of shocked-ISM and shocked-ejecta components. A gallery of specific astrophysical examples will be added in future.


The MARX simulator (run at the command line) is controlled by the values in the file marx.par, defining the simulation. The MARX parameters allow a few choices of very basic source geometry (e.g, POINT, ..., DISK) and, in addition, a very flexible source interface: USER. The USER source dynamically links to user-provided subroutines written in C (the routines user_open_source and user_create_ray in particular.)

While the ability to make custom C-coded source models is useful, it does come with the extra complexity that C involves. Many scientists are "fluent" in the less demanding (more efficient) "scriptable" languages such as IDL, MatLab, Python, and (ta-dah) S-Lang. Hence a piece of C-code that would act as an interface between MARX (via the USER model) and one of these scripting languages would provide easier user customization.

To this end, John Davis has written a USER model in C which takes as arguments the name of an S-Lang script file and any additional arguments which the S-Lang routines wish to use. The compiled MARX S-Lang User source file ( lets users write source models in S-Lang and take advantage of the range of packages available in/through S-Lang.

The diagram here shows a general schematic of the components of the MARX S-Lang User implementation:

An Example - It's Easy! (mostly...)

A step-by-step walk-through of a simple demonstration example is given in detail in the file:

which makes use of these files:

Anatomy of the Example

The following notes give a quick walk through of the essential elements of the example...

One of the key ingredients in the example is telling MARX to use the S-Lang User interface source by setting the parameters:

  pset marx.par SourceType="USER"
  pset marx.par UserSourceFile="./"

The desired S-Lang-defined source is then specified along with any arguments by the parameter:

 pset marx.par UserSourceArgs=" e0102_simple_shock_Bspec.dat"
Here the ASCII text file contains the S-Lang code to define the model and generate Monte Carlo rays; it also takes a standard MARX spectrum filename as an argument, e0102_simple_shock_Bspec.dat in this case.

Looking inside of the demonstration S-Lang file,, most of the lines and routines are general "boiler plate" that can be retained for different user models. Note the use of "import" and "evalfile" functions to gain access to packages that are used:

% v3d routines use gsl for random function and interpolation

% Load the v3d routines...
The main lines of interest, which describe the source geometry and which can be edited for other geometries, are indicated in the file (see the "USER CUSTOMIZATION section") and are shown here without the comment lines:

   v3darray = v3d_sphere(12.0,18.0) + 2.0*v3d_cube(6.0,[0.,30.0,30.]) +
     v3d_cube(9.0,[50.,0.0,-30.] );

the source is the sum of three v3d geometric components. The components are defined in a 3D cube with "radius" of 60 arc seconds and with a spatial resolution of 37 cells per radius ((2*37+1)^3 cells in all.) The first component is a spherical shell having inner radius 12" and outer radius 18". The other two are (non-physical) cubes of "radii" 6" and 9" and offset from the origin by the [X, Y, Z] values given. Note that +X is to the West, +Y is North, and +Z is towards the observer.

The velocity field for this source model is given a few lines further by the parameters:

   Vtype = 1;                   % v is proportional to r
   Vsyst_xyz = [0.,0.,-300.];   % 300 km/s redshift for the system
   Vvalue = 5000.0/30.0;        % 5000 km/s at a distance of 30.
   Vcenter_xyz = [0.,0.,0.];    % velocity center is at origin
where Vtype=1 gives a velocity proportional to radius (e.g., a "Hubble" or "homologous" expansion) the magnitude of which is given by Vvalue in km/s per arc second. A systematic velocity of v_Z = -300 km/s is also specified.

An image and closeups of the simulated observation including the zeroth-order (white images) and the dispersed orders (blue, green, red) are shown here created using evt2img. Because the smaller cube to the North is moving toward the observer (it is located at Z = +30) its dispersed image is blueshifted, i.e., it is shifted further inboard with respect to the spherical shell. In the minus-side dispersed images to the south (closeup in middle panel) this causes the small cube to get further from the spherical shell as the images are dispersed further from zeroth-order. In the North, plus-side dispersed images (closeup at right) this same inboard shift causes the cube to move toward the spherical shell and become less visible as the images overlap.

Modeling this kind of spatial-spectral effect is a new capability that this software provides.

Looking at the model geometry in 3D

The same v3d commands that defined the geometry in the MARX simulation above can be used to create a rotatable 3D view of the source by making use of the v3d_view command which uses volview and slgtk:

hydra>  v3d_setup(60.0,37);
hydra>  v3darray = v3d_sphere(12.0,18.0) + 2.0*v3d_cube(6.0,[0.,30.0,30.]) +
           v3d_cube(9.0,[50.,0.0,-30.] );                                  
hydra> v3d_view(v3darray);      
Here are two snapshots of the geometry at different viewing angles:

Front view.
Left is East,
Up is North.

Side view.
Left is toward-observer,
Up is North.

Please send comments etc. to