AUTOSLIT3                       October 1997, last update Dec 2011                by Judy Cohen, Patrick Shopbell, and (in 1997 Douglas Clowe) Table of Contents Quick Overview Using Autoslit Autoslit3 Parameters The Interactive Display Important Notice for Users -- Please Read This (added July 2011) Slit Widths Supported The Special Slits An Example of a Parameter/Special Slit file The Object List File Priorities and Object Assignments The Gaps in the CCD Mosaic  (added July 2011, deleted section on bar in          slitmask holder, which is no longer in use) Checking the Slit-Masks Astrometry Coordinate Systems Coordinate Change for the Milling Machine Engineering Mode Maximum Number of Slits Programming Considerations AUTOSLIT.INC The Output from AUTOSLIT3 (updated July 2011, adding region file) Other useful files Future Upgrades Comments and Suggestions Appendix A  ftp and compile instructions Appendix B  List of required files Appendix C  Example of a parameter/special slit file Appendix D  Example of an object input file Appendix E  Example of output files Appendix F  Alignment of Gratings and Mirror in LRIS Appendix G  Layout of the Mill Coordinate System Quick Overview     AUTOSLIT is a program designed to compute the slit positions for the     slit mask of the LRIS spectrograph.  AUTOSLIT is based upon AUTOFID2,     a similar program for the NORRIS spectrograph, by Alain Picard and     John Cromer.  AUTOSLIT3 is a complete rewrite of earlier versions     of AUTOSLIT carried out to incorporate the additional flexibility in     designing slitmasks to be produced by a numerically controlled mill,     to improve the astrometric model, and to add other desirable new     features.     Earlier versions supported the numerically controlled punch     to fabricate multi-slit masks for LRIS; AUTOSLIT3 supports only     the mill and allows LRIS observers to take full advantage of its     many new capabilities in designing slit-masks.     AUTOSLIT version 3.20 adds one new output file (a region file compatible     with the display server DS9), provides an indication     of the current gap between the CCDs in both the LRIS-B and LRIS-R     CCD mosaics, and outputs the center of field in the epoch J2000.     Pickoff mirrors on slitmasks are no longer supported at Keck nor in this release.     At present for version 3.20 and higher, until further notice, it is strongly     recommended that all object and centerfield positions be input with epoch 2000.      Some basic feature are:          Performs all calculations needed to transform Right Ascension          and Declination coordinates to the coordinates of the slitmask          including refraction and precession of the stars.          AUTOSLIT3 can handle conventional slits, tilted slits, boxes,          arcs, and other user defined shapes for slits.          The user specifies an hour angle and position angle          for the observations.          An interactive mode to allow the user to change or delete          any slit assignments with which he/she is unhappy.          A Hardcopy of the final setup may be created.          Output files include all relevant information to make          bookkeeping and slitmask alignment easier.          The input features of AUTOSLIT3 have been significantly          improved over earlier versions so it is now much          easier to vary one or more parameters and run multiple tries.          The latest astrometric fits have been incorporated          into AUTOSLIT3.  Also a confusion between equinox and          epoch in earlier versions of the code has been corrected.            In AUTOSLIT3 the equinox is used to precess the coordinates.          AUTOSLIT3 allows the adjustment of the position angle and field          center during the interactive phase of the design of a slitmask. Using AUTOSLIT AUTOSLIT3 requires the PGPLOT graphics subroutine library.  Also a Postscript printer is required to print the hardcopy output. Copy the software package from the Keck LRIS ftp archive. Compile the source code for your environment if necessary. These two steps are described in Appendix A, which gives the locations from which you can obtain the code as well as the address of the AUTOSLIT3 WWW page. Appendix B gives a detailed list of the files in the top level directory for AUTOSLIT3, and in the subdirectories for the source code, executable code, and example files. Set up the input file that assigns values to the AUTOSLIT3 parameters and that defines the specification of the special slits.  This file and the file containing the list of objects should be in a working directory where you wish to have all your input and output files.  As described later, the easiest way to make this file is to edit the template file we provide. The format of both the parameter/special slit file and the object list file are described in detail below. Change directories to the working directory. Type "autoslit3/bin/autoslit3" to invoke AUTOSLIT3. AUTOSLIT3 is inherently interactive.  The orientation of the interactive display corresponds to the normal astronomical convention of N up and E left (for position angle 0 degrees).  (The orientation has been changed from that of earlier versions.) AUTOSLIT3 Parameters    AUTOSLIT3 requires several user parameters to be defined at the beginning of each run. A complete list of the currently supported parameters is given below.     The position angle is the angle between the LRIS slit and the North direction, measured using the usual astronomical convention that a positive angle corresponds to a slit which is oriented more towards the East, and 0 degrees position angle corresponds to the slit aligned with the North direction.       A 150 g/mm grating has been received for use with LRIS.  This ruling is sufficiently coarse that the full width of a spectrum only covers part of the width of the LRIS detector.  Hence one will be able to observe with 2 ranks of multislits along the length of the LRIS slit, thus doubling the effective slit length for objects where low dispersion is acceptable.  When this grating is tested and becomes available the necessary code for dual rank operation (which is effectively only a modification of the overlap rejection algorithm) will be added to AUTOSLIT3. At the present time, only single ranks of multi-slits are supported.    The list of accepted parameters is given below.     FILENAME      (Character)  The input file containing the                   LRIS field objects.     FILEOUT       (Character)  Output file.  The root file name                   for the output files.  If you enter abcdef.file1 here,                   the output files will be abcdef.file1, abcdef.file2,                   and abcdef.file3, while the Postscript hardcopy will                   be in abcdef.ps. The output ds9 region file will be   in abcdef.reg.     PRIORITY     (Numeric) Limiting priority for object plots.  Objects                  with higher priority than this value are plotted with a                  different symbol.     RANK_TOP     [1|2]  - number of slit ranks in top half (Only RANK=1                  is supported at present.)     RANK_BOT     [1|2] - number of slit ranks in bottom half (Only RANK=1                  is supported at present.)     WSLIT        (real) Width of slits in arc-sec (SLIT_WID is also                  accepted)     SLIT_LEN     (real) Minimum slit length in arc-sec.     SLIT_SEP     (real) Minimum slit separation in arc-sec.     EPOCH        (real) Epoch for slitmask use.  Actually this is the equinox,                        but is called EPOCH for historical reasons.     TEMP         (real) Temperature of atmosphere, in degrees Celsius                  (Used in refraction calculation)     PRESS        (real) Pressure of the atmosphere in mm of Hg.                  (Used in refraction calculation)     WAVE         (real) Wavelength of light to use in atmospheric                  refraction computations.     LAT          (real) Latitude of the observatory in decimal degrees.     POS_ANGL     (real) Position angle in decimal degrees     HOUR_ANG     (real)  Hour angle at which you expect to use this                  slitmask in decimal hours.  (Used in refraction                  computations.)     ENG_TEST    (boolean) Set up for astrometric engineering tests.                 Regular LRIS observers should never use this feature !     ADC         (boolean) Prepare masks using a scale value appropriate                 for use of the atmospheric dispersion corrector. This                 parameter defaults to TRUE, since the ADC is expected to                 be used for all LRIS observations after June, 2007.     INTERACT    (boolean) Allows for interactive slitmask assignments                 (This should almost always be used.)     VERBOSE     (boolean)  Give a more verbose screen output.  The                 hardcopy plots and the output files themselves are                 unaffected.        For the values of the boolean keywords, any string beginning        with one of the letters [tyTY] denotes true/yes, while any        string beginning with one of the letters [fnFN] denotes        false/no. To produce your parameter file, edit the template file given in Appendix C and in the examples sub-directory. In the parameter file, lines beginning with the symbol # are ignored. The default values for these parameters are listed below and are also in the autoslit.inc include file.  If you do not set the value for a particular parameter, the parameter will revert to the default value.  The default values for the appropriate set of site parameters (air pressure, latitude, temperature, etc) are those characteristic of the Keck Observatory. Parameter                               Keyword        Default Value -------------------------------------------------------------- input parameters and special slits file [none] "autoslit.in" input file of objects FILENAME "autoslit.obj" primary output file FILEOUT "autoslit.file1" priority for plot symbol change PRIORITY 700 rank of top half of slit (1 or 2) RANK_TOP 1 rank of bottom half of slit (1 or 2) RANK_BOT 1 width of slit [arc-sec] WSLIT (or SLIT_WID)                                                        1.0 minimum slit length (arc-sec)           SLIT_LEN        5.0 minimum slit separation (arc-sec)       SLIT_SEP        2.757 engineering slit width [none] 1.0 epoch of use                            EPOCH           "today"   The correct term is equinox, which should be set to TODAY.     For historical reasons this is called EPOCH.                              temperature TEMP 0.0 air pressure at Keck PRESS 486.0 wavelength for refraction WAVE 6000.0 latitude of Keck LAT 19.828 position angle POS_ANGL 0.0 hour angle HOUR_ANG 0.0 is this an engineering test? ENG_TEST false atmos dispersion corrector in use? ADC true interactive slit selection? INTERACT true verbose output? VERBOSE false suffix for outfile2 [none] "file2" suffix for outfile3 [none] "file3" interactive plotting device [none] "/xwin" hardcopy plotting device [none] "/vps" (Both the /xwin and /xdisp PGPLOT options for the interactive plotting device should work for Unix (Sun) workstations.  The xdisp driver has the advantage that the display window does not disappear when the program terminates.) As of 2011, the use of pickoff mirrors (keyword MIRROR) is no longer supported. As of 2011, the default value for the equinox (keyword EPOCH for historical reasons) is that of the input centerfield position instead of TODAY.  In a future version of AUTOSLIT (see the discussion in the section ``Future Upgrades'') this should be restored to TODAY. The Interactive Display While AUTOSLIT3 will assign the objects in your list to slitlets in the slitmask on the basis of priorities and object locations, one usually needs to tune up the slit assignments using the INTERACTIVE mode.  In particular, that way you can make sure the slits are placed on objects as close as possible to the center of the frame in X, so that the spectra will all cover approximately the same wavelength region. The size of the detector in the X direction determines the range off the centerline within which objects can be placed and still have the desired spectral coverage.  With the large CCD mosaic now in use, which is somewhat wider (larger in the X direction) than the single 2048x2048 pixel CCD originally used with LRIS, this is less critical, but still merits attention. Remember that the spectral coverage for an object way at the edge of the field in X will be quite different from that of an object near the center of the field. In the INTERACTIVE mode, several new features have been incorporated into the menu in AUTOSLIT3.  The most useful new keys are M (mark the location of an object), C (move the field center), and P (specify the position angle). The keys currently recognized are listed below.  The key must be hit when the mouse is within the boundaries of the plot of the setup.   I to get info about an object O to try to assign a slit to an object B to try to assign a box slit of the default size to an object D to remove a slit assignment W to wipeout all normal slits assigned Z to wipeout all slits (including special slits) R to redraw the plot L to list objects in slits M to mark the location of a specific object on your object list (space-bar) to get the (X,Y) coordinates on the mask (in mm) for a point C to specify a (relative) offset in arc-sec of the field center P to specify the field position angle Q to exit this routine (Typing any other letter key produces the list above.) (The "Mark" option is case sensitive, i.e. A3 is not the same as a3.) Important Notice Users -- Please Read This When using AUTOSLIT3 in the interactive mode, you may offset the field center (C) or change the position angle (P). Please note that the output file FIELD.file1 contains the updated field center in the J2000.0 epoch and the final adopted position angle.   Make sure that in your coordinate file for use at the telescope you use this UPDATED position angle and centerfield RA, Dec. DO NOT use the original input value if you change either the PA or the centerfield. Slit Widths Supported With the replacement of the numerically controlled punch originally used to fabricate LRIS slitmasks by a numerically controlled mill, the width of the slitlets is no longer restricted by the width of the available punches.  Any slit width is now allowed, with a minimum value determined by the width of the end mills available at Keck. CARA uses 0.020 inch (0.7 arc-sec) as their normal tool bit size.  Smaller tool bits (0.015 in, or 0.53 arc-sec) are available. All the slits, with the exception of boxes and certain special slits, must have the same slit width. Do not use slits smaller than 0.7 arc-sec wide without prior consultation with CARA staff. The Special Slits AUTOSLIT3 enables the use of four non-standard slit types: tilted slits, arc slits, line segment slits, and boxes.  These slits are defined in the second section of the input parameter file.  Definition blocks are structured as follows:        (1) tilted slits            TILTS                                                  ...            The first line specifies the number of tilted slits to be            defined.  Each subsequent line defines one tilted slit.            Each slit is defined by the name of the object on which            the slit will be placed (from the input object file), the            position angle of the slit, and the minimum extent of            the slit in arc-seconds, above and below the position            of the object.            Tilted slits are tied to positions on the sky and hence            will rotate appropriately when the slitmask position angle            is changed.            A simple program to calculate the position angle and other            information for tilted slits is available (tilted_slit.f)            and should be used prior to running AUTOSLIT3 to help            the user create the appropriate input file entries for tilted slits.            Tilted slits could in principle tilt off the area of the LRIS            slitmask.  AUTOSLIT3 does not check for this.                     (2) arc slits            ARCS                                                              ...            The first line specifies the number of arc slits to be            defined.  Each subsequent line defines one arc slit.  Each            slit is defined by a name (arc slits need not be placed on            objects), the position of the center of curvature of the            arc, the epoch of the center position coordinates, the            radius of curvature in arc-sec, and the position angle            with respect to the center of curvature            at which the arc segment begins and at which it ends.            The RA and Dec of the center            should each be defined by three numbers (hours|degrees,            minutes, seconds), separated by whitespace.              Arc slits are calculated as a set of line segments            0.5 mm apart along the arc.            Arcs, unlike normal slits, are not lengthened during the            process of filling out the mask once the objects on it            have been selected.  You must make sure to add some length            to allow for the sky spectrum etc. PLEASE BE SURE TO CHECK the layout of all special slits, and especially all arcs, in the interactive display carefully and adjust the parameters as required. Non-vertical special slits (i.e. all special slits except boxes) are always defined to have the specified width along the dispersion. Recall that the end mill used has a finite width.  The minimum width across the slit goes as (slit-width along the dispersion)*cos(angle) As the special slit becomes closer to horizontal than to vertical, this can become smaller than the width of the tool.  In such a case, the mill control program will reject that slit. In general one is safe with 1 arc-sec wide slits whose tilt from vertical is not more than 30 deg.  For narrow slit widths or in case there is any doubt, send the mill file to Hawaii sufficiently in advance for a check of the file to be made there on the computer that operates the mill, so that the special slit can be redesigned if necessary.        (3) line segment slits (Design your own complex shaped slit)            SEGMENTS                                                                                                                                            ...            The first line specifies the number of points to be            defined for line segment slits.  Each subsequent line            defines one point in a line segment slit.  Each point is            defined by the name of the line segment slit (line segment            slits are not placed on objects), the position of the            point, and the epoch of the position coordinates.  All            consecutive line segment points which share the same slit            name will be connected to form a single slit.  For            example, the above declaration would create two slits, one            with 3 points (name1), and another with 4 points (name2).            See the file Examples/test.in for more examples.  Note            that the value on the first line of the block indicates            the number of points in the line segment slits, not the            number of slits.        (4) box slits - used to put bright guide stars into a mask.            BOXES                                          ...            The first line specifies the number of box slits to be            defined.  Each subsequent line defines one box slit.  Each            slit is defined by the name of the object on which the            slit will be placed (from the input object file), and the            size of the box, in arc-seconds.            Boxes are always squares aligned along the X,Y axes of            the multislit mask.  They are not tied to the sky and hence            do not rotate when the position angle of the slitmask is altered.            Boxes are allowed to interfere with other boxes, i.e. to have            the same position along the height of the slit.        The order of the slit definition blocks does not matter.        Multiple definition blocks are also allowed, i.e., two sets of        arc slits.  The only requirement is that the number of slit        definition lines in any given block must match the number        given on the declaration line, i.e., 'ARCS 4' must be followed        by 4 arc slit definitions. An Example of a Parameter/Special Slit file AUTOSLIT3 will prompt you for the name of the parameter/special slit file.  This file consists of two sections, with a structure as follows:                               ...         END                           ...         END          All words are case-insensitive, and spacing is not important. An example of a parameter/special slit file is given in Appendix C. The Object List File As in earlier versions of AUTOSLIT, AUTOSLIT3 requires a file containing the list of objects which you would like to consider for inclusion in a multi-slit mask.  This file, whose format has not changed, must contain one-line descriptions of each object of interest in the field, in a format identical to that originally used for Palomar Observatory's Norris spectrograph.  This format is described in more detail in the file GET_OBJ.C, but is summarized as follows: Each object description line consists of:             where            = object identifier (or name)           = object priority as assigned by the observer             = object magnitude              = object right ascension:             = object declination:           = epoch of the object's coordinates         = object equinox           = object proper motion in right ascension in arcsec/yr          = object proper motion in declination in arcsec/yr Note that the equinox specified here is used to precess the coordinates to the time when the mask will be used (i.e. ``today'').  In earlier versions of AUTOSLIT, the epoch field was incorrectly used for that purpose. It is highly recommended at the present time that the equinox of the centerfield be set to 2000.0 in order to minimize precession errors and enable a workable DS9 output region file for the mask. Although the order of the fields is important, spacing between the fields does not matter. The lines may be given in any order, *except* the first line, which should have a priority of '9999' and should provide the coordinates of the center of the field of interest. An example of an object input file is given in Appendix D. Priorities and Object Assignments The allocation algorithm assigns all the special slits first. They are assigned internal priorities with default values of 2100 for tilted slits, 2200 for arcs, 2300 for line segments, and 2400 for boxes.  Do not assign priorities in excess of 2000 to objects on your normal slitmask list. A conflict is equivalent to an overlap along the length of the slit (i.e. the Y direction) between two objects.  This applies to the actual position (plus or minus any specified height for the special objects) and plus or minus the minimum object separation (defined in autoslit.inc). You will be informed if there is a conflict among the special slits you have specified.  After that, if you are using the INTERACTIVE mode, you may choose the rest of the objects in your slit-mask.  If there is a conflict, AUTOSLIT3 will refuse to make the requested assignment. If there are multiple special slits of a given category, they are prioritized within each category, with the first tilted slit having higher priority than the second one, etc.  The base priority for each type of special slit is given in the include file autoslit.inc. The Gaps in the CCD Mosaic The present LRIS-R and LRIS-B detectors are both mosaics of CCDs instead of a single large monolithic CCD.  Because of the need for providing readout and control circuits to each CCD in the mosaic, there are physical gaps between the CCDs.  These gaps cut out a short rectanglar area in the LRIS focal plane for each of the red and blue cameras.  The rectangle has its long side along the dispersion and its short side along the length of the LRIS long slit. If the image of an object on the sky as viewed in the LRIS focal plane falls into one of these gaps, its image will not appear on the LRIS image, or if a slitmask is in use, its spectrum will not be obtained.   These gaps have been minimized during the design and fabrication of the CCD mosaics, but they are still large, with the blue detector mosaic having a smaller gap than the red side mosaic.  The large red side gap is indicated in the four output Postscript plots as dashed lines. The smaller blue side gap is indicated as dotted lines. The upper limit to the blue side gap is the same as that of the red side gap.  The interactive display also shows the two gaps. If you choose to place an object within one or both of these gaps, there will be a warning message from the interactive display, but the slit placement will be allowed, if consistent with other constraints such as minimum separation to any previously assigned slit. One might choose to do this, for example, to place an object within the area of the LRIS-R gap, but outside the area of the LRIS-B gap.  For such an object one would obtain only a LRIS-B spectrum.  The LRIS-R slitmask spectum will not contain a spectrum of this object. At present (July 2011), the CCD gap locations as seen on the sky are indicated correctly to within an accuracy of about 1 arcsec. The CCD gap locations as projected on to the sky may change if the instrument is realigned or recollimated, which happens very rarely. In the past, the slit-mask plates were restrained in their holders (and slightly curved to fit better the telescope focal plane by a bar which ran in the dispersion direction along the middle of the mask.  The bar was opaque.  Recently new slitmask holders were designed and fabricated with the curvature controlled without the need for the bar.  Thus there is no longer any occulted area within the LRIS itself.  Only the gaps between the CCDs in the detector mosaics produce issues of unavailable areas within the nominal LRIS field. Checking the Slit-Masks It may be desirable to check the mask before the mill file is sent to the Keck Observatory.  A program has been written for this purpose called "check_mask3".  This program, which requires the PGPLOT subroutine library, is installed in the Autoslit3 directory.   It takes the output file from Autoslit3 that is sent to the milling machine and produces a Postscript file which contains a full size image of the multi-slit mask.  The postscript file is called "pgplot.ps" and can be printed on any Postscript printer.   Since the mask is large, the image is on two sheets of standard size paper, for the top and bottom of the mask respectively. This program is self explanatory and very easy to use. Astrometry Two astrometric models are used in AUTOSLIT3.  The first and most critical is the model that relates the position of an object on the sky (RA, Dec) into position on the slitmask.   The baseline model, adopted before LRIS was completed from the details of the instrument and telescope design, was that of a fixed telescope focal plane scale of 0.7253 mm/arc-sec projected onto a bent slitmask.   (See the the LRIS Manual of Operations for details.)   Once LRIS was in use at the telescope this initial model was found to be inadequate and was refined by adding a small "touchup fix".  The latest version of the "touchup fix" (August 1997) is used in AUTOSLIT3.   A detailed discussion of the procedures, measurements and analysis for determining this is given in the following three LRIS reports:    The LRIS Focal Plan Astrometry - J.G.Cohen - December 1993    Report on the Alignment of the LRIS Slitmasks Based On Tests Conducted    During the January 1994 LRIS Commissioning Run - J.G.Cohen, January 1994    The Slitmask Astrometry of the LRIS - J.G. Cohen and P.L. Shopbell,    December 1996 It should be noted that only a major change to the instrument might affect the values of the parameters used in this aspect of the astrometric model for LRIS. In addition, AUTOSLIT3 predicts the (X,Y) positions of objects on the focal plane CCD detector in pixels as an aid for slitmask alignment. The astrometric model for this has been developed in a series of reports on the LRIS spatial distortion.  The latest of these is:    The Spatial Distortion in the LRIS - Addendum 5, The Scale Change    Introduced by the New LRIS Dewar - J.G. Cohen and P.L. Shopbell,    Nov. 7, 1996 (15 pages) The specific X,Y (CCD) predictions in Autoslit3 use this model for the new LRIS Dewar.  It should be noted that if changes are made to the LRIS optics or mechanical mountings (new Dewar, recollimation, re-alignment, etc.) the predicted X,Y(CCD pixels) may no longer be sufficiently accurate and new parameters for the fits in this model may be required. To facilitate updating the code, should a more complex and more accurate astrometric model become available in the future, the corrections from the baseline model are implemented only in the output file containing the positions for the numerically controlled mill that fabricates the LRIS slitmasks.  Thus the X,Y (mm) positions in the slitmask in the output files intended for the user are slightly different from those in the file used to fabricate the slitmask. The two astrometry models are isolated within two subroutines, ccd_coord_predict and slit_astrometry.  Updating the astrometric model just requires updating one or both of these subroutines. Coordinate Systems The LRIS coordinate system is defined in the LRIS Manual of Operation. The origin is the optical axis, and the X axis goes through the center of the LRIS entrance field.  In this coordinate system, the slitmask covers the region X = 174 to 436 mm, and Y = -174 to 174 mm.  Thus in this coordinate system, the center of the slitmask is at  X = 305.0 and Y = 0.0 mm. The slitmask punch originally used to fabricate LRIS slitmasks has an internal coordinate system whose origin is at X = 412.95, Y = 167.8 mm.  Its Y coordinate axis is opposite to that of the LRIS coordinate system (i.e. 180 degrees off).  The X coordinates are in the same direction for both frames, there is just an offset between coordinate systems. To avoid confusion and aid in code maintenance, all calculations in AUTOSLIT3 are done in the LRIS coordinate system until the stage where the output files are written. Coordinate Change for the Milling Machine The milling machine uses a coordinate system which is different from the nominal LRIS coordinate system used here and from that used with the slitmask punch.  In particular, X and Y must be interchanged. This is done only at the very end when the output file intended for the numerically controlled mill is written.  The file "mill_coords.ps", a Postscript file, illustrates the orientation and zero points for the mill and the nominal LRIS coordinate system on the slitmask.  A hardcopy of this figure is in Appendix G. The Keck mill has a very sophisticated computer control system.  It is possible to preview mask design files to check whether any constraints imposed during the fabrication process for the masks are violated.  In case of doubt, contact CARA staff to arrange a test of your AUTOSLIT3 mill file. Engineering Mode A mode is available, intended ONLY for engineering tests, which does not put in any modifications to the original baseline LRIS astrometric model, which bypasses all overlap checking, and which produces a slit-mask with 1 x 1 arc-sec boxes (unless a different slit width is specified in the parameter file) around each selected object. This can be used to produce a mask with hundreds of such boxes around objects with high quality astrometric positions, and one can use such a mask for checking the LRIS astrometric model. THIS MODE SHOULD NOT BE USED BY NORMAL LRIS OBSERVERS. Maximum Number of Slits AUTOSLIT3 will allow you to define up to 100 slits, except in engineering mode, where that is relaxed to 500 boxes. Programming Considerations     All of the important parameters relating to the geometry of the LRIS     spectrograph have been grouped together in an include file called     autoslit.inc.  This file must be located in the same directory as     the source code, autoslit3.f.     If it become necessary to change the parameters of the slitmask,     this can be easily done by:     Changing the relevant parameters in autoslit.inc     Recompiling AUTOSLIT3 as follows:  while in the AUTOSLIT directory,     type          % make autoslit3     This will recompile and link AUTOSLIT3 with the new parameters.     The following is a list of files which must be present for autoslit to     be compiled:               Makefile, autoslit3.f, autoslit.inc, math.inc     Further, the following must be located in a "lib" subdirectory: assign_slits.f       manual_slits.f       refract.f            write_setup.f ccd_coord_predict.f  match_slits.f        slit_astrometry.f    xy.f draw_hard.f          params.f             slits.f get_data.f           plot.f               write_mill.f isort.f              precess.f            write_objects.f env.c   get_key.c  get_obj.c Also the two include files, autoslit.inc and math.inc, must be in the lib subdirectory, as well as Makefile. A detailed list of the required files and directories is given in Appendix B. AUTOSLIT.INC An extract from the include file autoslit.inc that contains many of the important spectrograph definitions which might be altered by the user is given below.  If one of the values is altered, the program will have to be recompiled to force Autoslit3 to use the new value. C     Slit widths, lengths, and separations:      REAL*4     DEF_SLIT_WID,DEF_SLIT_LEN,DEF_SLIT_SEP      PARAMETER (DEF_SLIT_WID=1.0,              ! normal width, length,     :           DEF_SLIT_LEN=5.0,              ! and separation of     :           DEF_SLIT_SEP=2.757)            ! slits [arc-sec] C     Physical constants:      REAL*8    DEF_TEMP,DEF_PRES,DEF_WAVE,DEF_LAT,DEF_POS_ANGLE,DEF_H      PARAMETER (DEF_TEMP=0.0D0, ! temperature     :           DEF_PRES=486.0D0, ! air pressure at Keck     :           DEF_WAVE=6000.0D0, ! wavelength for refraction     :           DEF_LAT=19.828D0, ! latitude of Keck     :           DEF_POS_ANGLE=0.0D0, ! position angle     :           DEF_H=0.0D0) ! hour angle C     Spectrograph:      INTEGER*4 NORM_SLITS,ENG_SLITS      REAL*4    PUNCH_LEN,CCD_SIDE,CCD_SCALE,     :          XS_SLIT,YS_SLIT,     :          X_CENTER,Y_CENTER,     : SCALE,MASK_ANGLE,MASK_BEND      PARAMETER (     :           NORM_SLITS = 100,      ! number of slits for normal use     :           ENG_SLITS  = 500,      ! number of slits for engineering     : PUNCH_LEN  = 3.0,      ! length of punch used [not used]     :           CCD_SIDE   = 2048.0,   ! size of ccd in pixels     :           CCD_SCALE  = 0.15767,  ! mm per pixel of ccd at slitmask     :           XS_SLIT    = 215.9,    ! length of the x side of the slitmask     :           YS_SLIT    = 335.6,    ! length of the y side of the slitmask     :           X_CENTER   = 305.0,    ! center of mask in x coordinates     :           Y_CENTER   = 0.0,      ! center of mask in y coordinates     : SCALE      = 0.7253,   ! scale of mask in mm/arcsec     : MASK_ANGLE = 8.06, ! angle of mask in focal plane in deg     : MASK_BEND  = 1.94)     ! angle of bend in mask in deg The mathematical parameters that were formerly in autoslit.inc, such as conversion factors from radians to arc-sec, have been moved to a new include file called math.inc.           The Output from AUTOSLIT3    The output from AUTOSLIT3 consists of 3 text files, a Postscript plot file with four pages of plots, and a region file (added in July 2011).  The region file (courtesy of Caltech graduate student Andrew Newman) provides an input to the popular display server DS9 such that if you have an image with a world coordinate system (i.e. one for which RA and Dec can be determined for each pixel), then loading the region plot into DS9 will overlay the slitmask onto the sky field within the display.  This is extremely useful both in   designing the slitmask and in preparing charts of the setup/alignment   stars for each slitmask; these are required for slitmask alignment.     If you use the epoch 2000 for your centerfield coordinate, then the region file will be correct.  If you do not use 2000, then the region file will not be useful.  Please see the comments in the section Future Upgrades for details on this point.    Alignment of the slitmask at the telescope in the past required use of both the printed file output and a hardcopy of the graphics output from Autoslit.  The hard copy device for AUTOSLIT3 is a Postscript printer in the portrait (vertical) mode.   The current (early 2011) slitmask alignment scheme for LRIS is similar to that used for Deimos.  It is based on using the fixed MAGIQ guider for crude alignment, which gets an alignment star somewhere inside its respective box.  This is followed by imaging with the blue side of LRIS for fine alignment.  (The readout time of the LRIS-B detector array is much faster than that of the red one, and the change of configuration between imaging and multislit spectroscopy is faster as well.  Hence the choice of LRIS-B for slitmask alignment.  With this procedure, all that is required is finding charts of the alignment stars, each of which should be assigned a box at least 4 arcsec on a slide or larger.  At least five alignment stars well distributed over the LRIS field should be assigned within each slitmask.     Four figures are produced as Postscript files.  The first is labeled "Mask Layout.....".  It contains a view of the slit mask as seen from above.  The two arrows on the periphery of the frame denote the locating notches for inserting the frame into the LRIS slit mask holders and for locating the plate on the slit mask machine table. There is also an arrow indicating north and east.  The frame displays all the objects in the field, and indicates where the assigned slits are.  You can use this frame to check that the slit-mask has been made correctly.      The second file is labeled "Seen on CCD:...".  This file shows the mask as seen by the LRIS optics and CCD camera.  There is an inversion in x from the first output plot, as shown by the pair of arrows indicating north and east.  Otherwise this plot is identical to the first plot.      The third plot is also labeled "Seen on CCD:...".  It is identical to the second plot, but for each assigned slit, on the left side of the frame is given the (x,y) coordinates of the object in the slit in the LRIS coordinate system, while on the right side of the field are given the object name and magnitude, all at the appropriate y height for the object.  This plot is extremely useful in checking at the start of your run that the correct slitmasks have been installed in LRIS, working on slitmask alignment, etc.  You should bring a printed copy of it for each multi-slit you plan to use.     The final plot is also labeled "Seen on CCD...".  It displays only the objects that are selected to be in slits.  The full length of the slit is shown.  The objects are labeled with their names and their magnitudes. For each plot, the location of the notches that define the placement of the slitmask in the milling machine and in the slitmask holder re indicated by small arrows. Other useful files: ------------------ README contains a more detailed description of compiling this program TECHDOC contains a 1 sentence listing for each subroutine indicating its function. *** PLS read this section completely*** Future Upgrades: ----------------- Until July 2011, the default mode of operation of AUTOSLIT was to read the input coordinate list, and precess it to the equinox TODAY.  Then the calculations necessary for defining the layout of the slitmask were carried out, and the results given in the output files and plots.  One resulting confusion among observers was that in the output files, the centerfield coordinates were given with the equinox TODAY rather than 2000.  We have attempted in the current version to make the equinox of the centerfield in the AUTOSLIT output files much clearer. In July 2011, ouput of a DS9-type region file for use with the image display server was added.  This is very useful.  However, the standard format for this file only allows for 1950 and 2000 coordinates.  The logical thing to do would have been to precess the input centerfield and object coordinates to TODAY, which presumably is very close to the date at which the slitmask would be used at the telescope, as we have done in the past.  We then would need to precess the information for constructing the region file back to 2000. While trying to implement this, it was discovered that the precession routines used within AUTOSLIT are not sufficiently accurate to do this and maintain a precision of better than 0.05 arcsec over the 11 years since TODAY (i.e. July 2011).  It will require some work to find a more accurate precession routine whose code is free and publicly available, to revise the internal code within AUTOSLIT to implement the forward and backward precession as required, and to test the revisions.  So we (J. Cohen and P. Shopbell) decided for the present to ignore this problem. This is a real problem and we hope to fix it in the next version.  But meanwhile the present version of AUTOSLIT (3.20) yields slitmasks which work well and which are correct in all respects to within  0.05 arcsec. Clearly this must be fixed before TODAY and 2000 differ by more than 20 years, but that gives us plenty of time for the non-trivial required coding modifications. Comments and Suggestions: ------------------------ Comments, suggestions, reports of bugs, etc. should be directed to J.Cohen, at least until the shakedown period for this completely new version of AUTOSLIT is over and CARA becomes responsible for its maintenance, which never seems to happen. Judith Cohen                  jlc@astro.caltech.edu         Appendix A  Downloading and compiling autoslit Appendix B  List of required files Appendix C  Example of a parameter/special slit file Appendix D  Example of an object input file Appendix E  Example of output files Appendix F  Alignment of Gratings and Mirror in LRIS Appendix G  Layout of the Mill Coordinate System Appendix A Downloading and compiling autoslit The source code, a compiled version, and the help files can be obtained via anonymous ftp from ftp://astro.caltech.edu/users/pls/Autoslit/ or from ftp://ftp.keck.hawaii.edu/pub/lris/autoslit3. There is also a WWW page (http://astro.caltech.edu/~pls/autoslit). Compile instructions are given on the website and provided in the README and Makefile files, once the source code has been extracted. The latest version of the source code can always be obtained from the link: http://astro.caltech.edu/~pls/autoslit/autoslit.tar.gz For those wanting to use a pre-built binary, a selection of those can be downloaded from: http://astro.caltech.edu/~pls/autoslit/binaries/ Note that these are provided for a small selection of hardware and operating systems and may require certain libraries to be available. Please e-mail pls@astro.caltech.edu should you require a binary for a machine of a different architecture; we will try to assist. Appendix B     List of required files In the main directory, autoslit3.f, autoslit.inc, math.inc, autoslit3.doc, README, TECHDOC, and the Makefile. Also the coordinate system layout figure, mill_coords.eps. (Other useful codes include tilted_slit.f and check_mask3.f.) In the lib subdirectory, the following Fortran files: assign_slits.f       manual_slits.f       refract.f            write_setup.f ccd_coord_predict.f  match_slits.f        slit_astrometry.f    xy.f draw_hard.f          params.f             slits.f get_data.f           plot.f               write_mill.f isort.f              precess.f            write_objects.f and the following c files: env.c   get_key.c  get_obj.c the Makefile and the two include files (autoslit.inc and math.inc), which are just links to those in the top level directory. in the examples subdirectory: test1.in and grid.in test.objs and grid.objs test1.file1, test1.file2, test1.ps in the bin directory (or wherever you choose) autoslit3 Appendix C Two examples are given.  In the first, the grid test case, there are no special slits, while in the second test case there are several arcs and tilted slits. Grid test case parameter file: # Header comment FILENAME grid.objs FILEOUT grid.file1 Priority 750 Press 455.5 #Mirror    x0y0 Pos_Angl        90 WSlit 1.0 Interact True Verbose No # Eng_Test True # # several comments together # .... # END # Special slits: END Arc/tilted slit test parameter file # Header comment FILENAME test.objs FILEOUT test.file1 Priority 750 Press 455.5 #Mirror 1-73 Pos_Angl 0 WSlit 1.0 ADC False Interact True Verbose No # Eng_Test True # # several comments together # .... # END # Special slits: Tilts 3 Y 45 5 5 # 1-31 10 20 30 1-85 115 8 2 CF10 -25 4 12 Arcs 3 arc1 19 51 29.45   18 40  1.00  1950.0 25 0 180 # arc2 19 51 26.63   18 37 19.00  1950.0 10 -45 45 arc3 19 51 37.69   18 37 21.80  1950.0 15 -105 -10 arc4 19 51 34.11   18 38 50.30  1950.0 20 135 -135 END Appendix D  Example of an object input file The beginning of the object list file for the grid test case is given below.  The object input file for the arc/tilted slit case is similar, but longer, and is given in its entirety in the examples directory. The object input file has the format: name, priority, magnitude, RA, Dec, epoch, equinox, and proper motion.  The equinox field is now used for precession, correcting an earlier error of using the epoch field, so make sure that the equinox field is filled in appropriately. (60)%% more grid.objs CENTER     9999   0.00   15 10 33.00   12 15 30.00  2000.0  2000.0  0.0  0.0 x0y0         700  20.00   15 10 33.00   12 15 30.00  2000.0  2000.0  0.0  0.0 x10y0        700  20.00   15 10 33.682  12 15 30.00  2000.0  2000.0  0.0  0.0 x0y10        700  20.00   15 10 33.00   12 15 40.00  2000.0  2000.0  0.0  0.0 x10y10       700  20.00   15 10 33.682  12 15 40.00  2000.0  2000.0  0.0  0.0 x-10y0       700  20.00   15 10 32.318  12 15 30.00  2000.0  2000.0  0.0  0.0 x-10y10      700  20.00   15 10 32.318  12 15 40.00  2000.0  2000.0  0.0  0.0 x0y-10       700  20.00   15 10 33.00   12 15 20.00  2000.0  2000.0  0.0  0.0 x10y-10      700  20.00   15 10 33.682  12 15 20.00  2000.0  2000.0  0.0  0.0 x-10y-10     700  20.00   15 10 32.318  12 15 20.00  2000.0  2000.0  0.0  0.0 x30y0        700  20.00   15 10 35.047  12 15 30.00  2000.0  2000.0  0.0  0.0 x0y30        700  20.00   15 10 33.00   12 16 00.00  2000.0  2000.0  0.0  0.0 x-30y0       700  20.00   15 10 30.953  12 15 30.00  2000.0  2000.0  0.0  0.0 Appendix E  Example of output files Sample output files for the first two output files from Autoslit3 are given.   The first gives the details of the normal and special slits assigned in the slitmask.  This file is useful for slitmask alignment purposes.  The second is the file that list the X,Y coordinates of all the objects in the input list.  Only the beginning of this file is shown. (62)%% more test.file1 #                                               # #  ****       AUTOSLIT  3.0 OUTPUT        ****  # #  ****     Mon Oct 20 13:09:26 1997      ****  # #                                               # #                                               # #  ===========================================  # #              Autoslit Parameters              # #  -------------------------------------------  # #                                               # #  Files:                                       # #  -------------------------------------------  # #  Input object file:              test1.objs   # #  Output listing file:            test1.file1  # #  Output stage coordinate file:   test1.file2  # #  Output file for the punch/mill: test1.file3  # #  -------------------------------------------  # #                                               # #  Physical parameters:     [default]  [input]  # #  -------------------------------------------  # #  Temperature [C]:              0.0       0.0  # #  Air pressure [mm of Hg]:    486.0     198.0  # #  Latitude:                   19.83     19.83  # #  Wavelength [A]:            6000.0    6000.0  # #  Position angle:              0.00     45.00  # #  Hour angle:                  0.00      0.00  # #  Epoch:                     [center] 2000.00  # #  Slit width [arc-sec]:        1.00      3.00  # #  Slit length [arc-sec]:       5.00      5.00  # #  Slit separation [arc-sec]:   2.76      2.76  # #  -------------------------------------------  # #                                               # #  Slit layout parameters:                      # #  -------------------------------------------  # #  Top half of mask:    *single* rank of slits  # #  Bottom half of mask: *single* rank of slits  # #  Special plot symbols have priority  >   750  # #  Slit selection:                 interactive  # #  Pickoff mirror in use:                FALSE  # #  Atmos dispersion corrector in use:     TRUE  # #  Engineering run:                      FALSE  # #  -------------------------------------------  # #                                               # #  Slit inventory:           assigned/declared  # #  -------------------------------------------  # #  Number of standard slits:                24  # #  Number of boxes:                       0/ 0  # #  Number of tilted slits:                2/ 2  # #  Number of arc slits:                   1/ 3  # #  Number of line segment slits:          0/ 0  # #  ===========================================  # #                                               # #  ===========================================  # #                Center of Field                # #  -------------------------------------------  # #  Center of Field is:                          # #  RA  =   14h   29m  40.020s    [2000.00]      # #  DEC = -  5d   57m  26.000s                   # #  ===========================================  # #                                               # #  ===========================================  # #                   Slit Setup                  # #  -------------------------------------------  # #  X_STAR    Y_STAR       MIN_Y       MAX_Y    Percent   CCD_X   CCD_Y Prior      Name           Mag  #  101.96133 156.86742   171.37343   156.86742 100.0000  1004.2  1100.9  2200    arc4             0.000   80.51526 275.03802   279.50546   270.65359  50.4690   864.3   330.5  2101    Y               13.870  205.17894  96.66530   101.45148    94.41214  67.9919  1670.5  1495.2  2100    CF10            13.640  119.93607 138.65129   142.40982   123.86235  20.2643  1119.7  1219.6   900   1-40             14.690  201.25655 209.66850   212.99808   207.74945  63.4371  1644.5   755.3   900   1-77            12.650 #  ===========================================  # The X_STAR, Y_STAR, MIN_Y, and MAX_Y are given in mm in slitmask coordinates.  The slits start off being 4 arc-sec (2.9 mm in length), unless a different value is specified in SLIT_LEN.  After object selection is completed, the slits are then increased to their maximum length consistent with a minimum separation of SLIT_SEP arc-sec (with a default value of 2 mm = 2.8 arc-sec) to give the maximum possible length for the night sky spectrum at the ends of each slit. The Percent is the ratio of (Y_STAR - MIN_Y)/(MAX_Y - MIN_Y) for each slit.  Those slits with the Percentage less than 10 or more than 90 may have the stars too close to the edge of the slit for good spectra.   The CCD_X and CCD_Y are the pixels of the CCD in which the object is predicted to appear. The centerfield coordinates in this file include corrections for precession to the current epoch but not for atmospheric refraction.  Thus these centerfield coordinates can now be used as input to the Keck Telescope drive and control system (DCS) for pointing the telescope. (63)%% more test.file2   ****       AUTOSLIT  3.0 OUTPUT        ****   ****     Mon Oct 20 13:08:48 1997      ****   ===========================================                  Autoslit Parameters                  -------------------------------------------      Files:                                           -------------------------------------------      Input object file:              test1.objs       Output listing file:            test1.file1      Output stage coordinate file:   test1.file2      Output file for the punch/mill: test1.file3      -------------------------------------------      Physical parameters:     [default]  [input]      -------------------------------------------      Temperature [C]:              0.0       0.0      Air pressure [mm of Hg]:    486.0     198.0      Latitude:                   19.83     19.83      Wavelength [A]:            6000.0    6000.0      Position angle:              0.00     45.00      Hour angle:                  0.00      0.00      Epoch:                     [center] 2000.00      Slit width [arc-sec]:        1.00      3.00      Slit length [arc-sec]:       5.00      5.00      Slit separation [arc-sec]:   2.76      2.76      -------------------------------------------      Slit layout parameters:                          -------------------------------------------      Top half of mask:    *single* rank of slits      Bottom half of mask: *single* rank of slits      Special plot symbols have priority  >   750      Slit selection:                 interactive      Pickoff mirror in use:                FALSE      Atmos dispersion corrector in use:     TRUE   Engineering run:                      FALSE      -------------------------------------------      Slit inventory:           assigned/declared      -------------------------------------------      Number of boxes:                       0/ 0      Number of tilted slits:                0/ 2      Number of arc slits:                   0/ 3      Number of line segment slits:          0/ 0      ===========================================      ===========================================                Objects in Field   -------------------------------------------    Name                Mag        X       Y   -------------------------------------------   Y                   13.87    332.43 -107.24   CF10                13.64    207.77   71.13   1-73                14.79    258.70  -16.00   T,CF11              12.20    202.67   80.06   A4                  12.20    348.69   51.02   1-46                12.29    294.85   78.73   ===========================================     The X and Y coordinates here are given in mm in the official LRIS coordinate system, which has X going from 174 to 436, and Y from -174 to 174 mm. The file intended for the mill has the same header structure, which the mill control computer ignores.  This is followed by a set of blocks which resemble the one given below, which defines a normal slit.  This contains the X,Y,Z coordinates of the 4 corners that define the slit (Z = 0 always), together with a fifth corner which repeats the first one to form a closed rectangle. newrow  174.300003  129.618027    0.000000  164.287582  129.618027    0.000000  164.287582  128.892746    0.000000  174.300003  128.892746    0.000000  174.300003  129.618027    0.000000 newrow Appendix F  Alignment of Gratings and Mirror in LRIS In tests carried out in April 1997 with the slitmask alignment test hole pattern of drawing 108811A, the support bar of the slitmask frame falls at the following Y(CCD, pixels) location in the LRIS focal plane CCD detector: Grating/Mirror    Y location     Delta from Ideal (Y=1024 pixels)                  (pixels) Mirror           1090           +66 300/5000         1033            +9 600/5000         1003           -21 600/7500         1015            -9 1200/7500         999           -25 The LRIS optics were realigned in August 1997 to correct the pointing of this mirror.  Hence the value adopted for AUTOSLIT3 is (mirror - grating) = 0 pixels in Y (as of August 1997). The LRIS pointing origin was also redefined so as to point at the center of the mask in August 1997.  Furthermore, the zero point of the Keck 2 Cass instrument rotator was adjusted at that time based on tests with star trails to determine the correct value.  Contact CARA for details. Appendix G  Layout of the Mill Coordinate System