.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Sunrise 3pm"
.TH Sunrise 3pm "2010-03-21" "perl v5.10.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DateTime::Astro::Sunrise \- Perl DateTime extension for computing the sunrise/sunset on a given day
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& use DateTime;
\& use DateTime::Astro::Sunrise;
\& 
\& my $dt = DateTime\->new( year   => 2000,
\&                         month  => 6,
\&                         day    => 20,
\&                  );
.Ve
.PP
my \f(CW$sunrise\fR = DateTime::Astro::Sunrise \->new('\-118','33',undef,1);
.PP
my ($tmp_rise, \f(CW$tmp_set\fR) = \f(CW$sunrise\fR\->sunrise($dt);
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module will return a DateTime Object for sunrise and sunset for a given day.
.SH "USAGE"
.IX Header "USAGE"
.ie n .IP "\fBmy \fB$sunrise\fB = DateTime::Astro::Sunrise \-\fRnew(longitutide,latatude,ALT,Iteration);>" 4
.el .IP "\fBmy \f(CB$sunrise\fB = DateTime::Astro::Sunrise \-\fRnew(longitutide,latatude,ALT,Iteration);>" 4
.IX Item "my $sunrise = DateTime::Astro::Sunrise -new(longitutide,latatude,ALT,Iteration);>"
.RS 4
.Vb 4
\& Eastern longitude is entered as a positive number
\& Western longitude is entered as a negative number
\& Northern latitude is entered as a positive number
\& Southern latitude is entered as a negative number
.Ve
.Sp
.RS 4
inter is set to either 0 or 1.
If set to 0 no Iteration will occur.
If set to 1 Iteration will occur.
Default is 0.
.Sp
There are a number of sun altitides to chose 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
altitude (\s-1ALT\s0) with:
.IP "\fB0\fR degrees" 4
.IX Item "0 degrees"
Center of Sun's disk touches a mathematical horizon
.IP "\fB\-0.25\fR degrees" 4
.IX Item "-0.25 degrees"
Sun's upper limb touches a mathematical horizon
.IP "\fB\-0.583\fR degrees" 4
.IX Item "-0.583 degrees"
Center of Sun's disk touches the horizon; atmospheric refraction accounted for
.IP "\fB\-0.833\fR degrees" 4
.IX Item "-0.833 degrees"
Sun's supper limb touches the horizon; atmospheric refraction accounted for
.IP "\fB\-6\fR degrees" 4
.IX Item "-6 degrees"
Civil twilight (one can no longer read outside without artificial illumination)
.IP "\fB\-12\fR degrees" 4
.IX Item "-12 degrees"
Nautical twilight (navigation using a sea horizon no longer possible)
.IP "\fB\-15\fR degrees" 4
.IX Item "-15 degrees"
Amateur astronomical twilight (the sky is dark enough for most astronomical observations)
.IP "\fB\-18\fR degrees" 4
.IX Item "-18 degrees"
Astronomical twilight (the sky is completely dark)
.IP "\fINotes on Iteration\fR" 4
.IX Item "Notes on Iteration"
.RS 4
.RS 4
The orginal 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 use the iteration feature. This feature is new as of version 0.7. Here is
what I have tried to accomplish with this.
.Sp
a) Compute sunrise or sunset as always, with one exception: to convert \s-1LHA\s0 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.
.Sp
b) Re-do the computation but compute the Sun's \s-1RA\s0 and Decl, and also \s-1GMST0\s0, for the moment 
   of sunrise or sunset last computed.
.Sp
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.
.RE
.RE
.RS 4
.RE
.RE
.RS 4
.RE
.RE
.RS 4
.RE
.ie n .SH "($sunrise, $sunset) = $sunrise\->($dt);"
.el .SH "($sunrise, \f(CW$sunset\fP) = \f(CW$sunrise\fP\->($dt);"
.IX Header "($sunrise, $sunset) = $sunrise->($dt);"
Returns two DateTime objects sunrise and sunset.
Please note that the time zone for these objects
is set to \s-1UTC\s0. So don't forget to set your timezone!!
.SH "AUTHOR"
.IX Header "AUTHOR"
Ron Hill
rkhill@firstlight.net
.SH "CREDITS"
.IX Header "CREDITS"
.IP "Paul Schlyer, Stockholm, Sweden" 4
.IX Item "Paul Schlyer, Stockholm, Sweden"
for his excellent web page on the subject.
.IP "Rich Bowen (rbowen@rbowen.com)" 4
.IX Item "Rich Bowen (rbowen@rbowen.com)"
for suggestions
.SH "COPYRIGHT and LICENSE"
.IX Header "COPYRIGHT and LICENSE"
Here is the copyright information provided by Paul Schlyer:
.PP
Written as \s-1DAYLEN\s0.C, 1989\-08\-16
.PP
Modified to \s-1SUNRISET\s0.C, 1992\-12\-01
.PP
(c) Paul Schlyter, 1989, 1992
.PP
Released to the public domain by Paul Schlyter, December 1992
.PP
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the \*(L"Software\*(R"),
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:
.PP
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
.PP
\&\s-1THE\s0 \s-1SOFTWARE\s0 \s-1IS\s0 \s-1PROVIDED\s0 \*(L"\s-1AS\s0 \s-1IS\s0\*(R", \s-1WITHOUT\s0 \s-1WARRANTY\s0 \s-1OF\s0 \s-1ANY\s0 \s-1KIND\s0, \s-1EXPRESS\s0 \s-1OR\s0
\&\s-1IMPLIED\s0, \s-1INCLUDING\s0 \s-1BUT\s0 \s-1NOT\s0 \s-1LIMITED\s0 \s-1TO\s0 \s-1THE\s0 \s-1WARRANTIES\s0 \s-1OF\s0 \s-1MERCHANTABILITY\s0,
\&\s-1FITNESS\s0 \s-1FOR\s0 A \s-1PARTICULAR\s0 \s-1PURPOSE\s0 \s-1AND\s0 \s-1NONINFRINGEMENT\s0. \s-1IN\s0 \s-1NO\s0 \s-1EVENT\s0 \s-1SHALL\s0
\&\s-1THE\s0 \s-1AUTHOR\s0 \s-1BE\s0 \s-1LIABLE\s0 \s-1FOR\s0 \s-1ANY\s0 \s-1CLAIM\s0, \s-1DAMAGES\s0 \s-1OR\s0 \s-1OTHER\s0 \s-1LIABILITY\s0,
\&\s-1WHETHER\s0 \s-1IN\s0 \s-1AN\s0 \s-1ACTION\s0 \s-1OF\s0 \s-1CONTRACT\s0, \s-1TORT\s0 \s-1OR\s0 \s-1OTHERWISE\s0, \s-1ARISING\s0 \s-1FROM\s0, \s-1OUT\s0
\&\s-1OF\s0 \s-1OR\s0 \s-1IN\s0 \s-1CONNECTION\s0 \s-1WITH\s0 \s-1THE\s0 \s-1SOFTWARE\s0 \s-1OR\s0 \s-1THE\s0 \s-1USE\s0 \s-1OR\s0 \s-1OTHER\s0 \s-1DEALINGS\s0 \s-1IN\s0
\&\s-1THE\s0 \s-1SOFTWARE\s0.
.SH "BUGS"
.IX Header "BUGS"
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIperl\fR\|(1).