UVES Pipeline Reference Manual  5.4.0
uves_utils.h
1 /*
2  * This file is part of the ESO UVES Pipeline
3  * Copyright (C) 2004,2005 European Southern Observatory
4  *
5  * This program is free software; you can redistribute it and/or modify
6  * it under the terms of the GNU General Public License as published by
7  * the Free Software Foundation; either version 2 of the License, or
8  * (at your option) any later version.
9  *
10  * This program is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13  * GNU General Public License for more details.
14  *
15  * You should have received a copy of the GNU General Public License
16  * along with this program; if not, write to the Free Software
17  * Foundation, 51 Franklin St, Fifth Floor, Boston, MA 02111-1307 USA
18  */
19 
20 /*
21  * $Author: amodigli $
22  * $Date: 2013-04-16 15:35:24 $
23  * $Revision: 1.121 $
24  * $Name: not supported by cvs2svn $
25  * $Log: not supported by cvs2svn $
26  * Revision 1.120 2013/03/08 12:58:23 amodigli
27  * moved uves_min_int uves_min_double uves_error_fractionuves_max_int uves_max_int uves_max_double uves_round_double and similar small functions to header to speed-up
28  *
29  * Revision 1.119 2013/02/12 10:52:38 amodigli
30  * removed scaling by exptime as requested by Daniel PIPE-4020
31  *
32  * Revision 1.118 2011/12/08 13:54:40 amodigli
33  * include uves_cpl_size.h for CPL6
34  *
35  * Revision 1.117 2011/01/11 18:00:16 amodigli
36  * fixed compiler warnings (DFS09815)
37  *
38  * Revision 1.116 2010/12/20 16:35:57 amodigli
39  * added uves_table_remove_units(), uves_table_unify_units(), uves_tablenames_unify_units(), uves_tablename_remove_units(), useful in flames/uves to fix a problem on raw order fibre table generated by flames_cal_prep_sff_ofpos that has in an instance units filled by a string like ' ' and is being merged with a table with empty units. CPL5.3 makes a check on table column units consistency
40  *
41  * Revision 1.115 2010/12/16 16:57:40 amodigli
42  * fixed compiler warnings
43  *
44  * Revision 1.114 2010/12/01 11:32:22 amodigli
45  * add uves_image_mflat_detect_blemishes()
46  *
47  * Revision 1.113 2010/11/26 07:43:11 amodigli
48  * added uves_get_wave_map()
49  *
50  * Revision 1.112 2010/11/25 10:37:59 amodigli
51  * changed interface uves_flat_create_normalized_master()
52  *
53  * Revision 1.111 2010/10/06 07:52:13 amodigli
54  * changed interface uves_flat_create_normalized_master2()
55  *
56  * Revision 1.110 2010/09/29 09:40:05 amodigli
57  * fixed compiler warnings (changed function interface)
58  *
59  * Revision 1.109 2010/09/24 09:32:08 amodigli
60  * put back QFITS dependency to fix problem spot by NRI on FIBER mode (with MIDAS calibs) data
61  *
62  * Revision 1.107 2010/06/02 09:19:01 amodigli
63  * removed chip param from uves_imagelist_get_clean_mean_levels()
64  *
65  * Revision 1.106 2010/05/18 11:37:44 amodigli
66  * added uves_imagelist_get_clean_mean_levels
67  *
68  * Revision 1.105 2010/05/04 17:21:14 amodigli
69  * added uves_flat_create_normalized_master2
70  *
71  * Revision 1.104 2010/04/07 06:29:19 amodigli
72  * fixed compiler warnings
73  *
74  * Revision 1.103 2010/04/06 17:39:39 amodigli
75  * added uves_flat_create_normalized_master()
76  *
77  * Revision 1.102 2010/03/22 15:56:15 amodigli
78  * added uves_ksigma_stack
79  *
80  * Revision 1.101 2009/08/03 12:46:44 amodigli
81  * added uves_image_smooth_y
82  *
83  * Revision 1.100 2009/07/28 13:48:52 amodigli
84  * added smoothing functions
85  *
86  * Revision 1.99 2008/03/25 08:55:21 amodigli
87  * check if inline is defined to remove possible compilation warnings
88  *
89  * Revision 1.98 2008/02/29 10:26:08 amodigli
90  * added uves_rcosmic
91  *
92  * Revision 1.97 2008/02/15 12:43:21 amodigli
93  * added uves_string_tolower uves_string_toupper
94  *
95  * Revision 1.96 2008/02/04 14:08:58 amodigli
96  * added uves_parameterlist_duplicate
97  *
98  * Revision 1.95 2007/09/11 12:11:49 amodigli
99  * added uves_frameset_extract
100  *
101  * Revision 1.94 2007/08/02 15:18:44 amodigli
102  * added uves_frameset_dump
103  *
104  * Revision 1.93 2007/06/06 08:17:33 amodigli
105  * replace tab with 4 spaces
106  *
107  * Revision 1.92 2007/05/22 11:30:57 jmlarsen
108  * Removed MIDAS flag for good
109  *
110  * Revision 1.91 2007/05/02 13:18:52 jmlarsen
111  * Added function to simulate reconstruct raw image
112  *
113  * Revision 1.90 2007/04/24 12:50:29 jmlarsen
114  * Replaced cpl_propertylist -> uves_propertylist which is much faster
115  *
116  * Revision 1.89 2007/04/12 11:58:07 jmlarsen
117  * Check compile time CPL version number
118  *
119  * Revision 1.88 2007/04/10 07:10:50 jmlarsen
120  * uves_spline_hermite(): maintain current array position (for efficiency)
121  *
122  * Revision 1.87 2007/03/28 11:39:38 jmlarsen
123  * Removed MIDAS flag from uves_define_noise
124  *
125  * Revision 1.86 2007/03/13 15:34:07 jmlarsen
126  * Parametrize verbosity of autodegree fitting function
127  *
128  * Revision 1.85 2007/03/05 10:19:54 jmlarsen
129  * Define SPEED_OF_LIGHT
130  *
131  * Revision 1.84 2007/02/22 15:34:48 jmlarsen
132  * Implement gaussian function with linear background
133  *
134  * Revision 1.83 2006/11/13 12:49:38 jmlarsen
135  * Removed re-definition of cpl_table_erase_selected
136  *
137  * Revision 1.82 2006/11/07 14:05:35 jmlarsen
138  * Removed flag to enable/disable FLAMES code generation
139  *
140  * Revision 1.81 2006/11/06 15:19:42 jmlarsen
141  * Removed unused include directives
142  *
143  * Revision 1.80 2006/11/03 15:01:21 jmlarsen
144  * Killed UVES 3d table module and use CPL 3d tables
145  *
146  * Revision 1.79 2006/10/19 08:23:09 jmlarsen
147  * Enabled FLAMES code
148  *
149  * Revision 1.78 2006/10/12 11:37:28 jmlarsen
150  * Temporarily disabled FLAMES code generation
151  *
152  * Revision 1.77 2006/10/09 13:04:22 jmlarsen
153  * Removed message domain parameter of uves_initialize
154  *
155  * Revision 1.76 2006/09/20 12:53:57 jmlarsen
156  * Replaced stringcat functions with uves_sprintf()
157  *
158  * Revision 1.75 2006/09/08 14:05:39 jmlarsen
159  * Added max/min allowed values in autodegree fitting
160  *
161  * Revision 1.74 2006/08/24 11:43:49 jmlarsen
162  * Write recipe start/stop time to header
163  *
164  * Revision 1.73 2006/08/17 13:56:53 jmlarsen
165  * Reduced max line length
166  *
167  * Revision 1.72 2006/08/11 14:37:30 jmlarsen
168  * Implemented workaround for slow cpl_table_erase_selected
169  *
170  * Revision 1.71 2006/08/11 11:29:11 jmlarsen
171  * uves_get_version_binary
172  *
173  * Revision 1.70 2006/08/08 11:27:18 amodigli
174  * upgrade to CPL3
175  *
176  * Revision 1.69 2006/07/14 12:42:42 jmlarsen
177  * Added function uves_strincat_4
178  *
179  * Revision 1.68 2006/06/22 09:44:02 jmlarsen
180  * Added function to remove string prefix
181  *
182  * Revision 1.67 2006/06/01 14:43:17 jmlarsen
183  * Added missing documentation
184  *
185  * Revision 1.66 2006/05/12 15:12:11 jmlarsen
186  * Support minimum RMS in auto-degree fitting
187  *
188  * Revision 1.65 2006/05/05 13:58:09 jmlarsen
189  * Added uves_polynomial_regression_2d_autodegree
190  *
191  * Revision 1.64 2006/04/24 09:26:37 jmlarsen
192  * Added code to compute Moffat profile
193  *
194  * Revision 1.63 2006/04/06 08:51:43 jmlarsen
195  * Allow setting WANT_TIME_MEASURE when ./configure'ing
196  *
197  * Revision 1.62 2006/03/24 13:48:09 jmlarsen
198  * Macro to turn on/off timing info
199  *
200  * Revision 1.61 2006/03/09 10:55:50 jmlarsen
201  * Added timing macros
202  *
203  * Revision 1.60 2006/02/28 09:15:23 jmlarsen
204  * Minor update
205  *
206  * Revision 1.59 2006/02/21 14:26:54 jmlarsen
207  * Minor changes
208  *
209  * Revision 1.58 2006/02/15 13:19:15 jmlarsen
210  * Reduced source code max. line length
211  *
212  * Revision 1.57 2006/01/12 15:41:14 jmlarsen
213  * Moved gauss. fitting to irplib
214  *
215  * Revision 1.56 2005/12/20 08:11:44 jmlarsen
216  * Added CVS entry
217  *
218  */
219 #ifndef UVES_UTILS_H
220 #define UVES_UTILS_H
221 
222 
223 #ifdef HAVE_CONFIG_H
224 # include <config.h>
225 #endif
226 #include <uves_cpl_size.h>
227 /*-----------------------------------------------------------------------------
228  Includes
229  -----------------------------------------------------------------------------*/
230 
231 #include <uves_utils_polynomial.h>
232 #include <uves_extract_iterate.h>
233 #include <uves_extract_profile.h>
234 #include <uves_chip.h>
235 
236 #include <cpl.h>
237 #include <math.h>
238 
239 /*-----------------------------------------------------------------------------
240  Defines
241  -----------------------------------------------------------------------------*/
242 
243 /* If __func__ is not declared, use a default function name */
244 #if defined HAVE_DECL___FUNC__ && !HAVE_DECL___FUNC__
245 //static const char __func__[] = "<fctid>";
246 #ifndef __func__
247 #define __func__ "<fct.id>"
248 #endif
249 #endif
250 
251 #ifndef inline
252 #define inline /* inline */
253 #endif
254 
255 /*
256  * The purpose of this target is to
257  * decrease the amount of messages
258  * printed at the debug level.
259  *
260  * If set to non-zero, even more messages
261  * are printed at the debug level
262  * (sometimes 50 - 100 MB)
263  *
264  */
265 #ifndef WANT_BIG_LOGFILE
266 #define WANT_BIG_LOGFILE 0
267 #endif
268 
269 /*
270  * Set to 1 to show timing
271  * information on msg-level = info
272  */
273 #ifndef WANT_TIME_MEASURE
274 #define WANT_TIME_MEASURE 0
275 #endif
276 
277 
278 #if WANT_TIME_MEASURE
279 #define UVES_TIME_START(what) uves_msg("Timing (%s, l%d) %s start", \
280  __FILE__, __LINE__, what)
281 #define UVES_TIME_END uves_msg("Timing (%s, l%d) end", \
282  __FILE__, __LINE__)
283 #else
284 #define UVES_TIME_START(what) uves_msg_debug("Timing (%s, l%d) %s start", \
285  __FILE__, __LINE__, what)
286 #define UVES_TIME_END uves_msg_debug("Timing (%s, l%d) end", \
287  __FILE__, __LINE__)
288 #endif
289 
290 
291 #ifndef stringify
292 #ifndef make_str
293 #define stringify(X) #X
294 #define make_str(X) stringify(X)
295 #endif
296 #endif
297 
298 #define TWOSQRT2LN2 2.35482004503095
299 
300 #ifndef M_PI
301 #define M_PI 3.1415926535897932384626433832795
302 #endif
303 
304 #define SPEED_OF_LIGHT 299792458 /* SI-units */
305 
306 #define COS_DEG(x) cos(((x)/180)*M_PI)
307 #define SIN_DEG(x) sin(((x)/180)*M_PI)
308 #define ACOS_DEG(x) (acos(x)*180/M_PI)
309 
310 /*-----------------------------------------------------------------------------
311  Prototypes
312  -----------------------------------------------------------------------------*/
313 
314 cpl_image *
315 uves_create_image(uves_iterate_position *pos, enum uves_chip chip,
316  const cpl_image *spectrum, const cpl_image *sky,
317  const cpl_image *cosmic_image,
318  const uves_extract_profile *profile,
319  cpl_image **image_noise, uves_propertylist **image_header);
320 cpl_frameset *
321 uves_frameset_extract(const cpl_frameset *frames,const char *tag);
322 
323 const char*
324 uves_string_tolower(char* s);
325 const char*
326 uves_string_toupper(char* s);
327 
328 double uves_gaussrand(void);
329 double uves_pow_int(double x, int y);
330 
331 /*----------------------------------------------------------------------------*/
340 /*----------------------------------------------------------------------------*/
341 static inline long
342 uves_round_double(double x)
343 {
344  return (x >=0) ? (long)(x+0.5) : (long)(x-0.5);
345 }
346 
347 /*----------------------------------------------------------------------------*/
356 /*----------------------------------------------------------------------------*/
357 static inline double
358 uves_max_double(double x, double y)
359 {
360  return (x >=y) ? x : y;
361 }
362 /*----------------------------------------------------------------------------*/
371 /*----------------------------------------------------------------------------*/
372 static inline int
373 uves_max_int(int x, int y)
374 {
375  return (x >=y) ? x : y;
376 }
377 
378 /*----------------------------------------------------------------------------*/
387 /*----------------------------------------------------------------------------*/
388 static inline double
389 uves_min_double(double x, double y)
390 {
391  return (x <=y) ? x : y;
392 }
393 /*----------------------------------------------------------------------------*/
402 /*----------------------------------------------------------------------------*/
403 static inline int
404 uves_min_int(int x, int y)
405 {
406  return (x <=y) ? x : y;
407 }
408 
409 /*----------------------------------------------------------------------------*/
420 /*----------------------------------------------------------------------------*/
421 static inline double
422 uves_error_fraction(double x, double y, double dx, double dy)
423 {
424  /* Error propagation:
425  * sigma(x/y)^2 = (1/y sigma(x))^2 + (-x/y^2 sigma(y))^2
426  */
427  return sqrt( dx*dx/(y*y) + x*x*dy*dy/(y*y*y*y) );
428 }
429 
430 
431 const char *uves_get_license(void);
432 cpl_error_code uves_get_version(int *major, int *minor, int *micro);
433 int uves_get_version_binary(void);
434 
435 char * uves_initialize(cpl_frameset *frames, const cpl_parameterlist *parlist,
436  const char *recipe_id, const char *short_descr);
437 cpl_error_code uves_end(const char *recipe_id, const cpl_frameset *frames);
438 
439 uves_propertylist *uves_initialize_image_header(const char *ctype1, const char *ctype2, const char *cunit1, const char *cunit2,
440  const char *bunit,const double bscale,
441  double crval1 , double crval2,
442  double crpix1 , double crpix2,
443  double crdelt1, double crdelt2);
444 
445 cpl_parameterlist*
446 uves_parameterlist_duplicate(const cpl_parameterlist* pin);
447 
448 cpl_image *uves_define_noise(const cpl_image *image, const uves_propertylist *image_header,
449  int ncom, enum uves_chip);
450 cpl_image *uves_average_images(const cpl_image *image1, const cpl_image *noise1,
451  const cpl_image *image2, const cpl_image *noise2,
452  cpl_image **noise);
453 
454 
455 cpl_error_code uves_subtract_bias(cpl_image *image, const cpl_image *master_bias);
456 cpl_error_code uves_subtract_dark(cpl_image *image, const uves_propertylist *image_header,
457  const cpl_image *master_dark,
458  const uves_propertylist *mdark_header);
459 
460 polynomial *
462  const char *X1, const char *X2, const char *Y,
463  const char *sigmaY,
464  const char *polynomial_fit,
465  const char *residual_square,
466  const char *variance_fit,
467  double *mean_squared_error, double *red_chisq,
468  polynomial **variance, double kappa,
469  int maxdeg1, int maxdeg2, double min_rms,
470  double min_reject,
471  bool verbose,
472  const double *min_val,
473  const double *max_val,
474  int npos, double positions[][2]);
475 
476 polynomial *
477 uves_polynomial_regression_2d(cpl_table *t,
478  const char *X1, const char *X2, const char *Y,
479  const char *sigmaY,
480  int degree1, int degree2,
481  const char *polynomial_fit, const char *residual_square,
482  const char *variance_fit,
483  double *mse, double *red_chisq,
484  polynomial **variance, double kappa,
485  double min_reject);
486 
488  const char *X, const char *Y, const char *sigmaY,
489  int degree,
490  const char *polynomial_fit, const char *residual_square,
491  double *mean_squared_error, const double kappa);
492 
493 const char *uves_remove_string_prefix(const char *s, const char *prefix);
494 
495 double uves_spline_hermite_table( double xp, const cpl_table *t, const char *column_x,
496  const char *column_y, int *istart );
497 
498 double uves_spline_hermite( double xp, const double *x, const double *y, int n, int *istart );
499 
500 double uves_spline_cubic(double xp, double *x, float *y, float *y2, int n, int *kstart );
501 
502 int uves_absolute_order(int first_abs_order, int last_abs_order, int relative_order);
503 
504 double uves_average_reject(cpl_table *t,
505  const char *column,
506  const char *residual2,
507  double kappa);
508 
509 
510 cpl_table *uves_ordertable_traces_new(void);
511 cpl_error_code uves_ordertable_traces_add(cpl_table *traces,
512  int fibre_ID, double fibre_offset, int fibre_mask);
513 bool uves_table_is_sorted_double(const cpl_table *t, const char *column, const bool reverse);
514 
515 int uves_moffat(const double x[], const double a[], double *result);
516 int uves_moffat_derivative(const double x[], const double a[], double result[]);
517 int uves_gauss(const double x[], const double a[], double *result);
518 int uves_gauss_derivative(const double x[], const double a[], double result[]);
519 int uves_gauss_linear(const double x[], const double a[], double *result);
520 int uves_gauss_linear_derivative(const double x[], const double a[], double result[]);
521 void uves_check_version(void);
522 void uves_frameset_dump(cpl_frameset* set);
523 cpl_error_code
524 uves_rcosmic(cpl_image* ima,
525  cpl_image** flt,
526  cpl_image** out,
527  cpl_image** msk,
528  const double sky,
529  const double ron,
530  const double gain,
531  const int ns,
532  const double rc);
533 
534 cpl_image *
535 uves_image_smooth_x(cpl_image * inp, const int r);
536 cpl_image *
537 uves_image_smooth_y(cpl_image * inp, const int r);
538 
539 cpl_image *
540 uves_image_smooth_mean_x(cpl_image * inp, const int r);
541 
542 cpl_image *
543 uves_image_smooth_median_x(cpl_image * inp, const int r);
544 cpl_image *
545 uves_image_smooth_fft(cpl_image * inp, const int fx);
546 
547 cpl_image *
548 uves_ksigma_stack(const cpl_imagelist *imlist, double klow, double khigh, int kiter);
549 
550 
551 cpl_image *
552 uves_flat_create_normalized_master(cpl_imagelist * flats,
553  const cpl_table *ordertable,
554  const polynomial* order_locations,
555  const cpl_vector* gain_vals,
556  double* fnoise);
557 
558 cpl_image *
559 uves_flat_create_normalized_master2(cpl_imagelist * flats,
560  const cpl_table *ordertable,
561  const polynomial* order_locations,
562  const cpl_image* mflat);
563 
564 cpl_vector *
565 uves_imagelist_get_clean_mean_levels(cpl_imagelist* iml, double kappa);
566 cpl_error_code
567 uves_imagelist_subtract_values(cpl_imagelist** iml, cpl_vector* values);
568 cpl_image *
569 uves_get_wave_map(cpl_image * ima_sci,
570  const char *context,
571  const cpl_parameterlist *parameters,
572  const cpl_table *ordertable,
573  const cpl_table *linetable,
574  const polynomial* order_locations,
575  const polynomial *dispersion_relation,
576  const int first_abs_order,
577  const int last_abs_order,
578  const int slit_size);
579 
580 cpl_image*
581 uves_image_mflat_detect_blemishes(const cpl_image* flat,
582  const uves_propertylist* head);
583 
584 
585 cpl_error_code
586 uves_table_remove_units(cpl_table **table);
587 cpl_error_code
588 uves_table_unify_units(cpl_table **table2, cpl_table **table1);
589 cpl_error_code
590 uves_tablenames_unify_units(const char* tname2, const char* tname1);
591 cpl_error_code
592 uves_tablename_remove_units(const char* tname);
593 
594 #endif