view release on metacpan or  search on metacpan

lib/Astro/Sunrise.pm  view on Meta::CPAN

the module is to emit a warning in these cases ("Sun never rises!!"
or "Sun never sets!!"). But some programmers may find this inconvenient.
An alternate behaviour is to return special values reflecting the
situation.

So, if the C<polar> parameter is set to C<'warn'>, the module emits
a warning. If the C<polar> parameter is set to C<'retval'>, the
module emits no warning, but it returns either C<'day'> or C<'night'>.

Example:

  # Loosely based on Alex Gough's activities: scientist and Perl programmer, who spent a year
  # in Halley Base in 2006. Let us suppose he arrived there on 15th January 2006.
  my ($sunrise, $sunset) = sunrise( { year => 2006, month => 1, day => 15,
                                      lon => -26.65, lat => -75.58, # Halley Base: 75°35'S 26°39'W
                                      tz  => 3, polar => 'retval' } );
  if ($sunrise eq 'day') {
    say "Alex Gough saw the midnight sun the first day he arrived at Halley Base";
  }
  elsif ($sunrise eq 'night') {
    say "It would be days, maybe weeks, before the sun would rise.";
  }
  else {
    say "Alex saw his first antarctic sunset at $sunset";
  }

This parameter is optional and it can be specified only by keyword.

=item 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
F<doc/astronomical-notes.pod> to understand what the traced values
represent.

This parameter is optional and it can be specified only by keyword.

=item precise

Choice between a precise algorithm and a simpler algorithm.
The default value is 0, that is, the simpler algorithm.
Any true value switches to 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 use the precise algorithm. This feature is new as of version 0.7. Here is
what I 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.

This parameter is optional. It can be positional (#9).

=back

=head3 I<For Example>

 ($sunrise, $sunset) = sunrise( 2001, 3, 10, 17.384, 98.625, -5, 0 );
 ($sunrise, $sunset) = sunrise( 2002, 10, 14, -105.181, 41.324, -7, 1, -18);
 ($sunrise, $sunset) = sunrise( 2002, 10, 14, -105.181, 41.324, -7, 1, -18, 1);

=head2 B<sun_rise>, B<sun_set>

  $sun_rise = sun_rise( { lon => $longitude, lat => $latitude,
                          alt => $altitude, upper_limb => $bool,
                          offset  => $day_offset,
                          precise => $bool_precise, polar => $action } );
  $sun_set  = sun_set ( { lon => $longitude, lat => $latitude,
                          alt => $altitude, upper_limb => $bool,
                          offset  => $day_offset,
                          precise => $bool_precise, polar => $action } );
  $sun_rise = sun_rise( $longitude, $latitude );
  $sun_rise = sun_rise( $longitude, $latitude, $alt );
  $sun_rise = sun_rise( $longitude, $latitude, $alt, $day_offset );

Returns the sun rise time (resp. the sun set time) for the given location
and for today's date (as given by DateTime), plus or minus some offset in days.
The first form use all parameters and transmit them by name. The second form
uses today's date (from DateTime) and the default altitude.  The third
form adds specifying a custom altitude.  The fourth form allows for specifying
an integer day offset from today, either positive or negative.

The parameters are the same as the parameters for C<sunrise>. There is an additional
parameter, C<offset>, which allows using a date other than today: C<+1> for
to-morrow, C<-7> for one week ago, etc.

The arguments are:

=over 4

=item lon, lat

The longitude and latitude of the place for which you want to compute the sunrise and sunset.
They are given in decimal degrees. For example:

    lon => -3.6,  #  3° 36' W
    lat => 37.17, # 37° 10' N

 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

Mandatory, can be positional (#1 and #2).

=item alt

Altitude of the sun, in decimal degrees. Usually a negative number,
because the sun should be I<under> the mathematical horizon.
But if there is a high mountain range sunward (that is, southward if you