Guide to Making LDSS-3 Multi-Object Masks

This guide is intended to assist observers with making multi-object masks for LDSS-3. I have borrowed liberally from both Ken Clardy's own instructions on the code and from the IMACS Users' Manual. I am only covering the basics with this guide. There are many more details that can be found in Maskgen documentation, which also gives instructions on how to download the software.

LDSS-3 masks are cut by a computer-numerically-controlled laser-milling machine that resides in the Astronomer Support Building. The Technical Support Group at Magellan is responsible for producing the multislit masks. Please note that you must submit your slitmask files 6 weeks prior to your run to guarantee that they will be cut in time. The current fee for producing LDSS-3 slit masks is $35 per mask.

The code used to create LDSS-3 masks is identical to the code used for IMACS masks. Thus, if you've made IMACS masks, you probably don't need this guide. The LDSS-3 masks are cut out of the slitmask blanks used for IMACS. In principle, seven LDSS-3 masks can be cut out of a single IMACS blank. IMPORTANT NOTE: While it is sufficient to submit .SMF files for IMACS, for LDSS-3 users are required to create and submit .nc files.

The code used to make slitmasks was originally written by Ken Clardy (Carnegie Observatories) and is presently maintained by Chris Burns (Carnegie Observatories). Each institution that needs slitmasks should already have a copy of the software on their local system. If your intitution does not, please review the documentation linked above or contact (maskgen at obs.carnegiescience.edu) to get a local copy.

Getting Started

Before running the mask generating software, observers must prepare coordinate files for their targets. It is also necessary to have a number of alignment stars on the mask. We recommend that observers have a minimun of 4 alignment stars (better to have about 6). The stars should be located at different parts of the field, but not too close to the edges of the field. The stars should be no brighter than about 16th magnitude to avoid bleeding from saturation onto nearby slits. Our experience is that stars in the magnitude range 17-18 work best. You can use stars as faint as about 20th magnitude, but will need longer exposures during the alignment process.

The code requires equatorial coordinates (i.e. RA and Dec) for all targets. The alignment stars and target objects can be placed in a single file or in separate files. The code determines the type of object based on the first character in each row (see below).

The columns in the input file(s) correspond to the following quantities:

1. Object name. Note that the first character of this field must be a "@" character for a target object (i.e. @NGC1132) and a "*" character for a reference star (i.e. *star1). See Figure 1 and 2.

2. R.A. in hours with decimals or sexigisimals

3. Dec. in degrees with decimals or sexigisimals

4. Priority as floating point value. Often this will be the magnitude of the object. This column is optional.

5. If this column is an integer, it refers to the "use count" (i.e. how many times this object has appeared on a mask so far - see the discussion of the .obw file below). If a decimal point is present, the code interprets this field as the slit width. This is only useful if you want the slit width to vary from object to object. Otherwise, a global slit width can be easily set elsewhere. This column is optional.

6. Slit width (arcseconds). This column is optional.

7. Slit shape: 0=Circle, 1=Square, 2=Rectangle(slit), 3=Spaced Cross. This column is optional.

8. Slit length left of object (arcseconds). This column is optional.

9. Slit length right of object (arcseconds). This column is optional.

10. Slit angle (tilt in degrees).

The "#" symbol can be used to comment out a line.

It's probably best not to mix faint and bright objects on a single mask - this makes it difficult to estimate your exposure time if conditions are variable.

Setting Up the Mask Parameters

With the object files prepared, the astronomer runs INTGUI, a GUI used to create an observation file. Here the observer enters the field center, chooses the camera, grating or grism, wavelength range, etc., and specifies default values for slit length and width, and the possibility of a minimum gap between slits. This information is recorded in FILENAME.obs, where the observer has chosen an 8-character FILENAME to identify the mask ("Observ. File" field). The mask name may have only alphabetic and numeric characters, and no embeded spaces. It must serve as a part of a file name, and that file name must be acceptable to a DOS program at a later time. The observer can also give a title to the mask (this will be carved onto the edge of the mask). There is a limit of 16 characters for the "Observer" field.

When entering the R.A. and Dec. it is always good form to select the proper equinox from the pull-down menu. A standard value such as 2000.0 is preferred, but you can put in whatever you like. The value for "today" is the time of mask generation, not of observation.

The R.A. and Dec. positions are special numeric fields. When you start entering data the field goes all red. This indicates that a return is needed when you finish to store the data. For R.A. and Dec. the format is any of the following, all give -02:12:36 = -2.210

-02:12:36
-2 12 36
-2.210
-2 12.6

The value is changed to the dd:mm:ss.ss format after the user hits the "enter" key.

The instrument is mounted on the telescope's Naysmith focus rotator, which has only 360 degrees of rotation. If driven to its limit (of +/-180 degrees in rotator angle) it will then need to be driven back around by 360 degrees to start up again. That is best avoided during an observation. If this would happen with the position above the horizon, a "!ROTATOR!" appears to the right of the window to indicate a problem. If it happens closer than 6 hours to the upper meridian, this warning is in red. Otherwise, the "(OK)" appears. The default position of 90 degrees is OK at all declinations north of the latitude of -29 degrees. South of -29 degrees, you should replace the default value of 90 with 270 degrees, causing the instrument to still have dispersion north-south (actually south-north) and the slits will still run east-west. If your project needs a particular slit position angle, try it, and if a rotator conflict is indicated, change it by 180 degrees to get the conflict to go away. The filename of the list of candidate objects, call it OBJECTS.cat is entered here. By choosing the "skyview" option a map of the star field -- the same as will be seen by the Telescope Operator (with GMAP) to set the telescope and select guide stars -- the user will verify that both a guide star and a Shack-Hartmann star are accessible. Field centers can be shifted or fields rotated in the (unusual) event that one or both are not available. Shack-Hartmann stars fainter than 16.0 may be problematical.

The "Slit Pos. Ang." needs lots of explanation. A position of 90 degrees means that the slit runs at position angle 90 degrees on the sky, or east-west. This positions the instrument itself so that the dispersion direction is north-south.

A graphical display of the rotator problem(s) is present below the Declination and Slit Angle windows. It shows the object's above horizon arc from rise (east) on the left to set (west) on the right. Tic marks appear every hour, larger ones at 5 hour intervals. This band is green where there is no problem, and a blue dot indicates the hour angle(s) where the rotator has it's 180 degree problem.

Temperature is currently unused, but we plan to be able to correct for the thermal expansion of the mask during cutting being different from its size during observing. This value is the expected observing temperature, in degrees Centigrade.

To define your instrument and disperser, first select "LDSS" from the instrument pull-down menu the proper camera. Then, select the disperser from the "Disperser" menu. Note that although there are six dispersers listed, only three are generally available to observers (VPH red, VPH blue and grism Red (also known as medium redium)).

To maximize the number of objects that fit on a mask, it may be adventagous for some observers to limit the wavelengths range of the spectra. This can be done by putting a filter in the beam. For the medium red and VPH red grisms, second order contamination can be very important redward of about 7000A. In these cases, observers may want to use the existing OG590 filter to block light blueward of about 5900A. The observer should specify the wavelength range of interest in the "Filter" boxes. It is worth noting that because of the relatively high dispersion of the two VPH grisms, it is often difficult to get more than about 20 objects on a mask unless one significantly restricts the wavelength interval with a filter.

The slit specifications are in arc seconds. The full width of the slit is given, and it is centered on the object. There are two lenghts, to the "left" and "right" of the object position. In the normal orientation, with position angle of 90, "left" is East on the sky.

Below these slit lengths are the slit "Uncut" lengths. Those are the amounts of each left and right slit which are not to be cut in the mask. This is for a special mode known as "nod-and-shuffle". Leave these items zero unless you are using this special mode.

The "Overlap pixels" is the amount in pixels on the detector which adjacent spectra are allowed to overlap by. The default is a small negative number (typically -2) which requires a small gap between any two spectra.

The alignment hole size is the width and length of the square hole centered on each alignment star position. The default provides a 2 millimeter square hole in the mask for each alignment object, and is about right.

The repeat counts require a little explanation. Many users have very crowded fields, and cannot get even a majority of their objects on a single mask. They want to make multiple masks, with different objects on each one. For this purpose, the mask generation program produces a file, ".obw" which is in the object catalog format and includes for each object the count of the number of times that object has appeared on a mask. This file is then used as input for the "next" mask in place of the original catalog file. The repeat count is then the number of times an object is allowed to be repeated for this mask. An object whose current use count exceeds the repeat count allowed is marked to not be used for the mask. Usually, a repeat count of zero is selected, those objects with a use count of 1 (they got used on one of the previous masks) are then not used, and objects with a use count of 0 are considered for the mask.

Since reference objects actually HAVE to be present, their repeat count is defined separately to allow reference objects to appear on the later masks in the set.

The "Ref. Sel." parameter is a way of managing multiple reference stars on a set of masks to allow different reference stars on the masks and thus not always hide the same parts of the sky from possible observed objects. This parameter chooses only one of each "n" reference stars to appear on the mask. By combining this with the reference star repeat count, several different sets of reference objects may be selected repeatedly for subsequent masks.

The "MustHave" window specifies a priority at and above which an object is immune from removal due to conflict. Higher priorities are numerically smaller. The default value is -2.0.

The "Pdecide" window specifies a priority below which objects will be scanned and removed based on number of conflicts. The node with the largest number of conflicts will be removed first, and if several have the same number, the one with lowest priority is removed. This will tend to maximize the number of objects retained for the mask, with the priority being a secondary consideration. The default is 0.0. See the documentation for the code for a description of how the code picks objects to put on the mask. Note that this method is very different from the one used in the old LDSS-2 mask software.

The "Object Files" button pops up a sub-window in which one or more file specifications for object files may be entered. This is where you tell the mask generation program where your objects are. At least one list of object positions is expected, and multiple files are supported. One can put the alignment star positions in a separate file for example, as another way of managing separate lists of reference positions. Or, several programs might produce independent lists of objects in the same field. In any case, the mask generation program reads all the object files into the same internal data structure, effectively concatenating all these lists.

When you've finished filling out all of the fields, save the file and exit. If your field will have a rotator flip sometime during the night, the code will launch a window with a warning. Click "ok" and the progam will exit.

Making the mask

Next type "maskgen FILENAME", where FILENAME is the name of the file created by "intgui". The mask-making program is very sophisticated in that it maps where the spectra will appear on the detector in order to assess conflicts between the objects. Given the constraints entered in the GUI and the data file, the program will automatically select the maximum number of objects that can be accommodated in the slit mask. Maskgen will launch a window displaying the resulting mask (Figure 5). On this image, the alignment stars are plotted as open green circles and the objects as filled green circles. Blue lines are used to show the outline of the slits and boxes (to see these the user may need to zoom in using the "In" button). The large outer red circle shows the edge of the slit mask. Users should make sure that they have an adequate number of alignment stars on the mask. The user can also change from mask coordinates to detector coordinates to see where the spectra will fall (Figure 6).

Maskgen produces the file FILENAME.SMF, which is a description of the mask in ascii form. Also created by maskgen is FILENAME.obw. This contains an abridged version of the catalog file that is used to keep track of the objects that have been targeted. This file can be used to make subsequent masks that avoid duplication. The first four columns columns are the same as those in the input coordinate list, but the 5th column is now the "use" parameter (i.e. a value "1" appears if the objects was used on the mask and "0" appears if it was not). By setting "Repeat Obj" to "1" for the next mask you make of this field, the code will automatically discard all of the objects that were used on the first mask. To use different alignment stars, "Repeat Ref" should also be set to "1".

Creating the mask files to submit to Chile

As of September 2005, users must submit .nc files for their masks. These .nc files are created from the .SMF files using the program "maskcut" which is part of the standard mask making software. Because seven masks can be made from a single IMACS blank mask, "maskcut" has been designed to stitch together up to seven LDSS-3 masks. To run "maskcut", put all of your .SMF files in a single directory. Typing "maskcut *.SMF" will then make the appropriate .nc files. Note that if you have seven or fewer .SMF files, this will produce a single .nc file. If you have 8 or more .SMF files, you will get multiple .nc files (i.e. one for every 7 .SMF files).

As of February 2022, the mask-blanks stock is critically low. For this reason the science programs that need to cut their masks in the central position only, should follow the instructions below until further notice.

Experiments with LDSS3 masks indicate that the blank position4 only has small measured offsets at +/- 1.5 pixels or less and therefore astronomers are requested to extend slits by about 0.5” in each direction, when possible without conflict, so that the masks can be cut from used blank stock at position4. In order to achieve this, when creating the .nc file, the same .SMF file needs to be repeated 5 times, so that positions-0 to 4 are populated. Then the local crew can select and cut only position-4. 

A note on how the code selects objects

It is worth emphasizing that the current code makes masks in such a way to maximize the number of objects on the mask. While this is probably sufficient for scientific programs with large lists of targets of equal priority, it may not be sufficient for some programs. In particular, the code chooses objects for the mask based on the number of conflicts with other objects: objects with the most conflicts are removed from the candidate list and then the code recalculates the conflicts of the remaining objects, throws out the most conflicted sources again, and so on. If you have a list of objects with varying priority, you may find that the code picks lower priority objects simply because they have fewer conflicts.

One can get around this to some extent using the parameter "Pdecide" in "intgui". "Pdecide" allows the user to pick a priority number (in most cases a magnitude) below which the selection is made based on priority and not the number of conflicts. In this case, the algorithm based on conflict count runs first, and is applied only to objects with a lower priority (numerically greater) than Pdecide. Any object with priority lower than the Pdecide which conflicts with an object of priority higher than Pdecide is eliminated. In all of these decisions, when two objects are otherwise similar, having the same priority and conflicts, the final choice is by the order in which they were read in initially. The one read earlier will override the one read later. This is true for duplicates, and both kinds of conflict resolution algorithm.

Alternatively, observers may designate targets as "must haves" by giving them a priority value of -2 (or whatever value this parameter is set to when "intgui" is run). However, it is important to make sure that your "must have" objects do not conflict with each other. Last updated: September 22, 2005 by John S. Mulchaey, modification by D. Osip 2018