marsdate 1.1.7 → 2.0.1

data/bin/marsdate

@@ -8,10 +8,10 @@ def usage
 
     marsdate                # usage (this message)
     marsdate version        # current version number
-    marsdate today          # today's Martian date
-    marsdate now            # today's Martian date/time
+    marsdate today          # current Martian sol at 00:00
+    marsdate now            # current instant
 
-    marsdate calendar yyyy  # Martian calendar for yyyy (HTML)   **FIXME**
+    marsdate calendar yyyy  # Martian calendar for yyyy (HTML)
     marsdate calendar       # this year's Martian calendar (HTML)
 
     marsdate e2m yyyy-mm-dd hh:mm:ss   # Convert Earth date to Mars date,
@@ -32,7 +32,7 @@ def command(cmd)
     when "now"
       puts MarsDateTime.now
     when "calendar"
-      calendar   # fix later
+      calendar
     else
       abort "Unknown command '#{cmd}'"
   end
@@ -48,9 +48,8 @@ end
 def invoke(cmd, *args)
   send(cmd, *args)
 rescue => err
-  puts "Error in calling: #{cmd}(#{args.inspect[1..-2]})"
-  puts err.backtrace
-  exit
+  warn "Error in calling #{cmd}: #{err.message}"
+  exit 1
 end
 
 def e2m(ymd, hms)
@@ -63,15 +62,15 @@ end
 
 def m2e(ymd, hms)
   yyyy, mm, dd, hh, mi, ss = *get_data(ymd, hms)
-  mdate = MarsDateTime.new(yyyy,mm,dd)
+  mdate = MarsDateTime.new(yyyy, mm, dd, hh, mi, ss) # MXT
   date = mdate.earth_date
   puts date.strftime("%x %X")
 end
 
 class CalendarHTML
   def month_header(n)
-    @out.puts "<tr><td colspan=7"
-    @out.puts "<b><center><font size=4 face=arial color=red>#{MarsDateTime::Months[n]}</font><center></b>"
+    @out.puts "<tr><td colspan=7>"
+    @out.puts "<b><center><font size=4 face=arial color=red>#{MarsDateTime::Months[n]}</font></center></b>"
     @out.puts "</td></tr>"
     @out.puts "<tr bgcolor=#FFA833>"
     @out.puts "<td width=3%><font size=3 face='arial'>Sun</font></td>"
@@ -81,7 +80,6 @@ class CalendarHTML
     @out.puts "<td width=3%><font size=3 face='arial'>Thu</font></td>"
     @out.puts "<td width=3%><font size=3 face='arial'>Fri</font></td>"
     @out.puts "<td width=3%><font size=3 face='arial'>Sat</font></td>"
-    @out.puts "</font>"
     @out.puts "</tr>"
   end
 
@@ -90,7 +88,7 @@ class CalendarHTML
     ndays = 28
     ndays = MarsDateTime.sols_in_month(n, year) if n == 24
     mtoday = MarsDateTime.today
-    @curmonth = mtoday.month == n
+    @curmonth = mtoday.year == year && mtoday.month == n
     list = [""]*dow + (1..ndays).to_a
     l2 = []
     loop do
@@ -161,8 +159,8 @@ class CalendarHTML
 end
 
 
-def calendar
-  year ||= MarsDateTime.today.year
+def calendar(year = nil, _extra = nil)
+  year = (year || MarsDateTime.today.year).to_i
   CalendarHTML.new(year)
 end
 
@@ -232,5 +230,9 @@ case
     command(cmd)
   when [2,3].include?(args)
     invoke(ARGV[0], ARGV[1], ARGV[2])
+  else
+    warn "Wrong number of arguments (given #{args}, expected 0..3)"
+    usage
+    exit 1
 end
 

data/lib/marsdate/calendar.rb

@@ -0,0 +1,128 @@
+# MCE civil calendar on the official Mars timeline.
+#
+#   integer MSD = EPOCH_MSD + sol_index(year, month, sol)
+#
+# EPOCH_MSD is the integer Mars Sol Date of 1/1/1 00:00 MTC: the
+# Airy-0 midnight of the sol that contains the year-1 northern
+# vernal equinox (Allison Ls=0). Provisional: Allison is fitted
+# ~1874–2127; year 1 is an extrapolation. See TimeScale.epoch_report.
+
+class MarsDateTime
+  module Calendar
+    EPOCH_MSD = -665_773
+    SOLS_COMMON = 668
+    SOLS_LEAP = 669
+    MONTHS_OF_28 = 23
+    MEAN_YEAR = 668.591
+
+    module_function
+
+    # Same intercalation as MarsDateTime.leap? (MCE: /100 except /1000).
+    def leap?(year)
+      return (year % 2 == 1) if (year % 10 != 0)
+      return true if (year % 1000 == 0)
+      return false if (year % 100 == 0)
+      true
+    end
+
+    def sols_in_year(year)
+      leap?(year) ? SOLS_LEAP : SOLS_COMMON
+    end
+
+    def sols_in_month(month, year)
+      return 28 if month < 24
+      leap?(year) ? 25 : 24
+    end
+
+    # Leap years in 1..n inclusive. Closed form of the MCE rule.
+    def leaps_through(n)
+      return 0 if n <= 0
+      odds = (n + 1) / 2
+      tens = n / 10
+      centuries = n / 100
+      millennia = n / 1000
+      odds + tens - centuries + millennia
+    end
+
+    def leaps_before(year)
+      year <= 1 ? 0 : leaps_through(year - 1)
+    end
+
+    # 0-based sol index of 1/1 of +year+ (1/1/1 → 0).
+    def sols_before_year(year)
+      (year - 1) * SOLS_COMMON + leaps_before(year)
+    end
+
+    def check_ymd!(year, month, sol)
+      text = +""
+      text << "year #{year} is not a positive integer\n" unless year.is_a?(Integer) && year >= 1
+      text << "month #{month} is out of range\n" unless month.is_a?(Integer) && (1..24).include?(month)
+      text << "sol #{sol} is out of range\n" unless sol.is_a?(Integer) && (1..28).include?(sol)
+      if year.is_a?(Integer) && month == 24 && sol.is_a?(Integer)
+        max = sols_in_month(24, year)
+        text << "sol #{sol} is invalid in Taurus of year #{year}\n" if sol > max
+      end
+      raise ArgumentError, text unless text.empty?
+    end
+
+    # 0-based sols since 1/1/1.
+    def sol_index(year, month, sol)
+      check_ymd!(year, month, sol)
+      sols_before_year(year) + (month - 1) * 28 + (sol - 1)
+    end
+
+    # Integer MSD of Airy-0 midnight of that MCE date.
+    def msd_midnight(year, month, sol)
+      EPOCH_MSD + sol_index(year, month, sol)
+    end
+
+    # Instant MSD: date + fraction of a sol in [0, 1).
+    def msd_at(year, month, sol, frac = 0.0)
+      unless frac.is_a?(Numeric) && frac >= 0.0 && frac < 1.0
+        raise ArgumentError, "sol fraction must be in [0, 1) (got #{frac.inspect})"
+      end
+      msd_midnight(year, month, sol) + frac.to_f
+    end
+
+    def ymd(index)
+      unless index.is_a?(Integer) && index >= 0
+        raise ArgumentError,
+              "sol index must be a non-negative integer (got #{index.inspect})"
+      end
+      year = (index / MEAN_YEAR).floor + 1
+      year = 1 if year < 1
+      16.times do
+        start = sols_before_year(year)
+        stop = start + sols_in_year(year)
+        if index >= start && index < stop
+          return ymd_in_year(year, index - start)
+        end
+        year += 1 if index >= stop
+        year -= 1 if index < start
+        year = 1 if year < 1
+      end
+      raise "year search failed for sol index #{index}"
+    end
+
+    def ymd_from_msd(msd)
+      ymd(msd.to_f.floor - EPOCH_MSD)
+    end
+
+    # Sunday = 0, same as MarsDateTime#dow on 1/1/1.
+    def dow(year, month, sol)
+      sol_index(year, month, sol) % 7
+    end
+
+    def ymd_in_year(year, offset)
+      if offset < MONTHS_OF_28 * 28
+        month = offset / 28 + 1
+        sol = offset % 28 + 1
+      else
+        month = 24
+        sol = offset - MONTHS_OF_28 * 28 + 1
+      end
+      [year, month, sol]
+    end
+    private_class_method :ymd_in_year
+  end
+end

data/lib/marsdate/timescale.rb

@@ -0,0 +1,314 @@
+# Official Mars time scales (NASA/Allison / Mars24).
+#
+#   Earth instant → JD (UT) → JD (TT) → MSD → MTC / MXT
+#
+# MTC = Coordinated Mars Time (24 stretched hours, Airy-0 mean midnight)
+# MXT = Mars eXtended Time (SI hours, same midnight, day to ~24:39)
+
+require 'date'
+
+class MarsDateTime
+  module TimeScale
+    SOL_DAYS = 1.0274912517
+    SECONDS_PER_DAY = 86_400.0
+    SOL_SI_SECONDS = SOL_DAYS * SECONDS_PER_DAY # ~88775.244147
+    TT_MINUS_TAI = 32.184
+
+    # Mars24 C-2
+    MSD_JDTT_OFFSET = 2_451_549.5
+    MSD_EPOCH_SHIFT = 44_796.0
+    MSD_FINE = 0.0009626
+
+    J2000_JDTT = 2_451_545.0
+
+    # IERS Leap_Second.dat (Bulletin 72, July 2026). Each row is the
+    # UTC calendar date when TAI−UTC becomes that many seconds.
+    TAI_UTC_STEPS = [
+      [Date.new(1972, 1, 1), 10],
+      [Date.new(1972, 7, 1), 11],
+      [Date.new(1973, 1, 1), 12],
+      [Date.new(1974, 1, 1), 13],
+      [Date.new(1975, 1, 1), 14],
+      [Date.new(1976, 1, 1), 15],
+      [Date.new(1977, 1, 1), 16],
+      [Date.new(1978, 1, 1), 17],
+      [Date.new(1979, 1, 1), 18],
+      [Date.new(1980, 1, 1), 19],
+      [Date.new(1981, 7, 1), 20],
+      [Date.new(1982, 7, 1), 21],
+      [Date.new(1983, 7, 1), 22],
+      [Date.new(1985, 7, 1), 23],
+      [Date.new(1988, 1, 1), 24],
+      [Date.new(1990, 1, 1), 25],
+      [Date.new(1991, 1, 1), 26],
+      [Date.new(1992, 7, 1), 27],
+      [Date.new(1993, 7, 1), 28],
+      [Date.new(1994, 7, 1), 29],
+      [Date.new(1996, 1, 1), 30],
+      [Date.new(1997, 7, 1), 31],
+      [Date.new(1999, 1, 1), 32],
+      [Date.new(2006, 1, 1), 33],
+      [Date.new(2009, 1, 1), 34],
+      [Date.new(2012, 7, 1), 35],
+      [Date.new(2015, 7, 1), 36],
+      [Date.new(2017, 1, 1), 37]
+    ].freeze
+
+    module_function
+
+    # Astronomical Julian Date of the instant (offset-independent).
+    def jd_ut(earth)
+      earth.to_datetime.ajd.to_f
+    end
+
+    # TAI−UTC in seconds. Leap table from 1972-01-01; Mars24 polynomial
+    # for 1900-01-01...1972-01-01. Earlier dates raise (no UTC).
+    def tai_utc(earth)
+      dt = earth.to_datetime
+      date = dt.to_date
+      if date >= TAI_UTC_STEPS.first[0]
+        tai_utc_from_table(date)
+      elsif date >= Date.new(1900, 1, 1)
+        tt_utc_polynomial(jd_ut(dt)) - TT_MINUS_TAI
+      else
+        raise ArgumentError,
+              "TAI−UTC is undefined before 1900-01-01 (got #{date}); " \
+              "pass jd_tt: for antiquity"
+      end
+    end
+
+    def tt_utc(earth)
+      tai_utc(earth) + TT_MINUS_TAI
+    end
+
+    def jd_tt(earth, jd_tt: nil)
+      return jd_tt.to_f if jd_tt
+      jd_ut(earth) + tt_minus_ut(earth) / SECONDS_PER_DAY
+    end
+
+    # TT−UT in seconds. Leap table / polynomial from 1900; before
+    # that, 0 (treat the civil digits as TT). This is not a
+    # historical ΔT model. Year-1 Earth times are captions only.
+    def tt_minus_ut(earth)
+      dt = earth.to_datetime
+      return 0.0 if dt.to_date < Date.new(1900, 1, 1)
+      tt_utc(dt)
+    end
+
+    # Mars Sol Date (Mars24 C-2).
+    def msd(earth = nil, jd_tt: nil)
+      j = jd_tt(earth, jd_tt: jd_tt)
+      (j - MSD_JDTT_OFFSET) / SOL_DAYS + MSD_EPOCH_SHIFT - MSD_FINE
+    end
+
+    # Fractional sol in [0, 1).
+    def sol_fraction(earth = nil, jd_tt: nil)
+      frac = msd(earth, jd_tt: jd_tt) % 1.0
+      frac += 1.0 if frac < 0
+      frac
+    end
+
+    # MTC as hours in [0, 24).
+    def mtc_hours(earth = nil, jd_tt: nil)
+      sol_fraction(earth, jd_tt: jd_tt) * 24.0
+    end
+
+    def mtc_hms(earth = nil, jd_tt: nil)
+      hours_to_hms(mtc_hours(earth, jd_tt: jd_tt), limit: 24)
+    end
+
+    # SI seconds since Airy-0 mean midnight (0 ... SOL_SI_SECONDS).
+    def mxt_si_seconds(earth = nil, jd_tt: nil)
+      sol_fraction(earth, jd_tt: jd_tt) * SOL_SI_SECONDS
+    end
+
+    def mxt_hms(earth = nil, jd_tt: nil)
+      hours_to_hms(mxt_si_seconds(earth, jd_tt: jd_tt) / 3600.0)
+    end
+
+    def format_hms(h, m, s)
+      format('%02d:%02d:%06.3f', h, m, s)
+    end
+
+    # Areocentric solar longitude Ls (degrees), Mars24 B-1…B-5.
+    def ls_deg(jd_tt)
+      dt = jd_tt.to_f - J2000_JDTT
+      mean_anom = 19.3871 + 0.52402073 * dt
+      alpha_fms = 270.3871 + 0.524038496 * dt
+      pbs = mars_pbs(dt)
+      nu_m = (10.691 + 3.0e-7 * dt) * sind(mean_anom) +
+             0.623 * sind(2 * mean_anom) +
+             0.050 * sind(3 * mean_anom) +
+             0.005 * sind(4 * mean_anom) +
+             0.0005 * sind(5 * mean_anom) + pbs
+      wrap360(alpha_fms + nu_m)
+    end
+
+    # JD_TT of the northern vernal equinox (Ls = 0) nearest +around_jd_tt+.
+    def vernal_equinox_jd_tt(around_jd_tt)
+      year_days = 686.98 # Earth days per Mars tropical year, rough
+      lo = around_jd_tt - year_days * 0.6
+      hi = around_jd_tt + year_days * 0.6
+      # Bracket a rising-through-0 crossing of Ls.
+      step = 2.0
+      t = lo
+      prev = wrap180(ls_deg(t))
+      pair = nil
+      while t <= hi
+        t += step
+        cur = wrap180(ls_deg(t))
+        if prev < 0 && cur >= 0
+          pair = [t - step, t]
+          break
+        end
+        prev = cur
+      end
+      raise "no Ls=0 crossing near JD_TT #{around_jd_tt}" unless pair
+      a, b = pair
+      60.times do
+        mid = (a + b) / 2.0
+        if wrap180(ls_deg(mid)) < 0
+          a = mid
+        else
+          b = mid
+        end
+      end
+      (a + b) / 2.0
+    end
+
+    # Civil DateTime corresponding to an astronomical JD, treated as UT.
+    def datetime_from_ajd(ajd)
+      DateTime.jd(ajd + 0.5)
+    end
+
+    def epoch_report
+      # Allison Ls is fitted for ~1874–2127; year 1 is an extrapolation.
+      # Seed the search at the article’s “late January of Year 1.”
+      # Calendar::EPOCH_MSD is the frozen floor of this search.
+      #
+      # Earth fields treat JD_TT as UT (ΔT = 0). A real 1 CE ΔT is a
+      # few hours and would only slide these captions, not EPOCH_MSD.
+      hint = DateTime.new(1, 1, 22, 12, 0, 0)
+      around = hint.ajd.to_f
+      eq_tt = vernal_equinox_jd_tt(around)
+      eq_msd = msd(jd_tt: eq_tt)
+      epoch_msd = eq_msd.floor.to_i
+      midnight_tt = jd_tt_from_msd(epoch_msd)
+      frac = eq_msd - epoch_msd
+      {
+        caveat: 'Allison Ls extrapolated to 1 CE; Earth times treat JD_TT as UT (no year-1 ΔT)',
+        ls0_jd_tt: eq_tt,
+        ls0_msd: eq_msd,
+        ls0_mtc: format_hms(*hours_to_hms(frac * 24.0)),
+        ls0_earth_if_tt_were_ut: datetime_from_ajd(eq_tt),
+        epoch_msd: epoch_msd,
+        epoch_jd_tt: midnight_tt,
+        epoch_earth_if_tt_were_ut: datetime_from_ajd(midnight_tt)
+      }
+    end
+
+    def jd_tt_from_msd(msd)
+      # invert Mars24 C-2
+      ((msd - MSD_EPOCH_SHIFT + MSD_FINE) * SOL_DAYS) + MSD_JDTT_OFFSET
+    end
+
+    # Invert jd_tt: TT → UT. Before 1900, treat TT as UT.
+    def jd_ut_from_jd_tt(jd_tt)
+      j = jd_tt.to_f
+      guess = j - 69.184 / SECONDS_PER_DAY
+      8.times do
+        earth = datetime_from_ajd(guess)
+        if earth.to_date < Date.new(1900, 1, 1)
+          return j
+        end
+        nxt = j - tt_utc(earth) / SECONDS_PER_DAY
+        return nxt if (nxt - guess).abs < 1e-14
+        guess = nxt
+      end
+      guess
+    end
+
+    def earth_from_msd(msd)
+      datetime_from_ajd(jd_ut_from_jd_tt(jd_tt_from_msd(msd)))
+    end
+
+    def sol_fraction_of(msd)
+      frac = msd.to_f % 1.0
+      frac += 1.0 if frac < 0
+      frac = 0.0 if frac >= 1.0
+      frac
+    end
+
+    def tai_utc_from_table(date)
+      value = TAI_UTC_STEPS.first[1]
+      TAI_UTC_STEPS.each do |d, v|
+        break if date < d
+        value = v
+      end
+      value.to_f
+    end
+
+    # Mars24 A-4, dates before 1972 (used here only back to 1900).
+    def tt_utc_polynomial(jd_ut)
+      t = (jd_ut - J2000_JDTT) / 36_525.0
+      64.184 + 59.0 * t - 51.2 * t**2 - 67.1 * t**3 - 16.4 * t**4
+    end
+
+    def mars_pbs(dt)
+      terms = [
+        [0.0071, 2.2353, 49.409],
+        [0.0057, 2.7543, 168.173],
+        [0.0039, 1.1177, 191.837],
+        [0.0037, 15.7866, 21.736],
+        [0.0021, 2.1354, 15.704],
+        [0.0020, 2.4694, 95.528],
+        [0.0018, 32.8493, 49.095]
+      ]
+      terms.sum do |amp, tau, phase|
+        amp * cosd(0.985626 * dt / tau + phase)
+      end
+    end
+
+    def hours_to_hms(hours, limit: nil)
+      h = hours.floor
+      minf = (hours - h) * 60.0
+      m = minf.floor
+      s = ((minf - m) * 60.0).round(4)
+      if s >= 59.9995
+        if limit && h == limit - 1 && m == 59
+          # The instant is still inside the half-open clock interval.
+          # Keep its rounded display below the following midnight.
+          s = 59.9994
+        else
+          s = 0.0
+          m += 1
+        end
+      end
+      if m >= 60
+        m = 0
+        h += 1
+      end
+      [h, m, s]
+    end
+
+    def sind(deg)
+      Math.sin(deg * Math::PI / 180.0)
+    end
+
+    def cosd(deg)
+      Math.cos(deg * Math::PI / 180.0)
+    end
+
+    def wrap360(deg)
+      d = deg % 360.0
+      d += 360.0 if d < 0
+      d
+    end
+
+    def wrap180(deg)
+      d = wrap360(deg)
+      d -= 360.0 if d > 180.0
+      d
+    end
+  end
+end

data/lib/marsdate/version.rb

@@ -0,0 +1,3 @@
+class MarsDateTime
+  VERSION = '2.0.1'
+end