Last modified: 26 Jan 2021


Retrieve ChaRT Rays

CIAO 4.16 Science Threads



After running ChaRT, users will be sent an email providing the URL on the saotrace web server where they can download a compressed tarfile containing the results of the simulation. This thread illustrates how to retrieve, unpack, and view the output data.

The inputs to ChaRT are shown below

ChaRT screen shot
Coordinate : Celestial : RA = 12:16:56.990
                         Dec = +37:43:35.69
Spectrum:  Spectrum file: source_flux_chart.dat
Pointing:                OBS_ID = 942
Number of Iterations:    5
Random Seed :           -1

Last Update: 26 Jan 2021 - Update URLs to https://


Email from ChaRT

Once the job has finished, ChaRT will send an email which looks similar to this:

    Your ChaRT simulations are available for retrieval	627840 bytes

    The ChaRT threads explain how to analyze ray files.    
        Be sure to use the same aspect solution file with MARX or psf_project_ray
        pset marx DitherModel=FILE DitherFile=pcadf075214790N004_asol1.fits.gz
        pset psf_project_ray asolfile=pcadf075214790N004_asol1.fits.gz

With the location of the tar file containing the simulated ray files.

Download the Ray File

The name of the tar file, HRMA_ra184.23746_dec37.72658_source_flux_chart.dat_dithered.tar.gz, contains the source location, the energy and flux, and whether the simulation was done with dither or a single pointing. Users that specified the PSF location using θ and ϕ will find that position converted to ra and dec in the file name. There are two simple ways to retrieve the file from the server:

  • Paste the URL from the email ( into your web browser and a "Save As..." box should be launched.

  • From the command line, it is possible to use wget (most users have this tool installed on the system):

    unix% wget

    The curl utility can be used in a similar fashion.

Unpack tar file

The tar file will contain all the requested ray files -- one for each iteration.

unix% tar xvfz HRMA_ra184.23746_dec37.72658_source_flux_chart.dat_dithered.tar.gz

Since 5 iterations were requested, ChaRT returned ray files *_i0000_rays.fits through *_i0004_rays.fits. The structure of each of the ray files is the same as discussed next.

Columns and Header Keywords

There are several columns in the output rayfile:

unix% dmlist HRMA_ra184.23746_dec37.72658_source_flux_chart.dat_dithered_i0000_rays.fits cols

Columns for Table Block PSFRAYS
ColNo  Name                 Unit        Type             Range
   1   rt_cosx              none         Real8          -0.99978097306784:   -0.97714062288839 Label for field
   2   rt_cosy              none         Real8          -0.13330543731274:    0.07480484359520 Label for field
   3   rt_cosz              none         Real8          -0.21235076134009:    0.07406585033612 Label for field
   4   rt_kev               KeV          Real8          0.50000013919069:        6.987921080 Label for field
   5   rt_x                 mm           Real8          -10079.770:   -10079.770 Label for field
   6   rt_y                 mm           Real8          -949.7786946446:      361.5744518592 Label for field
   7   rt_z                 mm           Real8          -1890.9460:      834.2014160847 Label for field
   8   rt_time              sec          Real8          75214792.8426098526: 75265108.3036306649 Label for field
   9   rt_wght              none         Real8          0.0001972452452:    0.88110179383762 Label for field
  • rt_cosx, rt_cosy, rt_cosz: cosine of the ray direction

  • rt_kev: energy of the ray [keV]

  • rt_x, rt_y, rt_z: ray position in telescope coordinates [mm]

  • rt_time: The time of the ray. Since this simulation used an aspect solution (retrieved by OBS_ID), the time range in the ray file match the times in the aspect solution file.

  • rt_wght: fractional probability that this ray will reach the focal plane.

The header of the ray files contains several keywords that are important for later use. The most important keywords are highlighted and discussed below.

unix% dmlist HRMA_ra184.23746_dec37.72658_source_flux_chart.dat_dithered_i0000_rays.fits header
0001 SRFNO                2                              Int4         
0002 SRC_E                INDEF [keV]                    String       Energy used to generate rays
0003 SRC_DENS             0 [r/mm^2]                     Int4         Ray density
0004 SRC_FLUX             INDEF                          String       Source flux
0005 SRC_SPEC             source_flux_chart_broad.fits   String       Spectrum used to generate rays
0006 SRC_EXPT                 50315.5830989930 [sec]     Real8        Exposure time of simulation
0007 TOTCTS               0                              Int4         Total counts (weight) in PSF image
0008 SRC_THET                     5.9752305455 [arcmin]  Real8        input off axis angle
0009 SRC_PHI                    197.8625696606 [deg]     Real8        input azimuthal angle
0010 SRC_RA               184.237458333 [deg]            String       Input source Right Ascension
0011 SRC_DEC              37.7265805556 [deg]            String       Input source Declination
0012 TELESCOP             CHANDRA                        String       Telescope
0013 INSTRUME             TEL                            String       Instrument
0014 DETNAM               HRMA                           String       Detector
0015 CREATOR              saotrace                       String       Software that created this file
0016 PSFSEED2             388160                         Int4         Secondary random seed
0017 PSFBLOCK             1                              Int4         Block for saosac
0018 CONTENT              RAYS                           String       File contains simulated data
0019 ORIGIN               Unknown                        String       The origin of the FITS file
0020 DATE                 2015-05-11T09:56:50            String       Date FITS file was created
0021 DATE-OBS             2015-04-24T00:00:00            String       Date simulated
0022 HDUCLASS             ASC                            String       
0023 HDUCLAS1             RESPONSE                       String       
0024 HDUCLAS2             PSF                            String       
0025 HDUCLAS3             PSFRAY                         String       
0026 HDUVERS1             1.0.0                          String       
0027 RAYMETH              SAOTrace                       String       
0028 CONFFILE             orbit-200809-01f-a             String       
0029 ASOLFILE             pcadf075214790N004_asol1.fits.gz String       
Energy of source for a monochromatic source simulation. A value of 'INDEF' indicates that a polychromatic spectrum file was provided.
Photon flux of source for a monochromatic energy. A value of 'INDEF' indicates that a polychromatic spectrum file was provided.
The name of the spectrum file if one was uploaded.
Source exposure time. Since an aspect solution was specified, the time is taken from there, otherwise it will be the value input to ChaRT.
Off axis angle of source location.
Azimuthal angle of source.
R.A. of source location converted to decimal degrees.
Declination of source location converted to decimal degrees.
The random seed used for the simulation. ChaRT automatically increments the seed for each iteration in an attempt to provide statistically independent realizations.
unix% dmlist "HRMA*_rays.fits" header | grep PSFSEED2
0016 PSFSEED2             388160                         Int4         Secondary random seed
0016 PSFSEED2             388161                         Int4         Secondary random seed
0016 PSFSEED2             388163                         Int4         Secondary random seed
0016 PSFSEED2             388166                         Int4         Secondary random seed
0016 PSFSEED2             388170                         Int4         Secondary random seed
The name of the raytrace configuration file used in the simulation.
The aspect solution file name (if one was used). This file must be input to MARX or psf_project_ray to correct for the motion of the telescope that has been simulated.

Examining the PSF data

HRMA_ra184.23746_dec37.72658_source_flux_chart.dat_dithered_i0000_rays.fits is a FITS binary table with the data stored in the PSFRAYS block of the file. Using dmlist shows that this file contains 8387 rays.

unix% dmlist HRMA_ra184.23746_dec37.72658_source_flux_chart.dat_dithered_i0000_rays.fits blocks
Dataset: HRMA_ra184.23746_dec37.72658_source_flux_chart.dat_dithered_i0000_rays.fits
     Block Name                          Type         Dimensions
Block    1: PRIMARY                        Null        
Block    2: PSFRAYS                        Table         9 cols x 8387   rows
Do not simply merge ray files

Users must not try to simply merge the ray files together at this point. The ray files must be processed individually through MARX and then the results may be combined together. Merging the ray files first is likely to cause MARX to simulate pileup when non exists in the observation.


The output from ChaRT cannot be used directly in your analysis. It first needs to be projected onto the detector and have the detector response applied to it to create a simulated event file. The Using MARX to Create an Event File thread describes how to do this.


27 Jun 2003 original version, updated for CIAO 3.0: layout
13 Jul 2004 created Columns and Header Keywords section
16 Feb 2005 reviewed for CIAO 3.3: no changes
18 Aug 2008 updated for CIAO 4.0: minor changes to screen output
17 Feb 2010 reviewed for CIAO 4.2: no changes
15 Dec 2010 reviewed for CIAO 4.3: no changes
24 Sep 2012 thread renamed
26 Oct 2012 screen output text updated for the Linux version of the SAOTrace backend, after transition from Solaris version of SAOTrace/ChaRT.
11 May 2015 Updated for ChaRT v2.
26 Jan 2021 Update URLs to https://