simulate_psf

Synopsis

Simulate the Chandra PSF

simulate_psf  infile outroot ra dec spectrum [monoenergy] [flux]
[simulator] [rayfile] [projector] [random_seed] [blur] [readout_streak]
[pileup] [ideal] [extended] [binsize] [numsig] [minsize] [maxsize]
[numiter] [numrays] [keepiter] [asolfile] [marx_root]

Description

The Chandra Point Spread Function (PSF), or Point Response Function (PRF), is highly variable across the field of view. Near the optical axis the FWHM is less then 0.5 arcsec while at 8 arcmin off-axis, it grows to over 30 arcsec and continues to grow exponentially from there. The PSF is also a function of energy with the 90% encircled energy radius growing by about 10% across the Chandra energy range. The PSF is also affected by the detector geometry, placement in the focal plane, and detector readout.

Given all these complexities, there is no analytic, 2D model of the PSF. The only way to estimate the Chandra PSF is to simulate it.

There are two tools available to simulate the Chandra PSF. The most complete mirror simulator is SAOTrace which is maintained by the CXC optics group. It is the tool that is run by the ChaRT web service. It produces the highest fidelity simulation of the Chandra mirrors (HRMA), but does not include the instruments. For that users typically will run the SAOTrace output through MARX. However, MARX itself has its own model of the HRMA and can directly produce highly accurate simulations. For most typical sources either tool will yield statistically equivalent results. (See Appendix in Primini et al. and the MARX characterization pages.

The simulate_psf script simplifies the interface to MARX and to the rayfiles returned by ChaRT. It is useful to simulate a source PSF for an existing observation. The header information in the file for the existing observation is used to setup the simulation and the projection. Currently MARX is the only supported simulator for the Chandra mirror (HRMA), however the script also accepts a stack of rayfiles generated with ChaRT. In case of ChaRT rayfiles both MARX or the CIAO tool psf_project_rays can be used to project the rays onto the detector.

Software Versions

This script has only been tested with MARX versions 5.0 through 5.3. Earlier versions of MARX are not supported. Users are encouraged to use the most recent version of MARX. The install_marx script can be used to install the latest version.

Examples

Example 1

unix% setenv MARX_ROOT /soft/marx-5.3.0/
unix% setenv MARX_DATA_DIR ${MARX_ROOT}/share/marx/data

This example is to setup MARX. This example needs to performed once before the following examples are expected to work.

Bash shell users should replace the above setenv commands with the equivalent export commands and source the saotrace_setup.bash script.

Example 2

unix% simulate_psf infile=acisf00635_repro_evt2.fits ra=246.88628
dec=-24.556762 monoenergy=2.3 flux=1e-6 spectrum=none
outroot=simple_monoenergy

This example will use MARX to simulate a source at the specified RA and DEC. It will have a monochromatic spectrum at 2.3 keV with a flux of 1e-6 photon/cm^2/sec. The tool will locate the aspect solution file from the ASOLFILE keyword in the infile. The output image will be named simple_monoenergy.psf

Example 3

unix% simulate_psf infile=acisf00635_repro_evt2.fits ra=246.88628
dec=-24.556762 spectrum=source.dat outroot=abs_powlaw

This example uses the spectrum in the file source.dat to create the PSF. With the default parameter flux=INDEF, the flux values in the spectrum file are used directly without any modifications.

Instructions for creating the spectrum in the correct format are shown in the CIAO thread: Preparing to Run ChaRT

Example 4

unix% simulate_psf infile=acisf00635_repro_evt2.fits ra=246.88628
dec=-24.556762 spectrum=source.dat outroot=abs_powlaw flux=1e-6

The flux parameter is used to scale the input spectrum such that the total integrated flux is equal to the flux parameter.

Example 5

unix% simulate_psf infile=acisf00635_repro_evt2.fits ra=246.88628
dec=-24.556762 spectrum=source.dat outroot=abs_powlaw_mean numiter=10
minsize=256 maxsize=512

Using numiter, the simulation will be repeated 10 times. The output image will be at least 256 physical pixels but not more than 512 pixels and will be the result of combining the 10 simulations together.

Example 6

unix% simulate_psf infile=acisf00635_repro_evt2.fits ra=246.88628
dec=-24.556762 spectrum=source.dat outroot=abs_powlaw_mean
numiter=INDEF numrays=10000 minsize=256 maxsize=512

This is similar to the previous example, except now instead of requesting a number of iterations we have requested a minimum number of rays, 10000. This mode is only available when numiter=INDEF. If both numiter and numrays are specified, then numiter will be used.

Example 7

unix% simulate_psf infile=acisf00635_repro_evt2.fits ra=246.88628
dec=-24.556762 spectrum=none mono=2.3 flux=1e-6 outroot=mono_mean
numiter=10 keepiter=yes minsize=256 maxsize=512

In this example 10 different monochromatic simulations will be done for a 2.3 keV source with a flux of 1e-6 photon/cm^2/sec. The final output image will be the combination of the 10 individual simulations, however, with keepiter=yes, the individual files for each simulation are also retained including the marx parameter files.

Example 8

unix% simulate_psf infile=acisf00635_repro_evt2.fits ra=246.88628
dec=-24.556762 spectrum=none outroot=using_rayfile simulator=file
rayfile=HRMA_chart_output_i0000.fits pileup=yes readout_streak=yes
extend=no

This example shows how the ChaRT ray file can be input to this tool. This can be useful to test different combination of MARX or psf_project_ray parameters (blur, pileup, readout streak, etc.).

The spectrum of the source does not need to be supplied since that information is already determined from the input rayfile.

Parameters

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input event file

The input event file or image. Header information in the infile is used to setup the simulation and the projection. It includes, but is not necessarily limited to the following keywords: RA_NOM, DEC_NOM, ROLL_NOM, RA_PNT, DEC_PNT, ROLL_PNT, DY_AVG, DZ_AVG, DTH_AVG, SIM_X, SIM_Y, SIM_Z, INSTRUME, DETNAM, EXPTIME (ACIS), TIMEDEL, GRATING, TSTART, TSTOP, DATE-OBS, NROWS (ACIS), and TIMEDELB (ACIS).

Parameter=outroot (file required filetype=output)

Output directory plus root name

The final output file name will be ${outroot}.psf.

The size of the output image will depend on the size of the PSF and the following parameters: minsize, maxsize, binsize, numsig.

The PSF is normalized by the number of rays output by either marx or psf_project_ray. Since some of the PSF rays will in general be outside the image boundary, the sum of the pixel values in the PSF image will be <= 1.0

MARX creates many temporary files. This same outroot is used for those files and directories.

If the keepiter parameter (below) is set to yes, then several temporary files are kept from each iteration of the simulation. The set of files will depend on which simulator and projector was selected.

Parameter=ra (real required min=0 max=360 units=deg)

The Right Ascension of the source to simulate

Source positions must be in decimal degrees and in J2000 coordinates.

If using existing ray files from ChaRT, users can set ra=INDEF and dec=INDEF to use the SRC_RA and SRC_DEC keyword values.

Parameter=dec (real required min=-90 max=90 units=deg)

The Declination of the source to simulate

Source positions must be in decimal degrees and in J2000 coordinates.

If using existing ray files from ChaRT, users can set ra=INDEF and dec=INDEF to use the SRC_RA and SRC_DEC keyword values.

Parameter=spectrum (file required filetype=input)

File with spectral information

The spectrum file is a 3 column ASCII file with energy low and high in keV vs. flux in photon/cm^2/sec.

If spectrum is "none" or left blank, then the user can specify a monochromatic energy via the monoenergy parameter.

The absolute normalization of the spectrum can be controlled by the flux parameter (below).

The spectrum must only contain energies between 0.3 and 10 keV. The flux at all the energies must be > 0.

Parameter=monoenergy (real not required default=INDEF min=0.1 max=10 units=keV)

Monochromatic energy to simulate

A monochromatic energy must be supplied if the spectrum parameter is blank or "none". The flux parameter must also be supplied. The flux must be in units of photon/cm^2/sec.

The monoenergy parameter is ignored for spectrum=file.

Parameter=flux (real not required default=INDEF units=varies)

Absolute flux or flux scaling factor

If using a monochromatic energy (spectrum is blank or "none") the flux parameter is the flux of the point source in units of photon/cm^2/sec.

If a spectrum is supplied, the default value of INDEF will instruct MARX to use the unmodified flux in the spectrum file.

With simulator=marx, the flux value is used to establish an absolute integrated flux scaling factor. A value of flux=0.002 will scale the fluxes such that the total integrated flux over the input energy range is 0.002 photon/cm^2/sec.

The flux parameter is ignored with simulator=file.

Users should be careful not to try to increase the statistics in the PSF simulation by simply increasing the flux. Depending on the setting of pileup and readout_streak parameters, this can result in deformations of the PSF that are not present in the observed data.

Parameter=simulator (string not required default=marx)

Application to simulate the Chandra mirrors

Selects whether to use "marx" to simulate the Chandra mirrors or to use "file" which will use the ChaRT rayfiles specified in the rayfile parameter.

Parameter=rayfile (file not required filetype=input stacks=yes)

Input ray file when simulator=file

The ChaRT web service can be used to create the rayfiles.

This allows the user to bypass the HRMA simulation and generate different PSFs images with for example different readout_streak or pileup settings or at different image sizes.

Parameter=projector (string not required default=marx)

Which application to use to project rays onto the detectors

The rayfile files from ChaRT can be projected onto the appropriate instrument using either "marx" or "psf_project_ray". With simulator="marx" this parameter must also be "marx".

While they produce the same basic format output file, a pseduo Chandra event file, there are differences in how each models the instruments. There are use cases for both that are described in the "MARX vs psf_project_ray" section below.

Parameter=random_seed (integer not required default=-1)

Initial random seed for simulations.

The random_seed is set to initialize the simulation. With random_seed equal to the default value of -1, the script will use a random value for the initial random_seed.

The random_seed is automatically adjusted when multiple iterations, numiter>gt;1, are run.

Parameter=blur (real not required default=0.07 min=0 units=arcsec)

PSF Blur

It may be necessary to add an additional amount of blurring to the PSF to account for detector effects and/or uncertainity in the aspect reconstruction. The value of the blur parameter is passed directly to MARX as the value for the "AspectBlur" parameter or to psf_project_ray as the value for the "xblur" parameter.

Parameter=readout_streak (boolean not required default=no)

Simulate the ACIS readout streak with MARX?

The ACIS readout streak is the result of events being detected during the transfer of the pixel values to the readout buffer (frame store). This results in a line of events, in the CHIPY direction, that intersects bright sources.

Users may wish to include this effect in the PSF for certain types of analysis especially when measuring features in observed data that align with the CCD readout.

This parameter has no effect when projector=psf_project_ray.

Parameter=pileup (boolean not required default=no)

Simulate ACIS pileup with MARX?

Pileup occurs when two or more photons hit the ACIS CCD during a single exposure. Since the photons cannot be resolved into individual events, the effect is to detect a single event with energy equal to the sum of the input energies and a loss of counts.

As the incident flux increases, the detected flux will decrease and with sufficient pileup will go to zero -- resulting in the core of the PSF becoming a "crater".

Including this effect in the PSF may be necessary when trying to match the wings of the PSF to observed data; however, given the loss of flux this results in an inability to provide an accurate PSF fraction.

This parameter has no effect for projector=psf_project_ray.

Parameter=ideal (boolean not required default=yes)

Should MARX simulate ideal detectors?

This parameter can be set to simulate events hitting an ideal detector (QE=1). This may be necessary when using the PSF in conjunction with an exposure map (eg when doing 2D fitting); otherwise the exposure variations maybe applied twice.

This parameter has no effect for projector=psf_project_ray.

Parameter=extended (boolean not required default=yes)

Should PSF extend beyond the edge of the detector?

When fitting or convolving with the PSF, the edge of the detector should not be included. The PSF should extended to "infinity" (or a reasonably large size that is still practical to work with). The edge can be reintroduced by including the exposure map in the analysis which properly accounts for loss of counts at the edges.

Extended chip coordinates cannot be used when simulating pileup (pileup=yes).

This parameter has no effect for projector=psf_project_ray.

Parameter=binsize (real default=1 min=0 units=pixel)

Output PSF image pixel size.

The PSF image that is created will be centered at the input RA,DEC. This parameter controls the pixel size, in physical pixels.

Parameter=numsig (real default=7 min=0)

Size of the output image in number of standard deviations

The output image will be centered at the input RA,DEC and will have a pixel size equal to binsize. The image will be square with axis length equal to numsig times the maximum standard deviation of the simulated events' location along the X and Y axes.

If minsize is set, the image will be at least minsize square. If maxsize is set, the image will not be larger than maxsize square.

Parameter=minsize (integer default=INDEF min=0 units=pixel)

Minimum PSF image size

If set, this parameter controls the minimum output PSF image size.

minsize is in physical pixels.

If multiple iterations are requested, the image size is fixed to the first simulation.

minsize is ignored if it is less than the size determined by the numsig parameter.

Parameter=maxsize (integer default=INDEF min=0 units=pixel)

Maximum PSF image size

If set, this parameter controls the maximum output PSF image size.

maximum is in physical pixels.

If multiple iterations are requested, the image size is fixed to the first simulation.

maxsize is ignored if it is greater than the size determined by the numsig parameter.

Parameter=numiter (integer default=1 min=1)

Number of PSFs to simulate and combine together

The PSF created with this tool is the result of running random simulations and is therefore subject to statistical uncertainty.

To reduce these effects users may try to increase the flux; however doing so, especially when using either readout_streak=yes or pileup=yes will result in additional streak and/or pileup that may not match the actual observed dataset.

ChaRT users may also have tried to increase the exposure time to generate more rays. However, this is not a valid option when an aspect solution is used as the time range of the simulation must match the times in the ASOL file.

The correct approach is to generate several realizations of the simulation, each with a different random seed, and either combine them together or to repeat the analysis with each realization in order to quantify the simulation uncertainty/bias.

The numiter parameter is ignored for when rayfiles are supplied. The tool will loop over the stack of rayfiles and produce the combined PSF.

If numiter="INDEF", then the numrays parameter is used. If both numiter and numrays are set to integer values, then the numiter value will be used and numrays will be ignored.

Parameter=numrays (integer default=INDEF min=1)

Number of rays to simulate

Rather than specifying a fixed number of iterations users can specify the total number of rays (events) that they wish to simulate. In this mode, the tool will perform one iteration of the simulation, count the number of events, and will repeat the simulate again with a different random seed, until the total number rays has been met. This will repeat up to 10000 times at which point the tool will exit.

If numiter="INDEF", then the numrays parameter is used. If both numiter and numrays are set to integer values, then the numiter value will be used and numrays will be ignored.

Parameter=keepiter (boolean not required default=no)

Keep various files from each PSF simulation

The primary output from this tool is the PSF image file, ${outroot}.psf. This parameter allows additional files to be kept. The files are

${outroot}_iNNNN_projrays.fits : The simulated event file output from either MARX or psf_project_ray. The contents (columns) in the output varies between the two tools, but both include X and Y columns that are used to bin the data into an image.

${outroot}_iNNNN.psf : The image of the PSF created at each iteration. The final output PSF is the average of all the iterations.

${outroot}_iNNNN_marx.par : The MARX parameter file, if marx was used as the simulator and projector. Users can re-run marx using the exact same parameters like this

$ marx @@${outroot}_iNNNN_marx.par

Parameter=asolfile (file not required filetype=input)

Input aspect solution file

The aspect solution file for the observation. The optical axis dithers across the sky as a function of time. This means the observed PSF is actually a combination of the PSFs around the nominal pointing location. The general effect is to slightly blur the PSF. To properly account for this blur, the aspect solution should be used with the simulation.

If the parameter is left blank or set to the string "INDEF", the script will try to locate the correct file by looking for the file(s) listed in the ASOLFILE keyword.

If asolfile="none" or if no aspect soluiton file can be located, then MARX will be configured to use an internal dither model consistent with the default dither pattern for the detector being used (ACIS or HRC).

Parameter=marx_root (file not required)

The directory where MARX was installed.

The marx executable should be $marx_root/bin/marx.

MARX or psf_project_ray?

This section is only relevant when using simulator=file and supplying rayfiles.

MARX provides a full simulator for the Chandra instruments as well as the transmission gratings. This includes not only the detector geometry but also the event detection process in ACIS including the EDSER subpixel event positions. It can be used to simulate pileup and the ACIS readout streak.

psf_project_ray is a CIAO tool that takes the SAOTrace ray file and projects the rays onto semi-infinite planes at the surface of the detectors.

Caveats

Users should review the list of MARX caveats for issues directly related to MARX.

Below is a list of caveats related to PSF images created with this tool:

Subarray

ACIS subarrays are not supported. The MARX parameters are adjusted to account for the decreased subarray frame times; however, the spatial extent of the subarray is not modeled. This may lead to differences in the PSF when the parameter readout_streak=yes.

Windows

ACIS windows are not supported. The CHIP coordinates are saved in the ray files (keepiter=yes) which users can use to filter on to approximate a window. For example if all the PSF events fall on a single CCD then the following type of filter can be used

unix% dmcopy "mysim_i0001_rays.fits[exclude
chipx=100:200,chipy=300:600]" mysim_window_rays.fits

However, for grey filter windows (SAMP_CYC > 1) it is more difficult to try to duplicate the event sampling algorithm.

Continuous Clocking

Observations of ACIS continuous clocking mode are not supported.

PSF Artifact

There is an artifact in the PSF on the scale of 0.2 arcsec. The details of which are discussed in this PSF caveat. Neither MARX nor SAOTrace currently model this artifact.

HRC Pileup

For high count-rate sources, there may be an additional blurring of the data caused by pileup. This effect is not simulated by MARX. The page also links to a script users can run to filter out the piled up events at the expense of loosing some detector sensitivity.

Changes in the scripts 4.16.2 (August 2024) release

Added the maxsize parameter to specify the maximum allowed PSF image size.

If marx_root is blank then look for marx in the user's PATH and use that directory to derive marx_root.

Changes in the scripts 4.15.2 (April 2023) release

When simulating pileup (pileup=yes), the wrong frame time was used. For observations done with full-frame (1024 rows) the error is small, but for subarray data, the PSFs could be substantially over estimating the amount of pileup. While pileup is non-linear, the approximate error is on the order of 3.2 seconds divided by the frame time of the observation given by the EXPTIME keyword. This has now been fixed.

Changes in the scripts 4.14.2 (April 2022) release

Added the numrays parameters to allow users to request a specified number of rays (events) instead of the number of iterations.

Changes in the scripts 4.13.2 (June 2021) release

The MARX TStart value is now taken directly from the header of the input file. Previously it was converted from Chandra mission time (seconds since 1998.0) to Julian Epoch which resulted in a loss of numerical precision of approximately 3 days. The change is mostly cosmetic as it has little, if any, effect on the actual PSF image.

Changes in the scripts 4.12.3 (July 2020) release

Images can now be used as the infile. Previously only event files could be used.

Changes in the scripts 4.12.2 (April 2020) release

Fixed bug that caused parameter values in the script's HISTORY records to be reset to their default (blank) values.

Changes in the scripts 4.10.3 (October 2018) release

Recognizes when outroot is a directory and adjusts file names so they no longer begin with an underscore or period.

Changes in the scripts 4.10.1 (April 2018) release

If using rayfiles from Chart (simulator=file), now users can set ra=INDEF and dec=INDEF and simulate_psf will automatically use the SRC_RA and SRC_DEC keywords in the rayfile headers. There are also additional consistency checks when a stack of ray files is supplied.

Changes in the scripts 4.9.2 (April 2017) release

There is an internal change which ensures that the output ray file will retain the same event file sky boundary (ie TLMIN/TLMAX) as the input file. Prior to this the ray file may not have displayed nicely in ds9. This only affects the way the data are displayed.

About Contributed Software

This script is not an official part of the CIAO release but is made available as "contributed" software via the CIAO scripts page. Please see this page for installation instructions.

Bugs

There are no known bugs for this tool.

See Also

tools::aspect

asp_offaxis_corr

tools::coordinates

dmcoords

tools::download

install_marx

tools::image

aconvolve, acrosscorr, arestore, dmfilth, dmregrid

tools::region

psfsize_srcs

tools::response

arfcorr, make_psf_asymmetry_region, psf_project_ray, src_psffrac