crepyscule

Module crepyscule

[show private | hide private]

Module crepyscule

Package to get different information related to the sun going around the Earth. It is based on one or two locations on the Earth, based on the lat/lon and, optional, the different time zone and summer time codes. Currently the following information is given by this code: sunrise, sunset, sun altitude, daylight variation, solar flux.

crepyscule could be use in two modes: for graphics and as a module.

The python module numpy is required.
The graphic mode required other modules and is more tedious to install. rpy for python and GDD in R are required.
Starting from version 1.0.0, it is possible to use crepyscule as a module, one only needs to uncompress crepyscule and could import it and use it directly. It only uses standard python package and numpy.

Project home page is http://ptaff.ca/crepyscule/

Note:

The file /usr/share/apps/kstars/Cities.dat from software kdeedu was used as a base for informations about time zones. The list of available time zone can be found in crepyscule_summer_time.py

Name: crepyscule.py
Author: Miguel Tremblay
Date: February 12th 2008

Function Summary
	`check_required(parser, opt)` Extention of class OptionParser for mandatory argument.
	`crepyscule(dDataRequest, fLat1, fLon1, ctime, fUTC1, sFilename, sSummerTime1, fLat2, fLon2, sSummerTime2, fUTC2, sBackgroundColor)` This is the main function for using crepyscule in command line.
	`get_command_line()` Parse the command line and perform all the checks.
list	`get_daylight_variation_as_csv(ctime, fLat1, fLat2)` Returns a list containing the date, variation in daylight.
dictionnary	`get_daylight_variation_as_dict(ctime, fLat)` Return a list containing the daylight variation for the year correspoding to this ctime in a dictionnary.
float	`get_daylight_variation_day(ctime, fLat)` Get the sun dayligth variation value for this day.
list	`get_max_sf_as_csv(ctime, fLat1, fLat2)` Returns a list containing the date, maximum solar flux
dictionnary	`get_max_sf_as_dict(ctime, fLat)` Return a list containing the maximum solar flux for each day in the year where this ctime belongs.
float	`get_max_sf_day(ctime, fLat)` Get the maximum solar flux value for this day.
list	`get_sun_altitude_as_csv(ctime, fLat1, fLat2)` Returns a list containing the date,sun_altitude
dictionnary	`get_sun_altitude_as_dict(ctime, fLat)` Return a list containing the sun altitude for this ctime.
float	`get_sun_altitude_day(ctime, fLat)` Get the sun altitude value for this day.
dictionnary	`get_sunrise_as_dict(ctime, fLat, fLon, fUTC, sSummerTime)` Get a dictionary containing the sunrise time for the year of the ctime.
float	`get_sunrise_day(ctime, fLat, fLon, fUTC, sSummerTime)` Get the sunrise value for this day.
list	`get_sunrise_sunset_as_csv(ctime, fLat1, fLon1, fUTC1, sSummerTime1, fLat2, fLon2, fUTC2, sSummerTime2)` Returns a list containing the date,sunrise,sunset in a CSV format.
dictionnary	`get_sunset_as_dict(ctime, fLat, fLon, fUTC, sSummerTime)` Return a list containing the sunset time for this ctime.
float	`get_sunset_day(ctime, fLat, fLon, fUTC, sSummerTime)` Get the sunset value for this day.
list	`get_twilight_length_as_csv(ctime, fLat1, fLat2)` Returns a list containing the date and the twilight length in minute.
dictionnary	`get_twilight_length_as_dict(ctime, fLat)` Return a list containing the twilight length in minute for each day in the year where this ctime belongs.
float	`get_twilight_length_day(ctime, fLat)` Get the twilight length in minute value for this day.

Function Details

check_required(parser, opt)

Extention of class OptionParser for mandatory argument. Comes from http://www.python.org/doc/2.3.4/lib/optparse-extending-examples.html

Parameters:: parser - Parser containing the values in the command line
(type=OptionParser); opt - option to check if it is required.
(type=string)

crepyscule(dDataRequest, fLat1, fLon1, ctime, fUTC1=0, sFilename='', sSummerTime1='', fLat2=None, fLon2=None, sSummerTime2='', fUTC2=0, sBackgroundColor='white')

This is the main function for using crepyscule in command line. The result is png images and/or text files containing the requested information about the Sun.

Parameters:

dDataRequest - Contains what file(s) or image(s) should be created. See the command line options. Keys are options with '--' and values are booleans. Keys are: 'GRAPH-SUNRISE','GRAPH-ALTITUDE' 'GRAPH-DAYLIGHT_VARIATION','GRAPH-SOLAR_FLUX', 'GRAPH-TWILIGHT_LENGTH', 'TEXT-SUNRISE'
(type=dictionnary)

fLat1 - latitude of the first place. Latitude is in decimal degrees. Example: 30°30' should be 30.5
(type=float)

fLon1 - longitude of the first place. Longitude is in decimal degrees. Example: 30°30' should be 30.5. West longitude are negative East longitude are positive.
(type=float)

ctime - Any ctime in the day for the wanted value. If a graphic is created and there is only one place, a line is drawn with the values written at the intersection for this specific day.
(type=float)

fUTC1 - Time to add/substract for each time values for the first place. Usually used for UTC value of place.
(type=float)

sFilename - Filename for the images or text. Filename must ends with 'png' extension. The sunrise/sunset image is written with this filename. This terminology is used:

sunrise/sunset: filename.png
altitude: filename_alt.png 
daylight variation: filename_delta_t.png
solar flux: filename_sf.png
sunrise/sunset text file: filename.txt

(type=string)

sSummerTime1 - This variable is a 2 letters code indicating when is the daylight saving time (DST) starting and ending in the year for the first place. Default is no DST. For a list of DST code, see crepyscule_summer_time.lTimezone.
(type=string)

fLat2 - latitude of the second place. See fLat1.
(type=float)

fLon2 - longitude of the second place. See fLon1.
(type=float)

sSummerTime2 - This variable is a 2 letters code indicating when is the daylight saving time (DST) starting and ending in the year for the seconde place. Default is no DST. For a list of DST code, see crepyscule_summer_time.lTimezone.
(type=string)

fUTC2 - Time to add/substract for each time values for the second place.
(type=float)

sBackgroundColor - Color that will be used for the background color for the generated graphics. See Chart of R colors
(type=string)

get_command_line()

Parse the command line and perform all the checks.

get_daylight_variation_as_csv(ctime, fLat1, fLat2=None)

Returns a list containing the date, variation in daylight.

See function crepyscule_tools.get_daylight_variation_as_csv for detailed information.

Parameters:: ctime - Any ctime in the year of the result.
(type=float); fLat1 - Latitude in decimal for the first place.
(type=float); fLat2 - latitude in decimal for the second place.
(type=float)

Returns:: list containing the date,variation in daylight in CSV format. One line per item in the list.
(type=list)

get_daylight_variation_as_dict(ctime, fLat)

Return a list containing the daylight variation for the year correspoding to this ctime in a dictionnary.

Parameters:: ctime - Any ctime in the year of the result.
(type=float); fLat - Latitude in decimal for the place.
(type=float)

Returns:: Dictionnary containing daylight variation for the year of the ctime. Keys of dictionary is a string in iso8601 format like 'YYYY-MM-DD'.
(type=dictionnary)

get_daylight_variation_day(ctime, fLat)

Get the sun dayligth variation value for this day.

Parameters:: ctime - Any ctime in the year of the result.
(type=float); fLat - Latitude in decimal for the place.
(type=float)

Returns:: Daylight variation for this day in float.
(type=float)

get_max_sf_as_csv(ctime, fLat1, fLat2=None)

Returns a list containing the date, maximum solar flux

See function crepyscule_tools.get_solar_flux_as_csv for detailed information.

Parameters:: ctime - Any ctime in the year of the result.
(type=float); fLat1 - Latitude in decimal for the first place.
(type=float); fLat2 - Latitude in decimal for the second place.
(type=float)

Returns:: list containing the date,max_solar_flux in CSV format. One line per item in the list. Solar flux is in watt per meter square.
(type=list)

get_max_sf_as_dict(ctime, fLat)

Return a list containing the maximum solar flux for each day in the year where this ctime belongs.

Parameters:: ctime - Any ctime in the year of the result.
(type=float); fLat - Latitude in decimal for the place.
(type=float)

Returns:: Dictionnary containing maximum solar flux of each day for the year of the ctime. Keys of dictionary is a string in iso8601 format like 'YYYY-MM-DD'. Solar flux is in watt per meter square.
(type=dictionnary)

get_max_sf_day(ctime, fLat)

Get the maximum solar flux value for this day.

Parameters:: ctime - Any ctime in the year of the result.
(type=float); fLat - Latitude in decimal for the place.
(type=float)

Returns:: Maximum solar flux for this day in float. Solar flux is in watt per meter square.
(type=float)

get_sun_altitude_as_csv(ctime, fLat1, fLat2=None)

Returns a list containing the date,sun_altitude

No use for longitude, UTC or summer time. Use default values.

See function crepyscule.get_sun_altitude_as_csv for detailed information.

Parameters:: ctime - Any ctime in the year of the result.
(type=float); fLat1 - Latitude in decimal for the first place.
(type=float); fLat2 - latitude in decimal for the second place.
(type=float)

Returns:: list containing the date,sun_altitude in CSV format. One line per item in the list.
(type=list)

get_sun_altitude_as_dict(ctime, fLat)

Return a list containing the sun altitude for this ctime.

No use for longitude, UTC or summer time. Use default values.

Parameters:: ctime - Any ctime in the year of the result.
(type=float); fLat - Latitude in decimal for the place.
(type=float)

Returns:: Dictionnary containing sun altitude for the year of the ctime. Keys of dictionary is a string in iso8601 format like 'YYYY-MM-DD'.
(type=dictionnary)

get_sun_altitude_day(ctime, fLat)

Get the sun altitude value for this day. No use for longitude, UTC or summer time. Use default values.

Parameters:: ctime - Any ctime in the year of the result.
(type=float); fLat - Latitude in decimal for the place.
(type=float)

Returns:: Sun altitude for this day in float.
(type=float)

get_sunrise_as_dict(ctime, fLat, fLon, fUTC=0, sSummerTime='')

Get a dictionary containing the sunrise time for the year of the ctime. Keys of dictionary are date in iso8601 format.

Parameters:: ctime - Any ctime in the year of the result.
(type=float); fLat - Latitude in decimal.
(type=float); fLon - Longitude in decimal. West longitude are negative East longitude are positive.
(type=float); fUTC - Time to add/substract for each time values. Usually used for UTC value of place.
(type=float); sSummerTime - This variable is a 2 letters code indicating when is the daylight saving time (DST) starting and ending in the year for the first place. Default is no DST. For a list of DST code, see crepyscule_summer_time.lTimezone.
(type=string)

Returns:: Dictionnary containing sunrise time for the year of the ctime. Keys of dictionary are date in iso8601 format.
(type=dictionnary)

get_sunrise_day(ctime, fLat, fLon, fUTC=0, sSummerTime='')

Get the sunrise value for this day.

Parameters:: ctime - Any ctime in the day for the wanted value.
(type=float); fLat - Latitude in decimal.
(type=float); fLon - Longitude in decimal. West longitude are negative East longitude are positive.
(type=float); fUTC - Time to add/substract for each time values. Usually used for UTC value of place.
(type=float); sSummerTime - This variable is a 2 letters code indicating when is the daylight saving time (DST) starting and ending in the year for the first place. Default is no DST. For a list of DST code, see crepyscule_summer_time.lTimezone.
(type=string)

Returns:: Time of the day in float.
(type=float)

get_sunrise_sunset_as_csv(ctime, fLat1, fLon1, fUTC1=0, sSummerTime1='', fLat2=None, fLon2=None, fUTC2=0, sSummerTime2='')

Returns a list containing the date,sunrise,sunset in a CSV format. See function crepyscule_tools.get_sunrise_sunset_as_csv for detailed information.

Parameters:: ctime - Any ctime in the year of the result.
(type=float); fLat1 - Latitude in decimal for the first place.
(type=float); fLon1 - Longitude in decimal for the first place. West longitude are negative. East longitude are positive.
(type=float); fUTC1 - Time to add/substract for each time values for the first place. Usually used for UTC value of place.
(type=float); sSummerTime1 - This variable is a 2 letters code indicating when is the daylight saving time (DST) starting and ending in the year for the first place. Default is no DST. For a list of DST code, see crepyscule_summer_time.lTimezone.
(type=string); fLat2 - latitude of the second place. See fLat1.
(type=float); fLon2 - longitude of the second place. See fLon1.
(type=float); fUTC2 - Time to add/substract for each time values for the second place.
(type=float); sSummerTime2 - This variable is a 2 letters code indicating when is the daylight saving time (DST) starting and ending in the year for the seconde place. Default is no DST. For a list of DST code, see crepyscule_summer_time.lTimezone.
(type=string)

Returns:: list containing the date,sunrise,sunset in CSV format. One line per item in the list.
(type=list)

get_sunset_as_dict(ctime, fLat, fLon, fUTC=0, sSummerTime='')

Return a list containing the sunset time for this ctime.

Parameters:: ctime - Any ctime in the year of the result.
(type=float); fLat - Latitude in decimal.
(type=float); fLon - Longitude in decimal. West longitude are negative East longitude are positive.
(type=float); fUTC - Time to add/substract for each time values. Usually used for UTC value of place.
(type=float); sSummerTime - This variable is a 2 letters code indicating when is the daylight saving time (DST) starting and ending in the year for the first place. Default is no DST. For a list of DST code, see crepyscule_summer_time.lTimezone.
(type=string)

Returns:: Dictionnary containing sunset time for the year of the ctime. Keys of dictionary is a string in iso8601 format like 'YYYY-MM-DD'.
(type=dictionnary)

get_sunset_day(ctime, fLat, fLon, fUTC=0, sSummerTime='')

Get the sunset value for this day.

Parameters:: ctime - Any ctime in the day for the wanted value.
(type=float); fLat - Latitude in decimal.
(type=float); fLon - Longitude in decimal. West longitude are negative East longitude are positive.
(type=float); fUTC - Time to add/substract for each time values. Usually used for UTC value of place.
(type=float); sSummerTime - This variable is a 2 letters code indicating when is the daylight saving time (DST) starting and ending in the year for the first place. Default is no DST. For a list of DST code, see crepyscule_summer_time.lTimezone.
(type=string)

Returns:: Time of the day in float.
(type=float)

get_twilight_length_as_csv(ctime, fLat1, fLat2=None)

Returns a list containing the date and the twilight length in minute. Note: the twilight length is defined as the duration while the sun is below the horizon and less than 12° below (nautical twilight).

See function crepyscule_tools.get_twilight_length_as_csv for detailed information.

Parameters:: ctime - Any ctime in the year of the result.
(type=float); fLat1 - Latitude in decimal for the first place.
(type=float); fLat2 - Latitude in decimal for the second place.
(type=float)

Returns:: list containing the date, twilight_length in CSV format. One line per item in the list. Twilight length is minutes
(type=list)

get_twilight_length_as_dict(ctime, fLat)

Return a list containing the twilight length in minute for each day in the year where this ctime belongs.

Parameters:: ctime - Any ctime in the year of the result.
(type=float); fLat - Latitude in decimal for the place.
(type=float)

Returns:: Dictionnary containing the twilight length of each day for the year of the ctime. Keys of dictionary is a string in iso8601 format like 'YYYY-MM-DD'. Solar flux is in watt per meter square.
(type=dictionnary)

get_twilight_length_day(ctime, fLat)

Get the twilight length in minute value for this day.

Parameters:: ctime - Any ctime in the year of the result.
(type=float); fLat - Latitude in decimal for the place.
(type=float)

Returns:: Twilight length for this day in float. Length is in degree/hour
(type=float)

Generated by Epydoc 2.1 on Wed Jan 28 21:01:07 2009

http://epydoc.sf.net