solar¶
The solar module contains just one class definition, with many associated methods to perform a plethora of calculations based around the sun-earth relationship. It replicates the functionality of the common NOAA excel calculator, including adjustments due to atmospheric refraction. Each method may be run independently as the user wishes, as each method will automatically invoke any other calculations that must be performed first, and it will not unnecessarily redo calculations that have already been completed.
A solar class object allows scalar or numpy array inputs for latitude and longitude values for per-pixel computation and improved accuracy when scene-center calculations are insufficient. The solar class is not yet capable of ingesting digital elevation models to calculate slope and aspect dependent parameters, but it is a planned addition.
Examples¶
Compute all available solar parameters
For a simple example, lets just assume we want to go ahead and calculate everything. The inputs for all solar calculations come down to space and time. More specifically, latitude and longitude coordinates and a precise time in standard GMT. For the example below, we are going to use 2015-May-15th at exactly noon local time, in Hampton Virginia USA. Note that while observing daylight savings time, the east coast observes EDT, which is GMT-4, watch out for mistakes with time zones!
from dnppy import solar
lat = 37 # lat (N positive)
lon = -76.4 # lon (E positive)
datestamp = "20150515-120000" # date stamp
fmt = "%Y%m%d-%H%M%S" # datestamp format
tz = -4 # timezone (GMT/UTC) offset
sc = solar(lat, lon, datestamp, tz, fmt)
sc.compute_all()
The code above successfully updates solar instance sc to have all the attributes supported by the class, and prints a summary with descriptive variable names, values, and units. If the datestamp and fmt variables are unfamiliar to you, you can read more about python datetime objects and how to create them from strings with fmt syntax.
Once you mastered datetime objects, you will probably want to use them all the time (they are pretty great). Fortunately, you can simply input a datetime object in place of the datestamp variable in the code above, and omit the fmt variable entirely, such as:
from dnppy import solar
from datetime import datetime
lat = 37
lon = -76.4
dt_obj = datetime(2015,5,15,12,0,0)
tz = -4
sc = solar(lat, lon, dt_obj, tz)
sc.compute_all()
Lets say you aren’t interested in anything except the solar elevation angle. After consulting help(solar) or the function list below, we see there is a method called get_elevation, and decide to invoke that instead of compute_all() and save it in a new variable called solar_elevation.
solar_elevation = sc.get_elevation() # invoke method of solar instance "sc"
That’s it! you can get any available attribute of a solar instance in exactly the same way!
Code Help¶
Auto-documentation for functions and classes within this module is generated below!
-
class
solar(lat, lon, date_time_obj, time_zone=0, fmt=False, slope=None, aspect=None)[source]¶ Object class for handling solar calculations. Many equations are taken from the excel sheet at this url : [http://www.esrl.noaa.gov/gmd/grad/solcalc/calcdetails.html]
It requires a physical location on the earth and a datetime object
Parameters: - lat – decimal degrees latitude (float OR numpy array)
- lon – decimal degrees longitude (float OR numpy array)
- time_zone – float of time shift from GMT (such as “-5” for EST)
- date_time_obj – either a timestamp string following fmt or a datetime obj
- fmt – if date_time_obj is a string, fmt is required to interpret it
- slope – slope of land at lat,lon for solar energy calculations
- aspect – aspect of land at lat,lon for solar energy calculations
An instance of this class may have the following attributes:
attribute description type lat latitude (array) lon longitude (array) tz time zone (scalar) rdt reference datetime object (date_time_obj) (scalar) slope slope, derivative of DEM (array) aspect aspect (north is 0, south is 180) (array) ajd absolute julian day (scalar) ajc absolute julian century (scalar) geomean_long geometric mean longitude of the sun (scalar) geomean_anom geometric mean longitude anomaly of the sun (scalar) earth_eccent eccentricity of earths orbit (scalar) sun_eq_of_center the suns equation of center (scalar) true_long true longitude of the sun (scalar) true_anom true longitude anomaly of the sun (scalar) app_long the suns apparent longitude (scalar) oblique_mean_elip earth oblique mean ellipse (scalar) oblique_corr correction to earths oblique elipse (scalar) right_ascension suns right ascension angle (scalar) declination solar declination angle (scalar) equation_of_time equation of time (minutes) (scalar) hour_angle_sunrise the hour angle at sunrise (array) solar_noon LST of solar noon (array) sunrise LST of sunrise time (array) sunset LST of sunset time (array) sunlight LST fractional days of sunlight (array) true_solar LST for true solar time (array) hour_angle total hour angle (array) zenith zenith angle (array) elevation elevation angle (array) azimuth azimuthal angle (array) rad_vector radiation vector (distance in AU) (scalar) earth_distance earths distance to sun in meters (scalar) norm_irradiance incident solar energy at earth distance (scalar) Units used by this class unless otherwise labeled
- angle = degrees
- distance = meters
- energy = watts or joules
- time = mostly in datetime objects. labeled in most cases.
Planned improvements
- DONE. Inputs of numpy arrays for lat and lon needs to be allowed.
- inputs of a numpy array DEM for slope/aspect effects on incident solar energy
Present performance
To process about one landsat tile (7300^2 matrix) requires 9GB of memory and takes 45 seconds to process on a single 3.3GHz thread. It would be nice to get the same output to run on ~5GB of memory so a 8GB system could handle it.-
compute_all()[source]¶ Computes and prints all the attributes of this solar object. Spatial averages are printed for numpy array type attributes.
-
get_earth_distance()[source]¶ Return earth_distance: distance between the earth and the sun at ref_datetime
-
get_earth_eccent()[source]¶ Return earth_eccent: precise eccentricity of earths orbit at referece datetime
-
get_inc_irradiance()[source]¶ calculates the actual incident solar irradiance at a given lat,lon coordinate with adjustments for slope and aspect if they have been given. Not finished.
-
get_norm_irradiance()[source]¶ Calculates incoming solar energy in W/m^2 to a surface normal to the sun.
inst_irradiance is calculated as = sun_surf_radiance*(sun_radius / earth_distance)^2 and is then corrected as a function of solar incidence angle
Return norm_irradiance: the normal irradiance in W/m^2