MUSE Pipeline Reference Manual  2.1.1
muse_instrument.h
1 /* -*- Mode: C; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* vim:set sw=2 sts=2 et cin: */
3 /*
4  * This file is part of the MUSE Instrument Pipeline
5  * Copyright (C) 2008-2017 European Southern Observatory
6  *
7  * This program is free software; you can redistribute it and/or modify
8  * it under the terms of the GNU General Public License as published by
9  * the Free Software Foundation; either version 2 of the License, or
10  * (at your option) any later version.
11  *
12  * This program is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15  * GNU General Public License for more details.
16  *
17  * You should have received a copy of the GNU General Public License
18  * along with this program; if not, write to the Free Software
19  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
20  */
21 
22 #ifndef MUSE_INSTRUMENT_H
23 #define MUSE_INSTRUMENT_H
24 
25 /*----------------------------------------------------------------------------*
26  * Includes *
27  *----------------------------------------------------------------------------*/
28 /* none for this file */
29 
30 /*----------------------------------------------------------------------------*
31  * Telescope properties *
32  *----------------------------------------------------------------------------*/
33 /* these are the values that we got for the effective pupil area of *
34  * the VLT for the focal position of MUSE, and the semi-retracted sky *
35  * baffle diameter as apparently used with MUSE */
36 static const double kVLTPupilDiameter = 798.62; /* [cm] */
37 static const double kVLTSkyBaffleDeployed = 150.0; /* [cm] */
38 /* now the real area that we want, this is *
39  * (kVLTPupilDiameter**2 - kVLTSkyBaffleDeployed**2) * PI / 4 *
40  * [use way more digits than the measurement accuracy would suggest...] */
41 static const double kVLTArea = 483250.7024654051; /* [cm**2] */
42 
43 /*----------------------------------------------------------------------------*
44  * Instrument properties *
45  * *
46  * These variables are defined as static because they are included in several *
47  * C source files and linking will otherwise not work. *
48  *----------------------------------------------------------------------------*/
49 /* nominal sizes of MUSE spaxels in both WFM and NFM */
50 static const double kMuseSpaxelSizeX_WFM = 0.2;
51 static const double kMuseSpaxelSizeY_WFM = 0.2;
52 static const double kMuseSpaxelSizeX_NFM = 0.025;
53 static const double kMuseSpaxelSizeY_NFM = 0.025;
54 
55 /* Expected average FWHM [pix] of a point-like lamp emission line on the CCD */
56 static const double kMuseAverageFWHM_x = 1.6;
57 static const double kMuseAverageFWHM_y = 1.6;
58 
59 /* Output positions as they should be recorded in the FITS header (OUTn X/Y). *
60  * Values for the lower quadrants are always 1, so they are not listed here. */
61 static const int kMuseOutputXRight = 4096;
62 static const int kMuseOutputYTop = 4112;
63 /* standard size of pre- and overscans */
64 static const int kMusePreOverscanSize = 32;
65 
66 /* all values above this in raw data are considered saturated */
67 static const float kMuseSaturationLimit = 65500.;
68 
69 /* number of IFUs per exposure */
70 static const int kMuseNumIFUs = 24;
71 
72 /* number of slices in each MUSE CCD/IFU */
73 static const unsigned short kMuseSlicesPerCCD = 48;
74 /* maximum offset of the first slice to the CCD edge to be expected [pix] */
75 static const int kMuseSliceSearchRegion = 200;
76 /* maximum slice width ever to be expected [pix] */
77 static const int kMuseSliceMaxWidth = 100;
78 /* nominal width of a slice [pix] within the MUSE field of view */
79 static const int kMuseSliceNominalWidth = 75;
80 /* low and high values for likely slice widths to be found (in INM data, *
81  * values are between 74.2+/-0.2 and 79.2+/-0.3; take a bit more here) */
82 static const float kMuseSliceLoLikelyWidth = 72.2;
83 static const float kMuseSliceHiLikelyWidth = 82.2;
84 /* max expected width of a slice edge [pix] */
85 /* XXX effectively switch this off by choosing a high number, *
86  * otherwise tracing inaccuracies in the blue mark many pixels dark */
87 static const int kMuseSliceMaxEdgeWidth = 10;
88 
89 /* MUSE nominal spectral sampling in Angstrom */
90 static const float kMuseSpectralSamplingA = 1.25;
91 /* slice width in wavelength direction, in Angstrom. See
92  R.Bacon, Analysis of the spectral PSF, 2009, VLT-TRE-MUS-14670-0870. */
93 static const double kMuseSliceSlitWidthA = 2.61;
94 
95 /* MUSE nominal spectral range in Angstrom (extended wavelength range, WFM!) */
96 static const float kMuseNominalLambdaMin = 4650.;
97 static const float kMuseNominalLambdaMax = 9300.;
98 /* approximate lower limit of nominal wavelength range with detectable flux */
99 static const float kMuseNominalCutoff = 4750;
100 static const float kMuseAOCutoff = 4690;
101 /* where the blue cutoff filter really kicks in */
102 static const float kMuseNominalCutoffKink = 4775.;
103 static const float kMuseAOCutoffKink = 4700.;
104 /* most extreme wavelength ranges possibly recorded on the MUSE CCDs */
105 static const float kMuseLambdaMinX = 4150.;
106 static const float kMuseLambdaMaxX = 9800.;
107 /* useful wavelength ranges: *
108  * common, and illuminated ranges between all slices */
109 static const float kMuseUsefulELambdaMin = 4600.;
110 static const float kMuseUsefulNLambdaMin = 4750.;
111 static const float kMuseUsefulAOLambdaMin = 4700.;
112 static const float kMuseUsefulLambdaMax = 9350.;
113 /* range where the NaD notch filters absorbs significant flux */
114 static const float kMuseNaLambdaMin = 5755.; /* for WFM-AO-E */
115 static const float kMuseNaLambdaMax = 6008.;
116 static const float kMuseNa2LambdaMin = 5805.; /* for WFM-AO-N */
117 static const float kMuseNa2LambdaMax = 5966.;
118 /* maximum centering error [pix] to allow for arc lines */
119 static const float kMuseArcMaxCenteringError = 1.25;
120 /* minimum and maximum FWHM [pix] to allow for arc lines */
121 static const float kMuseArcMinFWHM = 1.0;
122 static const float kMuseArcMaxFWHM = 5.0;
123 /* minimum flux (Gaussian area) measured for arc lines */
124 static const float kMuseArcMinFlux = 50.0;
125 
126 /* typical MUSE datacube size in pixels, assuming "natural" sampling */
127 static const int kMuseTypicalCubeSizeX = 300;
128 static const int kMuseTypicalCubeSizeY = 288;
129 
130 /* The sky slice number for the CCD slice /index/, e.g. to get *
131  * sky-slice number for CCD slice 12, use kMuseGeoSliceSky[12 - 1]. *
132  * This relation was taken from the "Global Positioning System" *
133  * document (VLT-TRE-MUS-14670-0657 v1.06, dated 2010-12-14). */
134 static const unsigned char kMuseGeoSliceSky[] = {
135  9, 8, 1, 10, 7, 2, 11, 6, 3, 12, 5, 4, /* stack 4 */
136  21, 20, 13, 22, 19, 14, 23, 18, 15, 24, 17, 16, /* stack 3 */
137  33, 32, 25, 34, 31, 26, 35, 30, 27, 36, 29, 28, /* stack 2 */
138  45, 44, 37, 46, 43, 38, 47, 42, 39, 48, 41, 40 /* stack 1 */
139 };
140 
141 /* numbers from CU multi-pinhole mask (CUmpm / MultiP) design */
142 static const float kMuseCUmpmDX = 2.9450, /* +/- 0.0010 mm horizontal hole distance */
143  kMuseCUmpmDY = 0.6135; /* +/- 0.0010 mm vertical hole distance */
144 
145 /* expected number of pinholes per slice */
146 static const unsigned char kMuseCUmpmSpotsPerSlice = 3;
147 
148 /*----------------------------------------------------------------------------*
149  * Instrument constants related to the photo diodes/pico amplfiers (PAM/AMPL) *
150  *----------------------------------------------------------------------------*/
151 /* spectral sensitivity of photo diode 1 (BN-DSR-100F-1, SN 20478), *
152  * wavelengths in [Angstrom], sensitivity in [A/W] */
153 static const double kMuseAmpl1[][2] = {
154  { 2500., 0.12042285 },
155  { 2600., 0.10860598 },
156  { 2700., 0.10029241 },
157  { 2800., 0.1010473 },
158  { 2900., 0.11258141 },
159  { 3000., 0.12635038 },
160  { 3100., 0.13448966 },
161  { 3200., 0.13880026 },
162  { 3300., 0.1423209 },
163  { 3400., 0.14222383 },
164  { 3500., 0.14018333 },
165  { 3600., 0.13863897 },
166  { 3700., 0.14285144 },
167  { 3800., 0.15266077 },
168  { 3900., 0.16535348 },
169  { 4000., 0.1770276 },
170  { 4100., 0.18605701 },
171  { 4200., 0.19385006 },
172  { 4300., 0.20142353 },
173  { 4400., 0.20986195 },
174  { 4500., 0.21819498 },
175  { 4600., 0.22561278 },
176  { 4700., 0.23293989 },
177  { 4800., 0.23908501 },
178  { 4900., 0.24622256 },
179  { 5000., 0.25217267 },
180  { 5100., 0.25847973 },
181  { 5200., 0.2651326 },
182  { 5300., 0.27124827 },
183  { 5400., 0.27774291 },
184  { 5500., 0.28288282 },
185  { 5600., 0.28884646 },
186  { 5700., 0.29560289 },
187  { 5800., 0.30107169 },
188  { 5900., 0.30661891 },
189  { 6000., 0.31317781 },
190  { 6100., 0.3185658 },
191  { 6200., 0.3247822 },
192  { 6300., 0.33013667 },
193  { 6400., 0.33590527 },
194  { 6500., 0.34120136 },
195  { 6600., 0.34646811 },
196  { 6700., 0.35219427 },
197  { 6800., 0.35768868 },
198  { 6900., 0.36601971 },
199  { 7000., 0.36940652 },
200  { 7100., 0.3735187 },
201  { 7200., 0.37902808 },
202  { 7300., 0.38475409 },
203  { 7400., 0.39095198 },
204  { 7500., 0.39615039 },
205  { 7600., 0.40184217 },
206  { 7700., 0.40682911 },
207  { 7800., 0.41245076 },
208  { 7900., 0.41851005 },
209  { 8000., 0.42465427 },
210  { 8100., 0.4292767 },
211  { 8200., 0.43596086 },
212  { 8300., 0.44151703 },
213  { 8400., 0.4458525 },
214  { 8500., 0.45129183 },
215  { 8600., 0.45772061 },
216  { 8700., 0.46303733 },
217  { 8800., 0.4683445 },
218  { 8900., 0.4728841 },
219  { 9000., 0.47827183 },
220  { 9100., 0.48365046 },
221  { 9200., 0.48835047 },
222  { 9300., 0.49350086 },
223  { 9400., 0.49763584 },
224  { 9500., 0.50120751 },
225  { 9600., 0.50337176 },
226  { 9700., 0.50266209 },
227  { 9800., 0.49823605 },
228  { 9900., 0.48887253 },
229  { 10000., 0.47199137 },
230  { 10100., 0.44744711 },
231  { 10200., 0.41367036 },
232  { 10300., 0.37072293 },
233  { 10400., 0.31936173 },
234  { 10500., 0.26252744 },
235  { 10600., 0.2092668 },
236  { 10700., 0.16926374 },
237  { 10800., 0.13819477 },
238  { 10900., 0.11170627 },
239  { 11000., 0.089087876 },
240  { 0., 0. } /* signify end of curve */
241 };
242 /* spectral sensitivity of photo diode 2 (PD-9304-1, SN 16536aw1), *
243  * wavelengths in [Angstrom], sensitivity in [A/W] */
244 static const double kMuseAmpl2[][2] = {
245  { 3800., 0.017470643 },
246  { 3900., 0.028092218 },
247  { 4000., 0.042101743 },
248  { 4100., 0.057172072 },
249  { 4200., 0.072846443 },
250  { 4300., 0.088312251 },
251  { 4400., 0.10446471 },
252  { 4500., 0.12060106 },
253  { 4600., 0.13705176 },
254  { 4700., 0.15291203 },
255  { 4800., 0.16783374 },
256  { 4900., 0.18414104 },
257  { 5000., 0.2002173 },
258  { 5100., 0.21605915 },
259  { 5200., 0.23228403 },
260  { 5300., 0.24804161 },
261  { 5400., 0.26350352 },
262  { 5500., 0.27958034 },
263  { 5600., 0.2948433 },
264  { 5700., 0.3098418 },
265  { 5800., 0.32511413 },
266  { 5900., 0.3396649 },
267  { 6000., 0.35432272 },
268  { 6100., 0.36892068 },
269  { 6200., 0.38268224 },
270  { 6300., 0.3965248 },
271  { 6400., 0.41013499 },
272  { 6500., 0.42306177 },
273  { 6600., 0.43585509 },
274  { 6700., 0.44871039 },
275  { 6800., 0.46041305 },
276  { 6900., 0.47379706 },
277  { 7000., 0.48452311 },
278  { 7100., 0.49428201 },
279  { 7200., 0.50518957 },
280  { 7300., 0.51604378 },
281  { 7400., 0.52577538 },
282  { 7500., 0.53560665 },
283  { 7600., 0.54571763 },
284  { 7700., 0.55427559 },
285  { 7800., 0.56320912 },
286  { 7900., 0.57262044 },
287  { 8000., 0.58063817 },
288  { 8100., 0.58978081 },
289  { 8200., 0.59650748 },
290  { 8300., 0.60433599 },
291  { 8400., 0.61148995 },
292  { 8500., 0.61874995 },
293  { 8600., 0.62610294 },
294  { 8700., 0.63217003 },
295  { 8800., 0.63791206 },
296  { 8900., 0.6449613 },
297  { 9000., 0.65062382 },
298  { 9100., 0.65685802 },
299  { 9200., 0.66314835 },
300  { 9300., 0.6684782 },
301  { 9400., 0.67349904 },
302  { 9500., 0.67880835 },
303  { 9600., 0.68235343 },
304  { 9700., 0.68390407 },
305  { 9800., 0.68117654 },
306  { 9900., 0.67307881 },
307  { 10000., 0.65663219 },
308  { 10100., 0.62937674 },
309  { 10200., 0.5886552 },
310  { 10300., 0.53176402 },
311  { 10400., 0.46039876 },
312  { 10500., 0.37838965 },
313  { 10600., 0.29937021 },
314  { 10700., 0.23830659 },
315  { 10800., 0.19124631 },
316  { 10900., 0.1523348 },
317  { 11000., 0.1193815 },
318  { 0., 0. } /* signify end of curve */
319 };
320 /* physical size of the sensitive area of each photo diode */
321 static const double kMuseAmplPhysicalSize = 1.; /* [cm**2] */
322 
323 /*----------------------------------------------------------------------------*
324  * Special variable types *
325  *----------------------------------------------------------------------------*/
326 
327 /*----------------------------------------------------------------------------*/
337 /*----------------------------------------------------------------------------*/
338 typedef enum {
339  MUSE_MODE_WFM_NONAO_E = 0,
340  MUSE_MODE_WFM_NONAO_N = 1,
341  MUSE_MODE_WFM_AO_E = 2,
342  MUSE_MODE_WFM_AO_N = 3,
343  MUSE_MODE_NFM_AO_N = 4
344 } muse_ins_mode;
345 
346 /*----------------------------------------------------------------------------*
347  * Function prototypes *
348  *----------------------------------------------------------------------------*/
349 /* none for this file */
350 
351 #endif /* MUSE_INSTRUMENT_H */