 /*============================================================================
*
*    NAME:  solpos00.h
*
*    Contains:
*        S_solpos     (computes the solar position and intensity
*                      from time and place)
*            INPUTS:     (from posdata)
*                          year, month, day, hour, minute, second,
*                          latitude, longitude, timezone, interval
*            OPTIONAL:   (from posdata; defaults from S_init function)
*                            press   DEFAULT 1013.0 (standard pressure)
*                            temp    DEFAULT   10.0 (standard temperature)
*                            tilt    DEFAULT    0.0 (horizontal panel)
*                            aspect  DEFAULT  180.0 (South-facing panel)
*                            sbwid   DEFAULT    7.6 (shadowband width)
*                            sbrad   DEFAULT   31.7 (shadowband radius)
*                            sbsky   DEFAULT   0.04 (shadowband sky factor)
*
*            OUTPUTS:    (posdata) daynum, amass, ampress, azim, cosinc,
*                        elevref, etr, etrn, etrtilt, prime,
*                        sbcf, sretr, ssetr, unprime, zenref
*
*            RETURNS:   Long int status code (defined in solpos.h)
*
*    Usage:
*         In calling program, along with other 'includes', insert:
*
*              #include "solpos.h"
*
*    Martin Rymes
*    National Renewable Energy Laboratory
*    25 March 1998
*----------------------------------------------------------------------------*/

/*============================================================================
*
*     Define the function codes
*
*----------------------------------------------------------------------------*/
#define L_DOY    0x0001
#define L_GEOM   0x0002
#define L_ZENETR 0x0004
#define L_SSHA   0x0008
#define L_SBCF   0x0010
#define L_TST    0x0020
#define L_SRSS   0x0040
#define L_SOLAZM 0x0080
#define L_REFRAC 0x0100
#define L_AMASS  0x0200
#define L_PRIME  0x0400
#define L_TILT   0x0800
#define L_ETR    0x1000
#define L_ALL    0xFFFF

/*============================================================================
*
*     Define the bit-wise masks for each function
*
*----------------------------------------------------------------------------*/
#define S_DOY    ( L_DOY                          )
#define S_GEOM   ( L_GEOM   | S_DOY               )
#define S_ZENETR ( L_ZENETR | S_GEOM              )
#define S_SSHA   ( L_SSHA   | S_GEOM              )
#define S_SBCF   ( L_SBCF   | S_SSHA              )
#define S_TST    ( L_TST    | S_GEOM              )
#define S_SRSS   ( L_SRSS   | S_SSHA   | S_TST    )
#define S_SOLAZM ( L_SOLAZM | S_ZENETR            )
#define S_REFRAC ( L_REFRAC | S_ZENETR            )
#define S_AMASS  ( L_AMASS  | S_REFRAC            )
#define S_PRIME  ( L_PRIME  | S_AMASS             )
#define S_TILT   ( L_TILT   | S_SOLAZM | S_REFRAC )
#define S_ETR    ( L_ETR    | S_REFRAC            )
#define S_ALL    ( L_ALL                          )


/*============================================================================
*
*     Enumerate the error codes
*     (Bit positions are from least significant to most significant)
*
*----------------------------------------------------------------------------*/
/*          Code          Bit       Parameter            Range
      ===============     ===  ===================  =============   */
enum {S_YEAR_ERROR,    /*  0   year                  1950 -  2050   */
      S_MONTH_ERROR,   /*  1   month                    1 -    12   */
      S_DAY_ERROR,     /*  2   day-of-month             1 -    31   */
      S_DOY_ERROR,     /*  3   day-of-year              1 -   366   */
      S_HOUR_ERROR,    /*  4   hour                     0 -    24   */
      S_MINUTE_ERROR,  /*  5   minute                   0 -    59   */
      S_SECOND_ERROR,  /*  6   second                   0 -    59   */
      S_TZONE_ERROR,   /*  7   time zone              -12 -    12   */
      S_INTRVL_ERROR,  /*  8   interval (seconds)       0 - 28800   */
      S_LAT_ERROR,     /*  9   latitude               -90 -    90   */
      S_LON_ERROR,     /* 10   longitude             -180 -   180   */
      S_TEMP_ERROR,    /* 11   temperature (deg. C)  -100 -   100   */
      S_PRESS_ERROR,   /* 12   pressure (millibars)     0 -  2000   */
      S_TILT_ERROR,    /* 13   tilt                   -90 -    90   */
      S_ASPECT_ERROR,  /* 14   aspect                -360 -   360   */
      S_SBWID_ERROR,   /* 15   shadow band width (cm)   1 -   100   */
      S_SBRAD_ERROR,   /* 16   shadow band radius (cm)  1 -   100   */
      S_SBSKY_ERROR};  /* 17   shadow band sky factor  -1 -     1   */

struct posdata
{
  /***** ALPHABETICAL LIST OF COMMON VARIABLES *****/
                           /* Each comment begins with a 1-column letter code:
                              I:  INPUT variable
                              O:  OUTPUT variable
                              T:  TRANSITIONAL variable used in the algorithm,
                                  of interest only to the solar radiation
                                  modelers, and available to you because you
                                  may be one of them.

                              The FUNCTION column indicates which sub-function
                              within solpos must be switched on using the
                              "function" parameter to calculate the desired
                              output variable.  All function codes are
                              defined in the solpos.h file.  The default
                              S_ALL switch calculates all output variables.
                              Multiple functions may be or'd to create a
                              composite function switch.  For example,
                              (S_TST | S_SBCF). Specifying only the functions
                              for required output variables may allow solpos
                              to execute more quickly.

                              The S_DOY mask works as a toggle between the
                              input date represented as a day number (daynum)
                              or as month and day.  To set the switch (to
                              use daynum input), the function is or'd; to
                              clear the switch (to use month and day input),
                              the function is inverted and and'd.

                              For example:
                                  pdat->function |= S_DOY (sets daynum input)
                                  pdat->function &= ~S_DOY (sets month and day input)

                              Whichever date form is used, S_solpos will
                              calculate and return the variables(s) of the
                              other form.  See the soltest.c program for
                              other examples. */

  /* VARIABLE        I/O  Function    Description */
  /* -------------  ----  ----------  ---------------------------------------*/

  int   day;       /* I/O: S_DOY      Day of month (May 27 = 27, etc.)
                                        solpos will CALCULATE this by default,
                                        or will optionally require it as input
                                        depending on the setting of the S_DOY
                                        function switch. */
  int   daynum;    /* I/O: S_DOY      Day number (day of year; Feb 1 = 32 )
                                        solpos REQUIRES this by default, but
                                        will optionally calculate it from
                                        month and day depending on the setting
                                        of the S_DOY function switch. */
  int   function;  /* I:              Switch to choose functions for desired
                                        output. */
  int   hour;      /* I:              Hour of day, 0 - 23, DEFAULT = 12 */
  int   interval;  /* I:              Interval of a measurement period in
                                        seconds.  Forces solpos to use the
                                        time and date from the interval
                                        midpoint. The INPUT time (hour,
                                        minute, and second) is assumed to
                                        be the END of the measurement
                                        interval. */
  int   minute;    /* I:              Minute of hour, 0 - 59, DEFAULT = 0 */
  int   month;     /* I/O: S_DOY      Month number (Jan = 1, Feb = 2, etc.)
                                        solpos will CALCULATE this by default,
                                        or will optionally require it as input
                                        depending on the setting of the S_DOY
                                        function switch. */
  int   second;    /* I:              Second of minute, 0 - 59, DEFAULT = 0 */
  int   year;      /* I:              4-digit year (2-digit year is NOT
                                       allowed */

  /***** FLOATS *****/

  float amass;      /* O:  S_AMASS    Relative optical airmass */
  float ampress;    /* O:  S_AMASS    Pressure-corrected airmass */
  float aspect;     /* I:             Azimuth of panel surface (direction it
                                        faces) N=0, E=90, S=180, W=270,
                                        DEFAULT = 180 */
  float azim;       /* O:  S_SOLAZM   Solar azimuth angle:  N=0, E=90, S=180,
                                        W=270 */
  float cosinc;     /* O:  S_TILT     Cosine of solar incidence angle on
                                        panel */
  float coszen;     /* O:  S_REFRAC   Cosine of refraction corrected solar
                                        zenith angle */
  float dayang;     /* T:  S_GEOM     Day angle (daynum*360/year-length)
                                        degrees */
  float declin;     /* T:  S_GEOM     Declination--zenith angle of solar noon
                                        at equator, degrees NORTH */
  float eclong;     /* T:  S_GEOM     Ecliptic longitude, degrees */
  float ecobli;     /* T:  S_GEOM     Obliquity of ecliptic */
  float ectime;     /* T:  S_GEOM     Time of ecliptic calculations */
  float elevetr;    /* O:  S_ZENETR   Solar elevation, no atmospheric
                                        correction (= ETR) */
  float elevref;    /* O:  S_REFRAC   Solar elevation angle,
                                        deg. from horizon, refracted */
  float eqntim;     /* T:  S_TST      Equation of time (TST - LMT), minutes */
  float erv;        /* T:  S_GEOM     Earth radius vector
                                        (multiplied to solar constant) */
  float etr;        /* O:  S_ETR      Extraterrestrial (top-of-atmosphere)
                                        W/sq m global horizontal solar
                                        irradiance */
  float etrn;       /* O:  S_ETR      Extraterrestrial (top-of-atmosphere)
                                        W/sq m direct normal solar
                                        irradiance */
  float etrtilt;    /* O:  S_TILT     Extraterrestrial (top-of-atmosphere)
                                        W/sq m global irradiance on a tilted
                                        surface */
  float gmst;       /* T:  S_GEOM     Greenwich mean sidereal time, hours */
  float hrang;      /* T:  S_GEOM     Hour angle--hour of sun from solar noon,
                                        degrees WEST */
  float julday;     /* T:  S_GEOM     Julian Day of 1 JAN 2000 minus
                                        2,400,000 days (in order to regain
                                        single precision) */
  float latitude;   /* I:             Latitude, degrees north (south negative) */
  float longitude;  /* I:             Longitude, degrees east (west negative) */
  float lmst;       /* T:  S_GEOM     Local mean sidereal time, degrees */
  float mnanom;     /* T:  S_GEOM     Mean anomaly, degrees */
  float mnlong;     /* T:  S_GEOM     Mean longitude, degrees */
  float rascen;     /* T:  S_GEOM     Right ascension, degrees */
  float press;      /* I:             Surface pressure, millibars, used for
                                        refraction correction and ampress */
  float prime;      /* O:  S_PRIME    Factor that normalizes Kt, Kn, etc. */
  float sbcf;       /* O:  S_SBCF     Shadow-band correction factor */
  float sbwid;      /* I:             Shadow-band width (cm) */
  float sbrad;      /* I:             Shadow-band radius (cm) */
  float sbsky;      /* I:             Shadow-band sky factor */
  float solcon;     /* I:             Solar constant (NREL uses 1367 W/sq m) */
  float ssha;       /* T:  S_SRHA     Sunset(/rise) hour angle, degrees */
  float sretr;      /* O:  S_SRSS     Sunrise time, minutes from midnight,
                                        local, WITHOUT refraction */
  float ssetr;      /* O:  S_SRSS     Sunset time, minutes from midnight,
                                        local, WITHOUT refraction */
  float temp;       /* I:             Ambient dry-bulb temperature, degrees C,
                                        used for refraction correction */
  float tilt;       /* I:             Degrees tilt from horizontal of panel */
  float timezone;   /* I:             Time zone, east (west negative).
                                      USA:  Mountain = -7, Central = -6, etc. */
  float tst;        /* T:  S_TST      True solar time, minutes from midnight */
  float tstfix;     /* T:  S_TST      True solar time - local standard time */
  float unprime;    /* O:  S_PRIME    Factor that denormalizes Kt', Kn', etc. */
  float utime;      /* T:  S_GEOM     Universal (Greenwich) standard time */
  float zenetr;     /* T:  S_ZENETR   Solar zenith angle, no atmospheric
                                        correction (= ETR) */
  float zenref;     /* O:  S_REFRAC   Solar zenith angle, deg. from zenith,
                                        refracted */
};

/* For users that wish to access individual functions, the following table
lists all output and transition variables, the L_ mask for the function
that calculates them, and all the input variables required by that function.
The function variable is set to the L_ mask, which will force S_solpos to
only call the required function.  L_ masks may be ORed as desired.

VARIABLE      Mask       Required Variables
---------  ----------  ---------------------------------------
 amass      L_AMASS    zenref, press
 ampress    L_AMASS    zenref, press
 azim       L_SOLAZM   elevetr, declin, latitude, hrang
 cosinc     L_TILT     azim, aspect, tilt, zenref, coszen,etrn
 coszen     L_REFRAC   elevetr, press, temp
 dayang     L_GEOM     All date, time, and location inputs
 declin     L_GEOM     All date, time, and location inputs
 eclong     L_GEOM     All date, time, and location inputs
 ecobli     L_GEOM     All date, time, and location inputs
 ectime     L_GEOM     All date, time, and location inputs
 elevetr    L_ZENETR   declin, latitude, hrang
 elevref    L_REFRAC   elevetr, press, temp
 eqntim     L_TST      hrang, hour, minute, second, interval
 erv        L_GEOM     All date, time, and location inputs
 etr        L_ETR      coszen, solcon, erv
 etrn       L_ETR      coszen, solcon, erv
 etrtilt    L_TILT     azim, aspect, tilt, zenref, coszen, etrn
 gmst       L_GEOM     All date, time, and location inputs
 hrang      L_GEOM     All date, time, and location inputs
 julday     L_GEOM     All date, time, and location inputs
 lmst       L_GEOM     All date, time, and location inputs
 mnanom     L_GEOM     All date, time, and location inputs
 mnlong     L_GEOM     All date, time, and location inputs
 rascen     L_GEOM     All date, time, and location inputs
 prime      L_PRIME    amass
 sbcf       L_SBCF     latitude, declin, ssha, sbwid, sbrad, sbsky
 ssha       L_SRHA     latitude, declin
 sretr      L_SRSS     ssha, tstfix
 ssetr      L_SRSS     ssha, tstfix
 tst        L_TST      hrang, hour, minute, second, interval
 tstfix     L_TST      hrang, hour, minute, second, interval
 unprime    L_PRIME    amass
 utime      L_GEOM     All date, time, and location inputs
 zenetr     L_ZENETR   declination, latitude, hrang
 zenref     L_REFRAC   elevetr, press, temp
/*


/*============================================================================
*    Long int function S_solpos, adapted from the NREL VAX solar libraries
*
*    This function calculates the apparent solar position and intensity
*    (theoretical maximum solar energy) based on the date, time, and
*    location on Earth. (DEFAULT values are from the optional S_posinit
*    function.)
*
*    Requires:
*        Date and time:
*            year
*            month  (optional without daynum)
*            day    (optional without daynum)
*            daynum
*            hour
*            minute
*            second
*        Location:
*            latitude
*            longitude
*        Location/time adjuster:
*            timezone
*        Atmospheric pressure and temperature:
*            press     DEFAULT 1013.0 mb
*            temp      DEFAULT 10.0 degrees C
*        Tilt of flat surface that receives solar energy:
*            aspect    DEFAULT 180 (South)
*            tilt      DEFAULT 0 (Horizontal)
*        Shadow band parameters:
*            sbwid     DEFAULT 7.6 cm
*            sbrad     DEFAULT 31.7 cm
*            sbsky     DEFAULT 0.04
*        Functionality
*            function  DEFAULT S_ALL (all output parameters computed)
*
*    Returns:
*        everything defined at the top of this listing.
*----------------------------------------------------------------------------*/
long S_solpos (struct posdata *pdat);

/*============================================================================
*    Void function S_init
*
*    This function initiates all of the input functions to S_Solpos().
*    NOTE: This function is optional if you initialize all input parameters
*          in your calling code.
*
*    Requires: Pointer to a posdata structure, members of which are
*           initialized.
*
*    Returns: Void
*
*----------------------------------------------------------------------------*/
void S_init(struct posdata *pdat);


/*============================================================================
*    Void function S_decode
*
*    This function decodes the error codes from S_solpos return value
*
*    INPUTS: Long integer S_solpos return value, struct posdata*
*
*    OUTPUTS: Descriptive text of errors to stderr
*----------------------------------------------------------------------------*/
void S_decode(long code, struct posdata *pdat);

