iers 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fe885be7911b137f1052c4671b28d5ed63ec1f0a887745fbeede898e1d15eb68
-  data.tar.gz: 42763ecd8056ee961e489b666e6445553726c8dbe0d1606f1857eea6a427ba38
+  metadata.gz: 39a64a5333955d6d28a26abc77c01371004f91b8fb8ca4b958f3ac5d415cca13
+  data.tar.gz: 1f219ef6f35bc93ab6263832546a3af6534a7d2a29007425cfa54b2abea6c284
 SHA512:
-  metadata.gz: c2282980b523a94f9befbaf3146cb70bbe3284d73305cebf6073826bd60280da002b5a82dc9228fc6552d7db31c5ad38f6f05e9d6150aded290425aad2e47f56
-  data.tar.gz: b0579c1cfb2b2ef069e649ad80df7fddfe1d3828e360e28a6626a42f0a6d03ba1d563e622ee1e861e81bde0c4bc1a2373e112b5980ea2d1f8679bf66cd7e800e
+  metadata.gz: cd2df5b1019640ac16f44d7289a5af2721fc90bef064785921701992fd6798c96c94ce9ef9f34f69323e79baba9b4d2ab28310520045b18c7ac1332d63fc6b69
+  data.tar.gz: 42cc738efcb811f3f01f2de2d303d89b333a33ae394cbacc27f261cda39ab00e8e982ff2e3706eaac93b40a25a0e2522cfeb3d2dfe78c196137f7e3fbb8fd7b0

data/CHANGELOG.md

@@ -1,5 +1,96 @@
 # Changelog
 
+## 0.3.0 - 2026-09-06
+
+### Fixed
+
+- `DeltaT.at` answers every date in 1972 again. The switch from the Espenak &
+  Meeus polynomial to measured data was pinned to 1972-01-01, the start of the
+  modern UTC era, but the bundled EOP series only starts at 1973-01-02, so the
+  367 days in between belonged to neither source and raised `OutOfRangeError`.
+
+### Changed
+
+- `DeltaT.at` picks its source by asking what the loaded data actually covers
+  rather than by calendar date. The EOP series is used wherever it reaches, the
+  polynomial covers the rest of 1800–1986, and only a date outside both raises.
+  A configured or extended series therefore moves the seam with it, and no
+  fixed date can drift away from the data behind it again.
+
+  Two consequences for a series that does not span the query. A date past the
+  end of a short series now returns a polynomial estimate if it falls before
+  1986, where it used to raise; this cannot arise with the bundled data, which
+  ends decades beyond 1986. And a date outside both sources now raises with
+  a message naming the polynomial range and the series range, instead of the
+  EOP range alone, which read as if the caller had asked for something out of
+  range when the polynomial covered it.
+
+  Where the polynomial and the series meet in the bundled data they differ by
+  about 61 ms, well inside the polynomial's own error in that era.
+
+- Pointing the gem at a different data file now takes effect. `finals_path`,
+  `leap_second_path` and `cache_dir` memoised their parse on first read and
+  never dropped it, so setting any of them after a lookup kept serving the
+  previous file until `IERS.reset!`. Each now invalidates just the data it
+  governs; `interpolation`, `sources` and `download_timeout` leave the parse
+  in place, since they do not change which file is read, and a `Configuration`
+  the gem is not reading through governs nothing.
+
+- `Data.clear_cache!` drops the parse along with the files it deletes. It
+  removed the cached files and left their contents in memory, so the process
+  kept serving a deleted cache while `Data.status` already reported `:bundled`.
+
+- `Data.update!` drops the parse for each source as soon as it downloads it.
+  It replaced the files on disk but left the old contents in memory, so a
+  process that had already read them carried on with the pre-download data.
+
+- `OutOfRangeError` raised by `DeltaT.at` no longer carries an
+  `available_range`. What the gem can answer is two disjoint spans, and naming
+  one of them in a field called available range is the same thing that made the
+  old message misleading. The message names both spans; `requested_mjd` is
+  unchanged.
+
+- `Data.clear_loaded!` raises `ConfigurationError` for a source it does not
+  recognise, rather than clearing nothing and reporting success.
+
+- `DeltaT.at` consults the EOP series for every query, so a finals file that
+  fails to parse now raises `ParseError` even for a date the polynomial owns
+  outright, where it used to answer without reading the file. A file that
+  parses to no rows is a series covering nothing and still falls back to the
+  polynomial. A corrupt data file is worth surfacing whichever query reaches
+  it.
+
+- Refreshed the bundled `finals2000A.all` and `Leap_Second.dat` snapshots from
+  IERS. Final values now extend through 2026-08-27 (previously 2026-06-25) and
+  predictions through 2027-09-04 (previously 2027-07-03).
+
+## 0.2.0 - 2026-07-25
+
+### Added
+
+- `LeapSecond.expires_on`, `LeapSecond.expired?` and
+  `LeapSecond.updated_through` expose the expiry date and IERS bulletin that
+  `Leap_Second.dat` states in its header. Both were previously discarded with
+  the rest of the comment lines. Unlike `Data.status.cache_age`, which measures
+  when a file was downloaded, these describe how long the data itself stays
+  authoritative.
+- `LeapSecond.at` now answers 1961-01-01 through 1972-01-01, the era when UTC
+  was steered by rate adjustments rather than whole leap seconds. It returns
+  those values as exact `Rational`s. The coefficients come from the USNO
+  `tai-utc.dat` file and are bundled in source, since they are fixed. The
+  change is additive: the pre-1972 range previously raised, so no successful
+  call returns anything different. `TAI.utc_to_tai` and `TAI.tai_to_utc` gain
+  the same range for free.
+
+### Changed
+
+- `Parsers::LeapSecond.parse` returns a `Table` of `entries` and `metadata`
+  instead of an array of entries. `Parsers` is internal; the public API is
+  unaffected.
+- `Parsers::LeapSecond.parse` no longer raises `Encoding::CompatibilityError`
+  on a file containing invalid UTF-8. Header metadata is read on a best-effort
+  basis and an unreadable data row raises `ParseError` as before.
+
 ## 0.1.1 - 2026-06-27
 
 ### Changed

data/README.md

@@ -167,9 +167,10 @@ entry.observed?      # => true
 
 ### Delta T
 
-Compute Delta T (TT − UT1). From 1972 onward the value is derived from IERS
-data; before 1972 (back to 1800) it uses Espenak & Meeus polynomial
-approximations:
+Compute Delta T (TT − UT1). Wherever the loaded EOP series reaches, the value is
+derived from IERS data. Outside it, Espenak & Meeus polynomial approximations
+cover 1800 to 1986. The bundled series starts at MJD 41684 (1973-01-02), so
+earlier dates are estimated; `measured?` and `estimated?` say which you got:
 
 ```ruby
 entry = IERS::DeltaT.at(Time.utc(2020, 6, 15))
@@ -242,14 +243,28 @@ entries = IERS::EOP.between(
 Look up TAI−UTC at a given date:
 
 ```ruby
-IERS::LeapSecond.at(Time.utc(2017, 1, 1))  # => 37.0 (seconds)
+IERS::LeapSecond.at(Time.utc(2017, 1, 1))  # => 37 (seconds)
 ```
 
+`at` covers 1961-01-01 onward. From 1972 it returns a whole number of seconds
+as an `Integer`. Between 1961 and 1972, UTC was steered by small rate
+adjustments rather than whole leap seconds, so TAI−UTC was a fraction of a
+second that changed daily. `at` returns those values as exact `Rational`s:
+
+```ruby
+IERS::LeapSecond.at(mjd: 38_900)       # => (1910137/500000)
+IERS::LeapSecond.at(mjd: 38_900).to_f  # => 3.820274 (seconds, 1965-05-20)
+```
+
+The coefficients for that era are fixed and will never change, so they are
+bundled in the gem rather than downloaded. Anything before 1961-01-01 has no
+published UTC and raises `OutOfRangeError`.
+
 List all leap seconds:
 
 ```ruby
 IERS::LeapSecond.all
-# => [#<data IERS::LeapSecond::Entry effective_date=#<Date: 1972-01-01>, tai_utc=10.0>, ...]
+# => [#<data IERS::LeapSecond::Entry effective_date=#<Date: 1972-01-01>, tai_utc=10>, ...]
 ```
 
 Check for a future scheduled leap second:
@@ -258,6 +273,27 @@ Check for a future scheduled leap second:
 IERS::LeapSecond.next_scheduled  # => #<data IERS::LeapSecond::Entry ...> or nil
 ```
 
+#### Leap second file validity
+
+`Leap_Second.dat` states when it stops being authoritative and which IERS
+bulletin it was updated through. Both are read from the file that is actually
+loaded, so a custom or cached file reports its own header:
+
+```ruby
+IERS::LeapSecond.expires_on       # => #<Date: 2026-12-28> or nil
+IERS::LeapSecond.expired?         # => false
+IERS::LeapSecond.updated_through  # => "IERS Bulletin 71 issued in January 2026"
+```
+
+The stated date is itself still valid, so a file expiring on 28 December 2026
+is expired on the 29th. An expired file is not wrong: it means the IERS has
+published a newer one and a leap second may have been announced since.
+
+This is unrelated to `Data.status.cache_age`, which measures when the file was
+downloaded rather than how long it stays valid. A bundled snapshot can be a year
+old and still valid while a file downloaded this morning can be a week from
+expiry.
+
 ### TAI
 
 Convert between UTC and TAI time scales:
@@ -295,6 +331,10 @@ end
 
 Without `coverage_days_ahead`, the check ensures predictions cover today.
 
+`ensure_fresh!` is about prediction coverage in `finals2000A.all` only. Leap
+second file validity is a separate question, answered by
+`IERS::LeapSecond.expired?`.
+
 ### Data status and cache management
 
 ```ruby
@@ -358,6 +398,9 @@ release a new version, update the version number in `version.rb`, and then run
 `bundle exec rake release`, which will create a git tag for the version, push
 git commits and the created tag, and push the `.gem` file to [rubygems.org].
 
+To refresh the bundled snapshot in `data/`, run `bundle exec rake data:update`.
+A monthly workflow runs this and opens a pull request automatically.
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License].

data/Rakefile

@@ -10,3 +10,30 @@ require "rubocop/rake_task"
 RuboCop::RakeTask.new
 
 task default: %i[test rubocop]
+
+namespace :data do
+  desc "Download the latest IERS data"
+  task :update do
+    require "iers"
+
+    data_dir = File.expand_path("data", __dir__)
+    IERS.configure do |config|
+      config.finals_path = File.join(data_dir, "finals2000A.all")
+      config.leap_second_path = File.join(data_dir, "Leap_Second.dat")
+    end
+
+    result = IERS::Data.update!
+
+    unless result.success?
+      result.errors.each do |source, error|
+        warn "#{source}: #{error.class} - #{error.message}"
+      end
+      abort "IERS data update failed"
+    end
+
+    IERS::Data.ensure_fresh!(coverage_days_ahead: 90)
+    IERS::Data.leap_second_entries
+
+    puts "Updated: #{result.updated_files.join(", ")}"
+  end
+end

data/data/Leap_Second.dat

@@ -1,10 +1,10 @@
 #  Value of TAI-UTC in second valid beetween the initial value until
 #  the epoch given on the next line. The last line reads that NO
 #  leap second was introduced since the corresponding date 
-#  Updated through IERS Bulletin 71 issued in January 2026
+#  Updated through IERS Bulletin 72 issued in July 2026
 #  
 #
-#  File expires on 28 December 2026
+#  File expires on 28 June 2027
 #
 #
 #    MJD        Date        TAI-UTC (s)