NAME

Date::MSD - conversion between flavours of Mars Sol Date

SYNOPSIS

use Date::MSD qw(js_to_msd msd_to_cmsdnf cmsdn_to_js);

$msd = js_to_msd($js);
($cmsdn, $cmsdf) = msd_to_cmsdnf($msd, $tz);
$js = cmsdn_to_js($cmsdn, $cmsdf, $tz);

# and 69 other conversion functions

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 module performs conversions between different flavours of linear count of Martian solar days ("sols").

Among Martian day count 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 Airy Mean Time (time on the Martian prime meridian), and others that are interpreted according to a timezone. The functions of this module appropriately handle the semantics of all the non-trivial conversions.

The day count systems supported by this module are Mars Sol Date, Julian Sol, and Chronological Mars Solar Date, each in both integral and fractional forms.

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 "XYZ" which is a real count of days since a particular epoch (an integer plus a fraction) and a corresponding quantity named "XYZN" ("XYZ Number") which is a count of complete days since the same epoch. XYZN is the integral part of XYZ. There is also a quantity named "XYZF" ("XYZ Fraction") which is a count of fractional days since the XYZN changed (at midnight). XYZF is the fractional part of XYZ, in the range [0, 1).

This quantity naming pattern is derived from the naming of Terran day counts, particularly JD (Julian Date) and JDN (Julian Day Number) which have the described correspondence. The "XYZF" name type is a neologism, invented for Date::JD.

All calendar dates given are in the Darian calendar for Mars. An hour number is appended to each date, separated by a "T"; hour 00 is midnight at the start of the day. An appended "Z" indicates that the date is to be interpreted in the timezone of the prime meridian (Airy Mean Time), and so is absolute; where any other timezone is to be used then this is explicitly noted.

MSD (Mars Sol Date)

days elapsed since 0140-19-26T00Z (approximately MJD 5521.50 in Terrestrial Time). This epoch is the most recent near coincidence of midnight on the Martian prime meridian with noon on the Terran prime meridian. MSD is defined by the paper at http://pubs.giss.nasa.gov/docs/2000/2000_Allison_McEwen.pdf.

JS (Julian Sol)

days elapsed since 0000-01-01T00Z (MSD -94129.0) (approximately MJD -91195.22 in Terrestrial Time). This epoch is an Airy midnight approximating the last northward equinox prior to the first telescopic observations of Mars. The same epoch is used for the Darian calendar for Mars. JS is defined (but not explicitly) by the document describing the Darian calendar, at http://pweb.jps.net/~tgangale/mars/converter/calendar_clock.htm.

CMSD (Chronological Mars Solar Date)

days elapsed since -0608-23-20T00 in the timezone of interest. CMSD = MSD + 500000.0 + Zoff, where Zoff is the timezone offset in fractional days. CMSD is defined by the memo at http://www.fysh.org/~zefram/time/define_cmsd.txt.

Meaning of the day

A day count has meaning only in the context of a particular definition of "day". Potentially several time scales could be expressed in terms of a day count, just as Terran day counts such as MJD are used in the timescales UT1, UT2, UTC, TAI, TT, TCG, and others. 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 time scales is out of scope for this module.

FUNCTIONS

Day counts in this API may be native Perl numbers or Math::BigRat objects. Both are acceptable for all parameters, in any combination. In all conversion functions, the result is of the same type as the input, provided that the inputs are of consistent type. If native Perl numbers are supplied then the conversion is subject to floating point rounding, and possible overflow if the numbers are extremely large. The use of Math::BigRat is recommended to avoid these problems. With Math::BigRat the results are exact.

There are conversion functions between all pairs of day count systems. This is a total of 72 conversion functions (including 12 identity functions).

When converting between timezone-relative counts (CMSD) and absolute counts (MSD, JS), the timezone that is being used must be specified. It is given in a ZONE argument as a fractional number of days offset from the base time scale (typically Airy Mean Time). Beware of floating point rounding when the offset does not have a terminating binary representation; use of Math::BigRat avoids this problem. A ZONE parameter is not used when converting between absolute day counts (e.g., between MSD and JS) or between timezone-relative counts (e.g., between CMSD and CMSDN).

msd_to_msd(MSD)

msd_to_js(MSD)

msd_to_cmsd(MSD, ZONE)

js_to_msd(JS)

js_to_js(JS)

js_to_cmsd(JS, ZONE)

cmsd_to_msd(CMSD, ZONE)

cmsd_to_js(CMSD, ZONE)

cmsd_to_cmsd(CMSD)

These functions convert from one continuous day count to another. This principally involve a change of epoch. The input identifies a point in time, as a continuous day count of input flavour. The function returns the same point in time, represented as a continuous day count of output flavour.

msd_to_msdnn(MSD)

msd_to_jsnn(MSD)

msd_to_cmsdnn(MSD, ZONE)

js_to_msdnn(JS)

js_to_jsnn(JS)

js_to_cmsdnn(JS, ZONE)

cmsd_to_msdnn(CMSD, ZONE)

cmsd_to_jsnn(CMSD, ZONE)

cmsd_to_cmsdnn(CMSD)

These functions convert from a continuous day count to an integral day count. The input identifies a point in time, as a continuous day count of input flavour. The function returns the day number of output flavour that applies at that instant. The process throws away information about the time of (output-flavour) day.

msd_to_msdnf(MSD)

msd_to_jsnf(MSD)

msd_to_cmsdnf(MSD, ZONE)

js_to_msdnf(JS)

js_to_jsnf(JS)

js_to_cmsdnf(JS, ZONE)

cmsd_to_msdnf(CMSD, ZONE)

cmsd_to_jsnf(CMSD, ZONE)

cmsd_to_cmsdnf(CMSD)

These functions convert from a continuous day count to an integral day count with separate fraction. The input identifies a point in time, as a continuous day count of input flavour. The function returns a list of two items: the day number and fractional day of output flavour, which together identify the same point in time as the input.

msd_to_msdn(MSD)

msd_to_jsn(MSD)

msd_to_cmsdn(MSD, ZONE)

js_to_msdn(JS)

js_to_jsn(JS)

js_to_cmsdn(JS, ZONE)

cmsd_to_msdn(CMSD, ZONE)

cmsd_to_jsn(CMSD, ZONE)

cmsd_to_cmsdn(CMSD)

These functions convert from a continuous day count to an integral day count, possibly with separate fraction. The input identifies a point in time, as a continuous day count of input flavour. If called in scalar context, the function returns the day number of output flavour that applies at that instant, throwing away information about the time of (output-flavour) day. If called in list context, the function returns a list of two items: the day number and fractional day of output flavour, which together identify the same point in time as the input.

These functions are not recommended, because the context-sensitive return convention makes their use error-prone. They are retained for backward compatibility. You should prefer to use the more specific functions shown above.

msdn_to_msd(MSDN, MSDF)

msdn_to_js(MSDN, MSDF)

msdn_to_cmsd(MSDN, MSDF, ZONE)

jsn_to_msd(JSN, JSF)

jsn_to_js(JSN, JSF)

jsn_to_cmsd(JSN, JSF, ZONE)

cmsdn_to_msd(CMSDN, CMSDF, ZONE)

cmsdn_to_js(CMSDN, CMSDF, ZONE)

cmsdn_to_cmsd(CMSDN, CMSDF)

These functions convert from an integral day count with separate fraction to a continuous day count. The input identifies a point in time, as an integral day number of input flavour plus day fraction in the range [0, 1). The function returns the same point in time, represented as a continuous day count of output flavour.

msdn_to_msdnn(MSDN[, MSDF])

msdn_to_jsnn(MSDN[, MSDF])

msdn_to_cmsdnn(MSDN, MSDF, ZONE)

jsn_to_msdnn(JSN[, JSF])

jsn_to_jsnn(JSN[, JSF])

jsn_to_cmsdnn(JSN, JSF, ZONE)

cmsdn_to_msdnn(CMSDN, CMSDF, ZONE)

cmsdn_to_jsnn(CMSDN, CMSDF, ZONE)

cmsdn_to_cmsdnn(CMSDN[, CMSDF])

These functions convert from an integral day count with separate fraction to an integral day count. The input identifies a point in time, as an integral day number of input flavour plus day fraction in the range [0, 1). The function returns the day number of output flavour that applies at that instant. The process throws away information about the time of (output-flavour) day. If converting between systems that delimit days identically (e.g., between JS and MSD), the day fraction makes no difference and may be omitted from the input.

msdn_to_msdnf(MSDN, MSDF)

msdn_to_jsnf(MSDN, MSDF)

msdn_to_cmsdnf(MSDN, MSDF, ZONE)

jsn_to_msdnf(JSN, JSF)

jsn_to_jsnf(JSN, JSF)

jsn_to_cmsdnf(JSN, JSF, ZONE)

cmsdn_to_msdnf(CMSDN, CMSDF, ZONE)

cmsdn_to_jsnf(CMSDN, CMSDF, ZONE)

cmsdn_to_cmsdnf(CMSDN, CMSDF)

These functions convert from one integral day count with separate fraction to another. The input identifies a point in time, as an integral day number of input flavour plus day fraction in the range [0, 1). The function returns a list of two items: the day number and fractional day of output flavour, which together identify the same point in time as the input.

msdn_to_msdn(MSDN[, MSDF])

msdn_to_jsn(MSDN[, MSDF])

msdn_to_cmsdn(MSDN, MSDF, ZONE)

jsn_to_msdn(JSN[, JSF])

jsn_to_jsn(JSN[, JSF])

jsn_to_cmsdn(JSN, JSF, ZONE)

cmsdn_to_msdn(CMSDN, CMSDF, ZONE)

cmsdn_to_jsn(CMSDN, CMSDF, ZONE)

cmsdn_to_cmsdn(CMSDN[, CMSDF])

These functions convert from an integral day count with separate fraction to an integral day count, possibly with separate fraction. The input identifies a point in time, as an integral day number of input flavour plus day fraction in the range [0, 1). If called in scalar context, the function returns the day number of output flavour that applies at that instant, throwing away information about the time of (output-flavour) day. If called in list context, the function returns a list of two items: the day number and fractional day of output flavour, which together identify the same point in time as the input.

If converting between systems that delimit days identically (e.g., between JS and MSD), the day fraction makes no difference to the integral day number of the output, and may be omitted from the input. If the day fraction is extracted from the output when it wasn't supplied as input, it will default to zero.

These functions are not recommended, because the context-sensitive return convention makes their use error-prone. They are retained for backward compatibility. You should prefer to use the more specific functions shown above.

SEE ALSO

Date::Darian::Mars, Date::JD

AUTHOR

Andrew Main (Zefram) <zefram@fysh.org>

COPYRIGHT

Copyright (C) 2007, 2009, 2010, 2012, 2017 Andrew Main (Zefram) <zefram@fysh.org>

LICENSE

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