BASIC RELEASE NOTES This directory contains a new version of the software used to extract STIS spectra. The software is bundled as a temporary IRAF package (sc2d), containing two tasks (sx1d and sc2dref) and one pset (algpars). The "reffiles" subdirectory contains 100 Mb of new reference files used by the algorithm. The new reference files are not yet available from the calibration database maintained by the HST archive. In the next full release of STSDAS, the new sc2d functionality will be integrated as an option into the existing "stsdas$hst_calib/stis/x1d" task, but for now the software is available only as a temporary package available via anonymous ftp. Use of the two-dimensional scattered light correction algorithm will likely become part of the standard pipeline processing, as well. BRIEF DESCRIPTION OF THE ALGORITHM The new "sc2d" algorithm implemented in "sx1d" uses an iterative deconvolution scheme to model and remove scattered light from the two-dimensional image, prior to spectral extraction. The algorithm was developed by Don Lindler (Advanced Computer Concepts) and Chuck Bowers (Goddard), who helped design and test STIS on the ground. Ivo Busko (STScI) implemented the algorithm as part of the STIS spectral extraction software. The new algorithm obtains a two-dimensional model of the scattered light based on the extracted spectrum and known scattering properties of the instrument. Echelle scatter is modelled by redistributing extracted counts along lines of constant wavelength, using echelle line spread functions. Scattering by the cross disperser is treated by independently convolving each column with a scattering kernel. Scattering due to the aperture-truncated telescope PSF and isotropic detector halo are treated by 2-dimensional convolution. In the FUV, the PSF is a strong function of wavelength, so scattered light models are constucted at 2 or 3 different wavelengths, and then the results are combined with weights that vary as a function of wavelength. After three iterations, the final scattered light model is subtracted from the raw image, and extraction proceeds using the standard one-dimensional interpolation of the background remaining between orders. We are in the process of writing a detailed instrument science report that will quantify the magnitude of the error due to residual scattered light, using both the old and new algorithms. Here we provide only preliminary information to help potential users assess whether the new algorithm is required for particular science goals. Using the one-dimensional algorithm, errors in the cores of saturated interstellar lines are about 9% of the continuum at 1200 Angstroms (E140H and E140M), 3% at 1670 Angstroms (E230H), and 0.6% at 2800 Angstroms (E230H). Errors in emission line spectra are typically 1% of the peak line flux and can affect adjacent orders. RUNNING THE NEW PACKAGE Install the software as described in the INSTALLATION section below. Before the new algorithm will run successfully, the headers of input "_flt" images must be edited to include pointers to the new reference files. This editing can be done by hand or with the task "sc2dref". This convenient script inserts reference file pointers assuming the newly distributed reference files will be moved to in the standard "oref$" directory, prior to execution of the "sx1d" task. If for some reason you cannot copy the new reference files to your "oref$" directory, then you can edit the script "sc2dref", changing the value of the "refdir" parameter from "oref$" to the directory containing the new reference files. This approach should be used only a last resort, since there are no tools to automatically change the reference file pointers back to "oref$" should that become appropriate. The "sc2dref" script can only be used to add new reference file pointers; it will not update existing pointers. After invoking the "sc2d" package, the new two-dimensional scattered light correction algorithm is selected by using "epar sx1d" to set the "algorithm" parameter to "sc2d". The final scattered light model can be saved to disk by using "algpars" to set the "sc2dimage" parameter to the name of the file which is to contain the output image. Note that the algorithm is rather memory intensive, requiring about 330 Mb of free memory, with at least 256 Mb of real memory required to prevent excessive swapping. On a 360 MHz Sun 360, individual image sets take 6-11 minutes to process, depending on echelle grating and central wavelength. ADDITIONAL HELP: If you have questions or comments about the new scattered light algorithm, please contact email@example.com. INSTALLATION: The software is pre-built for the Sun Solaris architecture/OS. If installing in a different architecture, the package must be built from the source code, which is also provided in the distribution. Installing on a Sun Solaris machine: 1) Select where you want the software to be installed. For the sake of exposition, we will assume in what follows that the software is to be installed in the directory /user/mysoftware/. 2) Download the distribution tar file into /user/mysoftware/. 3) Extract the contents of the tar file. This creates a subdirectory named "sc2d" containing the software and reference files. 4) Go to the "sc2d/reffiles" subdirectory and copy or move all files the your "oref$" directory. If you do not have write permission for that directory, ask your system manager to copy the files. 5) After starting IRAF, install the new package by issuing the commands: cl> set sc2d = "/user/mysoftware/sc2d/" cl> task sc2d = sc2d$sc2d.cl These two commands must be executed every time a new IRAF session is started, so if you are going to use the new software a lot, it might be more convenient to include these two commands as part of your login.cl startup script. At this point the package is available for loading. Don't forget to pre-process your STIS echelle files with the "sc2dref" script in order to insert the new reference file pointers. Installing on a different architecture/OS: 1) Execute steps 1 - 4 described above. 2) Set the environment for compiling/linking under IRAF: 3.1) Set the environment variable "iraf" to point to your local IRAF installation, such as: % setenv iraf /project/devcl/odosw1/ssg/build_4_1/iraf/ 3.2) Source the IRAF initialization file: % source $iraf/unix/hlib/irafuser.csh 3) Make sure your Unix environment variable IRAFARCH is set to the appropriate architecture (e.g "ssun", "alpha", "redhat", etc.). If not, set it explictly, as in: % setenv IRAFARCH alpha 4) Change to the directory /user/mysoftware/sc2d/cal/ and delete file calstis.a. Change to the subdirectory cs6/ and delete files cs6.o and cs6.e. 5) Start an IRAF session. 6) Move to the directory /user/mysoftware/sc2d/cal/ and issue the command: cl> mkpkg -p stsdas This should re-build the cs6.e executable file. 7) Execute step 5 above to define the package.