| #### NREL's SOLPOS 2.0: Documentation

SOLPOS.C

Distributed by the National Renewable Energy Laboratory
Center for Renewable Energy Resources
Renewable Resource Data Center
February 2000

NOTICE
This report was prepared as an account of work sponsored by an agency of the United States government. Neither the United States government nor any agency thereof, nor any of their employees, makes any warranty, express or implied, or assumes an legal liability or responsibility for the accuracy, completeness, or usefulness of any information, apparatus, product, or process disclosed, or represents that its use would not infringe privately owned rights. Reference herein to any specific commercial produce, process or service by trade name, trademark, manufacturer, or otherwise does not necessarily constitute or imply its endorsement, recommendation or favoring by the United States government or any agency thereof. The view and opinions of authors expressed herein do not necessarily state or reflect those of the United States government or any agency thereof.

This C function calculates the apparent solar position and intensity (theoretical maximum solar energy) based on the date, time, and location on Earth. The software has been tested on a variety of platforms, but as noted above, is not guaranteed to work on yours. It is provided here as a convenience.

This document provides only a general overview of the software functionality. The accompanying sample program stest00.c provides additional information by example on how the function is set up and called from an application program. That program serves as the only tutorial for the use of S_solpos.

The module contains three functions:

| S_solpos |  | Performs calculations
| S_init |  | Initializes S_solpos
| S_decode |  | Decodes the return value from S_solpos

To obtain references for the algorithms see the REFERENCES section below. Comments in the source code specify references for each function.

====================================

S_solpos (computes solar position and intensity from time and place) INPUTS: (via posdata struct defined in solpos00.h) year, daynum, hour, minute, second, latitude, longitude, timezone, interval OPTIONAL: (via posdata struct) month, day, press, temp, tilt, aspect, function OUTPUTS: EVERY variable in the struct posdata (defined in solpos00.h)

S_init (optional initialization for all input parameters in the posdata struct) INPUTS: struct posdata* OUTPUTS: struct posdata* Initializes the required S_solpos INPUTS above to out-of-bounds conditions, forcing the user to supply the parameters; initializes the OPTIONAL S_solpos inputs above to nominal values. See listing below for default values provided by S_init.

S_decode (optional utility for decoding the S_solpos return code) INPUTS: long int S_solpos return value, struct posdata* OUTOUTS: Text to stderr

ALPHABETICAL LIST OF COMMON VARIABLES

The I/O column contains a letter code: I: INPUT variable O: OUTPUT variabl 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 target output variable. All function codes are defined in the solpos00.h file. The default S_ALL mask calculates all output variables. Multiple function masks may be ORed to create a composite function switch. For example, (S_TST | S_SBCF) will force the calculation of the shadow band correction factor as well as all variables required for S_TST (true solar time). Specifying only the functions necessary for required output variables might allow solpos to execute more quickly.

The S_DOY mask works as a toggle between the input date represented as a day of year number (daynum) and an input date represented by month and day of month. To set the switch (to use daynum input), the mask is ORed with the function variable; to clear the switch (to use month and day input), the mask is inverted and ANDed.

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 sample program stest00.c for other examples.

VARIABLE | I/O | Function | Description -------------------- | ------- | ---------------- | --------------------------------------------------------
/**** INTEGERS ****/ |
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 year, month, and day depending on the setting of the S_DOY function switch.
int function | I: |  | Bit-oriented switch to choose function) | for desired output..
int hour | I: |  | Hour of day, 0 — 24. (Time 24:00:00 is | treated internally as time 00:00:00 of the following day.)
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.
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.
int year | I: |  | 4-digit year (2-digit years 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_REFRAC | Solar elevation, no atmospheric | correction (= ETR)
float elevref | O: | S_REFRAC | Solar elevation angle, degrees 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 minusn | 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 facto
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
floattstfix | 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.

All functions require the input parameters for time, date, latitude, longitude, time zone, and measurement interval. Some functions may require additional input parameters. The table below indicates with an "X" which, if any, additional input parameters are required for each function. After determining the output variables you require from the above list, make note of the required functions, then determine the required inputs from the table:

Function |  | -------------------- Required Inputs ------------------
|  | solcon | press | sbwid | sbrad | sbsky | temp | tilt | aspect
S_AMASS |  | -- | X | -- | -- | -- | X | -- | --
S_DOY |  | -- | -- | -- | -- | -- | -- | -- | --
S_ETR |  | X | X | -- | -- | -- | X | -- | --
S_GEOM |  | -- | -- | -- | -- | -- | -- | -- | --
S_REFRAC |  | -- | X | -- | -- | -- | X | -- | --
S_PRIME |  | -- | X | -- | -- | -- | X | -- | --
S_SOLAZM |  | -- | -- | -- | -- | -- | -- | -- | --
S_SRSS |  | -- | -- | -- | -- | -- | -- | -- | --
S_SSHA |  | -- | -- | -- | -- | -- | -- | -- | --
S_SBCF |  | -- | -- | X | X | X | -- | -- | --
S_TILT |  | X | X | -- | -- | -- | X | X | X
S_TST |  | -- | -- | -- | -- | -- | -- | -- | --
S_ZENETR |  | -- | -- | -- | -- | -- | -- | -- | --

The S_init function provides nominal values for the above inputs. The values are listed below (note that time and location variables are initialized out of bounds to force the user to provide valid inputs):

day | = | -99 | /* undefined */
daynum | = | -999 | /* undefined */
hour | = | -99 | /* undefined */
minute | = | -99 | /* undefined */
month | = | -99 | /* undefined */
second | = | -99 | /* undefined */
year | = | -99 | /* undefined */
interval | = | 0 | /* instantaneous */
aspect | = | 180.0 | /* south */
latitude | = | -99.0 | /* undefined */
longitude | = | -999.0 | /* undefined */
press | = | 1013.0 | /* standard pressure */
solcon | = | 1367.0 | /* NREL uses this */
temp | = | 15.0 | /* Temperature of the standard atmosphere */
tilt | = | 0.0 | /* horizontal */
timezone | = | -99.0 | /* undefined */
sbwid | = | 7.6 | /* Eppley shadowband */
sbrad | = | 31.7 | /* Eppley shadowband */
sbsky | = | 0.04 | /* Eppley shadowband */
function | = | S_ALL | /* calculate ALL output parameters */

Certain conditions exist during which some of the output variables are undefined or cannot be calculated. In these cases, the variables are returned with flag values indicating such. In other cases, the variables may return a realistic, though invalid, value. These variables and the flag values or invalid conditions are listed below:

amass |  | -1.0 at zenetr angles greater than 93.0 degrees
ampress |  | -1.0 at zenetr angles greater than 93.0 degrees<
azim |  | invalid at zenetr angle 0.0 or latitude +/-90.0 or at night
elevetr |  | limited to —9 degrees at night
etr |  | 0.0 at night
etrn |  | 0.0 at night
etrtilt |  | 0.0 when cosinc is less than 0
prime |  | invalid at zenetr angles greater than 93.0 degrees
sretr |  | +/- 2999.0 during periods of 24 hour sunup or sundown
ssetr |  | +/- 2999.0 during periods of 24 hour sunup or sundown
ssha |  | invalid at the North and South Poles
unprime |  | invalid at zenetr angles greater than 93.0 degrees
zenetr |  | limited to 99.0 degrees at night

S_solpos returns a long integer error code. Each bit position in the long int represents an error in the range of a particular input parameter. The S_decode function in solpos.c examines the return code for errors and can be used as is or as a template for building an application-specific function.

The bit positions for each error are defined in solpos00.h, and are listed below. (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 | */

R E F E R E N C E S

ASTRONOMICAL SOLAR POSITION:

Michalsky, J. 1988. The Astronomical Almanac's algorithm for approximate solar
| position (1950-2050). Solar Energy 40 (3), 227-235.
Michalsky, J. 1988. ERRATA: The atronomical almanac's algorithm for approximate
| solar position (1950-2050). Solar Energy 41 (1), 113.

DISTANCE FROM SUN TO EARTH

Spencer, J. W. 1971. Fourier series representation of the position of the sun. Search 2
| (5), 172.
| NOTE: This paper gives solar position algorithms as well, but the Michalsky/Almanac algorithm above is more accurate.

ATMOSPHERIC REFRACTION CORRECTION

Zimmerman, John C. 1981. Sun-pointing programs and their accuracy. SAND81-0761,
| Experimental Systems Operation Division 4721, Sandia National Laboratories, Albuquerque, NM.

SHADOW BAND CORRECTION FACTOR

Drummond, A. J. 1956. A contribution to absolute pyrheliometry. Q. J. R. Meteorol.2
| Soc. 82, 481-493..

RELATIVE OPTICAL AIR MASS

Kasten, F. and Young, A. 1989. Revised optical air mass tables and approximation
| formula. Applied Optics 28 (22), 4735-4738.

RENORMALIZATION OF KT ("PRIME")

Perez, R., P. Ineichen, Seals, R., & Zelenka, A. 1990. Making full use of the clearness
| index for parameterizing hourly insolation conditions. Solar Energy 45 (2),
| 111-114.

SOLAR POSITION RELATIVE TO EARTH

Iqbal, M. 1983. An Introduction to Solar Radiation. Academic Press, NY.
| NOTE: The 1983 edition contains typographic errors in coefficients of some equations. Further, many algorithms given in this book are no longer the best. However, this book gives a complete overview of the issues and methods of measuring and modeling solar radiation

Return to RReDC home page ( http://www.nrel.gov/rredc)