Skip to main content

Solar Position and Intensity

NREL's Solar Position and Intensity (SOLPOS 2.0) C function calculates the apparent solar position and intensity (theoretical maximum solar energy) based on date, time, and location on Earth.

SOLPOS includes three C codes:

  • solpos.c – The actual code that computes the sun's intensity and position in the sky
  • solpos00.h – The header file that must be included in the code that calls "solpos.c"
  • stest00.c – A test code that exercises "solpos.c"

By accessing these files, you agree to abide by the NREL data disclaimer. This software has been tested on a variety of platforms, but it is not guaranteed to work on yours. It is provided here as a convenience


This documentation provides an overview of the software functionality. The 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 variable

T: TRANSITIONAL variable used in the algorithm of interest only to the solar radiation modelers.

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,

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, and then determine the required inputs from the below 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   */


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 astronomical 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.