iers 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc31ab2d8d7c623f16a33f1092ae9e0713ab9a9f785d0c86b4ffec022d2ab779
-  data.tar.gz: 5a1d2262a36a36d488f553f66ef5e7a79053aa4c319dbc678cb61d672f00f7a8
+  metadata.gz: 4977c2dce8a969f0590cabc8c9c2a992e946b14d5def3fd9e7b6635c76a5cd83
+  data.tar.gz: fd23f09386c87acbc6f4b25207d023198a41c9f55502c341859188496fc6f66b
 SHA512:
-  metadata.gz: b669b6e70cb16c915d0c23323a900306164c3da7c7b7c3abe8d9863872c0fdd4b89860fa6d84e0c85b6ad47002c0b9bb35eb5c0166ec6d0b096f9b23a63941df
-  data.tar.gz: 13f68ed59f48f60de2ce141cf630d4086c565e482062025bf6c104cb31f3167097975ae0f0c036c94a553103f76e9a70b4d77a58b900552bedde8a9efbb249ee
+  metadata.gz: c219975975bd14d24c47c45062868592999f4da0f19d254d73a01676b71b5d881faebd8f73afbb3d3155ef5da341459414846165e4f2540570f78e9487bba435
+  data.tar.gz: 0b13b6a3dc0daa6d2012e112662c3605b59de6c4d6b1437f4162912095bb424772cd13fb1c0cddb7cb3e234e85bfd0658ecf63ecf977a8281f063e13da05ceaa

data/.yardopts

@@ -0,0 +1,3 @@
+--markup markdown
+--no-private
+lib/**/*.rb

data/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
-## 0.0.1 - 2026-02-24
+## 0.1.0 - 2026-02-27
 
-- Initial release
+Initial public release.
+
+### Features
+
+- **Polar motion** - `PolarMotion.at` returns x/y coordinates with Lagrange or
+  linear interpolation; `PolarMotion.rotation_matrix_at` builds the full W
+  rotation matrix; `PolarMotion.between` for daily range queries
+- **UT1-UTC** - `UT1.at` with automatic UT1-TAI normalization across leap second
+  boundaries; Bulletin B preference over Series A when available
+- **Celestial pole offsets** - `CelestialPoleOffset.at` for dX/dY corrections
+- **Length of day** - `LengthOfDay.at` for LOD excess
+- **Delta T** - `DeltaT.at` for TT - UT1, extended back to 1800 with
+  Espenak & Meeus polynomials
+- **Earth Rotation Angle** - `EarthRotationAngle.at` per IERS Conventions 2010
+- **Greenwich Mean Sidereal Time** - `GMST.at` via ERA + polynomial
+- **Terrestrial rotation** - `TerrestrialRotation.at` for the R(ERA) × W matrix
+- **Unified EOP** - `EOP.at` and `EOP.between` composing all individual
+  parameters
+- **Leap seconds** - `LeapSecond.at` for TAI-UTC lookup with binary search;
+  `LeapSecond.next_scheduled` for the next known transition
+- **TAI utilities** - `TAI.utc_to_tai` and `TAI.tai_to_utc` for UTC↔TAI
+  conversion
+- **Bundled data** - ships a `finals2000A.all` and `Leap_Second.dat` snapshot
+  for out-of-the-box usage with no network calls required
+- **Data management** - `Data.update!` downloads fresh files with atomic writes
+  and redirect handling; `Data.ensure_fresh!` raises `StaleDataError` when
+  coverage is insufficient; `DataStatus` reports bundled/cached/custom state
+- **Configuration** - `IERS.configure` for data paths, interpolation method
+  (`:lagrange` or `:linear`), Lagrange order, freshness thresholds, and
+  download URLs; per-query `interpolation:` override on all `.at` methods
+- **Time inputs** - all query methods accept `Time`, `Date`, `DateTime`,
+  Modified Julian Date (float), or Julian Date (float)
+- **Data quality** - every `Entry` exposes `observed?` and `predicted?`
+  predicates via the `HasDataQuality` mixin; `date` via `HasDate`
+- **Lazy enumerators** - `between` returns a lazy `Enumerator` for
+  memory-efficient iteration over large date ranges
+- **Thread safety** - mutex-protected lazy caching in `Data` and `LeapSecond`
+- **Error hierarchy** - `IERS::Error` base with `ConfigurationError`,
+  `DataError`, `DownloadError`, `ParseError`, `FileNotFoundError`,
+  `OutOfRangeError`, and `StaleDataError`

data/README.md

@@ -5,6 +5,40 @@
 Access to Earth orientation parameters and time scale values from the
 International Earth Rotation and Reference Systems Service (IERS).
 
+## About IERS and Earth Orientation Parameters
+
+The [IERS] is an international service that monitors the irregularities of
+Earth's rotation and orientation in space. Because Earth's rotation is not
+perfectly uniform, precise timekeeping, satellite navigation, and telescope
+pointing all depend on regularly updated measurements.
+
+The key quantities tracked by the IERS are known as **Earth Orientation
+Parameters** (EOP):
+
+- **Polar motion (x, y)** — the position of Earth's rotational pole relative
+  to its crust, expressed in arcseconds. The pole wanders in a roughly circular
+  path of a few tenths of an arcsecond over ~14 months (the Chandler wobble).
+- **UT1−UTC** — the difference between astronomical time (UT1, tied to Earth's
+  actual rotation angle) and coordinated universal time (UTC, maintained by
+  atomic clocks). This difference drifts by up to ~0.9 s before a leap second
+  is introduced to keep them close.
+- **Leap seconds** — occasional one-second adjustments applied to UTC so that
+  it stays within 0.9 s of UT1. Since 1972, 27 leap seconds have been added.
+
+### Data files
+
+This library works with two data files published by the IERS:
+
+- **finals2000A** — a daily table spanning from 1973 to the present (plus
+  predictions ~1 year ahead). Each row contains polar motion, UT1−UTC, and
+  other EOP for one Modified Julian Date. Recent rows carry rapid "Series A"
+  values; older rows also include refined "Bulletin B" values.
+- **Leap_Second.dat** — the complete history of leap seconds with their
+  effective dates and the cumulative TAI−UTC offset.
+
+Both files are downloaded automatically by `IERS::Data.update!` and cached
+locally.
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
@@ -18,7 +52,300 @@ executing:
 
 ## Usage
 
-Coming soon.
+### Bundled data
+
+The gem ships with a snapshot of the IERS data files taken at release time, so
+queries work immediately without any download:
+
+```ruby
+require "iers"
+
+IERS::UT1.at(Time.utc(2020, 6, 15))  # works out of the box
+```
+
+The bundled snapshot includes predictions roughly one year into the future from
+the release date. As time passes those predictions expire, so you should
+download fresh data periodically:
+
+```ruby
+result = IERS::Data.update!
+result.success? # => true
+```
+
+You can also update a single source:
+
+```ruby
+IERS::Data.update!(:finals)
+IERS::Data.update!(:leap_seconds)
+```
+
+Downloaded files are cached in `~/.cache/iers/` by default and take precedence
+over the bundled snapshot.
+
+The bundled data files are sourced from the [IERS Earth Orientation Center] and
+the [USNO Rapid Service/Prediction Center].
+
+### Polar motion
+
+Query the pole position at any point in time:
+
+```ruby
+pm = IERS::PolarMotion.at(Time.utc(2020, 6, 15))
+pm.x          # => 0.070979... (arcseconds)
+pm.y          # => 0.456571... (arcseconds)
+pm.observed?  # => true
+```
+
+Retrieve daily grid values over a date range. `between` returns a lazy
+`Enumerator`, so entries are computed on demand:
+
+```ruby
+entries = IERS::PolarMotion.between(
+  Date.new(2020, 1, 1),
+  Date.new(2020, 1, 31)
+)
+entries.count  # => 31
+```
+
+#### Rotation matrix
+
+Compute the polar motion rotation matrix W (IERS Conventions 2010, §5.4.1):
+
+```ruby
+w = IERS::PolarMotion.rotation_matrix_at(Time.utc(2020, 6, 15))
+w.length     # => 3
+w[0].length  # => 3
+```
+
+Returns a nested `Array` (3×3, row-major).
+
+The matrix is also available on any `PolarMotion::Entry`:
+
+```ruby
+pm = IERS::PolarMotion.at(Time.utc(2020, 6, 15))
+pm.rotation_matrix  # => same nested Array
+```
+
+### UT1−UTC
+
+Query the difference between UT1 and UTC:
+
+```ruby
+entry = IERS::UT1.at(Time.utc(2020, 6, 15))
+entry.ut1_utc    # => -0.178182...
+entry.observed?  # => true
+```
+
+Daily grid values:
+
+```ruby
+entries = IERS::UT1.between(
+  Date.new(2020, 1, 1),
+  Date.new(2020, 1, 31)
+)
+```
+
+### Celestial pole offsets
+
+Query the celestial pole offset corrections (dX, dY):
+
+```ruby
+cpo = IERS::CelestialPoleOffset.at(Time.utc(2020, 6, 15))
+cpo.x  # => dX correction (milliarcseconds)
+cpo.y  # => dY correction (milliarcseconds)
+```
+
+### Length of day
+
+Query the excess length of day:
+
+```ruby
+entry = IERS::LengthOfDay.at(Time.utc(2020, 6, 15))
+entry.length_of_day  # => excess LOD (seconds)
+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:
+
+```ruby
+entry = IERS::DeltaT.at(Time.utc(2020, 6, 15))
+entry.delta_t    # => ~69.36 (seconds)
+entry.measured?  # => true
+
+entry = IERS::DeltaT.at(Time.utc(1900, 6, 15))
+entry.delta_t    # => ~-2.12 (seconds)
+entry.estimated? # => true
+```
+
+### Earth Rotation Angle
+
+Compute ERA (IERS Conventions 2010, eq. 5.15). The UT1-UTC correction is
+looked up internally:
+
+```ruby
+IERS::EarthRotationAngle.at(Time.utc(2020, 6, 15))  # => radians, in [0, 2π)
+```
+
+### Greenwich Mean Sidereal Time
+
+Compute GMST (IERS Conventions 2010, eq. 5.32). Uses ERA internally and adds
+the equinox-based polynomial evaluated at TT:
+
+```ruby
+IERS::GMST.at(Time.utc(2020, 6, 15))  # => radians, in [0, 2π)
+```
+
+### Terrestrial rotation matrix
+
+Compute R(ERA) × W, the rotation from ITRS to TIRS (IERS Conventions 2010,
+eq. 5.1), combining the Earth Rotation Angle and the polar motion matrix (W):
+
+```ruby
+r = IERS::TerrestrialRotation.at(Time.utc(2020, 6, 15))
+r.length     # => 3
+r[0].length  # => 3
+```
+
+Returns a 3×3 nested `Array` (row-major).
+
+### Earth Orientation Parameters (unified)
+
+Query all EOP components at once:
+
+```ruby
+eop = IERS::EOP.at(Time.utc(2020, 6, 15))
+eop.polar_motion_x   # => arcseconds
+eop.polar_motion_y   # => arcseconds
+eop.ut1_utc          # => seconds
+eop.length_of_day    # => seconds
+eop.celestial_pole_x # => milliarcseconds
+eop.celestial_pole_y # => milliarcseconds
+eop.observed?        # => true
+eop.date             # => #<Date: 2020-06-15>
+```
+
+Retrieve daily EOP over a date range:
+
+```ruby
+entries = IERS::EOP.between(
+  Date.new(2020, 1, 1),
+  Date.new(2020, 1, 31)
+)
+```
+
+### Leap seconds
+
+Look up TAI−UTC at a given date:
+
+```ruby
+IERS::LeapSecond.at(Time.utc(2017, 1, 1))  # => 37.0 (seconds)
+```
+
+List all leap seconds:
+
+```ruby
+IERS::LeapSecond.all
+# => [#<data IERS::LeapSecond::Entry effective_date=#<Date: 1972-01-01>, tai_utc=10.0>, ...]
+```
+
+Check for a future scheduled leap second:
+
+```ruby
+IERS::LeapSecond.next_scheduled  # => #<data IERS::LeapSecond::Entry ...> or nil
+```
+
+### TAI
+
+Convert between UTC and TAI time scales:
+
+```ruby
+tai_mjd = IERS::TAI.utc_to_tai(Time.utc(2017, 1, 1))  # => MJD in TAI
+utc_mjd = IERS::TAI.tai_to_utc(mjd: tai_mjd)           # => MJD in UTC
+```
+
+### Time input
+
+All query methods accept Ruby `Time`, `Date`, and `DateTime` objects as
+positional arguments. You can also use keyword arguments for numeric Julian
+Dates:
+
+```ruby
+IERS::UT1.at(mjd: 58849.0)        # Modified Julian Date
+IERS::UT1.at(jd: 2458849.5)       # Julian Date
+IERS::UT1.at(Time.utc(2020, 1, 1)) # Ruby Time
+```
+
+### Data freshness
+
+Check that predictions cover enough of the future before relying on
+query results:
+
+```ruby
+begin
+  IERS::Data.ensure_fresh!(coverage_days_ahead: 90)
+rescue IERS::StaleDataError => e
+  puts "Predictions end #{e.predicted_until}, need #{e.required_until}"
+  IERS::Data.update!
+end
+```
+
+Without `coverage_days_ahead`, the check ensures predictions cover today.
+
+### Data status and cache management
+
+```ruby
+status = IERS::Data.status
+status.cached?    # => true if downloaded data exists
+status.cache_age  # => age in seconds, or nil
+
+IERS::Data.clear_cache!  # remove downloaded files
+```
+
+### Custom data paths
+
+Point the gem at your own copies of the IERS data files:
+
+```ruby
+IERS.configure do |config|
+  config.finals_path = "/path/to/finals2000A.all"
+  config.leap_second_path = "/path/to/Leap_Second.dat"
+end
+```
+
+### Configuration
+
+```ruby
+IERS.configure do |config|
+  config.cache_dir = "/path/to/cache"
+  config.interpolation = :linear   # default: :lagrange
+  config.lagrange_order = 6        # default: 4
+  config.download_timeout = 60     # default: 30 (seconds)
+end
+```
+
+To fully reset configuration and cached data:
+
+```ruby
+IERS.reset!
+```
+
+### Error handling
+
+All errors inherit from `IERS::Error`:
+
+- `IERS::DataError`: base for data-related errors
+  - `IERS::ParseError`: malformed data file
+  - `IERS::FileNotFoundError`: data file not found
+  - `IERS::StaleDataError`: predictions don't extend far enough
+- `IERS::DownloadError`: base for download-related errors
+  - `IERS::NetworkError`: HTTP or connection failure
+  - `IERS::ValidationError`: downloaded file failed validation
+- `IERS::OutOfRangeError` — query outside data coverage
+- `IERS::ConfigurationError` — invalid configuration
 
 ## Development
 
@@ -40,6 +367,9 @@ The gem is available as open source under the terms of the [MIT License].
 Everyone interacting in the IERS Ruby project's codebases, issue trackers, chat
 rooms and mailing lists is expected to follow the [code of conduct].
 
+[IERS]: https://www.iers.org
+[IERS Earth Orientation Center]: https://hpiers.obspm.fr/eop-pc/
+[USNO Rapid Service/Prediction Center]: https://maia.usno.navy.mil/ser7/
 [Bundler]: https://bundler.io
 [rubygems.org]: https://rubygems.org
 [MIT License]: https://opensource.org/licenses/MIT

data/data/Leap_Second.dat

@@ -0,0 +1,41 @@
+#  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
+#  
+#
+#  File expires on 28 December 2026
+#
+#
+#    MJD        Date        TAI-UTC (s)
+#           day month year
+#    ---    --------------   ------   
+#
+    41317.0    1  1 1972       10
+    41499.0    1  7 1972       11
+    41683.0    1  1 1973       12
+    42048.0    1  1 1974       13
+    42413.0    1  1 1975       14
+    42778.0    1  1 1976       15
+    43144.0    1  1 1977       16
+    43509.0    1  1 1978       17
+    43874.0    1  1 1979       18
+    44239.0    1  1 1980       19
+    44786.0    1  7 1981       20
+    45151.0    1  7 1982       21
+    45516.0    1  7 1983       22
+    46247.0    1  7 1985       23
+    47161.0    1  1 1988       24
+    47892.0    1  1 1990       25
+    48257.0    1  1 1991       26
+    48804.0    1  7 1992       27
+    49169.0    1  7 1993       28
+    49534.0    1  7 1994       29
+    50083.0    1  1 1996       30
+    50630.0    1  7 1997       31
+    51179.0    1  1 1999       32
+    53736.0    1  1 2006       33
+    54832.0    1  1 2009       34
+    56109.0    1  7 2012       35
+    57204.0    1  7 2015       36
+    57754.0    1  1 2017       37