Page Last Updated : Jan 16 14:59
Introduction to xfitmask for 2015A:
MMIRS slit masks are laser cut into anodized aluminum sheets. "xfitmask" is the software used to generate the mask files used to prepare the final design file that gets cut into a mask. This software must be run by observers, by downloading a binary distribution to a compatible 64-bit linux box (details below). This download is a quick and simple process that does not require any building. If you do not have access to a compatible computer, please contact Brian McLeod about getting a short-term ( 4-week ) CF guest account on the Center for Astrophysics (CfA) system.
The final cost is approximately $300/mask. Billing will not be to your institution. Instead, you will be billed for mask costs along with your room and board costs for the observing run (which can now be paid via credit card on-site). Reimbursement of mask costs should be handled by individual observers and their host institutions.
Summary of New Features in xfitmask for 2015A:
Summary of New Features in xfitmask for 2014B
Summary of New Features in xfitmask for 2014A
Summary of New Features in xfitmask for 2013A
Mask Preparation Procedure
Prepare Inputs to xfitmask
Click here to see a list of mask IDs that have already been used in previous runs: MMIRS Slit Mask Identifiers.
xfitmask will create an identifier for the mask, of the form <rootname><N>, where N is a single digit.
For example, if you choose rootname "mymask", the mask ID will be "mymask1" for a single mask. If you optimize multiple masks simultaneously, using rootname "mymask", you will end up with a sequence of numbered mask IDs, e.g. "mymask1", "mymask2", "mymask3".
Once again, you must use a different rootname for each mask, and you must not rename the resulting .msk file.
This input catalog is a list of targets, and needs to have relative astrometry good to at least 0.2" and absolute astrometry good to within 1-2", so the alignment stars end up in their holes the first time around. The format of this input catalog is a starbase table  with the following tab-delimited columns:
ra (J2000) HH:MM:SS.sss dec (J2000) 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)Here is an example file showing the correct format: short.targets. Additional columns (e.g. magnitude) are permitted, but will be ignored. However, note that alignment stars should have H mags between about 13 and 17 for the best alignment. The name of the targets file must be <root>.targets.
NOTE: If you are not familiar with starbase, there is lots of information here: 
The input catalog must specify:
Optionally, you may also specify the height and width of slits on a target-by-target basis by including columns called "height" and/or "width" in your targets file. If you include these columns, you must include their values for every TARGET line.
Starting in xfitmask 2014A, you now also have the option to specify the desired wavelength or wavelength range you wish to observe, for one or more targets, by adding a new column called "wavelen".
a. Simplest case: a single field center. This center must be stored in a starbase table named <root>.center For example: short.center. The program will optimize over rotation angle using this center position.
b. Multiple overlapping masks, each at a fixed center position. In this case you would create multiple center position files, named <root>.center<N> each with a single entry. In theory you can optimize over position angles on each slit simultaneously, but this will take 360(raised to N) optimizations, where N is the number of masks. In practice you can optimize only N=2.
A more practical approach is as follows:
If you have multiple overlapping masks, you might want to allow objects to be duplicated onto a second mask if no other object would taken that spot on the mask. This can be accomplished by putting duplicate entries in your targets catalog and reducing the priority of the duplicates.
c. Optimize a single mask over a grid of positions. For this case, you will use a single centers file with multiple lines. Each position will be checked for all rotation angles.
d. Optimize multiple masks over a grid of positions. As in b), you will have multiple files, but now each will have multiple lines. The optimizer will check all combinations of the center files. So if you have 4 positions in each file, a total of 16 position combinations will be checked, each at 360 different position angles.
If you don't supply a FITS file, then xfitmask will download an image from the DSS. The name of the fits must be rootname.fits. Sometimes the xfitmask program tries to load the dss image before it is completely flushed, and you might get an error. Check to see that the fits file was loaded (and saved in your current directory) and re-try the "CreateMask" button.
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. Since starbase is all about "tab" whitespace, this tool will help you find whitespace issues which are difficult to see. Blank lines at the end of these files are also not allowed.
If all is well, check will just return silently.
Install and try out the xfitmask package
We currently offer binary distributions of xfitmask for Linux (Fedora or Ubuntu) 64-bit. If you do not have access to a compatible machine you will need to contact Brian McLeod to set up a short-term CF guest account on the CfA computer system for the purpose of mask design.
chmod +x xfitmask
cd Example ./doclean xfitmask exampl exampl.center
You can compare your output with what was generated here in the "output" subdirectory, though the files may not match exactly.
Run the Mask Fitting Software xfitmask
Please note: we strongly recommend using a separate directory for each single mask or set of multiple masks. This will help maintain unique root names, as noted above. Also, you must change to the relevant directory before running xfitmask; you cannot do it from inside xfitmask.
xfitmask rootname centerfile1 ... centerfileN
xfitmask rootname centerfile1 ... centerfileN -filter zJ -grism HK
xfitmask rootname centerfile1 ... centerfileN -filter "zJ H" -grism "J HK"
Fill in the date of your observation in the Date field, in the form Mon DD HH:MM:SS YYYY, e.g. Jun 18 12:00:00 2013. The default date shown is the start of the upcoming MMIRS run, or the last date used if you have already run this mask. NOTE: ALL 4 DATE ELEMENTS ARE REQUIRED, or you will get a syntax error. xfitmask will also warn you if you enter a date that is before the current year or after the end of the upcoming MMIRS run, but you can continue if you do want to do this.
Wait a moment and the program will fill in the time when your target becomes observable ( Rise ), the time it transits ( Transit ), and the time it ceases to be observable ( Set ). A target is observable when it is above 30 deg. elevation and the sun is more than 12 degrees below the horizon. The Airmass is also shown for Rise, Transit, and Set.
A default Start time and a maximum duration ( Minutes ) will also be filled in every time that you enter a new "Date". xfitmask will ensure that the rotator remains within range for the duration of your observation. 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. This could potentially give you better target matching as more position angles will be tried. We recommend starting with the longest possible observation window.
Sum over rank of N(rank) (1. + MFactor rank)(1. - rank).See this file for a plot of the weights for various values of MFactor: merit.ps. Note that the merit function is not used to assign targets to a mask, only to order the various trial masks.
Filters and Grisms:
Click on "CreateMask" to display the results from the selected row of the configuration list and create the complete mask for the selected fit. Again, the mask will be overlaid on a ds9 window and the resulting mask file will be displayed in a new window. As before, if you click on a particular line in the mask file, the corresponding target will be highlighted in the ds9 window.
The targets are color coded in the ds9 display as follows:
NOTE: Any subsequent clicks on "CreateMask" will use the same fit, unless you select a different one from the configuration list. This is also true if you start up xfitmask with existing fit files from a previous run; "CreateMask" will use that fit selection again.
The ds9 overlay file shows the geometry of the instrument. The 4'x7' IR array is drawn in the center - with the requested slits and alignment boxes shown.
Outside this box are two nested "wfs camera" regions, 1 and 2, on either side of the center array. To ensure accurate and stable alignment there must be a valid star in each of the 2 cameras. One camera/star will be used for simple guiding and the other camera/star will be used for guiding+wave-front sensing (WFS) during the observation.
The criteria for the WFS star are stricter than for the guide star. The WFS star must be 12<R<14.5, whereas the guide star can be fainter with 12<R<16). Also the WFS star must be in the inner region of the wfs camera outline. The Guide star can be in either the inner or outer region of the wfs camera.
It has been determined that the optics from camera2 are better than those from camera1, so it is preferred to have the WFS star on camera2 if at all possible. The fitting software should ensure the availability of appropriate stars - but it does not ensure that the WFS star is in camera 2.
The alignment boxes must have unambiguous stars in them.
Also, verify that there are at least 4 alignment boxes and that they are not all clustered together in one part of the mask; they should be spread out over the mask as much as possible.
Finally, verify that none of the alignment boxes are also targets (they should only have purple circles around them. Even if a box is also a target, it will still be cut as a box.
Confirm that the target is in the slit (you may need to overlay a catalog in DS9).
NOTE: it's a good idea to do this (start fresh) if you are having difficulty getting the results you want.
ALWAYS, ALWAYS, ALWAYS press CreateMask as the last action at the end of each mask design and then exit the software. xfitmask will warn you if you try to exit without doing this. This will ensure that the a complete set of mask files is saved for the fit you really want. If you fail to do this then the final msk file may _not_ match the design file that is manufactured, presenting problems at the telescope. The results of the most recent CreateMask are saved in the ./CompleteMask subdirectory of the current directory.
grep label *.mskand make sure the result matches the root of the .msk file name. This is just to double check that you did not accidentally rename the .msk file output by xfitmask. As noted above, every mask must have a unique "label", and it must be the same as the root of the .msk file name.
Deliver Final Mask Designs
If You Have Problems Making Masks: Sending Files to CfA
If you have problems making your mask(s), it will help Anne debug the problem if you send her all the files as follows:
xfittar root [ ... rootN ]
The above tar files should be deposited on the CfA's incoming anonymous ftp account:
ftp cfa-ftp.harvard.edu Name: anonymous Passwd: ftp> cd incoming ftp> mkdir yourname ftp> cd yourname ftp> put yourfiles ftp> quit
If you resubmit a file you will need to rename it, as files cannot be overwritten on the ftp server.
Send an email with the ftp directory and filenames to:
along with a contact email address in case we need further information concerning the mask designs.