Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
DateTime::Event::SunriUser)Contributed Perl DocumenDateTime::Event::Sunrise(3)

NAME
       DateTime::Event::Sunrise	- Perl DateTime	extension for computing	the
       sunrise/sunset on a given day

SYNOPSIS
	 use DateTime;
	 use DateTime::Event::Sunrise;

	 # generating DateTime objects from a DateTime::Event::Sunrise object
	 my $sun_Kyiv =	DateTime::Event::Sunrise->new(longitude	=> +30.85,  # 30A<degree>51'E
						      latitude	=> +50.45); # 50A<degree>27'N
	 for (12, 13, 14) {
	   my $dt_yapc_eu = DateTime->new(year	    => 2013,
					  month	    =>	  8,
					  day	    =>	 $_,
					  time_zone => 'Europe/Kiev');
	   say "In Kyiv	(50A<degree>27'N, 30A<degree>51'E) on ", $dt_yapc_eu->ymd, " sunrise occurs at ", $sun_Kyiv->sunrise_datetime($dt_yapc_eu)->hms,
								" and sunset occurs at ", $sun_Kyiv->sunset_datetime ($dt_yapc_eu)->hms;
	 }

	 # generating DateTime objects from DateTime::Set objects
	 my $sunrise_Austin = DateTime::Event::Sunrise->sunrise(longitude => -94.73,  #	97A<degree>44'W
								latitude  => +30.3);  #	30A<degree>18'N
	 my $sunset_Austin  = DateTime::Event::Sunrise->sunset (longitude => -94.73,
								latitude  => +30.3);
	 my $dt_yapc_na_rise = DateTime->new(year      => 2013,
					     month     =>    6,
					     day       =>    3,
					     time_zone => 'America/Chicago');
	 my $dt_yapc_na_set = $dt_yapc_na_rise->clone;
	 say "In Austin	(30A<degree>18'N, 97A<degree>44'W), sunrises and sunsets are";
	 for (1..3) {
	   $dt_yapc_na_rise = $sunrise_Austin->next($dt_yapc_na_rise);
	   $dt_yapc_na_set  = $sunset_Austin ->next($dt_yapc_na_set);
	   say $dt_yapc_na_rise, ' ', $dt_yapc_na_set;
	 }

	 # If you deal with a polar location
	 my $sun_in_Halley = DateTime::Event::Sunrise->new(
					longitude => -26.65, # 26A<degree>39'W
					latitude  => -75.58, # 75A<degree>35'S
					precise	  => 1,
					);
	 my $Alex_arrival = DateTime->new(year	=> 2006, # approximate date, not necessarily the exact one
					  month	=>    1,
					  day	=>   15,
					  time_zone => 'Antarctica/Rothera');
	 say $Alex_arrival->strftime("Alex Gough (a Perl programmer) arrived at	Halley Base on %Y-%m-%d.");
	 if ($sun_in_Halley->is_polar_day($Alex_arrival)) {
	   say "It would be days, maybe	weeks, before the sun would set.";
	 }
	 elsif ($sun_in_Halley->is_polar_night($Alex_arrival)) {
	   say "It would be days, maybe	weeks, before the sun would rise.";
	 }
	 else {
	   my $sunset =	$sun_in_Halley->sunset_datetime($Alex_arrival);
	   say $sunset->strftime("And he saw his first antarctic sunset	at %H:%M:%S.");
	 }

DESCRIPTION
       This module will	computes the time of sunrise and sunset	for a given
       date and	a given	location. The computation uses Paul Schlyter's
       algorithm.

       Actually, the module creates a DateTime::Event::Sunrise object or a
       DateTime::Set object, which are used to generate	the sunrise or the
       sunset times for	a given	location and for any date.

METHODS
   new
       This is the DateTime::Event::Sunrise constructor. It takes keyword
       parameters, which are:

       longitude
	   This	is the longitude of the	location where the sunrises and
	   sunsets are observed.  It is	given as decimal degrees: no minutes,
	   no seconds, but tenths and hundredths of degrees.  Another break
	   with	the normal usage is that Eastern longitude are positive,
	   Western longitudes are negative.

	   Default value is 0, that is Greenwich or any	location on the
	   eponymous meridian.

       latitude
	   This	is the latitude	of the location	where the sunrises and sunsets
	   are observed.  As for the longitude,	it is given as decimal
	   degrees. Northern latitudes are positive numbers, Southern
	   latitudes are negative numbers.

	   Default value is 0, that is any location on the equator.

       altitude
	   This	is the height of the Sun at sunrise or sunset. In astronomical
	   context, the	altitude or height is the angle	between	the Sun	and
	   the local horizon. It is expressed as degrees, usually with a
	   negative number, since the Sun is below the horizon.

	   Default value is -0.833, that is when the sun's upper limb touches
	   the horizon,	while taking in	account	the light refraction.

	   Positive altitude are allowed, in case the location is near a
	   mountain range behind which the sun rises or	sets.

       precise
	   Boolean to control which algorithm is used. A false value gives a
	   simple algorithm, but which can lead	to inaccurate sunrise times
	   and sunset times. A true value gives	a more elaborate algorithm,
	   with	a loop to refine the sunrise and sunset	times and obtain a
	   better precision.

	   Default value is 0, to choose the simple algorithm.

	   This	parameter replaces the "iteration" deprecated parameter.

       upper_limb
	   Boolean to choose between checking the Sun's	upper limb or its
	   center.  A true value selects the upper limb, a false value selects
	   the center.

	   This	parameter is significant only when the altitude	does not
	   already deal	with the sun radius.  When the altitude	takes into
	   account the sun radius, this	parameter should be false.

	   Default value is 0, since the upper limb correction is already
	   taken in account with the default -0.833 altitude.

       silent
	   Boolean to control the output of some warning messages.  With polar
	   locations and dates near the	winter solstice	or the summer
	   solstice, it	may happen that	the sun	never rises above the horizon
	   or never sets below.	 If this parameter is set to false, the	module
	   will	send warnings for these	conditions. If this parameter is set
	   to true, the	module will not	pollute	your STDERR stream.

	   Default value is 0, for backward compatibility.

       trace
	   This	parameter should  either be a false value or  a	filehandle
	   opened for output.  In the  latter case,  a few messages  are
	   printed  to the filehandle, which  allows the programmer to	see
	   step	by step	 how the sunrise and the sunset	are computed.

	   Used	for  analysis and debugging purposes.  You need	to read	 the
	   text	doc/astronomical-notes.pod in  the sister  module
	   Astro::Sunrise to understand	what the traced	values represent.

	   Default value is 0, which does not produce trace messages.

   sunrise, sunset
       Although	they come from the DateTime::Event::Sunrise module, these
       methods are "DateTime::Set" constructors. They use the same parameters
       as the "new" constructor, but they give objects from a different	class.

   sunrise_datetime, sunset_datetime
       These two methods apply to "DateTime::Event::Sunrise" objects (that is,
       created with "new", not "sunrise" or "sunset"). They receive one
       parameter in addition to	$self, a "DateTime" object. They return
       another "DateTime" object, for the same day, but	with the time of the
       sunrise or sunset, respectively.

   sunrise_sunset_span
       This method applies to "DateTime::Event::Sunrise" objects. It accepts a
       "DateTime" object as the	second parameter. It returns a
       "DateTime::Span"	object,	beginning at sunrise and ending	at sunset.

   is_polar_night, is_polar_day, is_day_and_night
       These methods apply to "DateTime::Event::Sunrise" objects. They accept
       a "DateTime" object as the second parameter. They return	a boolean
       indicating the following	condutions:

       o   is_polar_night is true when the sun stays under the horizon.	Or
	   rather under	the altitude parameter used when the
	   "DateTime::Event::Sunrise" object was created.

       o   is_polar_day	is true	when the sun stays above the horizon,
	   resulting in	a "Midnight sun". Or rather when it stays above	the
	   altitude parameter used when	the "DateTime::Event::Sunrise" object
	   was created.

       o   is_day_and_night is true when neither is_polar_day, nor
	   is_polar_night are true.

   next	current	previous contains as_list iterator
       See DateTime::Set.

EXTENDED EXAMPLES
	 my $dt	= DateTime->new( year	=> 2000,
				 month	=> 6,
				 day	=> 20,
			 );

	 my $sunrise = DateTime::Event::Sunrise	->sunrise (
			       longitude =>'-118',
			       latitude	 =>'33',
			       altitude	 => '-0.833',
			       precise	 => '1'
			 );

	 my $sunset = DateTime::Event::Sunrise ->sunset	(
			       longitude =>'-118',
			       latitude	 =>'33',
			       altitude	 => '-0.833',
			       precise	 => '1'
			 );

	 my $tmp_rise =	$sunrise->next(	$dt );

	 my $dt2 = DateTime->new( year	 => 2000,
				  month	 => 12,
				  day	 => 31,
			  );

	 # iterator
	 my $dt_span = DateTime::Span->new( start =>$dt, end=>$dt2 );
	 my $set = $sunrise->intersection($dt_span);
	 my $iter = $set->iterator;
	 while ( my $dt	= $iter->next )	{
	   print ' ',$dt->datetime;
	 }

	 # is it day or	night?
	 my $day_set = DateTime::SpanSet->from_sets(
	   start_set =>	$sunrise, end_set => $sunset );
	 print $day_set->contains( $dt ) ? 'day' : 'night';

	 my $dt	= DateTime->new( year	=> 2000,
			  month	 => 6,
			  day	 => 20,
			  time_zone => 'America/Los_Angeles',
			   );

	 my $sunrise = DateTime::Event::Sunrise	->new(
			      longitude	=>'-118' ,
			      latitude	=> '33',
			      altitude	=> '-0.833',
			      precise	=> '1'

	 );

	 my $tmp = $sunrise->sunrise_sunset_span($dt);
	 print "Sunrise	is:" , $tmp->start->datetime , "\n";
	 print "Sunset is:" , $tmp->end->datetime;

NOTES
   Longitude Signs
       Remember, contrary to the usual convention,

       EASTERN longitudes are POSITIVE,

       WESTERN longitudes are NEGATIVE.

       On the other hand, the latitude signs follow the	usual convention:

       Northen latitudes are positive,

       Southern	latitudes are negative.

   Sun Height
       There are a number of sun heights to choose from. The default is	-0.833
       because this is what most countries use.	Feel free to specify it	if you
       need to.	Here is	the list of values to specify the sun height with:

       o   0 degrees

	   Center of Sun's disk	touches	a mathematical horizon

       o   -0.25 degrees

	   Sun's upper limb touches a mathematical horizon

       o   -0.583 degrees

	   Center of Sun's disk	touches	the horizon; atmospheric refraction
	   accounted for

       o   -0.833 degrees

	   Sun's supper	limb touches the horizon; atmospheric refraction
	   accounted for

       o   -6 degrees

	   Civil twilight (one can no longer read outside without artificial
	   illumination)

       o   -12 degrees

	   Nautical twilight (navigation using a sea horizon no	longer
	   possible)

       o   -15 degrees

	   Amateur astronomical	twilight (the sky is dark enough for most
	   astronomical	observations)

       o   -18 degrees

	   Astronomical	twilight (the sky is completely	dark)

   Notes on the	Precise	Algorithm
       The original method only	gives an approximate value of the Sun's
       rise/set	times.	The error rarely exceeds one or	two minutes, but at
       high latitudes, when the	Midnight Sun soon will start or	just has
       ended, the errors may be	much larger. If	you want higher	accuracy, you
       must then select	the precise variant of the algorithm. This feature is
       new as of version 0.7. Here is what I (module creator) have tried to
       accomplish with this.

       a)  Compute sunrise or sunset as	always,	with one exception: to convert
	   LHA from degrees to hours, divide by	15.04107 instead of 15.0 (this
	   accounts for	the difference between the solar day and the sidereal
	   day.

       b)  Re-do the computation but compute the Sun's RA and Decl, and	also
	   GMST0, for the moment of sunrise or sunset last computed.

       c)  Iterate b) until the	computed sunrise or sunset no longer changes
	   significantly.  Usually 2 iterations	are enough, in rare cases 3 or
	   4 iterations	may be needed.

       However,	I (second module maintainer) have checked with a few external
       sources,	to obtain test data. And actually, using the value 15.0	gives
       results closer to what Stellarium  and the NOAA solar calculator	give.
       So I will use value 15.0, unless	I find a bug in	the precise algorithm
       as presently implemented.

   Notes on polar locations
       If the location is beyond either	polar circle, and if the date is near
       either solstice,	 there can be  midnight	sun  or	polar night.  In this
       case, there  is neither	sunrise	nor sunset,  and the  module "carp"s
       that the	sun never  rises or never sets.	Then, it  returns the time at
       which the sun is	at its highest or lowest point.

       When computing twilights	instead	of  sunrises / sunsets,	the limit for
       polar locations extends a little	beyond the polar circle. For example,
       for  nautical twilights	(12 degrees  below the	horizon), the  limits
       where midnight sun might	happen is  12 degrees southward	of the Arctic
       Circle  and 12  degrees northward  of the  Antarctic Circle,  that is,
       about 54A<degree> latitude instead of 66A<degree>33a^2.

DEPENDENCIES
       This module requires:

       o   DateTime

       o   DateTime::Set

       o   DateTime::Span

       o   Params::Validate

       o   Set::Infinite

       o   POSIX

       o   Math::Trig

BUGS AND CAVEATS
       Using a latitude	of 90 degrees (North Pole or South Pole) gives curious
       results.	 I guess that it is linked with	a ambiguous value resulting
       from a 0/0 computation.

       Using a longitude of 177	degrees, or any	longitude near the 180
       meridian, may also give curious results,	especially with	the precise
       algorithm.

       The precise algorithm should be thoroughly analysed, to understand why
       the value 15.04107 advised by Paul Schlyter does	not give the expected
       results.

       The precise algorithm is	not tested with	polar locations. At least, it
       is tested with a	near-polar location,  Fairbanks, at the	time when the
       night is	at its shortest, that is, in June.

AUTHORS
       Original	author:	Ron Hill <rkhill@firstlight.net>

       Co-maintainer: Jean Forget <JFORGET@cpan.org>

SPECIAL	THANKS
       Robert Creager [Astro-Sunrise@LogicalChaos.org]
	   for providing help with converting Paul's C code to perl.

       FlA!vio S. Glock	[fglock@pucrs.br]
	   for providing the the interface to the DateTime::Set	module.

       Eric Jensen
	   for	positive and  interesting advices  about the  new version  of
	   the module

CREDITS
       Paul Schlyter, Stockholm, Sweden
	   for his excellent web page on the subject.

       Rich Bowen (rbowen@rbowen.com)
	   for suggestions.

       People at <https://geocoder.opencagedata.com/>
	   for noticing	an endless loop	condition in Astro::Sunrise and	for
	   fixing it.

COPYRIGHT and LICENSE
   Perl	Module
       This program is distributed under the same terms	as Perl	5.16.3:	GNU
       Public License version 1	or later and Perl Artistic License

       You can find the	text of	the licenses in	the LICENSE file or at
       <https://dev.perl.org/licenses/artistic.html> and
       <https://www.gnu.org/licenses/gpl-1.0.html>.

       Here is the summary of GPL:

       This program is free software; you can redistribute it and/or modify it
       under the terms of the GNU General Public License as published by the
       Free Software Foundation; either	version	1, or (at your option) any
       later version.

       This program is distributed in the hope that it will be useful, but
       WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A	PARTICULAR PURPOSE.  See the GNU
       General Public License for more details.

       You should have received	a copy of the GNU General Public License along
       with this program; if not, write	to the Free Software Foundation, Inc.,
       <https://www.fsf.org/>.

   Original C program
       Here is the copyright information provided by Paul Schlyter for the
       original	C program:

       Written as DAYLEN.C, 1989-08-16

       Modified	to SUNRISET.C, 1992-12-01

       (c) Paul	Schlyter, 1989,	1992

       Released	to the public domain by	Paul Schlyter, December	1992

       Permission is hereby granted, free of charge, to	any person obtaining a
       copy of this software and associated documentation files	(the
       "Software"), to deal in the Software without restriction, including
       without limitation the rights to	use, copy, modify, merge, publish,
       distribute, sublicense, and/or sell copies of the Software, and to
       permit persons to whom the Software is furnished	to do so, subject to
       the following conditions:

       The above copyright notice and this permission notice shall be included
       in all copies or	substantial portions of	the Software.

       THE SOFTWARE IS PROVIDED	"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
       OR IMPLIED, INCLUDING BUT NOT LIMITED TO	THE WARRANTIES OF
       MERCHANTABILITY,	FITNESS	FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
       IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES OR	OTHER
       LIABILITY, WHETHER IN AN	ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
       FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
       DEALINGS	IN THE SOFTWARE.

SEE ALSO
       perl(1).

       DateTime	Web page at <http://datetime.perl.org/>

       DateTime::Set

       DateTime::SpanSet

       Astro::Sunrise

       DateTime::Event::Jewish::Sunrise

       Astro::Coords

       Astro::PAL

       Paul Schlyter's homepage	at <https://stjarnhimlen.se/english.html>

       The NOAA	solar calculator at
       <https://www.esrl.noaa.gov/gmd/grad/solcalc/>

perl v5.32.1			  2020-07-09	   DateTime::Event::Sunrise(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS | EXTENDED EXAMPLES | NOTES | DEPENDENCIES | BUGS AND CAVEATS | AUTHORS | SPECIAL THANKS | CREDITS | COPYRIGHT and LICENSE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=DateTime::Event::Sunrise&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help