MMIRS mask making with xfitmask

These notes are based on those that can be found on this page:

https://www.cfa.harvard.edu/wiki/mmti/MMTI/MMIRS/ObsManual/MMIRS+Mask+Making

'xfitmask' is the software used to generate the mask files (*.msk) used to prepare the final design file (*.dxf) that gets cut into a mask. The final design file will be emailed to you after the mask has been cut. 'xfitmask' is available only as a 64-bit linux binary. Mask files generally must be submitted one month prior to the start of the next MMIRS observing run.

Prepare Inputs

You must choose a rootname for your masks. The rootname should be unique (click here to see rootnames that have already been used), may not begin with a digit and must be 6 characters or less in length. The identifier on the mask will be of the form <root><N> where N is a single digit.

The input catalog needs to have relative astrometry good to at least 0.2" and absolute astrometry good to within 1-2". The format of the input catalog is a starbase table with tab-delimited columns, e.g.

ra    dec    object    rank    type

-      -         -            -          -

12:23:29.923    -09:37:55.02    NGC1234    1    TARGET

12:22:52.345    -09:38:48.39    S23       9    BOX

The column headers must be lowercase and the line of dashes is required. The following is required for each column:

ra (J2000) in the form HH:MM:SS.sss

dec (J2000) in the form DD:MM:SS.ss

object (name of the target)

rank (1=must do; 2-5=high priority; 6-10=lower priority)

type (TARGET, for a target, or BOX, for an alignment star)

It is possible to specify the slit 'height' and 'width' by adding these columns, but they must be added for all objects. Additional columns (e.g. magnitude) are permitted and will be ignored by 'xfitmask'.

Alignment stars (i.e. those of type BOX) are used to position the mask and they must be the brightest object in their 2"x6" box. They should have H mags between about 13 and 17 and can all be given the same priority, usually low, e.g. 9.

The name of the input catalog must be <rootname>.targets. A center file, named <rootname>.center, must also be created, again, in a starbase table, e.g.:

ra dec -- -- 10:00:34.2087 2:12:00.00

You can verify that your input files are in valid starbase format using the starbase 'check' program:

check -v < <rootname>.targets

check -v < <rootname>.center

This routine will print out any lines in the files that do not conform to proper starbase format. If all is well, check will just return silently.

Run 'xfitmask'

'xfitmask' can be downloaded from here and installation instructions can be found here.

To run 'xfitmask', start a new terminal and change to the installation directory. For 2011A that would be <path>/fitmaskexport2011A. In that directory type:

source .fitmaskrc.cshrc (for csh/tcsh; source .fitmaskrc for bash/sh)

Then change to the directory containing the input and center files and type:

xfitmask <rootname>.targets <rootname>.center

Change the date of observation to sometime near the middle of the observing run. If you want to ensure that your mask is usable the entire time that the target is observable, use the Rise time for the Start time and (Set - Rise) time for the duration. Alternatively, if you intend to limit yourself to a shorter observation period, you can specify a more restrictive Start and duration by altering the Start field (Mon DD HH:MM YYYY) and Minutes duration of your observation.

Make sure you set the correct slit length and width.

Click 'Fit' and the program will cycle through all position angles and try to assign slits to objects. For a given RA,Dec,PA specification, targets are assigned to the mask in strict priority order, e.g. a rank 2 object will never displace a rank 1 object. At the end, alignment stars are added to the mask, possibly displacing targets, until 4 alignment stars are on the mask. Lower priority targets are displaced first. Once the targets are all assigned to the mask, then the merit function is computed.

Once this has finished click the 'Merit' button three times, this will order the various configurations from the highest merit (best) to the lowest (worst). Generally, the highest merit configuration has the most number of object allocated but, due to the need for guides stars and wave front sensor (WFS) stars, you may need to choose a configuration with a different PA that has a lower merit.

Clicking on one of the configuration lines (in the bottom of the GUI) will bring up a summary of how many targets of each rank have been matched on the right-hand section. If too many alignment stars are being allocated (you only need 4, but I go with 6 in case of any problems) you may want to remove some from your input catalog and run the fit again. Targets are de-allocated, starting from those with the lowest priority, to make way for the alignment stars. Clicking on one of the configurations will also give you a preview of the mask by bringing up a ds9 window with the mask on it, and the mask file and catalog in their own windows. If you click on a particular line in the mask file, the corresponding target will be highlighted in the ds9 window. The different colored circles represent different priority levels.

This feature allows you to browse and preview different configurations before creating the complete mask, especially look at the guide and WFS stars. Verify that there is a WFS star candidate (12<=R<=14.5 mag) in the inner ring of wfscamera 2. Verify that there is a guide star candidate (12<=R<=16 mag) in the inner OR outer ring of the "other" camera - nominally wfscamera 1. Make sure they are both really point sources (beware of double stars from the catalog). Confirm that the targets are in the slits. Finally, verify that the alignment boxes have unambiguous stars in them and that they are spread out over the mask as much as possible.

The parameters of the last fit run are saved, so if you return to the same directory and restart 'xfitmask' with the same targets, it will remember the parameter selections from the last run. To start from scratch, delete all the files except the *.targets, *.center, and *.fits files.

Click CreateMask after selecting your preferred configuration, this will ensure that the a complete set of mask files is saved for the configuration you really want. Then exit.

Collect all the files used to create the final masks using 'xfittar':

xfittar <rootname1> [...<rootnameN>]

Then submit the tar files to CfA and send an email notifying them that you uploaded the files. More details can be found here.