giastroutils.c

/*
 * This file is part of the GIRAFFE Pipeline
 * Copyright (C) 2002-2019 European Southern Observatory
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 */
 
#ifdef HAVE_CONFIG_H
#  include <config.h>
#endif
 
#include <math.h>
 
#include <cxtypes.h>
 
#include <cpl_msg.h>
 
#include <giastroutils.h>
 
 
 
static const cxdouble TINY = 1.e-12;
 
static const cxdouble DEG_TO_RAD =
        0.017453292519943295769236907684886127134428718885417; /* pi/180  */
 
static const cxdouble SEC_TO_DEG = 15. / 3600.;
 
 
 
/*
 * @brief
 *  Compute the zenith distance of a point in the sky
 *
 * @param hourangle  Hour angle in radians
 * @param delta      Declination in radians
 * @param latitude   Latitude of the observatory in radians
 *
 * @return
 *  The secant of the zenith distance, or @c 0. if na error occurred.
 *
 * The function computes the secans of the zenith distance of a point
 * in the sky, given by the angle @em hourangle from the meridian and the
 * declination @em delta. The latitude of the observing site is given by
 * @em latitude.
 *
 * The domain of the hour angle, declination and the latitude of the
 * observing site are [$-\pi$, \pi$], [$-0.5\pi, 0.5\pi$] and [$0, 2\pi$]
 * respectively.
 */
 
inline static cxdouble
_giraffe_compute_zdistance(cxdouble hourangle, cxdouble delta,
                           cxdouble latitude)
{
 
    cxdouble p0 = sin(latitude) * sin(delta);
    cxdouble p1 = cos(latitude) * cos(delta);
    cxdouble z  = p0 + cos(hourangle) * p1;
 
    if (fabs(z) < TINY) {
        z = z < 0. ? -TINY : TINY;
    }
 
    return 1. / z;
 
}
 
/*
 * @brief
 *  Compute approximated airmass value.
 *
 * @param secz  Secant of the zenith distance.
 *
 * @return
 *  The function returns the approximated airmass value.
 *
 * The function uses the approximation given by Young (Young A. T.,
 * 1994, "Air mass and refraction", Applied Optics, 33, 1108-1110) to
 * compute the airmass for a given sec(z) @em secz, where z is the true
 * zenith angle.
 */
 
inline static cxdouble
_giraffe_compute_airmass_young(cxdouble secz)
{
 
    cxdouble z = 1. / secz;    /* cos(zt) cosine of the true zenith angle */
    cxdouble x = 0.;
    cxdouble y = 0.;
 
    x = 1.002432 * z * z + 0.148386 * z + 0.0096467;
    y = z * z * z + 0.149864 * z * z + 0.0102963 * z + 0.000303978;
 
    return x / y;
 
}
 
 
cxdouble
giraffe_compute_airmass(cxdouble alpha, cxdouble delta, cxdouble lst,
                        cxdouble exptime, cxdouble latitude)
{
 
    const cxchar* const fctid = "giraffe_compute_airmass";
 
 
    /* Weights for Stetson's formula */
 
    const cxdouble weights[] = {1. / 6., 2. / 3., 1. / 6.};
 
 
   /*
    * Accuracy limit for airmass approximation (cf. Young A. T., Irvine W. M.,
    * 1967, Astron. J. 72, 945).
    */
 
    const cxdouble airmass_upper_limit = 10.;
 
 
    cxdouble z = 0.;
    cxdouble hourangle = 0.;
    cxdouble airmass = 0.;
 
 
   /*
    * Compute hour angle of the observation in degrees.
    */
 
    hourangle = lst * SEC_TO_DEG - alpha;
 
 
   /*
    * Range adjustments. Angle between line of sight and the meridian
    * is needed.
    */
 
    if (hourangle < -180.) {
        hourangle += 360.;
    }
 
    if (hourangle > 180.) {
        hourangle -= 360.;
    }
 
 
   /*
    * Convert angles from degrees to radians
    */
 
    delta *= DEG_TO_RAD;
    latitude *= DEG_TO_RAD;
    hourangle *= DEG_TO_RAD;
 
 
   /*
    * Calculate airmass of the observation using the approximation given
    * by Young (Young A. T., 1994, "Air mass and refraction", Applied
    * Optics, 33, 1108-1110)for the individual airmass values. For finite
    * exposure times these airmass values are averaged using the weights
    * given by Stetson (Stetson P., 1987, PASP 99, 191)
    */
 
    z = _giraffe_compute_zdistance(hourangle, delta, latitude);
 
    if (fabs(z) < TINY) {
        cpl_msg_debug(fctid, "Airmass computation failed. Object is "
                      "below the horizon.");
        return -1.;
    }
 
    airmass = _giraffe_compute_airmass_young(z);
 
    if (exptime > 0.) {
 
        const cxint nweights = CX_N_ELEMENTS(weights);
 
        cxint i = 0;
 
        cxdouble timestep = exptime / (nweights - 1) * SEC_TO_DEG *
                DEG_TO_RAD;
 
 
        airmass *= weights[0];
 
        for (i = 1; i < nweights; i++) {
 
            z = _giraffe_compute_zdistance(hourangle + i * timestep,
                                           delta, latitude);
 
            if (fabs(z) < TINY) {
 
                cpl_msg_debug(fctid, "Airmass computation failed. Object "
                              "is below the horizon.");
                return -1.;
 
            }
 
            airmass += weights[i] * _giraffe_compute_airmass_young(z);
 
        }
 
    }
 
 
    if (airmass > airmass_upper_limit) {
        cpl_msg_debug(fctid, "Airmass larger than %f", airmass_upper_limit);
    }
 
    return airmass;
 
}