view release on metacpan or  search on metacpan

lib/Date/JD.pm  view on Meta::CPAN

=head1 NAME

Date::JD - conversion between flavours of Julian Date

=head1 SYNOPSIS

    use Date::JD qw(jd_to_mjd mjd_to_cjdnf cjdn_to_rd);

    $mjd = jd_to_mjd($jd);
    ($cjdn, $cjdf) = mjd_to_cjdnf($mjd, $tz);
    $rd = cjdn_to_rd($cjdn, $cjdf);

    # and 509 other conversion functions

=head1 DESCRIPTION

For date and time calculations it is convenient to represent dates by
a simple linear count of days, rather than in a particular calendar.
This is such a good idea that it has been invented several times.
If there were a single such linear count then it would be the obvious
data interchange format between calendar modules.  With several
versions, calendar modules can use such sensible data formats and still
have interoperability problems.  This module tackles that problem,
by performing conversions between different flavours of day count.
These day count systems are generically known as "Julian Dates", after
the most venerable of them.

Among Julian Date systems there are also some non-trivial differences
of concept.  There are systems that count only complete days, and
those that count fractional days also.  There are some that are fixed
to Universal Time (time on the prime meridian), and others that are
interpreted according to a timezone.  Some consider the day to start at
noon and others at midnight, which is semantically significant for the
complete-day counts.  The functions of this module appropriately handle
the semantics of all the non-trivial conversions.

The day count systems supported by this module are Julian Date, Reduced
Julian Date, Modified Julian Date, Dublin Julian Date, Truncated Julian
Date, Chronological Julian Date, Rata Die, and Lilian Date, each in both
integral and fractional forms.

=head2 Flavours of day count

In the interests of orthogonality, all flavours of day count come in both
integral and fractional varieties.  Generally, there is a quantity named
"XYZD" ("XYZ Date") which is a real count of days since a particular epoch
(an integer plus a fraction) and a corresponding quantity named "XYZDN"
("XYZ Day Number") which is a count of complete days since the same epoch.
XYZDN is the integral part of XYZD.  There is also a quantity named
"XYZDF" ("XYZ Day Fraction") which is a count of fractional days since
the XYZDN changed (whether that is noon or midnight).  XYZDF is the
fractional part of XYZD, in the range [0, 1).

This quantity naming pattern is derived from JD (Julian Date) and JDN
(Julian Day Number) which have the described correspondence.  Most of
the other flavours of day count listed below conventionally come in only
one of the two varieties.  The "XYZDF" name type is a neologism.

All calendar dates given are in ISO 8601 form (Gregorian calendar with
astronomical year numbering).  An hour number is appended to each date,
separated by a "T"; hour 00 is midnight at the start of the day and hour
12 is noon in the middle of the day.  An appended "Z" indicates that the
date is to be interpreted in Universal Time (the timezone of the prime
meridian), and so is absolute; where any other timezone is to be used
then this is explicitly noted.

=over

=item JD (Julian Date)

days elapsed since -4713-11-24T12Z.  This epoch is the most recent
coincidence of the first year of the Metonic cycle, indiction cycle, and
day-of-week cycle, using the Julian calendar.  It was correspondingly
named after the Julian calendar, and thus after Julius Caesar.  Some
information can be found at L<http://en.wikipedia.org/wiki/Julian_day>.

=item RJD (Reduced Julian Date)

days elapsed since 1858-11-16T12Z (JD 2400000.0).  Rarely used.

=item MJD (Modified Julian Date)

days elapsed since 1858-11-17T00Z (JD 2400000.5).  This was introduced by
the Smithsonian Astrophysical Observatory in 1957, and is recommended for
general use by the International Astronomical Union and other authorities.

=item DJD (Dublin Julian Date)

days elapsed since 1899-12-31T12Z (JD 2415020.0).  This was invented by
the International Astronomical Union, and the epoch in Terrestrial Time
is the J1900.0 epoch used in astronomy.  (Note: not B1900.0, which is
a few hours later.)  It is rarely used.

=item TJD (Truncated Julian Date)

days elapsed since 1968-05-24T00Z (JD 2440000.5).  This is primarily
used by NASA, who devised it during the Apollo era.  There is a
rumour that it's defined cyclically, as (JD - 0.5) mod 10000, but see
L<http://cossc.gsfc.nasa.gov/cossc/batse/hilev/TJD.TABLE>.

=item CJD (Chronological Julian Date)

days elapsed since -4713-11-24T00 in the timezone of interest.
CJD = JD + 0.5 + Zoff, where Zoff is the timezone offset in
fractional days.  This was devised by Peter Meyer, and described in
L<http://www.hermetic.ch/cal_stud/cjd.htm>.

=item RD (Rata Die)

days elapsed since 0000-12-31T00 in the timezone of interest (CJD
1721425.0).  This is defined in the book Calendrical Calculations.
Confusingly, in the book the integral form is also called "RD".
The integral form is called "RDN" by this module to avoid confusion,
reserving the name "RD" for the fractional form.  (The book is best
treated with caution due to the embarrassingly large number of errors
and instances of muddled thinking.)

=item LD (Lilian Date)

days elapsed since 1582-10-14T00 in the timezone of interest (CJD
2299160.0).  This epoch is the day before the day that the Gregorian
calendar first went into use.  It is named after Aloysius Lilius, the
inventor of the Gregorian calendar.

=back

The interesting differences between these flavours are whether the
day starts at noon or at midnight, and whether they are absolute or
timezone-relative.  Three of the four combinations of these features
exist.  There is no convention for counting days from timezone-relative
noon that the author of this module is aware of.

For more background on these day count systems,
L<http://en.wikipedia.org/wiki/Julian_Date> is a good starting place.

=head2 Meaning of the day

A day count has meaning only in the context of a particular definition
of "day".  There are two main flavours of day to consider: solar and
conventional.

A solar day is based on the apparent motion of Sol in the Terran sky (and
thus on the rotation and orbit of Terra).  The rotation of Terra is not
constant in time, so this type of day is really a measure of angle, not
of time.  This is how days have been counted since antiquity, and is still
(as of 2006) the basis of civil time.  There are two subtypes of solar
day: apparent and mean.  The apparent solar day is based on the actual
observable position of Sol in the sky from day to day, whereas the mean
solar day smooths this motion out, in time, over the course of the year.
At the sub-second level there are different types of smoothing that can
be used (UT1, UT2, et al).

A conventional day is any type of day that is not based on Terran
rotation.  The astronomical Ephemeris Time, a time scale based on the
motion of bodies in the Solar system, has a time unit that it calls
"day" which is derived from astronomical observations.  The modern
relativistic coordinate time scales such as TT have a notional "day"
of exactly 86400 SI seconds.  The atomic time scale TAI also has a "day"
which is as close to 86400 SI seconds as can be achieved.  All of these
"days" are roughly the duration of one Sol-relative rotation of Terra
during the early nineteenth century, but are not otherwise related to
planetary rotation.

Each of the day count scales handled by this module can be used with any
of these types of day.  For a day number to be meaningful it is necessary
to be aware of which kind of day it is counting.  Conversion between the
different types of day is out of scope for this module.  (See L<Time::UTC>
for TAI/UTC conversion.)

=cut

package Date::JD;

{ use 5.006; }
use warnings;
use strict;

use Carp qw(croak);

our $VERSION = "0.006";

use parent "Exporter";
our @EXPORT_OK;