diff options
Diffstat (limited to 'noao/artdata/doc/mkechelle.hlp')
| -rw-r--r-- | noao/artdata/doc/mkechelle.hlp | 585 |
1 files changed, 585 insertions, 0 deletions
diff --git a/noao/artdata/doc/mkechelle.hlp b/noao/artdata/doc/mkechelle.hlp new file mode 100644 index 00000000..34e022c5 --- /dev/null +++ b/noao/artdata/doc/mkechelle.hlp @@ -0,0 +1,585 @@ +.help mkechelle Mar93 noao.artdata +.ih +NAME +mkechelle -- Make artificial echelle spectra +.ih +USAGE +mkechelle images [clobber] +.ih +PARAMETERS +.ls images +List of echelle spectra to create or modify. +.le +.ls clobber (query) +If an existing image is specified the clobber query parameter is used. +Normally the parameter is not specified on the command line so that +a query will be made for each image which exists. Putting a value +on the command line permanently overrides the query. This should be +done if the task is run in the background. +.le +.ls ncols = 512, nlines = 512, norders = 23 +For two dimensional spectra these parameters define the number of columns +and lines in the final image and the maximum number of orders (there may be +orders falling outside the image). The dispersion is along the columns +which is the second or line axis (dispersion axis is 2) so the number of +columns is the number of pixels across the dispersion and the number of +lines is the number of pixels along the dispersion per order. + +The extracted format turns the number of lines into the number columns +and the number of orders is the number of lines; i.e the image +has the specified number of extracted orders, one per image line, +with the number of pixels along the dispersion specified by the +\fInlines\fR parameter. This is equivalent to what the \fBapextract\fR +package would produces for an extracted echelle format with an original +dispersion axis of 2. There is no check in this case for orders +which might fall outside the two dimensional format; i.e. exactly +the number of orders are created. +.le +.ls title = "Artificial Echelle Spectrum" +Image title to be given to the spectra. Maximum of 79 characters. +.le +.ls header = "artdata$stdheader.dat" +Image or header keyword data file. If an image is given then the image +header is copied. If a file is given then the FITS format cards are +copied. The data file consists of lines in FITS format with leading +whitespace ignored. A FITS card must begin with an uppercase/numeric +keyword. Lines not beginning with a FITS keyword such as comments or lower +case are ignored. The user keyword output of \fBimheader\fR is an +acceptable data file. See \fBmkheader\fR for further information. +.le +.ls list = no +List the grating/instrument parameters? +.le +.ls make = yes +Make the artificial spectra? This is set to no if only the grating +parameter listing is desired. +.le +.ls comments = yes +Include comments recording task parameters in the image header? +.le + +.ce +FORMAT PARAMETERS +.ls xc = INDEF, yc = INDEF +The column and line position of the blaze peak in the reference order (see +\fIorder\fR parameter. If INDEF then the middle of the dimension is used. +This allows setting the image center relative to the center of the echelle +pattern. As with the number of lines and columns the interpretation of +these numbers relative to the image created depends on whether the format +is extracted or not. +.le +.ls pixsize = 0.027 +Pixel size in millimeters. This is used to convert the focal length +and dispersion to pixels. If INDEF then these parameters are +assumed to be in pixels. +.le +.ls profile = "gaussian" (extracted|gaussian|slit) +The order profile across the dispersion. If the value is "extracted" +then an extracted echelle format spectrum is produced. Otherwise a +two dimensional format with a gaussian or slit profile is produced. +See \fBmk2dspec\fR for a discussion of the profile functions. +.le +.ls width = 5. +If two dimensional echelle images are selected this parameter specifies +the order profile full width at half maximum in pixels. See \fBmk2dspec\fR +for a fuller discussion. +.le +.ls scattered = 0. +Scattered light peak flux per pixel. A simple scattered light component +may be included in the two dimensional format. The scattered light has the +blaze function shape of the central order along the dispersion and the +crossdisperser blaze function shape across the dispersion with the peak +value given by this parameter. A value of zero indicates no scattered +light component. +.le + +.ce +GRATING PARAMETERS + +Any of the following parameters may be specified as INDEF. The missing +values are resolved using the grating equations described in the +DESCRIPTION section. If it is not possible to resolve all the grating +parameters but the order, wavelength, and dispersion are specified +then a linear dispersion function is used. Also in this case the +extracted format will include dispersion information. +.ls f = 590., cf = 590. +Echelle and crossdisperser focal lengths in millimeters (if \fIpixsize\fR +is given) or pixels. Technically it is defined by the equation x = f * tan +(theta) where x is distance from the optical axis on the detector and theta +is the diffraction angle; i.e. it converts angular measures to millimeters +or pixels on the detector. If the focal length is specified as INDEF it +may be computed from the dispersion, which is required in this case, and +the other parameters. +.le +.ls gmm = 31.6, cgmm = 226. +Echelle and crossdisperser grating grooves per millimeter. If specified as +INDEF it may be computed from the order, which is required in this case, +and the other parameters. +.le +.ls blaze = 63., cblaze = 4.53 +Echelle and crossdisperser blaze angles in degrees. It is always specified or printed as a positive +angle relative to the grating normal. If specified as INDEF it is +computed from the other parameters. +.le +.ls theta = 69., ctheta = -11.97 +Echelle and crossdisperser angles of incidence in degrees. The angle of +incidence must be in the plane perpendicular to face of the grating. The +angle of incidence may be specified relative to the grating normal or the +blaze angle though it is always printed relative to the grating normal. To +specify it relative to the blaze angle add 360 degrees; for example to have +an angle of 15 degrees less than the blaze angle specify 360 - 15 = 345. +If the angle of incidence is specified as INDEF it is computed from the +other parameters. +.le +.ls order = 112 +The central or reference echelle order for which the wavelength and +dispersion are specified. If specified as INDEF it will be computed from +the grooves per mm, which is required in this case, and the other +parameters. In combination with the number of orders this defines the +first and last orders. The highest order is the central order plus +the integer part of one half the number of orders. However, the +lowest order is constrained to be at least 1. The +reference order is also used in the definitions of \fIxc\fR and \fIyc\fR. +.le +.ls corder = 1 +The crossdisperser order for which the crossdisperser blaze wavelength and +dispersion are specified. If specified as INDEF it will be computed from +the grooves per mm, which is required in this case, and the other +parameters. + +If the order is zero then the other grating parameters are ignored and a +prism-like dispersion is used with the property that the order spacing is +constant. Specifically the dispersion varies as the inverse of the +wavelength with the \fIcwavelength\fR and \fIcdispersion\fR defining the +function. +.le +.ls wavelength = 5007.49 cwavelength = 6700. +Echelle and crossdisperser blaze wavelengths in Angstroms at the reference +orders. If specified as INDEF it will be computed from the other parameters. +.le +.ls dispersion = 2.61 cdispersion = 70. +Echelle and crossdisperser blaze dispersions in Angstroms per millimeter +(if \fIpixsize\fR is specified) or pixels. +If specified as INDEF it will be computed from the focal length, which is +required in this case, and the other parameters. +.le + +.ce +SPECTRA PARAMETERS +.ls rv = 0. +Radial velocity (km/s) or redshift, as selected by the parameter \fIz\fR, +applied to line positions and continuum. Velocities are converted to +redshift using the relativistic relation 1+z = sqrt ((1+rv/c)/(1-rv/c)). +Note the shift is not a shift in the dispersion parameters but in the +underlying artificial spectrum. +.le +.ls z = no +Is the velocity parameter a radial velocity or a redshift? +.le +.ls continuum = 1000. +Continuum at the echelle blaze peak in the reference order. +.le +.ls temperature = 5700. +Blackbody continuum temperature in Kelvin. A value of 0 is used if +no blackbody continuum is desired. The intensity level is set by +scaling to the continuum level at blaze peak reference point. +.le + +.ls lines = "" +List of spectral line files. Spectral line files contain lines of rest +wavelength, peak, and widths (see the DESCRIPTION section). +The latter two parameters may be missing in which case they default to +the task \fIpeak\fR and \fIsigma\fR parameters. If no file or a new +(nonexistent) file is specified then a number of random lines given by the +parameter \fInlines\fR is generated. If a new file name is specified then +the lines generated are recorded in the file. If the list of spectral +line files is shorter than the list of input spectra, the last +spectral line list file is reused. +.le +.ls nlines = 0 +If no spectral line file or a new file is specified then the task will +generate this number of random spectral lines. The rest wavelengths are +uniformly random within the limits of the spectrum, the peaks are +uniformly random between zero and the value of the \fIpeak\fR parameter +and the width is fixed at the value of the \fIsigma\fR parameter. +If a redshift is applied the rest wavelengths are shifted and repeated +periodically. +.le +.ls peak = -0.5 +The maximum spectral line peak value when generating random lines or +when the peak is missing from the spectral line file. +This value is relative to the continuum unless the continuum is zero. +Negative values are absorption lines and positive values are emission lines. +.le +.ls sigma = 1. +The default line width as a gaussian sigma in Angstroms when generating +random lines or when the width is missing from the spectral line file. +.le +.ls seed = 1 +Random number seed. +.le + +PACKAGE PARAMETERS +.ls nxsub = 10 +Number of pixel subsamples used in computing the gaussian spectral line +profiles. +.le +.ls dynrange = 100000. +The gaussian line profiles extend to infinity so a dynamic range, the ratio +of the peak intensity to the cutoff intensity, is imposed to cutoff the +profiles. +.le +.ih +DESCRIPTION +This task creates or adds to artificial extracted (one dimensional +"echelle" format) or two dimensional echelle spectra. The input spectrum +(before modification by the spectrograph model) may be a combination of +doppler shifted blackbody or constant continuum and emission and absorption +gaussian profile spectral lines. The lines may have randomly selected +parameters or be taken from an input file. Note that the parameters and +method is similar to the task \fBmk1dspec\fR except that the input line list +cannot specify a profile type and only Gaussian profiles are currently +allowed. The input spectrum is then +separated out into echelle orders and either recorded as extracted one +dimensional orders or convolved with a spatial profile and crossdispersed +into a two dimensional image. The properties of the echelle grating, +crossdisperser, and instrumental configuration are modeled described +later. + +If an existing image is specified the \fIclobber\fR parameter is used +to determine whether to add the generated artificial echelle spectrum +to the image. Generally the clobber parameter is not specified on the +command line to cause a query with the image name to be made for +each image which already exists. However, it is possible to put +the clobber parameter on the command line to eliminate the query. +This is appropriate for running the task in the background. + +There is \fIno\fR checking for consistency with an existing image; +i.e. that it is an echelle image, whether it is an extracted format +or a two dimensional spectrum, and what it's wavelength and order +coverage is. The only thing that happens is that the \fIncols\fR, +\fInlines\fR, and \fInorders\fR parameters are replaced by the appropriate +dimensions of the image with the choice between \fInlines\fR and +\fInorders\fR made by the \fIprofile\fR parameter (as discussed below) +and not by the format of the image. + +The created spectra are two dimensional, real datatype, images. A title +may be given and a set of header keywords be added by specifying an image +or data file with the \fIheader\fR parameter (see also \fBmkheader\fR). If +a data file is specified lines beginning with FITS keywords are entered in +the image header. Leading whitespace is ignored and any lines beginning +with words having lowercase and nonvalid FITS keyword characters are +ignored. In addition to this optional header, various parameters which +occur during reduction of real echelle spectra, such a wavelength +coordinates for extracted and dispersion corrected spectra, are added. +Finally, comments may be added to the image header recording the task +parameters and any information from the line file which are not line +definitions. + +The creation of an artificial echelle spectra has three stages. First a +true spectrum is generated; i.e. the spectrum which arrives at the +spectrograph. The spectrum is then separated into orders and the +dispersion and blaze functions of the echelle and crossdisperser gratings +(or crossdisperser prism) are applied. Finally, if a two dimensional +format is desired it is convolved by an spatial profile (either a gaussian +or a broader slit-like profile) and the orders are placed as required by +the crossdispersion relation. + +Generation of the model spectrum has three parts; defining a continuum, +adding emission and absorption lines, and applying a doppler shift. The +continuum has two parameters; an intensity scale set by the \fIcontinuum\fR +parameter and a shape set by the \fItemperature\fR parameter. The +intensity scale is set by defining the total, final, extracted intensity in +a pixel at the blaze peak (rest) wavelength in the reference order; i.e. at +the wavelength set by the \fIwavelength\fR parameter. Note this means that +the efficiency of the gratings at that wavelength is included. The shape +of the continuum may be either a blackbody if a positive temperature is +specified or constant. + +Spectral lines are modeled by gaussian profiles of specified wavelength, +peak, and sigma. The lines are defined in a spectral line file or +generated randomly. A spectral line file consists of text lines giving +rest wavelength, peak, and sigma. The sigma or the sigma and peak may be +absent in which case the parameters \fIsigma\fR and \fIpeak\fR will be +used. If peak values are missing random values between zero and the +\fIpeak\fR value are generated. Thus, a simple list of wavelengths or a +list of wavelengths and peaks may be used. + +If no spectral line file is specified or a new (nonexistent) file is named +then the number of random lines given by the parameter \fInlines\fR is +generated. The rest wavelengths are uniformly random within the wavelength +range of the spectrum and extend periodically outside this range in the +case of an applied velocity shift, the peaks are uniformly random between +zero and the \fIpeak\fR parameter, and the widths are given by the +\fIsigma\fR parameter. If a new file is named then the parameters of the +generated lines will be output. + +The peak values are taken relative to a positive continuum. In other words +the generated line profile is multiplied by the continuum (with a minimum +of zero for fully saturated absorption lines). If the continuum is less +than or equal to zero, as in the case of an artificial arc spectrum or pure +emission line spectrum, then the peak values are interpreted as absolute +intensities. Positive peak values produce emission lines and negative +values produce absorption lines. Odd results will occur if the continuum +has both positive and zero or negative values. + +The width values are gaussian sigmas given in Angstroms. + +The underlying rest spectrum may be shifted. This is used primarily for +testing radial velocity measuring algorithms and is not intended as a +complete model of redshift effects. The observed wavelength coverage as +defined by the grating parameters and number of orders is not changed by +redshifting. Input line wavelengths are specified at rest and then shifted +into or out of the final spectrum. To be realistic the line list should +include wavelengths over a great enough range to cover all desired +redshifts. The peaks and sigma are also appropriately modified by a +redshift. As an example, if the redshift is 1 the lines will appear +broader by a factor of 2 and the peaks will be down by a factor of 2 in +order to maintain the same flux. + +The random line generation is complicated because one wants to have the +same set of lines (for a given seed) observed at different redshifts. What +is done is that the specified number of random lines is generated within +the observed wavelength interval taken at rest. This set is then repeated +periodical over all wavelengths. A redshift will then shift these rest +lines in to or out of the observed spectrum. If the lines are output to a +line file, they are given at rest. \fBNote that this periodicity may be +important in interpreting cross-correlation redshift tests for large shifts +between template and object spectra.\fR + +The definitions of the continuum are also affected by a redshift. The +reference point for the continuum level and blackbody shape is the starting +wavelength taken at rest. Shifts will then modify the continuum level at +the reference pixel appropriately. In particular a large redshift will +shift the blackbody in such a way that the flux is still given by the +\fIcontinuum\fR parameter at the reference wavelength at rest. + +Once the input spectrum is defined it is modified by the effects of an +echelle grating and crossdispersion. This includes the dispersion relation +between pixel and wavelength, the blaze response function of the gratings, +and separation into orders. + +The primary reference for the model of the echelle grating (a +crossdisperser grating also obeys this model) used in this task is "Echelle +efficiencies: theory and experiment" by Schroeder and Hilliard in Applied +Optics, Vol. 19, No. 16, 1980, p. 2833. (The nomenclature below is similar +to that paper except we use theta for alpha, their theta is theta - blaze, +the reciprocal of the groove spacing which is the grooves per millimeter, +and the dispersion per linear distance at the detector rather than per +radian). This task only treats the case where the incident beam is in the +plane perpendicular to the grating face (gamma=0). In this case the basic +equation is + +.nf +(1) m * lambda = (sin(theta) + sin(beta)) / g +.fi + +where m is the order, lambda the wavelength, g the grooves per wavelength +unit, theta the angle of incidence to the grating normal, and beta the +angle of diffraction to the normal. The diffraction angle relative to that +of the blaze maximum, psi, is given by + +.nf +(2) beta = psi + 2 * blaze - theta +.fi + +where blaze is the blaze angle. The diffraction angle psi is related to +position on the detector, again measured from the blaze peak, by + +.nf +(3) x = f / pixsize * tan(psi) +.fi + +where f is the effective focal length (as defined by this equation) and +pixsize is the pixel size in millimeters that converts the detector +positions to pixels. If a pixel size is not specified then f will be +taken as being in pixels. + +The second basic equation is the diffraction pattern or blaze response +given by + +.nf +(5) I = I0 * (sin(delta) / delta) ** 2 +(6) delta = 2 * pi / lambda * (cos(theta) / g) / cos(epsilon) * + sin(psi/2) * cos(epsilon-psi/2) +(7) epsilon = theta - blaze +.fi + +where epsilon is the angle between the blaze angle and the angle of +incidence (the theta of Shroeder and Hilliard). When theta = blaze, (6) +simplifies to + +.nf +(6a) delta = pi / lambda * (cos (blaze) / g) * sin (psi) +.fi + +As discussed by Schroeder and Hilliard, the relative intensity at the blaze +peak, I0, must be reduced by the fraction of light at the same wavelength +as the blaze peak which is diffracted into other orders. Furthermore at +some diffraction angles the light is reflected off the second face of the +grating giving a different effective diffraction angle to be used in (6). +This computation is done by the task giving a variation in relative blaze +response with order and reproducing the calculations of Schroeder and +Hilliard. The absolute normalization, including the crossdisperser blaze +function if any, is such that the response at the blaze peak of the +reference order is unity. This insures that specified continuum level at +the reference wavelength is produced. + +At the blaze maximum psi = x = 0 and the wavelength and dispersion per +millimeter on the detector are given by (1) and the derivative of (1) with +respect to x: + +.nf +(8) wavelength = 1E7*(sin(theta)+sin(2*blaze-theta))/(gmm*order) +(9) dispersion = 1E7*cos(2*blaze-theta)/(gmm*order*f/pixsize) +.fi + +The variable names are the same as the parameters in this task. In +particular, gmm is the echelle grooves per millimeter with the factors of +1E7 (10 to the seventh power) to convert to Angstroms, the factor of f / +pixsize to convert the dispersion to per pixel, and order is the reference +order for the wavelength and dispersion. + +The \fBmkechelle\fR task provides different ways to define the parameters. +If there is insufficient information to determine all the grating +parameters but the wavelength, dispersion, order are specified then +a simplified grating equation is used which is linear with pixel +position. The approximation is that tan(psi) = sin(psi) = psi so +that + +.nf +(9) lambda = (order * wavelength + dispersion * x) / m + = (a + b * x) / m +(10) delta = pi * order * dispersion / lambda * x + = c / lambda * x +.fi + +Also in this case the extracted format (described later) includes +wavelength information in the header so that the spectra appear as fully +dispersion corrected. + +If there are at least five of the seven grating parameters specified +then equations (8) and (9) are used to determine +unspecified parameters or to override parameters if the equations are +overspecified. For example, suppose the grooves per millimeter is known +but not the blaze angle or focal length. Then the wavelength and +dispersion at the reference order are used to compute these quantities. + +The full set of grating parameters derived and used to create the spectra +are documented in the image header if the \fIcomments\fR parameter is +specified. Also the \fIlist\fR parameter may be set to print the grating +parameters and the \fImake\fR parameter may be set to no to check the +grating parameters without making the spectra. + +The crossdisperser grating parameters are treated exactly as above except, +since only one order is used, the relative blaze efficiency is not +computed. + +There is a variant on the crossdispersion to allow a prism-like separation +of the echelle orders. If the crossdispersion grating order, \fIcorder\fR +is set to zero then the other grating parameters are ignored and a +prism-like dispersion is used with the property that the order spacing is +constant. Specifically the dispersion varies as the inverse of the +wavelength with the \fIcwavelength\fR and \fIcdispersion\fR defining the +function. There is no crossdisperser blaze function in this case either; +i.e. the relative intensities between orders is solely due to the echelle +grating blaze response. + +There is an interesting effect which follows from the above equations but +which is not obvious at first glance. When the full grating equation is +used the dispersion varies with wavelength. This means the size of a pixel +in wavelength varies and so the flux in a pixel changes. The effect is +such that the order intensity maximum shifts to the blue from the blaze peak +because the pixel width in Angstroms increases to the blue faster, for a +while, than the blaze response decreases. + +Once the spectrum has been separated into orders, modified by the +grating blaze functions, and sampled into pixels in the dispersion +direction it may be output as an extracted "echelle" format spectrum. +This occurs when the spatial profile is specified as "extracted". +The keywords added by the \fBapextract\fR package are included in +the image header. If the dispersion model is linear +the keywords are the same as those produced by the dispersion +correction task \fBecdispcor\fR. + +If the spatial profile is specified as "gaussian" or "slit" then the +orders are convolved by the profile function and the crossdispersion +relation is used to determine where the order falls at each wavelength. +The spatial profiles are defined by the formulas: + +.nf + gaussian: I(x) = exp (-ln(2) * (2*(x-xc(w))/width)**2) + slit: I(x) = exp (-ln(2) * (2*(x-xc(w))/width)**10) +.fi + +where x is the spatial coordinate, xc(w) is the order center at +wavelength w, and width is the full width at half maximum specified by +the parameter of that name. The "gaussian" profile +is the usual gaussian specified in terms of a FWHM. The "slit" +profile is one which is relatively flat and then rapidly drops +to zero. The profile is normalized to unit integral so that +the total flux across the profile is given by the scaled +1D spectrum flux. The profile is fully sampled and then binned to +the pixel size to correctly include sampling effects as a function +of where in a pixel the order center falls. + +Note that in this model the orders are always tilted with respect +to the columns and constant wavelength is exactly aligned with the +image lines. +.ih +EXAMPLES +1. Create an absorption spectrum with blackbody continuum and scattered +light using the default grating parameters then add noise. + +.nf + cl> mkechelle ex1 nrand=100 scat=100. + cl> mknoise ex1 gain=2 rdnoise=5 poisson+ +.fi + +2. Create an arc spectrum using the line list noao$lib/onedstds/thorium.dat. + +.nf + cl> mkechelle ex2 cont=10 temp=0 \ + lines=noao$lib/onedstds/thorium.dat peak=1000 sigma=.05 +.fi + +Note that the line intensities are random and not realistic. The peak +intensities range from 0 to 1000 times the continuum or 10000. + +3. Create an extracted version of example1. + +.nf + cl> mkechelle ex1.ec prof=extracted nrand=100 scat=100. + cl> mknoise ex1.ec gain=2 rdnoise=5 poisson+ +.fi + +Note that the noise is different and greater than would be the case with +extracting the orders of example 1 because the noise is not summed +over the order profile but is added after the fact. + +4. Create an extracted and dispersion corrected version of example1. + +.nf + cl> mkechelle ex1.ec prof=extracted nrand=100 scat=100. \ + gmm=INDEF blaze=INDEF theta=INDEF + Echelle grating: Using linear dispersion + Warning: Insufficient information to resolve grating parameters + cl> mknoise ex1.ec gain=2 rdnoise=5 poisson+ +.fi + +The warning is expected. By not specifying all the parameters needed to +fully model an echelle grating the default action is to use a linear +dispersion in each order and to set the image header dispersion +information. When a complete grating model is specified, as in example 3, +the extracted spectrum is not given dispersion information so that the +nonlinear behavior of the dispersion can be applied by \fBecidentify\fR and +\fBdispcor\fR. As with example 3, the noise is different since it is added +after extraction and dispersion correction. +.ih +REVISIONS +.ls MKECHELLE V2.10.3 +The task was updated to produce the current coordinate system format. +.le +.ih +SEE ALSO mknoise, mk1dspec, mk2dspec, mkheader, astutil.gratings +.endhelp |