package Astro::Montenbruck::Time;

use warnings;
use strict;

our $VERSION = 0.01;

use Exporter qw/import/;

our $SEC_PER_DAY = 86400;        # Seconds per day
our $SEC_PER_CEN = 3155760000;
our $J2000       = 2451545;      # Standard Julian Date for 1.1.2000 12:00
our $J1900       = 2415020
  ;    # Standard Julian Date for  31.12.1899 12:00 (astronomical epoch 1900.0)
our $SOLAR_TO_SIDEREAL = 1.002737909350795
  ;    # Difference in between Sidereal and Solar hour (the former is shorter)
our $GREGORIAN_START = 15821004;    # Start of Gregorian calendar (YYYYMMDD)
our $JD_UNIX_EPOCH = _gmtime2jd( gmtime(0) )
  ; # Standard Julian date for the beginning of Unix epoch, Jan 1 1970 on most Unix systems

our %EXPORT_TAGS = (
    all => [
        qw/jd_cent after_gregorian cal2jd jd2cal jd0 unix2jd jd2mjd mjd2jd
          jd2unix jdnow t1900 jd2gst jd2lst
          is_leapyear day_of_year
          $SEC_PER_DAY $SEC_PER_CEN $J2000 $J1900 $GREGORIAN_START $JD_UNIX_EPOCH/
    ],
);

our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );

use POSIX;
use Astro::Montenbruck::MathUtils qw/polynome ddd frac to_range/;

sub after_gregorian {
    my $y   = shift;
    my $m   = shift;
    my $d   = shift;
    my %arg = ( gregorian_start => $GREGORIAN_START, @_ );
    return 0 unless defined $arg{gregorian_start};
    polynome( 100, $d, $m, $y ) >= $arg{gregorian_start};
}

sub cal2jd {
    my $ye  = shift;
    my $mo  = shift;
    my $da  = shift;
    my %arg = ( gregorian_start => $GREGORIAN_START, @_ );

    my $j = $da + 1720996.5;
    my ( $m, $y ) = ( $mo > 2 ) ? ( $mo, $ye ) : ( $mo + 12, $ye - 1 );
    if ( after_gregorian( $ye, $mo, $da, %arg ) ) {
        $j += int( $y / 400 ) - int( $y / 100 ) + int( $y / 4 );
    }
    else {
        $j += int( ( $y + 4716 ) / 4 ) - 1181;
    }
    $j + 365 * $y + floor( 30.6001 * ( $m + 1 ) );
}

sub jd2cal {
    my $jd = shift;
    my %arg = ( gregorian => 1, @_ );

    my ( $f, $i ) = modf( $jd - $J1900 + 0.5 );
    if ( $arg{gregorian} && $i > -115860 ) {
        my $a = floor( $i / 36524.25 + 9.9835726e-1 ) + 14;
        $i += 1 + $a - floor( $a / 4 );
    }

    my $b  = floor( $i / 365.25 + 8.02601e-1 );
    my $c  = $i - floor( 365.25 * $b + 7.50001e-1 ) + 416;
    my $g  = floor( $c / 30.6001 );
    my $da = $c - floor( 30.6001 * $g ) + $f;
    my $mo = $g - ( $g > 13.5 ? 13 : 1 );
    my $ye = $b + ( $mo < 2.5 ? 1900 : 1899 );
    $ye, $mo, $da;
}

sub jd0 {
    my $j = shift;
    floor( $j - 0.5 ) + 0.5;
}

sub unix2jd {
    $JD_UNIX_EPOCH + $_[0] / $SEC_PER_DAY;
}

sub jd2unix {
    int( ( $_[0] - $JD_UNIX_EPOCH ) * $SEC_PER_DAY );
}

sub _gmtime2jd {
    cal2jd( $_[5] + 1900, $_[4] + 1, $_[3] + ddd( @_[ 2, 1, 0 ] ) / 24 );
}

sub jdnow {
    _gmtime2jd( gmtime() );
}

sub jd2mjd {
    $_[0] - $J2000;
}

sub mjd2jd {
    $_[0] + $J2000;
}

# converts Julian date to period in centuries since epoch
# Arguments:
# julian date
# julian date corresponding to the epoch start
sub _t {
    my ( $jd, $epoch ) = @_;
    ( $jd - $epoch ) / 36525;
}

sub jd_cent {
    _t( $_[0], $J2000 );
}

sub t1900 {
    _t( $_[0], $J1900 );
}

sub jd2gst {
    my $jh = shift;
    my $j0 = jd0($jh);
    my $s0 = polynome( t1900($j0), 0.276919398, 100.0021359, 0.000001075 );
    24 * ( frac($s0) + abs( $jh - $j0 ) * $SOLAR_TO_SIDEREAL );
}

sub jd2lst {
    my ( $jd, $lon ) = @_;
    $lon //= 0;
    to_range( jd2gst($jd) - $lon / 15, 24 );
}

sub is_leapyear {
    my $yr = shift;
    my %arg = ( gregorian => 1, @_ );
    $yr = int($yr);
    return $arg{gregorian}
      ? ( $yr % 4 == 0 ) && ( ( $yr % 100 != 0 ) || ( $yr % 400 == 0 ) )
      : $yr % 4 == 0;
}

sub day_of_year {
    my $yr = shift;
    my $mo = shift;
    my $dy = shift;

    my $k = is_leapyear($yr, @_) ? 1 : 2;
    $dy = int($dy);
    int(275 * $mo / 9.0) - ($k * int(($mo + 9) / 12.0)) + $dy - 30
}

1;

__END__



head


Astro::Montenbruck::Time - Time-related routines




    use Astro::Montenbruck::Time qw/:all/;

    # Convert Gregorian (new-style) date to old-style date
    my $j = cal2jd(1799, 6, 6); # Standard Julian date of A.Pushkin's birthday
    my $d = jd2cal($j, gregorian => 0) # (1799, 5, 25) = May 26, 1799.

    # Julian date in centuries since epoch 2000.0
    my $t = jd_cent($j); # -2.0056810403833
    ...




Library of date/time manipulation routines for practical astronomy. Most of them
are based on so called I<Julian date (JD)>, which is the number of days elapsed
since mean UT noon of B<January 1st 4713 BC>. This system of time measurement is
widely adopted by the astronomers.




Many routines use Modified Julian date, which starts at B<2000 January 0>
(2000 January 1.0) as the starting point.




There is disagreement between astronomers and historians about how to count the
years preceding the year 1. Astronomers generally use zero-based system. The
year before the year +1, is the year zero, and the year preceding the latter is
the year -1. The year which the historians call 585 B.C. is actually the year
-584.

In this module all subroutines accepting year assume that B<there is year zero>.
Thus, the sequence of years is: C<BC -3, -2, -1, 0, 1, 2, 3, AD>.




Time is represented by fractional part of a day. For example, 7h30m UT
is C<(7 + 30 / 60) / 24 = 0.3125>.




I<Civil calendar> in most cases means I<proleptic Gregorian calendar>. it is
assumed that Gregorian calendar started at Oct. 4, 1582, when it was first
adopted in several European countries. Many other countries still used the older
Julian calendar. In Soviet Russia, for instance, Gregorian system was accepted
on Jan 26, 1918. See:
L<https://en.wikipedia.org/wiki/Gregorian_calendar#Adoption_of_the_Gregorian_Calendar>




* C<$SEC_PER_DAY> seconds per day (86400)


item

* C<$SEC_PER_CEN> seconds per century (3155760000)


* C<$J2000> Standard Julian date for start of epoch 2000,0 (2451545)


* C<$J1900> Standard Julian date for start of epoch 1900,0 (2415020)


* C<$GREGORIAN_START> Start of Gregorian calendar, YYYYMMDD (15821004)


* C<$JD_UNIX_EPOCH> Standard Julian date for start of the Unix epoch


* L</after_gregorian($year, $month, $date)>



Convert Standard Julian Date to centuries passed since epoch 2000.0



after_gregorian($year, $month, $date, gregorian_start => $YYYYMMDD )



Does the given date fall to period after Gregorian calendar?



* B<date> UTC date (1-31) with hours and minutes as decimal part



B<gregorian_start> — start of Gregorian calendar. Default value is
B<15821004> If the date is Julian ("old style"), use C<undef> value.
To provide non-standard start of Gregorian calendar, provide a number
in format YYYYMMDDD, e.g. C<19180126> for Jan 26, 1918.

=back




Convert civil date/time to Standard Julian date.

If C<gregorian_start> argument is not provided, it is assumed that this is a date
of I<Proleptic Gregorian calendar>, which started at Oct. 4, 1582.



root

TimeUtils

Other

React

=begin React :component<HeaderCol> :id<menu> 
=para L<Documentation|/doc/introduction>
=para L<Modules| /mods>
=para L<Examples| file:../examples/index.podlite>
=para L<Download |file:../download/index.podlite>
=para L<About|file:../about/index.podlite>
=para 🔍 K<⌘K>/K<ctrl-K>
=end React


=begin React :component<HeaderCol> :id<footer>  
=begin nested :!nested
=item1 B<Language>
    =item2 L<Get started|file:../getting-started/getting-started.podlite>
    =item2 L<Why Raku?|/doc/language/faq#Why-should-I-learn-Raku-What's-so-great-about-it>
    =item2 L<Try Raku|https://glot.io/new/raku>
    =item2 L<Raku cheat sheet|https://github.com/Raku/mu/blob/master/docs/Perl6/Cheatsheet/cheatsheet.txt>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<Raku on Exercism|https://exercism.org/tracks/raku>
    =item2 L<Wikipedia|https://en.wikipedia.org/wiki/Raku_(programming_language)>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=begin nested :!nested

=item1 B<L<Documentation|/doc>>
    =item2 L<Getting started, Migration guides from other languages, & Tutorials | file:../doc/introduction.podlite>
    =item2 L<Language References|file:../doc/reference.podlite>
    =item2 L<Type Reference| file:../doc/types.podlite>
    =item2 L<Miscellaneous| file:../doc/miscellaneous.podlite>
    =item2 L<FAQs (Frequently Asked Questions)|/doc/language/faq>
    =item2 L<Community|/doc/language/community>
    =item2 L<The list of all documents|file:../doc/index.podlite>

=item1 B<Resources>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>

=end nested
=begin nested :!nested

=item1 B<Resoures>
    =item2 L<Download | file:../download/index.podlite>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=item1 B<Learning>
    =item2 L<The Raku Guide|https://raku.guide/>
    =item2 L<Wikibook |https://en.wikibooks.org/wiki/Raku_Programming>
    =item2 L<Books |https://perl6book.com/>
    =item2 L<Rosetta Code | https://www.raku.org/community/rosettacode>
    =item2 L<Learn Raku in Y minutes|https://learnxinyminutes.com/docs/raku/>
    =item2 L<Golfing |https://github.com/AlexDaniel/raku-golf-cheatsheet>
=end nested
=begin nested :!nested

=item1 B<Explore>
    =item2 L<Raku Blog Aggregator|https://planet.raku.org/>
    =item2 L<Rakudo Weekly|https://rakudoweekly.blog/>
    =item2 L<The Weekly Challenge |https://perlweeklychallenge.org/>
    =item2 L<Raku Advent Calendar|https://raku-advent.blog/>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>
    =item2 L<empty|#>

=end nested
=end React


=begin React :component<CookieConsent> :id<CookieConsent> :buttonCaption("Got it!")
=para
This website uses cookies for analytics.
=end React


NAME

VERSION

SYNOPSIS

DESCRIPTION

JD and MJD

Civil year vs astronomical year

Date and Time

Gregorian calendar

EXPORTED CONSTANTS

EXPORTED FUNCTIONS

FUNCTIONS

jd_cent($jd)

after_gregorian($year, $month, $date, gregorian_start => $YYYYMMDD )

Positional Arguments

Optional Named Arguments

Returns

cal2jd($year, $month, $date)

Positional Arguments:

Optional Named Arguments

Returns

jd2cal($jd)

Positional Arguments

Optional Named Arguments

Returns

jd0($jd)

unix2jd($seconds)

jd2unix($jd)

jdnow()

jd2mjd($jd)

mjd2jd($mjd)

jd_cent($jd)

t1900($jd)

jd2gst($jd)

jd2lst($jd, $lng)

Arguments

AUTHOR

LICENSE AND COPYRIGHT

DateTime::Julian v1.1.0

Authors

License

Dependencies

Test Dependencies

Provides

Documentation