Introduction

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.

• Please make sure always to download the latest xfitmask, even if you have one already--it may be an earlier release, and you'll want to have the latest and greatest.

• Users at CfA must also download xfitmask; it is not available in any other form at CfA.

• Please be sure to read these instructions completely, as there will be changes for each new release.

• Please note: xfitmask does not create the final design (.dxf) file. The .dxf file is created at LCO from the mask files you send in, and will be emailed back to you. Please submit masks (.msk files only) to Dave Osip, dosip at lco.cl .

  ~The 2013A MMIRS mask submission deadline is 1 May, 2013, in order to allow 6 weeks for production and delivery prior to the start of the 2013A MMIRS campaigns on 16 June.~

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 2013A

1. Rotator limits adjusted for Magellan:
   • The new Software Rotator Limits are: -153.5 / +163.0, updated from previous values of -144.44, 166.97.

2. Grism and Filter selection update:
   • The grisms supported are now just J, H, HK; you no longer need to specify HK2 or HK3. xfitmask will now automatically use the H and HK grism higher orders of interest for the various filter combinations.
     • See the "Filters" section of the MMIRS Observing Manual [1] for details on filter and grism properties.

   • The filters supported remain: zJ, Y, J, H, K, HK

   • Creating a mask without specifying a filter and grism is still supported; simply check the "Open" box.

3. Overlapping projected spectra are now checked when both slits are alignment boxes.
   • Previously, overlapping spectra were only checked when two slits were both targets, or if one slit was a target and one was an alignment box.

4. Version Compatibility:
   • There is no internal format difference between masks made with xfitmask 2013A and earlier versions. Masks made with earlier versions will continue to work with the MMIRS observing software.

Mask Preparation Procedure

================

Prepare Inputs

================

1. Choose a rootname for each field
   • The rootname must be <= than 6 characters long, and may not begin with a digit. xfitmask will return an error if you use a rootname > 6 characters long, or beginning with a digit. Older releases of xfitmask (and why are you using one?): if you get an error message of the form "expected integer but got <rootname>.center", this is likely the cause.

   • The rootname must be a unique identifier. Since the masks are saved and stored for possible reuse in future runs, the rootnames *must be unique across all masks* : yours and everyone else's.

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

     • This mask ID will be in the .msk file, and will be used by the MMIRS mask installation and observing software. The mask ID will also be the root of the resulting .msk file name, and the mask ID will be engraved on the physical mask, so that the mask can be identified by the human who installs it in MMIRS. It is imperative that they all match exactly; if not, you may not be able to use your mask.

     • xfitmask will take care of this for you, but you must do your part and:
       • ~Do not rename the .msk file.~

     Once again, you must use a different rootname for each mask, and you must not rename the resulting .msk file.

2. Prepare an input catalog

   The input catalog 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 [2] 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 and will be ignored. Alignment stars should have H mags between about 13 and 17. The name of the targets file must be <root>.targets.

   NOTE: If you are not familiar with starbase, there is lots of information here: [3]

   The input catalog must specify:

   • TARGET objects with appropriate ranks

   • BOX objects to be used for alignment. It is important that the alignment star be the brightest object in the 2x6 arcsec box.
     • NOTE: The recommended alignment star magnitude range is 13.5 < H < 16, to avoid saturation during the exposure time required for alignment.

     • You need to include at least 4 possible BOX objects; otherwise you may not get any fits. 4 alignment objects provides optimal information to the MMIRS alignment software during observing. It may be possible, however, to align with as few as two BOX objects; see the "Troubleshooting" section below, for how to work around the 4-box minimum.

   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.

3. Prepare a list of field centers

   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:

   • Run the fit using the first centers file with a single entry. Select the best position angle (PA).

   • Edit the centers file by appending a new "pa" column and entering the position angle value from the selected fit.

   • Run the fit a second time with the first two centers files. The PA on the first center will be held fixed, the 2nd will be optimized.

   • Repeat the above 3 steps as needed, adding the selected PA from the previous fit to the corresponding centers file, and then adding one more centers file to the fit.

   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

=========================================

Currently we have only a binary distribution 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 tar file and unpack in <fitpath>: fitmaskexport2013A.tgz.

   Note: <fitpath> can be any directory you like.

   NOTES FOR UBUNTU USERS:

   You do not need a separate xfitmask distribution; you only need to use the provided bin.ubuntu directory as your ./bin.

   ./bin is linked by default to bin.redhat; to change this to use the correct Ubuntu ./bin, simply remove the "bin" link and recreate, it as follows:

   rm bin
   ln -s bin.ubuntu bin
   

   Ubuntu users will now also need to add the following link in the fitmask/bin directory (this will be fixed in the next release.)

   cd bin
   ln -s column check
   

   You only need to do these things once.

2. Start a fresh shell: Your path will be altered by the configuration file. You can exit the shell when you are done and restore your normal environment.

   sh (or tcsh or csh or bash)
   

3. Configure the runtime environment: Move to the <fitpath>/fitmask directory (cd <fitpath>/fitmask) and configure the runtime environment by typing (for bash/sh users)

   source .fitmaskrc
   

   or typing (for csh/tcsh users)

   source .fitmaskrc.cshrc
   

   The distribution includes the required starbase programs as well as a copy of ds9. This configuration alters your default path to ensure you are using the distributed versions rather than any local versions.

4. Test the installation using the Example subdirectory

   cd Example
   ./doclean
   xfitmask exampl exampl.center
   

   • When the GUI comes up, make sure it says "xfitmask 2013A" in the window title bar. If it doesn't, you have the wrong version of xfitmask and should retry the download. If you still have problems, please contact Anne Matthews (amatthews at cfa.harvard.edu.)

   • You will notice that the "Date" entry near the top will be "Sep 23" and that the computed "minutes" will be negative, because this sample field is not visible in Sept. (Just click Yes on any prompts about creating a mask outside the dates of the upcoming MMIRS run).

   • Edit the "Date" entry to "Apr 23" rather than "Sep 23"; several boxes will update and you should see that "minutes" is now 300.

   • Click the "Open" checkbutton to enable the filter and grism checkbuttons, and select the H/HK checkbutton.

   • Proceed by pressing the "Fit" button. You will see a number above the Start field, that will run quickly from 0-360 as it cycles through all the possible rotation angles.

   • When it is finished, press the "Merit" button to get a sort on the output table with the highest Merit at the top.

   • Click on the first line of the list (PA = -104), and you should get a ds9 display with overlays as well as windows showing the catalog list, etc.

   • In the ds9 display, go to frame 2, or use Frame->Tile Frames to see the projected spectra display (this was new in 2012B).
     • Try clicking on a mask slit in the mask text window to see the corresponding spectrum get highlighted in the ds9 frame.

     • Note this display shows another example of the slit-stacking feature which was new in release 2012B.

   • Click on "CreateMask" and it will overlay all the mask slits, box slits and catalog objects on the display, and write out the .msk file as well as other auxiliary info.

     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

=======================================

1. Start a fresh shell (if you haven't above) Your path will be altered by the configuration file. You can exit the shell when you are done and restore your normal environment.

   sh (or tcsh or csh or bash)
   

2. Configure the runtime environment (if you haven't above) Move to the fitmask directory (cd <fitpath>/fitmask) and typing

   source .fitmaskrc
   

3. Bring up the "xfitmask" GUI
   • cd to the directory with your target files (cd <maskpath> )

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

   • Usage:

     xfitmask rootname centerfile1 ... centerfileN
     

   • (See "Multiple overlapping masks" above for how to use multiple centers files.)

   • Specifying filter and grism pairs on the command line:
     • It is easiest to specify filters and grisms on the GUI, but if you wish, you can also specify the filter and grism on the xfitmask command line with the "-filter" and "-grism" switches.

     • Example:

       xfitmask rootname centerfile1 ... centerfileN -filter zJ -grism HK
       

     • When xfitmask comes up, you will see the box for zJ/HK checked in the Grisms and Filters area of the GUI.

     • Multiple filter/grism pairs:
       • Multiple filter/grism pairs are specified with space-separated lists in quotes, as follows:

         xfitmask rootname centerfile1 ... centerfileN -filter "zJ H" -grism "J HK"
         

       • Filter and grism pairs are created from by matching the nth element in both lists

       • The number of filters and grisms specified in each list must be equal

       • The above example will result in the filter/grism pairs zJ/J, H/HK being selected for the fit.

       • When xfitmask comes up, you will see the boxes for zJ/J and H/HK checked in the Grisms and Filters area of the GUI.

     • NOTE: If filter and grism are not specified, the default is "Open" (no filter/grism) and the "Open" box will be checked on the GUI.

4. 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:

   • Thres: List only the configurations that exceed this merit function value.

   • Check Guides: This box should be normally be left checked so that the program will ensure that proper guiding and wavefront sensing stars are available. Turn off this feature temporarily only if you suspect that you are not getting successful configurations because of a lack of guide stars.

   • Box Height & Box Width: The size of the box used for the alignment stars. The default of 7 arcsec should be fine for most purposes.

   • Slit Length: The default of 7" should be OK for point sources and will allow small dithers back and forth along the slit. If your source density is not particularly high, you should consider trying 10" slits for potentially better sky background subtraction.

   • Slit Width: The default is 0.5" arcsec which will give R=1000 with the HK grism. The smallest recommended slit is 0.4" which gives Nyquist sampling and R=1200, and the largest amount of spectrum uncontaminated by OH lines. For a continuum background (which we only have in K-band) the optimum slit width is about 1.5 x the FWHM.

   • YGap: This is the minimum gap between the end of one slit and the start of the next.

   • MFactor: This controls the merit function that is assigned to each configuration. The merit function is

     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:

   • Starting in release 2012B, the xfitmask GUI contains an area below the parameters section, where you can specify filter and grism pairs to use when creating the mask. This is a set of check boxes for each filter and grism pair. File xfitmask2013A.png shows the new xfitmask GUI.

   • The default selection is Open (Open box checked). The filter and grism check boxes are disabled.

   • Uncheck the Open box to enable the filter and grism check boxes.

   • Notice that only check boxes for combinations of filters and grisms that produce spectra on the detector chip are shown.

   • Check the appropriate box for the desired filter and grism pair.
     • Multiple filter/grism pairs may be specified by checking additional boxes. Only slits that fit in all the spectra for the specified filter/grism pairs will be selected, so this is more restrictive.

   • If you check the Open box again, the filter and grism boxes will be disabled and the selections will not be used for the fit. However, your selections will stay checked just in case you want to uncheck Open and go back to them.

   • To remove all filter/grism selections, click the Clear All button.
     • This will only work if the check buttons are enabled, so you'll need to uncheck Open if it is checked.

   • You must either check the Open box or at least one filter/grism box, or xfitmask will complain.

   • The filter(s) and grism(s) used are saved in the <rootname>.par file that is created with the mask. They are also noted in the .msk file.

   • Please see the "Filters" section of the MMIRS Observing Manual[4] for details on filter and grism properties.

5. Press "Fit" to start the fit process:
   • How it works: First the rotator angles are checked to make sure that the mask remains observable for the entire specified observation period. The rotator limits are currently set to -144.44 to +166.97 deg. 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.

   • The bottom section of the xfitmask GUI shows the list of configurations that exceed the threshold merit specified in the top section. The columns listed are: the configuration number, the merit function, the PA, and (in future) the rotator angles at the start, mid-point, and end of the observation period. The list can be sorted by clicking on one of the column-heading buttons. "Merit" will be the most useful of these.
     • Please note: the rotator angle column is not yet supported.

   • Click on one of the listed configuration lines, and a summary of how many targets of each rank have been matched will be displayed in the right-hand section. You will also get a preview of the mask in a ds9 window with the mask on it, and the mask file and catalog in their own text windows. In addition, a display of the projected spectra for the mask, showing spectra for all the filter/grism pairs selected for the fit, will appear in frame 2 on ds9.
     • The spectra are numbered to match the slit numbers from the mask, and increase from right to left.

     • The spectrum for slit 1 will be labelled <filter>_<grism>_<order> in the same color, for example, H_H_1, to assist with identification.

     • The spectra for each filter/grism pair selected are shown in a different color. Any higher orders are in the same color.

     • Select Frame->Tile Frames in ds9 to show the mask and spectra frames together.

     • Example of spectra display frame showing spectra for one filter/grism pair (H/H): xfitmask_2012B_blanc_H_H_slit_stacking.png

     • Example of spectra display frame showing spectra for two filter/grism pairs (zJ/J and H/H): xfitmask_2012B_blanc_zJ_J_H_H.png

     • If you have multiple masks in a fit, the spectra for each mask will appear in its own frame.

   • Target highlighting: If you click on a particular line (slit) in the mask file in the mask text window, the corresponding target will be highlighted in the ds9 mask window. The relevant slit will also be highlighted on the spectra display. This feature allows you to browse and preview different fits before creating the complete mask.
     • Example of mask and spectrum ds9 frames, with mask window, showing selected slit 22: xfitmask_2012B_blanc_H_HK.png
       • On this spectrum window, you can see the spectra for the higher HK grism orders, that mostly do not fall on the chip.

     • NOTE 1: if you have multiple masks, you must currently select the frame for each mask in order to have the spectrum selected when you click on a slit in the mask text window. You don't have to do this if you have only 1 mask.

     • NOTE 2: You can also click on a target in the catalog text window, and it will be highlighted on the ds9 mask window. Highlighting the relevant spectrum in the ds9 spectra window will be supported in a future release.

6. 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:

   • magenta Guide
   • red Rank 1
   • orange Rank 2
   • yellow Rank 3
   • green Rank 4
   • cyan Rank 5
   • blue Rank 6-8
   • purple Rank 9 and Boxes

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

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

9. Verify the slits for the selected targets

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

10. Verify the alignment, guide and WFS stars
    • Verify the stars in the alignment boxes are within this recommended alignment star magnitude range: 13.5 < H < 16,to avoid detector saturation at the longer alignment exposure times.

    • Verify that there is a WFS star candidate (<14.5 mag) in the inner ring of wfscamera 2

    • Verify that there is a guide star candidate (<16 MAG) in the inner OR outer ring of the "other" camera - nominally wfscamera 1

    • Verify that the candidate guide and WFS stars are really point sources (beware of double stars from the catalog).

11. Iterate as needed
    • You may select a different row from GUI's list of position angles to examine different options from the current fit.

    • You may alter other GUI parameters and rerun the fit.

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

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

14. Summary of mask vetting criteria:
    • Mask ID <= 7 chars, unique across all existing masks, and must not begin w/digit
      • Mask ID is the "label" field in the .msk file

    • Mask name ("label" field again) is the same as the root of the .msk file name
      • You can check this with

        grep label *.msk
        

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

    • Start date is on or near the planned observation date
    • WFS star (mag 12.0 - 14.5) in center part of Camera 2 (or Camera 1 if necessary)
    • Guide star (mag 12.0 - 16.0) in Camera 1 (or Camera 2 if WFS star is in Camera 1)
    • Guide and WFS stars are point sources
    • At least 4 alignment boxes are given, and are well-distributed around the mask
    • These alignment boxes are not also targets
    • The stars in these alignment boxes are within the recommended alignment star magnitude range, 13.5 < H < 16
    • The alignment boxes appear on the .ds9 where the mask (.msk) file says they do

15. Exit the current shell when done with xfitmask

This will restore your normal path and environment.

exit

===========================

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.

============================

Feedback

• We welcome your comments and suggestions about xfitmask any time; please email them to Anne Matthews, amatthews at cfa.harvard.edu .

=================================

Troubleshooting

• No fits when running fitmask?
  • This problem is most frequently caused by not enough alignment box targets. Check to see if your .targets file contains fewer than 4 alignment box targets, and add more as you can. If the field does not offer 4 possible alignment targets, you can go to as few as 2 (but no fewer), though this is not optimal. To work around this limit, edit the file rootname.par in your mask fitting directory. Change the "boxmin 4" line to "boxmin 3" or "boxmin 2"; restart xfitmask and rerun the fit.

==========================================================

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

3. Notify us of the files via email

   Send an email with the ftp directory and filenames to:

   • bmcleod at cfa.harvard.edu
   • amatthews at cfa.harvard.edu

   along with a contact email address in case we need further information concerning the mask designs.

============================================================================

Troubleshooting

• No fits when running fitmask?
  • This problem is most frequently caused by not enough alignment box targets. Check to see if your .targets file contains fewer than 4 alignment box targets, and add more as you can. If the field does not offer 4 possible alignment targets, you can go to as few as 2 (but no fewer), though this is not optimal. To work around this limit, edit the file rootname.par in your mask fitting directory. Change the "boxmin 4" line to "boxmin 3" or "boxmin 2"; restart xfitmask and rerun the fit.

============================================================================

Creating specialty slit shapes

===============================

NOT CURRENTLY SUPPORTED. THIS SECTION NEEDS TO BE UPDATED.

Fitmask can handle slit shaped defined by arbitrary polygons. The simplest way to create a slit to mask a unique astronomical feature that you would like to target is to draw a region around an image of the target in ds9.

1. Obtain an image of the target area with has suitably accurate WCS.
2. Display your input catalog on ds9 as a region. Check that your alignment box stars are correctly overlaid on the image.
3. Delete all the regions.
4. Create a single circle region at the "center" of the target feature. This circle will be used as the zero point of a relative polygon definition.
5. Create a single polygon region that outlines the slit feature.
6. Run "reg2fitpoly". This program reads the two regions defined above and outputs a fitmask input catalog with one custom slit target.

   	$ reg2fitpoly ds9 xxx Arc
   

Custom slit target example:

Arc	-1.9800000001168883	0.32291999999909393	-0.5039999999553402	4.7019599999995165	1.9079999998893982	7.579440000000126	12.1679999999742	14.943960000000267	13.17599999988488	14.943960000000267	2.9519999999138236	7.579440000000126	0.5399999998644489	4.7019599999995165	-1.0080000001153167	0.32291999999909393	-0.46800000004623143	-4.754880000000838	1.1879999998654966	-7.842240000000089	6.228000000032807	-15.115680000000609	5.291999999940344	-15.115680000000609	0.1799999999548163	-7.842240000000089	-1.4040000001386943	-4.754880000000838

ra         	dec        	type
--         	---        	----
22:47:11.701	-02:05:38.18	Arc

Using an editor merge your alignment star catalog with the custom slit catalog. You can also create duplicate target rows of type "Arc" (or whatever) to place your custom slit at different positions on the mask.