Äîêóìåíò âçÿò èç êýøà ïîèñêîâîé ìàøèíû. Àäðåñ îðèãèíàëüíîãî äîêóìåíòà : http://www.stsci.edu/hst/nicmos/documents/isrs/isr_2000_005.pdf
Äàòà èçìåíåíèÿ: Mon Nov 19 16:59:08 2007
Äàòà èíäåêñèðîâàíèÿ: Sun Dec 23 02:43:00 2007
Êîäèðîâêà:

Ïîèñêîâûå ñëîâà: zodiacal light
NICMOS ISR-00-005

The new NICMOS Exposure Time Calculator: Software and Installation
A. Sivaramakrishnan, B. Simon, S. Holfeltz, H. Shukla and M. Sosey October 2, 2000

ABSTRACT This report describes the latest version of the NICMOS Imaging Exposure Time Calculator (ETC) from a software developer and instrument support point of view. This ETC uses STScI Calibration Data Base tables for instrument and telescope data, and STSDAS.SYNPHOT for its throughput engine. It uses a self-contained library to calculate thermal background due to telescope and instrument optics. We describe technical details of the software in case observers wish to extend the capabilities of the ETC.

Introduction
This is a companion ISR to NICMOS ISR 001-00 describing the use of the new NICMOS exposure time calculator maintained by STScI. We offer the source code to observers interested in modifying the ETC for their purposes. STScI cannot support such extension, but features developed outside can be incorporated into the STScI version of the NICMOS ETC, as is consistent with a bazaar style (http://www.ccil.org/~esr/writings/cathedral-paper.html) of software development where interested users can develop and improve the application. Exposure Time Calculators (ETCs) are used to estimate expected signal to noise ratios given a source brightness and size and an expected sky background. In the infrared, a knowledge of the thermal properties of the optics is also required. We describe the software architecture and required data files of the new NICMOS ETC which uses instrument throughput and data files maintained and updated by the Calibration Data Base System


NICMOS ISR-00-005 (CDBS) at Space Telescope Science Institute (STScI). Earlier ETCs for HST's NICMOS use independently maintained private data files. The STSDAS package SYNPHOT is the primary throughput calculator used in this ETC. All the code used is non-proprietary, and can be distributed and modified without concern about licensing issues. A self-contained library of modular thermal and optical transfer routines was written for this ETC. The NICMOS thermal model implemented in this library uses measured value of mirror emissivities and temperatures (Robberto et al. 2000). This library uses the CFITSIO library (Pence 1999) to read instrument calibration data files. A model of the zodiacal light at 45 degrees elevation is used to estimate sky background in the first release of this ETC. Other models (high or low elevations) can be added to the ETC. These models are stored on disk. A file describing the imaging modes is also stored on disk --- this is a holdover from earlier versions of STScI ETC software for other instruments, and is being removed as the NICMOS camera object in this ETC incorporates more of the camera parameters within it. The dark current is not obtained from the `mode' file because it depends on detector temperature, for instance. It is obtained from a NIC_physical object (described later). This segregation is not yet complete. Point source signal is estimated in apertures of 1, 1 and 2 arc seconds diameter in cameras NIC 1, NIC 2 and NIC 3 cameras respectively. The point spread function (PSF) simulator Tiny Tim is used to simulate the PSF (Bushouse, 1997) in order to calculate the fraction of light falling in the standard aperture of the camera under consideration, as well as the fraction of light incident on the central pixel. COUNTRATE provides the pivot wavelength of the passband. This is parsed from the SYNPHOT call's output for the source. PSF-related quantities are evaluated at this pivot wavelength. The necessary PSF data for this is hardwired in the NICMOS thermal and optical library. The ETC is compiled with gcc and run under the Solaris operating system. It requires IRAF and STSDAS to be accessible. It also required access to copies of CDBS data files pertaining to NICMOS and HST.

Process Execution Thread and Software Architecture
This ETC is derived from the STIS ETC (Hack et al., 1996, Simon, 1999). Much of the high level code preserves the basic structure of the antecedent code. The controlling executable is compiled from a C program that parses name-value pairs typical of an HTML post. That is, a web GUI interface can create the appropriate input file, and post the information to the ETC executable (a link in the web server's cgi-bin directory which points to the actual executable file ETCHOME/bin/etc). Here and elsewhere we refer to the top level ETC directory as ETCHOME. The appendix A1 contains a sample posted input file.

2


NICMOS ISR-00-005 When run, this executable program then calls the STSDAS.SYNPHOT.COUNTRATE task with the appropriate parameters, and calculates the expected signal to noise ratio (SNR). Two calls to COUNTRATE are made by the ETC: one for the source and one for the sky background. Example parameter files are shown in Appendix A2. COUNTRATE is invoked from the executable by means of a popen()UNIX system call in the routine ETCHOME/src/runimaging.c. Parameters for the SYNPHOT task are written to a disk file in a world-writable directory (ETCHOME/stage, a link to a physical directory accessible to the web server), and COUNTRATE is pointed to this file for its parameters. In order for a working IRAF environment to be present for this call, the file zzsetenv.def must exist in the working directory of the SYNPHOT executable's process (see Appendix A3). When called from a web browser, this working directory is usually the cgi-bin directory where the link to the ETC executable resides. The ETC can also be run from the command line using ASCII input which mimics the POST command from the web browser. The output of COUNTRATE is read through the pipe created by the call to popen(). Output to stdout from the ETC executable is normally HTML, and is driven by an externally defined output HTML file, ETCHOME/html/img_out.html. This enables the output to be displayed on the browser if the ETC is being run via the web. The manner in which an html file drives the output is not explained here, it is driven by the automatically created file html/img_out.html, which is generated from html/ img_out.inc.

Development and Debugging
Given this architecture, it is possible to capture the posted output of the web GUI and use that as an input file (argv[1])of the ETC executable itself, in order to run the ETC from the UNIX command line. This feature is used extensively during development, and can be useful for investigating large numbers of possible instrument configurations or targets. In order to capture the web post data, a freely distributable program ETCHOME/bin/postquery is called with the post data instead of the ETC executable. Switching between the real ETC and the web-post data capturing program is done with two scripts ETCHOME/ fake and ETCHOME/real --- these merely point the symbolic link in the cgi-bin directory of the web server to the ETC executable or the post-query executable. When `post-query' is executed, the posted name-value pairs appear on the browser after the `submit calculation' button is pressed, and this text can be captured into a file. The text must have trailing blanks removed in order to provide acceptable input to the ETC input parser. This input file is simple enough to be edited by hand to vary the submitted request. The camera, filter name, magnitude of source, and so on, can be changed this way. Error handling by the ETC (especially when run from the web browser) is minimal. Errors trapped within the ETC executable are typically reported via the output HTML form. Errors within the NICMOS thermal module are reported back to the executable

3


NICMOS ISR-00-005 using numerical error codes in the return values of the routines called. This is an area that could use improvement. Because incorrect HTML output by the ETC will cause the browser to fail to display the returned page, a compile switch -DDPRINTF is used when making prototype versions of the executable. This enables simple printf-style output to be produced (using a private dprintf() function) to facilitate development and command-line mode debugging. When this compile switch is not used, the printing to stdout from dprintf() is suppressed. The routine ETCHOME/src/dprintf.c implements this developer's feature, and must therefore be touch`ed to force its recompilation.The Makefile in the primary source code directory, ETCHOME/src/Makefile, contains sample compiler flag lines to enable or disable this feature. The HTML used to generate the web GUI and drive the ETC's output resides in ETCHOME/html. The ".html" files there are automatically generated from the `*.inc' and ".html.sav" files. This is an inherited feature from the STIS ETC code design. In order to change the GUI or the web output, one must edit these `.inc' files, remove all existing html files, and re-run the Makefile (using make) in this html directory. The script mmk in ETCHOME/html does this for the developer.

The thermal optics library
At this time SYNPHOT does not handle thermal radiation by components of the optical relay. Each optic in the relay has an area, a temperature and an emissivity (which is usually the quantity with the greatest uncertainty). An optical invariant known as the etendue is used to calculate the background thermal count rate in each pixel. The reflectivities and emissivities of the optics in the relay must be known to the NICMOS thermal optics module. At the moment this duplicates some telescope- and instrument-specific information that also exists in the CDBS data base. For more information on these details see Sivaramakrishnan et al, 2000 NICMOS ISR 01-00 and Robberto et al. (2000). SYNPHOT's CALCBAND task was used to create all possible `filter times DQE' throughput tables. The IRAF CL script which performs this calculation is described in Appendix A4. These tables are read in from a file specified in the call to the public functions offered by this library, and the thermal background for the instrument is returned. These files usually reside in a `filter_dqe' directory in the nicmos thermal library directory, to keep all the instrument-specific data within one directory. In the distribution described here a link is made to this directory in the general ETC data directory --- the directory name is passed as a parameter to the thermal library routine which calculates the background. The high level code obtains it from a #define in ETCHOME/src/config.h. The routine in the thermal library returns the thermal background (photons per second) in a pixel of a given camera, when using a given filter.

4


NICMOS ISR-00-005 NICMOS PSF-related quantities are hardwired into the source code of the thermal and optical library in a single file, ETCHOME/src/src_nicthermal/nic_physical.c. The telescope optical and thermal properties used to estimate telescope thermal background contributions are defined in the file ETCHOME/src/nic_thermal/hst_physical.c These are offered via two `public' calls in the library ETCHOME/lib/libnic.a.

Data files and models, and parameter and log files
All data files need to be located in world readable directories in order to be accessed from an executable in the cgi-bin directory of a web server. The NICMOS ETC uses the following data files in the ETCHOME/data directory · img_modes.dat: ASCII file, columns are camera number (1, 2 or 3), dark current (e-/s per pixel), readnoise (standard deviation in e- for a double correlated read), pixel scale (arcseconds/pixel), radius in pixels of 80% encircled energy disc when the psf is centered on a pixel, and finally the gain in data numbers per electron. Note that NICMOS has a gain in electrons per photon of unity. The camera parameters should be input to the NIC_physical object loaded by the call to the load_nic_physical() in the nicmos thermal library. With that in mind, the img_modes file should cease to be used. This encapsulation of camera-specific input is in progress. wavecat.dat: table of wavelengths used by SYNPHOT to calculate throughputs. [high, avg, low]z.tab files are currently just pointers to a calculated Zodiacal light model found in the original NICMOS ETC fortran code (cf. the STIS ETC). When data are generated for these sources of background radiation the links can be replaced with files containing realistic estimates various zodiacal background levels. This means that earthshine is not considered in the estimation of signal to noise ratios. Filter times DQE directory containing all possible filter and dqe throughputs. These are generated by the IRAF script "calcband.cl" in this directory. The directory is hardwired by the line #define QEFILTSUBDIR "filt+dqe_11_aug_1988/" in the file ETCHOME/src/config.h. The directory name indicates the date of the most recent CDBS data file used to create the `filter + DQE' throughput files. cat_*.dat: file containing list of spectral templates in the same directory, and the spectral templates themselves in various *.dat or other SYNPHOT-compliant files ETCHOME/stage is a world-writable directory where SYNPHOT's ASCII parameter files are written by the executable before the calls to SYNPHOT are forked. A log of each run of the ETC is also written here. This directory needs periodic file purging.

· ·

·

· ·

Source code directories
In ETCHOME there are two source code directories: src and html. The html directory contains all the html files and makefiles needed to generate the GUI web interface. The src directory contains the `high level ETC code' (in *.c and *.h files), as well as the NICMOS

5


NICMOS ISR-00-005 thermal library module (in the subdirectory src/src_nicthermal) and the CFITSIO library in src/src_cfitsio subdirectory. More detail on these is given in Appendix A5. All changes in the C code required to port the code to a new location are restricted to the first section of the ETCHOME/src/config.h file, and are clearly marked as local information. Changes in the web interface are restricted to the POST command in ETCHOME/ html/img_etc.inc file where a particular server might need to be specified

Adding template spectra and classes of spectra
A new spectral class of source or single spectrum can be added to the web interface by editing the file ETCHOME/html/img_etc.inc. To add a single source follow the examples in the html code there, being careful to distinguish between a character string presented in the web interface (e.g. "Gliese 229B") and its corresponding value in the POST'ed output stream (e.g. "Gl229B". To add a new class of sources, a new section must be added to the ETCHOME/html/ img_etc.inc file, but the C source code in the ETC must also be expanded. The file ETCHOME/src/dict.h will need a legal field added to the #define'd variable SPEC_TYPES, and the source code in ETCHOME/src/objectpars.c and ETCHOME/src/ setspecname.c will need revision. The ASCII file creating the mapping between the new class and the corresponding spectral data files will need to be created as well. For example, to add "Starburst Galaxies", with a corresponding `sorigin' value of "starburst" in the POST output stream of the web browser to the ETC executable, a field of `starburst', the file dict.h will need to be modified as follows:
#define SPEC_TYPES "user|model|cal|nonstellar|qso|synbb|synpl|synflat|starburst"

and a key added to the list following this #define: #define SPEC_STARBURST 9 (its value is a sequential number in the sequence of allowed types) The appropriate code corresponding to the added type will need to be inserted in the case statement in objectpars.c and setspecname.c. In objectpars.c, the corresponding `safecopy' call will specify "starburst" in its calling parameter list. A file ETCHOME/data/ cat_starburst will need to be created. In this file the particular offerings in the web page will be matched to SYNPHOT-compliant spectral data files present in ETCHOME/data. If the web page offered three choices of starburst spectral templates in the ETCHOME/html/ img_etc.inc file: