/ 
Astro-Montenbruck-1.20
River stage zero No dependents
/ Astro::Montenbruck::RiseSet

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 bellow

# 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.

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.

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.