Page Last Updated : Jul 16 16:53
Front Page Help  |  Recent Changes  |  Orphans Make Dir  |  Edit This Page  |  Attach File Set Access

Introduction to xfitmask for 2014B:

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 2014B:

  1. Support for new filters and grisms:

    These new filters and grisms are now available for selection in the grisms and filters section of the xfitmask window.

  2. Updated angle for HK grism, which was taken out and reinstalled in run 2014A.

  3. Run and mask creation date are now written out to the .msk file.

  4. Version Compatibility:

Summary of New Features in xfitmask for 2014A

Summary of New Features in xfitmask for 2013A

Mask Preparation Procedure


Prepare Inputs to xfitmask


  1. Choose a rootname for each field

  2. Prepare an input catalog (.targets 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 [1] 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: [2]

    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".

  3. Prepare a list of field centers (.center file or files)

    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.

  4. Optionally supply a FITS file of your field with a WCS that matches your catalog.

    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.

  5. Verify that your input files are in valid starbase format using the "check" program:, where "rootname" is the name of your .targets and .center file.

    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.

  1. Download the xfitmask program for your version of Linux:

  2. On your computer, rename this file to "xfitmask", and set its mode to executable:

    chmod +x xfitmask

  3. Test the installation using the Example subdirectory:

    1. Download the xfitmask example tar file: xfitmaskExample2014B.tar

    2. Unpack it in a directory anywhere you like and do the following steps, which assume you've put the files in directory "Example".

      cd Example
      xfitmask exampl exampl.center


Run the Mask Fitting Software xfitmask


  1. Bring up the "xfitmask" GUI

  2. Configure the GUI Parameters

    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.

    Additional parameters:

    Filters and Grisms:

  3. Press "Fit" to start the fit process:

  4. Display the results and create the complete mask:

    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.

  5. Guide and WaveFrontSensor(WFS) geometry

    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 camera1 are not as good as from camera2, 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 1.

  6. Verify the alignment boxes

    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.

  7. Verify the slits for the selected targets

    Confirm that the target is in the slit (you may need to overlay a catalog in DS9).

  8. Verify the alignment, guide and WFS stars

  9. Iterate as needed

  10. 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, .centerN, and .fits files. If you don't want to delete the files, simply copy the .targets, .centerN, and .fits files to another directory and run xfitmask there.

    NOTE: it's a good idea to do this (start fresh) if you are having difficulty getting the results you want.

  11. WARNING!

    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.

  12. Summary of mask vetting criteria:


Deliver Final Mask Designs


  1. Please email your final .msk file(s) to Dave Osip at LCO: dosip at lco.cl. The .dxf file will be emailed back to you.

  2. We recommend that you save the rest of the files associated with your mask by copying ./CompleteMask to somewhere safe and memorable for you. If there are any problems with your mask during observation that might be related to xfitmask, these files can be extremely helpful to CfA for debugging.






If You Have Problems Making Masks: Sending Files to CfA


  1. Collect all the files used to create the final masks

    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 ]

  2. Submit the files to the CfA

    The above tar files should be deposited on the CfA's incoming anonymous ftp account:

    ftp cfa-ftp.harvard.edu
    Name: anonymous
    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.

  3. Notify us of the files via email

    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.



Attachment Author Date Size Actions
fitmaskexport.tgz mo [c/o] 08-24-2010 12M Delete
fitmaskexport.ubuntu.2010-08-07.tgz mo [c/o] 08-07-2010 15M Delete
fitmaskexport.ubuntu.2010-08-16.tgz mo 08-16-2010 13M Delete
fitmaskexport.ubuntu.2010-08-19.tgz mo 08-19-2010 13M Delete
fitmaskexport.ubuntu.2010-08-24.tgz mo 08-24-2010 13M Delete
fitmaskexport2011A.tgz amatthew 04-07-2011 26M Delete
fitmaskexport2011B.tgz amatthew 08-29-2011 26M Delete
fitmaskexport2012A.tgz amatthew [c/o] 01-11-2012 26M Delete
fitmaskexport2012B.tgz amatthew 08-22-2012 26M Delete
fitmaskexport2013A.tgz amatthew 03-29-2013 26M Delete
merit.ps bmcleod 02-17-2010 111K Delete
rootnames.txt amatthew 05-23-2011 912 Delete
short.center amatthew 04-18-2013 38 Delete
short.targets amatthew 04-18-2013 702 Delete
xfitmask2012B.png amatthew 08-22-2012 80K Delete
xfitmask2013A.png amatthew 03-29-2013 92K Delete
xfitmask2014B.png amatthew 07-16-2014 89K Delete
xfitmaskExample.tar amatthew 02-27-2014 4.5M Delete
xfitmaskExample2014A.tar amatthew 07-16-2014 4.5M Delete
xfitmaskExample2014B.tar amatthew 07-16-2014 4.5M Delete
xfitmaskRedHat amatthew 02-27-2014 21M Delete
xfitmaskRedHat2014A amatthew 07-16-2014 21M Delete
xfitmaskRedHat2014B amatthew 07-16-2014 21M Delete
xfitmaskRedHat_CentOS_5.10 amatthew 03-11-2014 21M Delete
xfitmaskUbuntu amatthew 02-27-2014 16M Delete
xfitmaskUbuntu2014A amatthew 07-16-2014 16M Delete
xfitmaskUbuntu2014B amatthew 07-16-2014 16M Delete
xfitmask_2012B_blanc_H_HK.png amatthew 08-22-2012 667K Delete
xfitmask_2012B_blanc_H_H_slit_stacking.png amatthew 08-22-2012 21K Delete
xfitmask_2012B_blanc_zJ_J_H_H.png amatthew 08-22-2012 21K Delete