++ed by:
1 non-PAUSE user
Author image Sergey Krushinsky
and 1 contributors

NAME

Astro::Montenbruck::RiseSet - rise, set, transit.

SYNOPSIS

    use Astro::Montenbruck::Ephemeris::Planet qw/:ids/;
    use Astro::Montenbruck::MathUtils qw/frac/;
    use Astro::Montenbruck::RiseSet::Constants qw/:all/;
    use Astro::Montenbruck::RiseSet qw/:all/;

    # create function for calculating rise/set/transit events for Munich, Germany, on March 23, 1989.
    my $func = rst(
        date   => [1989, 3, 23],
        phi    => 48.1,
        lambda => -11.6
    );

    # calculate Moon rise, set and transit
    $func->(
        $MO,
        on_event   => sub {
            my ($evt, $jd) = @_;
            say "$evt: $jd";
        },
        on_noevent => sub {
            my ($evt, $state) = @_; # $STATE_CIRCUMPOLAR or $STATE_NEVER_RISES
            say "$evt: $state";
        }        
    );

    # alternatively, call the function in list context:
    my %res = $func->($MO); # result structure is described below

    # calculate civil twilight    
    twilight(
        date       => [1989, 3, 23],
        phi        => 48.1,
        lambda     => -11.6,
        on_event   => sub {
            my ($evt, $jd) = @_;
            say "$evt: $jd";
        },
        on_noevent => sub {
            my $state = shift;
            say $state;
        }
    );

VERSION

Version 0.02

DESCRIPTION

High level interface for calculating rise, set and transit times of celestial bodies, as well as twilight of different types.

There are two low-level functions for calculating the events, based on based on different algorithms:

  1. Astro::Montenbruck::RiseSet::Plarise::rst, which calculates rise, set and transit times using iterative method.

  2. Astro::Montenbruck::RiseSet::Sunset::riseset_func, which calculates rise and set times using quadratic interpolation.

Both of them are described in "Astronomy On The Personal Computer" by O.Montenbruck and T.Phleger. However, they are built on different algorithms: riseset_func utilizes quadratic interpolation while rst is iterative. Along with rise and set, rst gives transit times. At the other hand, riseset_func is a base for calculating twilight.

To take into account parallax, refraction and apparent radius of the bodies, we use average corrections to geometric altitudes:

  • sunrise, sunset : -0 deg 50 min

  • moonrise, moonset : 0 deg 8 min

  • stars and planets : -0 deg 34 min

TWILIGHT

The library also calculates the times of the beginning of the morning twilight (dawn) and end of the evening twilight (dusk).

Twilight occurs when Earth's upper atmosphere scatters and reflects sunlight which illuminates the lower atmosphere. Astronomers define the three stages of twilight – civil, nautical, and astronomical – on the basis of the Sun's elevation which is the angle that the geometric center of the Sun makes with the horizon.

  • astronomical

    Sun altitude is -18 deg In the morning, the sky is completely dark before the onset of astronomical twilight, and in the evening, the sky becomes completely dark at the end of astronomical twilight. Any celestial bodies that can be viewed by the naked eye can be observed in the sky after the end of this phase.

  • nautical

    Sun altitude is -12 deg. This twilight period is less bright than civil twilight and artificial light is generally required for outdoor activities.

  • civil

    Sun altitude is -6 deg. Civil twilight is the brightest form of twilight. There is enough natural sunlight during this period that artificial light may not be required to carry out outdoor activities. Only the brightest celestial objects can be observed by the naked eye during this time.

CAVEATS

Sometimes rise and set happen on different calendar dates. For example, here is the output of riseset.pl script:

  $ perl .\script\riseset.pl --date=1989-03-28 --place=48.1 -11.6 --timezone=UTC

  Date      :  1989-03-28 UTC
  Place     :  48N06, 011E35
  Time Zone :  UTC

          rise       transit    set     
  Moon    23:34:17   03:23:59   07:10:54

This directly depends on time zone. Since event time is always given as Julian date, it is not hard to determine correct order of events.

EXPORT

FUNCTIONS

FUNCTIONS

rst( %args )

Returns function for calculating times of rises, sets and transits of celestial bodies. See "rst" in Astro::Montenbruck::RiseSet::Plarise .

Named Arguments

  • date - array of year (astronomical, zero-based), month [1..12] and day, [1..31].

  • phi - geographical latitude, degrees, positive northward

  • lambda - geographical longitude, degrees, positive westward

Returns

function, which calculates rise, set and transit for a celestial body. It accepts celestial body identifier as positional argument (see Astro::Montenbruck::Ephemeris::Planet) and two optional callbacks as named arguments:

  • on_event($event, $jd - callback called when the event time is determined. The first argument is one of: $EVT_RISE, $EVT_SET or $EVT_TRANSIT constants (see Astro::Montenbruck::RiseSet::Constants), the second - Standard Julian Date.

  • on_noevent($event, $state - callback called when the body is circumpolar or never rises. The first argument is then one of: $EVT_RISE, $EVT_SET or $EVT_TRANSIT, the second - either $STATE_CIRCUMPOLAR or $STATE_NEVER_RISES.

List context

When called in list context:

  my %res = func();

the function returns a hash:

  (
      rise    => $hashref,
      set     => $hashref,
      transit => $hashref  
  )
  

When rise or set takes place, $hashref contains:

  {ok => 1, jd => JD} 

JD is a Standard Julian Date. Otherwise,

  {ok => 0, state => STATE}

STATE is $STATE_CIRCUMPOLAR or $STATE_NEVER_RISES.

riseset( %args )

Returns function for calculating times of rises and sets of given celestial body. See "riseset_func" in Astro::Montenbruck::RiseSet::Sunset.

Named Arguments

  • planet - celestial body identifier (see Astro::Montenbruck::Ephemeris::Planet)

  • date - array of year (astronomical, zero-based), month [1..12] and day, [1..31].

  • phi - geographical latitude, degrees, positive northward

  • lambda - geographical longitude, degrees, positive westward

Returns

function, which calculates rise and set times of the planet. It accepts and two callbacks as named arguments:

  • on_event($event, $jd) callback called when the event time is determined. The first argument is one of: $EVT_RISE, $EVT_SET or $EVT_TRANSIT constants (see Astro::Montenbruck::RiseSet::Constants), the second - Standard Julian Date.

  • on_noevent($state callback called when the body is circumpolar or never rises. The argument is either $STATE_CIRCUMPOLAR or $STATE_NEVER_RISES.

When called in list context, returns a hash, described in "List context" in rst( %args ), except that transit key is missing.

twilight( %args )

Function for calculating twilight. See "TWILIGHT EVENT FUNCTION" below.

Named Arguments

  • type - type of twilight, $TWILIGHT_NAUTICAL, $TWILIGHT_ASTRO or $TWILIGHT_CIVIL, see "TYPES OF TWILIGHT" in Astro::Montenbruck::RiseSet::Constants.

  • date - array of year (astronomical, zero-based), month [1..12] and day, [1..31].

  • phi - geographical latitude, degrees, positive northward

  • lambda - geographical longitude, degrees, positive westward

  • on_event - callback called when the event time is determined. The arguments are:

  • on_noevent is called when the event never happens, either because the body never rises, or is circumpolar. The argument is respectively $STATE_NEVER_RISES or $STATE_CIRCUMPOLAR, see "STATES" in Astro::Montenbruck::RiseSet::Constants.

AUTHOR

Sergey Krushinsky, <krushi at cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2010-2021 by Sergey Krushinsky

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.