psTime.h

Go to the documentation of this file.

/** @file  psTime.h
 *
 *  @brief Definitions for time, time utilities, and conversion functions for use
 *  with psLib astronomy functions.
 *
 *  A collection of functions are required by psLib to manipulate time data. These
 *  functions primarily consist of conversions between specific time formats.  They
 *  use the UNIX timeval time system as the base upon which International Atomic
 *  Time (TAI) and Universal Time Coordinated (UTC) are calculated.
 *
 *  @author Ross Harman, MHPCC
 *
 *  @version $Revision: 1.1.1.1 $ $Name:  $
 *  @date $Date: 2005/06/15 21:08:12 $
 *
 *  Copyright 2004-2005 Maui High Performance Computing Center, University of Hawaii
 */

#ifndef PSTIME_H
#define PSTIME_H

#include <time.h>
#include <sys/types.h>
#include <sys/time.h>

#include "psType.h"
#include "psImage.h"

struct psSphere;

/// @addtogroup Time
/// @{


/** Time type.
 *
 * Enumeration for psTime types, TAI or UTC time.
 */
typedef enum {
    PS_TIME_TAI,        ///< Temps Atomique International (TAI) time (time with leapseconds).
    PS_TIME_UTC,        ///< Universal Time Coordinated (UTC) time (time without leapseconds).
    PS_TIME_UT1,        ///< Universal Time corrected for polar motion
    PS_TIME_TT,         ///< Terrestrial Time
} psTimeType;

/** Time Bulletin type
 *
 * Enumeration for psTimeBulletin type, A or B.
 */
typedef enum {
    PS_IERS_A,          ///< IERS Bulletin A
    PS_IERS_B,          ///< IERS Bulletin B
} psTimeBulletin;

/** Definition of psTime.
 *
 *  The psTime struct is used by psLib to represent time values critical to
 *  astronomical calculations.  This structure represents a time which is
 *  equivalent to TAI (International Atomic Time) and is measured in both
 *  seconds and microseconds.
 */
typedef struct psTime
{
    psS64 sec;          ///< Seconds since epoch, Jan 1, 1970.
    psU32 nsec;         ///< Nanoseconds since last second.
    psBool leapsecond;  ///< if time falls on UTC leapsecond
    psTimeType type;    ///< Type of time.
}
psTime;


/** Initialize time data.
 *
 * Reads config and data files associated with various time conversions.
 *
 * @return  bool: True for success, false for failure.
 */
psBool p_psTimeInit(const char *fileName);

/** Free memory persistant time data.
 *
 * Frees time data to be held in memory until the end of successful program execution.
 *
 * @return  void: void.
 */
psBool p_psTimeFinalize(void);

/** Allocate time struct.
 *
 * Allocates an empty time struct. User must specify the psTimeType
 * (PS_TIME_TAI or PS_TIME_UTC) in the argument. The seconds and microseconds members
 * of the struct are set to zero.
 *
 * @return  psTime*: Struct with empty time.
 */
psTime* psTimeAlloc(
    psTimeType type                     ///< Type of time to create (UTC or TAI).
);

/** Get current time.
 *
 * Gets current time from the system clock. User must specify the psTimeType
 * (PS_TIME_TAI or PS_TIME_UTC) in the argument.
 *
 *  @return  psTime*: Struct with current time.
 */
psTime* psTimeGetNow(
    psTimeType type                     ///< Type of time to get (UTC or TAI).
);

/** Convert psTime to UTC or TAI time.
 *
 *  Converts psTime to UTC or TAI time based on the psTimeType argument.
 *
 *  @return  psTime*: Pointer to psTime.
 */
psTime* psTimeConvert(
    psTime *time,                       ///< Time to be converted.
    psTimeType type                     ///< Type to be converted to.
);

/** Convert psTime to Local Mean Sidereal Time (LMST).
 *
 *  Converts psTime at the given longitude to LMST time. If the input time is not
 *  in UTC format, then it is converted.
 *
 *  @return  psF64: LST Time.
 */
psF64 psTimeToLMST(
    psTime *time,                       ///< psTime to be converted.
    psF64 longitude                    ///< Longitude.
);

/** Determine UT1 - UTC from table lookup.
 *
 *  This function is necessary to for various SLALIB functions.
 *
 *  @return  psF64: Time difference.
 */
psF64 psTimeGetUT1Delta(
    const psTime *time,                 ///< psTime to be looked up.
    psTimeBulletin bulletin             ///< IERS bulletin to use
);

/** Determine TAI - UTC from table lookup.
 *
 *  This function is necessary to for various psTime functions.
 *
 *  @return  psF64: Time difference.
 */
psF64 p_psTimeGetTAIDelta(
    const psTime *time                  ///< psTime to be looked up.
);

/** Determine polar coordinates at a given time.
 *
 *  Determines the orientation of the polar axis at the given time.
 *
 *  @return  psSphere*: Spherical coordinates of Earth's polar axias.
 */
struct psSphere* p_psTimeGetPoleCoords(
                const psTime *time      ///< psTime determine polar orientation.
            );

/** Calculate the number of leapseconds between two times.
 *
 *  Calculates the number of leapseconds between two times.
 *
 *  @return  psS64: leapseconds added between given times
 */
psS64 psTimeLeapSecondDelta(
    const psTime* time1,                ///< First input time.
    const psTime* time2                 ///< Second input time.
);

/** Determine if UTC time is a leapsecond.
 *
 *  Determines if the specified UTC time is a valid leapsecond.
 *
 *  @return  psBool: valid leap second
 */
psBool psTimeIsLeapSecond(
    const psTime* utc                  ///< UTC to verify if leap second
);

/** Convert psTime to Julian date time.
 *
 *  Converts psTime to Julian date (JD) time. This function does not add or
 *  subtract leapseconds.
 *
 *  @return  psF64: Julian Date (JD) time.
 */
psF64 psTimeToJD(
    const psTime* time                  ///< Input time to be converted.
);
/** Convert psTime to modified Julian date time.
 *
 *  Converts psTime to modified Julian date (MJD) time. This function does not
 *  add or subtract leapseconds.
 *
 *  @return  psF64: Modified Julian Days (MJD) time.
 */
psF64 psTimeToMJD(
    const psTime* time                  ///< Input time to be converted.
);

/** Convert psTime to ISO8601 formatted string.
 *
 *  Converts psTime to a null terminated string in the form of YYYY-MM-DDThh:mm:ss.sss.
 *  This function does not add or subtract leapseconds.
 *
 *  @return  char*: Pointer null terminated array of chars in ISO time.
 */
char* psTimeToISO(
    const psTime* time                  ///< Input time to be converted.
);

/** Convert psTime to timeval time.
 *
 *  Converts psTime to timeval time. This function does not add or subtract leapseconds.
 *
 *  @return  timeval*: timeval struct time.
 */
struct timeval* psTimeToTimeval(
                const psTime* time     ///< Input time to be converted.
            );

/*
 * Convert psTime to tm time.
 *
 * Converts psTime to tm time. This function is based on a Perl algorithm availble
 * in the Pan-STARRS Image processing Algorithm Design Description (ADD). This function
 * does not add or subtract leapseconds.
 *
 *  @return  tm: tm struct time.
 *
struct tm* p_psTimeToTM(
                const psTime *time     ///< Input time to be converted.
            );
*/
/** Convert JD to psTime.
 *
 *  Converts JD time to psTime. This function does not add or subtract leapseconds.
 *
 *  @return  psTime: time.
 */
psTime* psTimeFromJD(
    psF64 time                       ///< Input time to be converted.
);

/** Convert MJD to psTime.
 *
 *  Converts MJD time to psTime. This function does not add or subtract leapseconds.
 *
 *  @return  psTime: time.
 */
psTime* psTimeFromMJD(
    psF64 time                      ///< Input time to be converted.
);

/** Convert ISO to psTime.
 *
 *  Converts ISO time to psTime. This function does not add or subtract leapseconds.
 *
 *  @return  psTime*: time
 */
psTime* psTimeFromISO(
    const char* time                 ///< Input time to be converted.
);

/** Convert timeval to psTime.
 *
 *  Converts timeval time to psTime. This function does not add or subtract leapseconds.
 *
 *  @return  psTime*: time.
 */
psTime* psTimeFromTimeval(
    const struct timeval *time       ///< Input time to be converted.
);

/** Convert Terrestrial Time to psTime
 *
 *  Converts Terrestial Time to psTime.  This function assumes resultant time is of type TT.
 *
 *  @return psTime*: time (TT)
 */
psTime* psTimeFromTT(
    psS64 sec,                      ///< Input terrestrial time in seconds
    psU32 nsec                      ///< Input terrestrial time fraction of seconds (nanoseconds)
);

/** Convert UTC time to psTime
 *
 *  Converts UTC time to psTime.  It will verify if time specified is a leapsecond.
 *
 *  @return psTime*: time (UTC)
 */
psTime* psTimeFromUTC(
    psS64  sec,                    ///< Input time in seconds
    psU32  nsec,                   ///< Input time fraction of seconds (nanoseconds)
    psBool leapsecond              ///< Input time is a leapsecond
);

/** Convert tm time to psTime.
 *
 *  Converts tm time to psTime. This function is based on a Perl algorithm availble
 *  in the Pan-STARRS Image processing Algorithm Design Description (ADD). This function
 *  does not add or subtract leapseconds.
 *
 *  @return  psTime*: time.
 */
psTime* p_psTimeFromTM(
    const struct tm *time            ///< Input time to be converted.
);

/** Adds delta to time. Result is in TAI time.
 *
 *  Adds delta to time. Input time is converted to TAI format if necessary.
 *
 *  @return  psTime*: time.
 */
psTime* psTimeMath(
    const psTime *time,              ///< Time.
    psF64 delta                      ///< Time delta.
);

/** Determine difference between two times. Result is in TAI time.
 *
 *  Determine difference between two times. Input times are converted to TAI format if necessary.
 *
 *  @return psF64: Time difference.
 */
psF64 psTimeDelta(
    const psTime *time1,             ///< First time.
    const psTime *time2              ///< Second time.
);

/** Get the filename of the psLib configuration file.
 *
 *  @return char*          If a PS_CONFIG_FILE environment variable exists,
 *                         that is returned, otherwise the default location
 *                         dependent on the installation location.
 */
char* p_psGetConfigFileName();

/// @}

#endif // #ifndef PSTIME_H

---