horologium 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 513d825c2d141d84274c76333af312631c4b9a077803d2e2921033782af518ce
-  data.tar.gz: '0108ee60e9bf9c1f149baefafe6e78f8d735dd824148ed91c69267b5ca10aad8'
+  metadata.gz: 65e0d322bb82639c79c818b3c8473f507ecfcb25215c522f20d41c5ef7f5be25
+  data.tar.gz: 1d2d822d56768a6d9383cc29a700208e03ef3e6f639460d1a99b4eb18e01e1de
 SHA512:
-  metadata.gz: edfa8b82fc1b2d4f795abbf0c01b0a9753cbfb31aa03c37de952b5ea64e62687207bb4efde740d05246ec9df63b6226d682d998ef5d917e401f48fae2cf4402d
-  data.tar.gz: a75b50d13419e546ae0b8cca4d0dce80d078a90578e3e80664a65b2f207ae5535900eb9f36a6291b5a303ce41ccd834b9cd5c226c46e4992d081cf1949b2ba56
+  metadata.gz: b4c87cfb9449bb41e362d2596c03ff44e2907ab593c332eb37155fb833b7d8a366911eece54a0759fff1e72410599c244c82d6757d49df66edf904783115f811
+  data.tar.gz: 3fda2d236fb3c9afaa33e921a0a3e3738518df46cefc9e10146acf590f144cdd67f4c162448fef7c2a002ba62cd74efbd45f500b069c91e8a8020341ec082f22

data/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.0.4 - 2026-09-05
+
+The epochs astronomy counts from arrive as instants, a duration reads back in
+the unit you want it in, and the conversions cost a good deal less than they
+did.
+
+### Features
+
+- Add `Epochs`, with `J2000`, `J1900`, `GPS_ZERO`, `UNIX` and
+  `TT_TCG_TCB_ORIGIN`. An epoch is an ordinary `Instant`, so the time elapsed
+  since one is a subtraction and no Julian Date is involved
+- Add the `Duration` constructors `minutes`, `hours`, `julian_years`,
+  `julian_centuries` and `zero`, where a Julian year is exactly 365.25 days and
+  a Julian century 36,525
+- Add `Duration#in_seconds`, `#in_minutes`, `#in_hours`, `#in_days`,
+  `#in_julian_years` and `#in_julian_centuries`, which come out as a Float at
+  `:standard` and a Rational at `:exact`
+- Add `zero?`, `negative?` and `positive?` to `Numeric::TwoPartFloat` and
+  `Numeric::Exact`, and `Numeric::Precision.compare`, which orders two values
+  by the number they denote whatever precision each is held in
+
+### Improvements
+
+- Build an instant in about half the time at `:standard` and a third less at
+  `:exact`, allocating 3 objects where it allocated 30. An instant no longer
+  works out its exact Rational value when it is built, the two-part arithmetic
+  keeps its intermediate parts in Floats, and a Julian Date given as a single
+  Float skips a step it does not need
+- Read UTC twice as fast at `:standard` and a third faster at `:exact`. The
+  conversion reads each leap second offset once, and settles the day without
+  spelling the value out as a Rational
+- Read `ScaleReading#provenance` from the scale that took the reading, when it
+  is asked rather than on every reading
+
+**Full Changelog**: https://github.com/rhannequin/horologium/compare/v0.0.3...v0.0.4
+
 ## 0.0.3 - 2026-08-22
 
 The scale conversions arrive. An instant is now a point with no scale of its

data/README.md

@@ -94,6 +94,10 @@ Horologium::Instant.from_tai(2025, 5, 1, 12, 0, 0)
 Horologium::Instant.from_tdb(2025, 5, 1, 12, 0, 0)
 ```
 
+TDB is the one scale that rests on a model rather than a definition. Horologium
+runs the full 787-term Fairhead and Bretagnon series, the one [ERFA] evaluates
+in `dtdb`, rather than a truncation of it.
+
 A date that does not exist is refused rather than rolled over, and the message
 says which field is wrong.
 
@@ -218,6 +222,20 @@ so a duration and a calendar day are different things.
 Horologium::Duration.days(1) == Horologium::Duration.seconds(86_400)  # => true
 Horologium::Duration.nanoseconds(1_000_000_000) ==
   Horologium::Duration.seconds(1)                                     # => true
+
+Horologium::Duration.minutes(90)
+Horologium::Duration.hours(6)
+Horologium::Duration.zero
+```
+
+A Julian year is exactly 365.25 days and a Julian century is 36,525 days. They
+are astronomical constants. A calendar year holds 365 or 366 days, so a Julian
+year lands a few hours away from the same date next year.
+
+```rb
+Horologium::Duration.julian_years(1) ==
+  Horologium::Duration.days(365.25)     # => true
+Horologium::Duration.julian_centuries(0.25)
 ```
 
 Durations add, subtract, and negate among themselves, and read back out in SI
@@ -232,6 +250,19 @@ Horologium::Duration.days(1).to_r  # => (86400/1), the whole value
 Horologium::Duration.days(1).to_f  # => 86400.0
 ```
 
+A duration also reads in a unit. The division happens inside the precision the
+duration is held in, so a `:standard` duration keeps the digits a collapsed
+`Float` would lose, and an `:exact` one reads as a `Rational`.
+
+```rb
+Horologium::Duration.days(1).in_hours                  # => 24.0
+Horologium::Duration.hours(12).in_days                 # => 0.5
+Horologium::Duration.days(36_525).in_julian_centuries  # => 1.0
+
+exact = Horologium::Duration.julian_years(1, precision: :exact)
+exact.in_days  # => (1461/4)
+```
+
 Adding a duration to an instant makes sense, but adding two instants together
 does not, so it raises an error.
 
@@ -239,6 +270,30 @@ does not, so it raises an error.
 instant + instant  # => raises Horologium::DimensionalError
 ```
 
+The astronomical epochs are built as instants, so the elapsed time since one is
+a subtraction and no Julian Date is involved.
+
+```rb
+instant = Horologium::Instant.from_tt(2026, 1, 1)
+
+(instant - Horologium::Epochs::J2000).to_f  # => 820497600.0 SI seconds
+```
+
+The scale is part of an epoch's definition. `J2000` is noon TT, which is 64.184
+seconds away from noon UTC on the same day.
+
+```rb
+Horologium::Epochs::J2000              # 2000-01-01 12:00:00 TT
+Horologium::Epochs::J1900              # 1899-12-31 12:00:00 TT
+Horologium::Epochs::GPS_ZERO           # 1980-01-06 00:00:00 UTC
+Horologium::Epochs::UNIX               # 1970-01-01 00:00:00 UTC
+Horologium::Epochs::TT_TCG_TCB_ORIGIN  # 1977-01-01 00:00:00 TAI
+```
+
+An epoch is fixed at `:exact`, since it is a definition. Subtracting one from a
+`:standard` instant gives an `:exact` duration, the way any other mix of the two
+does.
+
 Exact equality is rarely what scientific code wants, so you can compare within a
 tolerance:
 
@@ -261,8 +316,8 @@ with ordinary floating-point arithmetic.
 
 Every value carries one of two precisions, fixed when it is built:
 
-- `:standard`, the default, keeps the value as a two-part float. It is fast and
-  stays within a few nanoseconds of the true value.
+- `:standard`, the default, keeps the value as a two-part float. It stays
+  within a few nanoseconds of the true value.
 - `:exact` keeps the value as a `Rational`, with no rounding. The test suite
   uses it to check that `:standard` stays within its stated precision.
 
@@ -291,12 +346,30 @@ Horologium.with_precision(:exact) do
 end
 ```
 
+A library can depend on Horologium without taking the configuration away from
+the application that depends on it. Reading the configuration does not freeze
+it, so a gem that converts an instant while it loads still leaves
+`Horologium.configure` open to the host. And a value built with an explicit
+`precision:` ignores the default, so a gem that pins its own precision computes
+the same thing whatever the host sets.
+
 Exactness is contagious. An operation between two `:standard` values stays
 `:standard`. Mixing a `:standard` and an `:exact` value gives an `:exact`
 result, so precision is not quietly lost. `:exact` guarantees the arithmetic
 Horologium performs. It cannot bring back precision that an input already lost
 when it was built.
 
+A `:standard` value turns a `Rational` into a pair of `Float`s on the way in and
+back again on the way out, and that conversion costs more than the arithmetic it
+feeds. So `:exact` is the faster one whenever a `Rational` goes in or comes out,
+by up to about twice on a build and a read. With a `Float` in and a `Float` out
+the two are close enough that the machine decides. `:standard` is the cheaper
+one for a long run of arithmetic between values already held that way. Mixing
+the two is the expensive case, because promoting a `:standard` value to a
+`Rational` costs more than the operation it is promoted for, so inside a loop it
+is worth keeping to one precision. `bin/benchmark` measures all of this on your
+own machine.
+
 ## Status
 
 This library is in early development, before its first public release. The
@@ -315,6 +388,12 @@ which is enforced at 100% of lines and branches in CI. You can also run
 holds stubs for gems that ship none of their own, and stays out of the gem so
 it cannot clash with a downstream RBS collection.
 
+Run `bin/benchmark` to time the paths a consumer runs in a loop and count the
+objects each one allocates. Timings drift by a few percent between runs, so it
+rotates the order of the cases and reports the fastest round for each. The
+allocation counts do not drift, so where a timing and a count disagree, trust
+the count. Run it on a branch and on `main` to compare.
+
 Run `bin/ci` to run every check that GitHub Actions runs (RuboCop, Steep, YARD
 documentation coverage, and the tests with coverage) in a single pass. It runs
 each check even when an earlier one fails, so you see everything that needs

data/lib/horologium/duration.rb

@@ -15,15 +15,31 @@ module Horologium
   # Adding an Instant to a Duration raises {DimensionalError}; it is
   # {Instant#+} that shifts a point by a span.
   #
+  # A duration reads back in a unit with {#in_seconds}, {#in_minutes},
+  # {#in_hours}, {#in_days}, {#in_julian_years} and {#in_julian_centuries}.
+  # They come out as a Float at +:standard+ and a Rational at +:exact+.
+  #
   # @example A day is a fixed number of SI seconds
   #   Horologium::Duration.days(1) == Horologium::Duration.seconds(86_400)
   #   # => true
   class Duration
     include PreciseValue
 
+    # The number of SI seconds in a minute.
+    SECONDS_PER_MINUTE = 60
+
+    # The number of SI seconds in an hour.
+    SECONDS_PER_HOUR = 3_600
+
     # The number of SI seconds in a day.
     SECONDS_PER_DAY = 86_400
 
+    # The number of SI seconds in a Julian year of 365.25 days.
+    SECONDS_PER_JULIAN_YEAR = 31_557_600
+
+    # The number of SI seconds in a Julian century of 36,525 days.
+    SECONDS_PER_JULIAN_CENTURY = 3_155_760_000
+
     # The number of nanoseconds in a second.
     NANOSECONDS_PER_SECOND = 1_000_000_000
 
@@ -40,6 +56,30 @@ module Horologium
         from_seconds(count, precision)
       end
 
+      # A duration of +count+ minutes.
+      #
+      # @param count [Numeric] the number of minutes
+      # @param precision [Symbol] +:standard+ or +:exact+, taken from the
+      #   precision in effect when omitted
+      # @return [Horologium::Duration]
+      # @example
+      #   Horologium::Duration.minutes(90)
+      def minutes(count, precision: Horologium.current_precision)
+        from_seconds(count * SECONDS_PER_MINUTE, precision)
+      end
+
+      # A duration of +count+ hours.
+      #
+      # @param count [Numeric] the number of hours
+      # @param precision [Symbol] +:standard+ or +:exact+, taken from the
+      #   precision in effect when omitted
+      # @return [Horologium::Duration]
+      # @example
+      #   Horologium::Duration.hours(6)
+      def hours(count, precision: Horologium.current_precision)
+        from_seconds(count * SECONDS_PER_HOUR, precision)
+      end
+
       # A duration of +count+ days, each of {SECONDS_PER_DAY} SI seconds. This
       # counts time and is not tied to the calendar.
       #
@@ -54,6 +94,36 @@ module Horologium
         from_seconds(count * SECONDS_PER_DAY, precision)
       end
 
+      # A duration of +count+ Julian years, each of exactly 365.25 days. It is
+      # the astronomical constant, and a calendar year holds 365 or 366 days,
+      # so shifting an instant by a Julian year lands a few hours away from
+      # the same date next year.
+      #
+      # @param count [Numeric] the number of Julian years
+      # @param precision [Symbol] +:standard+ or +:exact+, taken from the
+      #   precision in effect when omitted
+      # @return [Horologium::Duration]
+      # @example
+      #   Horologium::Duration.julian_years(1) ==
+      #     Horologium::Duration.days(365.25) # => true
+      def julian_years(count, precision: Horologium.current_precision)
+        from_seconds(count * SECONDS_PER_JULIAN_YEAR, precision)
+      end
+
+      # A duration of +count+ Julian centuries, each of a hundred Julian
+      # years, or 36,525 days. It is the unit the astronomical series count
+      # their time in.
+      #
+      # @param count [Numeric] the number of Julian centuries
+      # @param precision [Symbol] +:standard+ or +:exact+, taken from the
+      #   precision in effect when omitted
+      # @return [Horologium::Duration]
+      # @example
+      #   Horologium::Duration.julian_centuries(0.25)
+      def julian_centuries(count, precision: Horologium.current_precision)
+        from_seconds(count * SECONDS_PER_JULIAN_CENTURY, precision)
+      end
+
       # A duration of +count+ nanoseconds.
       #
       # @param count [Numeric] the number of nanoseconds
@@ -66,6 +136,17 @@ module Horologium
         from_seconds(Rational(count) / NANOSECONDS_PER_SECOND, precision)
       end
 
+      # A duration of no time at all.
+      #
+      # @param precision [Symbol] +:standard+ or +:exact+, taken from the
+      #   precision in effect when omitted
+      # @return [Horologium::Duration]
+      # @example
+      #   Horologium::Duration.zero.zero? # => true
+      def zero(precision: Horologium.current_precision)
+        from_seconds(0, precision)
+      end
+
       private
 
       # Builds a duration of +seconds+ SI seconds at the given precision. At
@@ -134,24 +215,83 @@ module Horologium
 
     # @return [Boolean]
     def zero?
-      rational.zero?
+      value.zero?
     end
 
     # @return [Boolean]
     def negative?
-      rational.negative?
+      value.negative?
     end
 
     # @return [Boolean]
     def positive?
-      rational.positive?
+      value.positive?
+    end
+
+    # The duration in SI seconds.
+    #
+    # @return [Float, Rational] a Float at +:standard+, a Rational at
+    #   +:exact+
+    # @example
+    #   Horologium::Duration.days(1).in_seconds # => 86400.0
+    def in_seconds
+      in_unit(1)
+    end
+
+    # The duration in minutes of {SECONDS_PER_MINUTE} SI seconds each.
+    #
+    # @return [Float, Rational] a Float at +:standard+, a Rational at
+    #   +:exact+
+    # @example
+    #   Horologium::Duration.hours(1).in_minutes # => 60.0
+    def in_minutes
+      in_unit(SECONDS_PER_MINUTE)
+    end
+
+    # The duration in hours of {SECONDS_PER_HOUR} SI seconds each.
+    #
+    # @return [Float, Rational] a Float at +:standard+, a Rational at
+    #   +:exact+
+    # @example
+    #   Horologium::Duration.days(1).in_hours # => 24.0
+    def in_hours
+      in_unit(SECONDS_PER_HOUR)
+    end
+
+    # The duration in days of {SECONDS_PER_DAY} SI seconds each.
+    #
+    # @return [Float, Rational] a Float at +:standard+, a Rational at
+    #   +:exact+
+    # @example
+    #   Horologium::Duration.hours(12).in_days # => 0.5
+    def in_days
+      in_unit(SECONDS_PER_DAY)
+    end
+
+    # The duration in Julian years of 365.25 days each.
+    #
+    # @return [Float, Rational] a Float at +:standard+, a Rational at
+    #   +:exact+
+    def in_julian_years
+      in_unit(SECONDS_PER_JULIAN_YEAR)
+    end
+
+    # The duration in Julian centuries of 36,525 days each. It is the time
+    # argument the astronomical series are written for.
+    #
+    # @return [Float, Rational] a Float at +:standard+, a Rational at
+    #   +:exact+
+    # @example
+    #   Horologium::Duration.days(36_525).in_julian_centuries # => 1.0
+    def in_julian_centuries
+      in_unit(SECONDS_PER_JULIAN_CENTURY)
     end
 
     # The duration in SI seconds, exactly.
     #
     # @return [Rational]
     def to_r
-      rational
+      value.to_r
     end
 
     # The duration in SI seconds. A Float has about 15 digits, so a long
@@ -166,5 +306,19 @@ module Horologium
     def inspect
       format("#<%s %s s (%s)>", self.class, to_f, precision)
     end
+
+    private
+
+    # The duration counted in a unit. The division happens in the precision
+    # the duration is held in, so the digits survive it.
+    #
+    # @param seconds_per_unit [Integer] the SI seconds one unit holds
+    # @return [Float, Rational] a Float at +:standard+, a Rational at
+    #   +:exact+
+    def in_unit(seconds_per_unit)
+      return value.to_r / seconds_per_unit if precision == :exact
+
+      (value / seconds_per_unit).to_f
+    end
   end
 end

data/lib/horologium/epochs.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Horologium
+  # The astronomical epochs, built as instants. An epoch is an ordinary
+  # {Instant}, so the elapsed time since one is a subtraction and no Julian
+  # Date is involved.
+  #
+  # The scale is part of an epoch's definition. {J2000} is noon TT, which is
+  # 64.184 seconds away from noon UTC on the same day. The two epochs defined
+  # in UTC are given in TAI, with the TAI - UTC offset of their day written
+  # into the constant, so requiring the library reads no leap second data.
+  #
+  # An epoch is fixed at +:exact+, since it is a definition. Subtracting one
+  # from a +:standard+ instant gives an +:exact+ {Duration}, the way any other
+  # mix of the two does.
+  #
+  # @example The time elapsed since J2000
+  #   instant = Horologium::Instant.from_tt(2026, 1, 1)
+  #   (instant - Horologium::Epochs::J2000).to_f # => 820497600.0
+  module Epochs
+    # 2000-01-01 12:00:00 TT, Julian Date 2451545.0 in TT. The epoch the
+    # current theories of the solar system motion are written for.
+    J2000 = Instant.from_tt(2000, 1, 1, 12, precision: :exact)
+
+    # 1899-12-31 12:00:00 TT, Julian Date 2415020.0 in TT. It is one Julian
+    # century of 36,525 days before {J2000}, and it is what the older formulae
+    # count from. The date is a day earlier than the name suggests.
+    J1900 = Instant.from_tt(1899, 12, 31, 12, precision: :exact)
+
+    # 1980-01-06 00:00:00 UTC, where GPS time starts. TAI - UTC was 19 seconds
+    # on that day. GPS time counts SI seconds from here, so it stays a fixed
+    # offset from TAI.
+    GPS_ZERO = Instant.from_tai(1980, 1, 6, 0, 0, 19, precision: :exact)
+
+    # 1970-01-01 00:00:00 UTC, where Unix time starts. UTC was still steered
+    # by rate adjustments in 1970, so TAI - UTC was 8.000082 seconds on that
+    # day.
+    UNIX = Instant.from_tai(
+      1970, 1, 1, 0, 0,
+      Rational(8_000_082, 1_000_000),
+      precision: :exact
+    )
+
+    # 1977-01-01 00:00:00 TAI, Julian Date 2443144.5003725 in TT. TT, TCG and
+    # TCB were set to read the same here, and the rates that separate them are
+    # counted from this point.
+    TT_TCG_TCB_ORIGIN = Instant.from_tai(1977, 1, 1, precision: :exact)
+  end
+end

data/lib/horologium/instant.rb

@@ -440,12 +440,7 @@ module Horologium
       time_scale = Horologium.configuration.scale(scale)
       reading = time_scale.from_reference(value, precision)
 
-      ScaleReading.new(
-        scale,
-        reading,
-        precision,
-        time_scale.provenance(reading)
-      )
+      ScaleReading.new(scale, reading, precision, time_scale)
     end
 
     # The instant in a representation, read in a scale. This is the shorthand

data/lib/horologium/numeric/exact.rb

@@ -54,6 +54,21 @@ module Horologium
         self.class.new(value / scalar_rational(scalar))
       end
 
+      # @return [Boolean]
+      def zero?
+        value.zero?
+      end
+
+      # @return [Boolean]
+      def negative?
+        value.negative?
+      end
+
+      # @return [Boolean]
+      def positive?
+        value.positive?
+      end
+
       # @param other [Object]
       # @return [Boolean]
       def ==(other)

data/lib/horologium/numeric/precision.rb

@@ -25,9 +25,12 @@ module Horologium
         # @return [Symbol] the same precision
         # @raise [UnknownPrecisionError] when it is not one of {NAMES}
         def validate!(precision)
-          return precision if NAMES.include?(precision)
-
-          raise UnknownPrecisionError.new(precision, NAMES)
+          case precision
+          when :standard, :exact
+            precision
+          else
+            raise UnknownPrecisionError.new(precision, NAMES)
+          end
         end
 
         # The precision a result takes from its two operands. Same precision
@@ -102,6 +105,8 @@ module Horologium
         def add(left, right)
           if left.is_a?(TwoPartFloat) && right.is_a?(TwoPartFloat)
             left + right
+          elsif left.is_a?(Exact) && right.is_a?(Exact)
+            left + right
           else
             promote(left) + promote(right)
           end
@@ -116,11 +121,36 @@ module Horologium
         def subtract(left, right)
           if left.is_a?(TwoPartFloat) && right.is_a?(TwoPartFloat)
             left - right
+          elsif left.is_a?(Exact) && right.is_a?(Exact)
+            left - right
           else
             promote(left) - promote(right)
           end
         end
 
+        # Orders two values by the number they denote, whatever precision each
+        # is held in. Two two-part floats are compared through the difference
+        # of their parts, which is where the answer already is.
+        #
+        # That difference answers only when it is finite and away from zero.
+        # Reaching zero says the values are close rather than equal, and parts
+        # large enough to overflow can cancel into a NaN, so both cases are
+        # settled exactly instead.
+        #
+        # @param left [TwoPartFloat, Exact] one value
+        # @param right [TwoPartFloat, Exact] the other value
+        # @return [Integer] -1, 0, or 1
+        def compare(left, right)
+          if left.is_a?(TwoPartFloat) && right.is_a?(TwoPartFloat)
+            difference = (left.high - right.high) + (left.low - right.low)
+
+            return sign_of(difference) if difference.finite? &&
+              !difference.zero?
+          end
+
+          sign_of(left.to_r - right.to_r)
+        end
+
         # Checks that a value matches a precision: a {TwoPartFloat} for
         # +:standard+, an {Exact} for +:exact+.
         #
@@ -147,11 +177,28 @@ module Horologium
         # @return [Class] the type its values take
         # @raise [UnknownPrecisionError] when the precision is not recognised
         def value_type(precision)
-          (validate!(precision) == :exact) ? Exact : TwoPartFloat
+          case precision
+          when :standard
+            TwoPartFloat
+          when :exact
+            Exact
+          else
+            raise UnknownPrecisionError.new(precision, NAMES)
+          end
         end
 
         private
 
+        # Where a number sits against zero.
+        #
+        # @param number [Float, Rational] the number to read
+        # @return [Integer] -1 below zero, 0 at it, 1 above it
+        def sign_of(number)
+          return 0 if number.zero?
+
+          number.negative? ? -1 : 1
+        end
+
         # One side of an operation, as an exact value.
         #
         # @param value [TwoPartFloat, Exact] the value to promote