Using MARX to Simulate a Planned Observation
![[CXC Logo]](../../imgs/cxc-logo.gif){kind=logo}
CIAO 4.17 Science Threads
Overview
Synopsis:
Simulating rays with MARX is very similar to the steps needed to reproject ChaRT rays, and is only a matter of setting a couple additional parameters. In this example, a hypothetical point source is generated and projected on the detector-plane with the MARX software.
Note that MARX was originally intended as a PSF simulator and not an observation simulator, but can be used to help in observation planning.
Using MARX allows the user to take into account all changes to the photon distribution emerging from the HRMA due to the detector response. In particular, the detector QE & QEU and the roll are accounted for. In addition to simulating the detector response, MARX uses the ray weights to account for the mirror effects, i.e. different efficiency of different shells at different angles/energies.
Related Links:
-
The full MARX documentation and more examples can be found at https://space.mit.edu/cxc/marx/.
- Caveats page: details on what is not included when using MARX.
- The MARX Frequently Asked Questions webpage
- Using a PSF Image as the Convolution Kernel
Last Update: 09 Dec 2024 - Added note about MARX installation; happens by default with ciao-install in CIAO 4.17 or can be installed with conda.
Contents
Setting up MARX
This thread uses MARX v5.5.3; if you do not already have the
software, download
and install MARX before continuing.
![[New]](../../imgs/new.gif)
MARX is installed automatically when CIAO is installed
using the ciao-install script or it can be installed
using conda by adding marx to the list of packages
to install.
Alternatively, the
install_marx script may also be used
to download and install the latest available version of
MARX.
Set up your environment to access all the files and directories which MARX needs:
---(t)csh---
unix% setenv MARX_ROOT <local_marx_directory>/marx-5.2.0
unix% setenv MARX_DATA_DIR ${MARX_ROOT}/share/marx/data
unix% setenv PATH ${PATH}:${MARX_ROOT}/bin
unix% setenv PFILES ${PFILES}:$MARX_ROOT/share/marx/pfiles
---bash---
unix% export MARX_ROOT=<local_marx_directory>/marx-5.2.0
unix% export MARX_DATA_DIR=${MARX_ROOT}/share/marx/data
unix% export PATH=${PATH}:${MARX_ROOT}/bin
unix% export PFILES=${PFILES}:${MARX_ROOT}/share/marx/pfiles
If you installed MARX from the CIAO conda channel then you should set:
---(t)csh--- unix% setenv MARX_ROOT $CONDA_PREFIX ---bash--- unix% export MARX_ROOT=$CONDA_PREFIX
and the rest of the parameters should be set using that value for MARX_ROOT.
Alternatively, the MARX DataDirectory parameter can be defined to point to the data files. By default, this parameter is set to the contents of the $MARX_DATA_DIR environment variable. At this point, your system is ready to run simulations.
Simulating the Source
In this example, we will simulate an on-axis point source for a hypothetical observation; where the goal is to have good spatial resolution of the primary target; and secondarily, have a source in the field for imaging spectroscopy that is off-axis, which helps reduce pile-up by spreading the source's flux over a larger number of pixels.
We will first define the source coordinates, in decimal degrees—where we use the position of the western lobe of the Pictor A jet, which is RA=05:19:26.204 [79.859546 deg], Dec=-45:45:53.69 [-45.765033 deg]—for our hypothetical source.
Obtaining Telescope Parameters and Physical Feasibility
*This sub-section is only needed if a specific telescope roll angle is needed. Otherwise, the user may just assume a roll angle of zero for the simulation by setting Roll_Nom=0.
Before running the simulation, it is necessary to determine the nominal position of the detector for the hypothetical observation. The PRoVis and ObsVis proposal planning tools can both be used to help determine these values.
PRoVis is used to examine the expected visibility of a target by Chandra over a period of time, and illustrates periods where observations are forbidden due to spacecraft constraints.
Begin by going to the Target Parameters frame and enter the time period in the future of interest—in this particular example, spanning from 2016 Jan 01 to 2016 Dec 31—and then enter the target's J2000 coordinates. In lieu of directly entering the coordinates, the target name can be provided, and coordinates determined by clicking the Resolve Name button on top of the page. A visibility/roll/pitch plot is then displayed after clicking the Generate Plot button.
Figure 1: PRoVis-generated Plot
![[Thumbnail image: Telescope properties over a year, if aimed at Pictor A]](provis.png)
[Version: full-size]
Figure 1: PRoVis-generated Plot
PRoVis plot of various spacecraft parameters for an observation of Pictor A over the course of 2016. The target is observable throughout the entire year with no restrictions.
The visibility plot shows that the target source is observable throughout the entire year, with no spacecraft restrictions, having a maximum observational exposure length being roughly 75% of the Chandra orbital period.
Since there are no spacecraft restrictions for an observation, we can then use ObsVis to visualize the placement of the source on the detector and determine the corresponding SIM offset parameters. ObsVis is started from the command-line in a terminal with CIAO started,
unix% obsvis &
where the ObsVis GUI and a DS9 session are opened.
To use the cataloged coordinates, type "PicA" (without quotes) in the Target Name box and click the Resolve button. Since the primary interest is to perform on-axis imaging, ACIS-I will be used, with the addition of ACIS-S3 optionally turned on for archival use. On the ObsVis GUI, click on ACIS-I under Instrument and then click twice on S3 under Instrument Detail. The Roll(deg) will be left empty, since the roll is unconstrained for the target coordinates, and we can explore various roll angles later. Then click on the New FoV button. A new Field of View (FoV) labeled fov0 (the default) will appear in the table at the bottom of the GUI and in the DS9 window, a DSS Server box will open loading a DSS field containing the desired target in DS9 with the Chandra field of view, for the specified chips overlaid.
The blue boxes represent the active chips and the yellow, dashed box represents the optional chip for the observation. The red crosshair is centered at the entered target coordinates and the red box displays the size of the default Chandra dither pattern. The green circular box is the the telescope's nominal aimpoint and the blue circular box is the telescope's optical axis.
The lobe of the jet emanating from Pictor A is located at roughly RA = 05:19:26.204 [79.859546 deg] and Dec = -45:45:53.69 [-45.765033 deg], so we may reposition the red target cursor to this position by going to the ObsVis GUI menu and selecting Adjust-FoV → Move, and the red crosshairs will be highlighted. Either drag the cursor to the new position or go to the DS9 menu Region → Get Information and edit the Center field with the lobe's position.
Next, various roll angles can be experimented with. This can be interactively done by going to the ObsVis GUI menu and selecting Adjust-FoV → Roll (with Shiftkey) so that the entire detector array will be highlighted, and going to one of the corners of and holding the shift key, the cursor will change and left-clicking the mouse while moving the cursor will alter the telescope roll angle. A roll angle of ~215 degrees places the lobe near the optical-axis and aimpoint, and the Pictor A core near the center of the ACIS-I3.
Zooming in on the target, it is seen that the nominal aimpoint (green circular box) is centered on the target, while the optical-axis (blue circular box) is slightly offset. But instead, suppose we want to center the optical-axis on the target, select Adjust-FoV → OffsetYZ in the ObsVis GUI, and the optical-axis is highlighted, so it may be moved to the target coordinates.
While the optical-axis and nominal aimpoint will not co-align, the separation can be minimized by offsetting the SIM along the telescope's z-axis by select Adjust-FoV → OffsetSimZ in the ObsVis GUI, and moving the highlighted aimpoint.
Figure 2: ObsVis GUI
![[Thumbnail image: ObsVis GUI after adjusting observation parameters]](obsvis_menu.png)
[Version: full-size]
Figure 2: ObsVis GUI
The ObsVis GUI after adjusting observation parameters.
From the ObsVis GUI, the useful values—besides the target coordinates—for our needs are the Roll(deg) = 215 and Offset-SimZ(mm) = 0.0133843999477 fields, which will be incorporated into the MARX simulation. The nominal aimpoint position can be now obtained by selecting the Adjust-FoV → OffsetSimZ menu in the ObsVis GUI, and then Region → Get Information menu in DS9, to obtain RA = 05:19:26.416 [79.860065 deg] and Dec = -45:45:53.25 [-45.76479 deg].
Figure 3: ObsVis Results
![[Thumbnail image: ObsVis results]](obsvis.png)
[Version: full-size]
Figure 3: ObsVis Results
Upper Panel: The Chandra field of view as defined in ObsVis, overlaid on a DSS field centered on Pictor A.
Center Panel: Zooming in on Pictor A from the Upper Panel. The crosshair (red) and optical-axis (blue) centered on the jet lobe and the nominal aimpoint (green) is illustrated. X-ray contour (yellow) are overlaid to assist visualization.
Lower Panel: Previous Chandra observation of Pictor A (ObsID 346), a 25.8 ks exposure on ACIS-S3.
Additional information needed for the simulation is the observation date—which affects the contamination model applied to the detector—and the minimum number of counts to detect. Note that this is not the same as the total number of source counts, which would be included in the total counts detected.
From the earlier PRoVis run, a roll angle of ~215 degrees corresponds to a date of MJD 57515.85, which corresponds to a decimal year of roughly 2016.35 for the simulation's TStart value.
![[TIP]](../../imgs/tip.png)
The MARX TSTART parameter can be in terms of "mission time" or decimal years. Values <2100 are interpreted as decimal years, otherwise the value is treated as seconds on the spacecraft clock. The prop_dates proposal planning tool can be used to convert from a MJD start time to decimal years and mission time:
# Decimal Year unix% prop_dates p0 from MJD to JEPOCH exit 57515.85 J2016.35 # Mission Time unix% prop_dates p0 from MJD to TIME exit 57515.85 579039845
In this thread, a value of TStart = 2016.35 is used, which is sufficiently precise for MARX's usage.
The appropriate telescope and detector configuration should also be set. First, copy over the parameter file locally:
unix% cp $MARX_ROOT/share/marx/pfiles/marx.par ./marx5sim.par
and set the necessary parameters:
unix% pset ./marx5sim SourceRA=79.859546 unix% pset ./marx5sim SourceDEC=-45.765033 unix% pset ./marx5sim RA_Nom=79.860065 unix% pset ./marx5sim Dec_Nom=-45.76479 unix% pset ./marx5sim Roll_Nom=215 unix% pset ./marx5sim TStart=2016.35 unix% pset ./marx5sim OutputDir=PicA_lobe_marxsim.dir unix% pset ./marx5sim ExposureTime=0.0 unix% pset ./marx5sim NumRays=-1000 unix% pset ./marx5sim DetectorType=ACIS-I unix% pset ./marx5sim GratingType=NONE unix% pset ./marx5sim MirrorType=HRMA unix% pset ./marx5sim DitherModel=INTERNAL unix% pset ./marx5sim DitherAmp_RA=8 unix% pset ./marx5sim DitherAmp_Dec=8 unix% pset ./marx5sim DetOffsetZ=0.0133
There are a few things to note in the pset commands:
-
Make sure to use the correct detector for the DetectorType parameter; valid options are: HRC-S, ACIS-S, HRC-I, or ACIS-I. Valid options for the GratingType parameter are: HETG, LETG, or NONE. The ACIS array-types are specific, defined sets of CCDs:
- ACIS-I = ACIS-0123
- ACIS-S = ACIS-456789
-
In this example, we will detect at least 1000 counts. The negative sign preceding the integer-value of the NumRays parameter sets the minimum total number of rays to detect. If a positive-value is used, then that value is the minimum number of rays generated by the simulation. The ExposureTime is set to 0.0 to ensure that the correct exposure time to detect the set NumRays value is calculated.
-
The DitherAmp_RA and DitherAmp_Dec parameters must be appropriately set for the dither model. The typical amplitudes of the Lissajous pattern are both 8 arcsec for ACIS observations and 20 arcsec for HRC observations.
-
From the prior ObsVis work, the SIM is offset along the telescope z-axis by ~0.0133 mm, which is accounted for in the DetOffsetZ parameter.
To define the source being simulated, a two-column ASCII spectrum file—with the first column as energies in keV and the second column as flux densities in photons/s/cm2/keV—or a uniform energy spectrum may be specified.
unix% pset ./marx5sim SpectrumType=FLAT unix% pset ./marx5sim MinEnergy=2.4 unix% pset ./marx5sim MaxEnergy=2.4 unix% pset ./marx5sim SourceType=POINT unix% pset ./marx5sim SourceFlux=1e-4
In this example, a monochromatic energy of 2.4 keV for the point source is established by setting SpectrumType=FLAT, SourceType=POINT, and restricting the energy range of the uniform continuum to a single value, MinEnergy=MaxEnergy=2.4. The FEF/RMF used by MARX will subsequently affect the energy distribution of the detected rays (generally shaped like a narrowly peaked line spread function, centered at the selected monochromatic energy). When SpectrumType=FLAT, the total source flux is set by the SourceFlux parameter in units of photons/s/cm2.
If an ASCII spectrum file is used, then set SpectrumType=FILE and the SpectrumFile parameter to the path of the spectrum file; the SourceType parameter also should be set. In this source mode, the SourceFlux parameter is used to set the overall normalization of the input spectrum. Setting SourceFlux to a positive, non-zero value will cause MARX to re-normalize the spectrum read from the ASCII file to the specified total flux; a negative value will cause MARX to normalize the input spectrum by the specified factor. Using SourceFlux=-1 will use the normalization inherent to the input spectrum.
Blurring Effects
When simulating Chandra data, to avoid pixelization effects in the pseudo-events file, there is an AspectBlur parameter which can be set. Users may experiment with the varying the value of AspectBlur since it may deviate from the default value depending on the source spectral distribution and instrument used. In this example, we choose:
For ACIS: unix% pset ./marx5sim AspectBlur=0.28 For HRC: unix% pset ./marx5sim AspectBlur=0.1
Should an aspect solution be needed for your analysis, the marxasp tool can be used with the internal dither model from your MARX simulation.
unix% cp $MARX_ROOT/share/marx/pfiles/marxasp.par . unix% marxasp MarxDir=PicA_lobe_marxsim.dir OutputFile=PicA_asol.fits
This asol file can be used in CIAO along with the generated pseudo-events file. Note that if marxasp is used with a simulation where DitherModel≠INTERNAL, an error message is produced.
Run MARX
Now run the tool. Note the syntax (@@) required to use the local parameter file; see Example 9 of ahelp parameter for details.
unix% marx @@./marx5sim.par MARX version 5.2.0, Copyright (C) 2002-2015 Massachusetts Institute of Technology ... screen output omitted... [Using INTERNAL dither model] Initializing source type POINT... System initialized. Starting simulation. NumRays to detect = 1000, dNumRays = 1000 Collecting 1000 photons... 1000 collected. Reflecting from HRMA Detecting with ACIS-I Writing output to directory 'PicA_lobe_marxsim.dir' ... Total photons: 1000, Total Photons detected: 118, (efficiency: 0.118000) (efficiency this iteration 0.118000) Total time: 8472.998250 Collecting 1000 photons... 1000 collected. Reflecting from HRMA Detecting with ACIS-I Writing output to directory 'PicA_lobe_marxsim.dir' ... Total photons: 2000, Total Photons detected: 218, (efficiency: 0.109000) (efficiency this iteration 0.100000) Total time: 17114.095951 Collecting 1000 photons... 1000 collected. Reflecting from HRMA Detecting with ACIS-I Writing output to directory 'PicA_lobe_marxsim.dir' ... Total photons: 3000, Total Photons detected: 332, (efficiency: 0.110667) (efficiency this iteration 0.114000) Total time: 25822.010671 Collecting 1000 photons... 1000 collected. Reflecting from HRMA Detecting with ACIS-I Writing output to directory 'PicA_lobe_marxsim.dir' ... Total photons: 4000, Total Photons detected: 439, (efficiency: 0.109750) (efficiency this iteration 0.107000) Total time: 34255.168298 Collecting 1000 photons... 1000 collected. Reflecting from HRMA Detecting with ACIS-I Writing output to directory 'PicA_lobe_marxsim.dir' ... Total photons: 5000, Total Photons detected: 574, (efficiency: 0.114800) (efficiency this iteration 0.135000) Total time: 42597.323857 Collecting 1000 photons... 1000 collected. Reflecting from HRMA Detecting with ACIS-I Writing output to directory 'PicA_lobe_marxsim.dir' ... Total photons: 6000, Total Photons detected: 684, (efficiency: 0.114000) (efficiency this iteration 0.110000) Total time: 51407.798271 Collecting 1000 photons... 1000 collected. Reflecting from HRMA Detecting with ACIS-I Writing output to directory 'PicA_lobe_marxsim.dir' ... Total photons: 7000, Total Photons detected: 790, (efficiency: 0.112857) (efficiency this iteration 0.106000) Total time: 60347.319832 Collecting 1000 photons... 1000 collected. Reflecting from HRMA Detecting with ACIS-I Writing output to directory 'PicA_lobe_marxsim.dir' ... Total photons: 8000, Total Photons detected: 890, (efficiency: 0.111250) (efficiency this iteration 0.100000) Total time: 68964.051016 Collecting 1000 photons... 1000 collected. Reflecting from HRMA Detecting with ACIS-I Writing output to directory 'PicA_lobe_marxsim.dir' ... Total photons: 9000, Total Photons detected: 1008, (efficiency: 0.112000) (efficiency this iteration 0.118000) Total time: 77563.466335
Simulating Another Source in the Field
The off-axis point source Pictor A core may also be simulated within the telescope's field of view, as is currently setup, by just updating the SourceRA and SourceDEC parameters, in addition to the OutputDir to avoid overwriting the previous simulation of the jet lobe. The core has coordinates of RA = 5:19:49.723 [79.957179 deg] and Dec = -45:46:43.85 [-45.778847 deg].
unix% pset ./marx5sim OutputDir=PicA_core_marxsim.dir unix% pset ./marx5sim SourceRA=79.957179 unix% pset ./marx5sim SourceDEC=-45.778847
It may be also desirable to match the exposure time with the simulation of the lobe, in which case the ExposureTime parameter will be set to the total time of the lobe simulation (69278.677225 sec), and supersedes the NumRays parameter if ExposureTime is a non-zero value. In doing so, it may also be worthwhile to change the emitted flux of the core. In this example, assume that the core is 50% brighter than the lobe.
unix% pset ./marx5sim ExposureTime=69278.68 unix% pset ./marx5sim SourceFlux=1.5e-4
The tool can now be run, as shown earlier.
unix% marx @@./marx5sim.par MARX version 5.2.0, Copyright (C) 2002-2015 Massachusetts Institute of Technology ... screen output omitted... [Using INTERNAL dither model] Initializing source type POINT... System initialized. Starting simulation. Exposure Time set to 6.927868e+04 seconds Collecting 100000 photons... 11943 collected. Reflecting from HRMA Detecting with ACIS-I Writing output to directory 'PicA_core_marxsim.dir' ... Total photons: 11943, Total Photons detected: 2873, (efficiency: 0.240559) (efficiency this iteration 0.240559) Total time: 69278.774270
Create an Events File
MARX creates a number of ASCII files in the specified output directory (PicA_lobe_marxsim.dir):
unix% ls PicA_lobe_marxsim.dir b_energy.dat det_theta.dat obs.par sky_roll.dat xpos.dat zcos.dat det_dy.dat energy.dat pha.dat time.dat ycos.dat zpos.dat det_dz.dat marx.par sky_dec.dat xcos.dat ypixel.dat detector.dat mirror.dat sky_ra.dat xpixel.dat ypos.dat
These .dat files need to be converted to a FITS events file before they can be used in CIAO. The MARX tool marx2fits does this, given the directory name and the output filename:
unix% marx2fits --pixadj=EDSER PicA_lobe_marxsim.dir PicA_lobe.fits Reading subpix file Examining PicA_lobe_marxsim.dir/time.dat Examining PicA_lobe_marxsim.dir/detector.dat Examining PicA_lobe_marxsim.dir/energy.dat Examining PicA_lobe_marxsim.dir/b_energy.dat Examining PicA_lobe_marxsim.dir/xpos.dat Examining PicA_lobe_marxsim.dir/ypos.dat Examining PicA_lobe_marxsim.dir/zpos.dat Examining PicA_lobe_marxsim.dir/xcos.dat Examining PicA_lobe_marxsim.dir/ycos.dat Examining PicA_lobe_marxsim.dir/zcos.dat Examining PicA_lobe_marxsim.dir/xpixel.dat Examining PicA_lobe_marxsim.dir/ypixel.dat Examining PicA_lobe_marxsim.dir/pha.dat Examining PicA_lobe_marxsim.dir/mirror.dat Examining PicA_lobe_marxsim.dir/sky_ra.dat Examining PicA_lobe_marxsim.dir/sky_dec.dat Examining PicA_lobe_marxsim.dir/sky_roll.dat Examining PicA_lobe_marxsim.dir/det_dy.dat Examining PicA_lobe_marxsim.dir/det_dz.dat Examining PicA_lobe_marxsim.dir/det_theta.dat unix%
and similarly with the simulation of the core.
unix% marx2fits --pixadj=EDSER PicA_core_marxsim.dir PicA_core.fits
By default, data obtained from the data archive—and if using the default pix_adj values when reprocessing the data with chandra_repro—has the EDSER sub-pixel event repositioning algorithm applied to ACIS data, and no pixel randomization is applied to HRC data. The --pixadj switch is used to replicate this behavior, where --pixadj=EDSER is used for ACIS and --pixadj=NONE or --pixadj=EXACT for HRC simulations.
The files may be viewed in DS9:
unix% ds9 PicA_lobe.fits PicA_core.fits &
Figure 4: The events files created by MARX
![[Thumbnail image: The events file created by MARX includes the ACIS readout streak.]](marx.png)
[Version: full-size]
Figure 4: The events files created by MARX
Image of the pseudo-events files of the simulated 2.4 keV jet lobe (left) and core (right).
MARX includes a simulation of the ACIS readout streak in the events file.
If the objective is to simulate an observation as opposed to generating a model PSF for an observation, then you may want to include pileup effects. First you need to be sure that your simulation parameters exactly match the observation (for example the spectrum flux was not artifically increased to increase sampling of the PSF). If these are not correct, the observed pileup cannot be matched to the simulation.
To include pileup, you must run the marxpileup tool:
unix% cp $MARX_ROOT/share/marx/pfiles/marxpileup.par . unix% marxpileup MarxOutputDir=PicA_lobe_marxsim.dir
When creating the events file, to include the pileup effects, use the --pileup flag to process the pileup simulation with marx2fits.
unix% marx2fits --pixadj=EDSER --pileup PicA_lobe_marxsim.dir/pileup PicA_lobe_pileup.fits
Note: With pileup enabled, it is unclear how to apply an ad-hoc normalization to get the simulation to match the data. One can try to use a region away from the core of the PSF; however, if the observed data does have any extended emission (dust halo, PWN, etc) then the result will be incorrect.
*A bug in MARX 5.0.0, marxpileup introduces an offset on the source position, placing the source between 0.2-0.4 arcsec at 40 degrees from the readout streak, in the direction of the streak. This bug was fixed in MARX 5.1.0.
The two pseudo-events files can even be merged into a single events file by using dmmerge.
unix% dmmerge PicA_lobe.fits,PicA_core.fits PicA_merge.fits
The pseudo-events file can now be used, for example, to create an image of the PSF.
Summary
This thread demonstrated how to generate simulations of unobserved sources with MARX and produce pseudo-events files from the results.
History
| 23 Sep 2014 | original version |
| 24 Feb 2015 | updated DEFOCUS and SIM values |
| 11 Feb 2016 | updated for CY18 CfP and MARX 5.2.0 |
| 06 Apr 2016 | revised AspectBlur values. |
| 11 Apr 2016 | Added warning about installing MARX on OSX with default C compiler. |
| 10 Jun 2016 | Revised information about handling the SIM offset and added information about the MARX AspectBlur parameter. |
| 10 May 2017 | Updated running marx2fits with --pileup. |
| 30 Mar 2018 | Removed warning about clang compiler on OSX. |
| 01 Aug 2019 | added bash setup instructions. |
| 31 Jan 2022 | Review for CIAO 4.14. No updates needed. |
| 21 Mar 2023 | Replaced references to ${MARX_DIR} to ${MARX_ROOT}. |
| 27 Apr 2023 | revised AspectBlur description. |
| 09 Dec 2024 | Added note about MARX installation; happens by default with ciao-install in CIAO 4.17 or can be installed with conda. |