horologium 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7acd6f601c9ea6b6023d91c7b6891d82bede556ce4a744ab821b722615bb4f1c
-  data.tar.gz: f968a52ed82141bdadaef004483cfe56f48511e05d4c2c6db1b27c6557b53166
+  metadata.gz: 8ea577f62fb959e825d069499184cafa4b1b15d4702700a1588d3ac4b00b7c2b
+  data.tar.gz: 71b854eb59c20acaa9cd1adf77f17e97b2c0c03c9f62168dfba952f50f273dda
 SHA512:
-  metadata.gz: f6e0f093c7f13b748beed1a6c8a7f53dd18fdcddce28b3bd33caa8b06cd2ffd1a1042ca77569dd6766ca3572fc6e3cc108cb6defbbfd34c9bc389963c4cfda0f
-  data.tar.gz: c3f4bd6142298f451311c76bbbb210023ba04002f6677488d8b22ee850d58f4f127d671bd8d9b425034930ba27d8c00fe4fab6865e32d6b3b46bd80cb5d6ed14
+  metadata.gz: 8a5144d687290a581ef5ec2861f58383d35e7c416032bfbf351bc6033ab9f5889c57a3cb48bd812e52d4d19ee0b0688e929fe1e05e0d44231ac6b41f7d8e9251
+  data.tar.gz: a5070ecf423cf7d49623d547a133e9fb0907935843397f8336e989bc4e7816cbcc662af2acfed63913c852bdf5620ef03fd7ba0e660c50c9463f3d7aa22d6624

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.0.2 - 2026-07-14
+
+The first functional release. It ships the numeric core and the two value
+objects the rest of the library is built on: `Instant` and `Duration`. The
+scale conversions are not here yet, so an instant is built directly from a
+TAI Julian Date for now.
+
+### Features
+
+- Add `Numeric::TwoPartFloat`, a number kept as a high and a low `Float` for
+  about twice the precision of one, with Shewchuk error-free arithmetic
+- Add `Numeric::Exact`, a value kept as an exact `Rational`, with no rounding
+- Add the precision contract: every value carries a precision, `:standard` or
+  `:exact`, set when it is built and never changed. Mixing the two promotes
+  the result to `:exact` instead of dropping to `:standard`
+- Add `Horologium.configure` for the set-once default precision, and
+  `Horologium.with_precision` for a scoped, per-fiber override
+- Add `Instant`, a frozen point on the TAI timeline, built with
+  `Instant.from_tai_julian_date`
+- Add `Duration`, a frozen span in SI seconds, built with `Duration.seconds`,
+  `Duration.days`, and `Duration.nanoseconds`
+- Add instant and duration arithmetic: shift an instant by a duration, and
+  subtract two instants to measure the duration between them
+- Add `Instant#equal_within?` for comparison inside a tolerance
+- Guard against meaningless operations: adding two instants raises
+  `DimensionalError`
+
+**Full Changelog**: https://github.com/rhannequin/horologium/compare/v0.0.1...v0.0.2
+
 ## 0.0.1 - 2026-07-06
 
 - Gem creation

data/README.md

@@ -7,26 +7,140 @@ Horologium is a Ruby library dedicated to **scientific time**: the time scales
 intervals, and rigorous conversions between scales that astronomy and physics
 require.
 
+Ruby already has `Time`, `Date`, `DateTime`, and `ActiveSupport` for civil time:
+time zones, calendars, human formatting. None of them knows the difference
+between UTC and a continuous scale, the TAI, TT, and TDB scales an ephemeris
+needs, or a Julian Date kept precise to the nanosecond. That is the gap
+Horologium fills.
+
+## Content
+
+- [Installation](#installation)
+- [Usage](#usage)
+- [Precision](#precision)
+- [Status](#status)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+- [Code of Conduct](#code-of-conduct)
+
 ## Installation
 
-Install the gem and add it to the application's Gemfile by running:
+Install the gem and add it to the application's Gemfile by executing:
+
+    $ bundle add horologium
+
+If [Bundler] is not being used to manage dependencies, install the gem by
+executing:
+
+    $ gem install horologium
+
+## Usage
+
+An `Instant` is a single point on the timeline, kept internally as a TAI Julian
+Date. A `Duration` is an amount of time in SI seconds, with no date and no scale
+attached. You shift an instant by a duration, and you subtract two instants to
+get the duration between them.
+
+```rb
+require "horologium"
+
+instant = Horologium::Instant.from_tai_julian_date(2_460_000.5)
 
-```sh
-bundle add horologium
+later = instant + Horologium::Duration.days(1)
+later == Horologium::Instant.from_tai_julian_date(2_460_001.5)  # => true
+instant < later                                                 # => true
+
+b = Horologium::Instant.from_tai_julian_date(2_460_001.5)
+b - instant == Horologium::Duration.days(1)                     # => true
+```
+
+A `Duration` counts SI seconds, so `Duration.days(1)` is always 86,400 SI
+seconds. Because of leap seconds a civil day can be a second longer or shorter,
+so a duration and a calendar day are different things.
+
+```rb
+Horologium::Duration.days(1) == Horologium::Duration.seconds(86_400)  # => true
+Horologium::Duration.nanoseconds(1_000_000_000) ==
+  Horologium::Duration.seconds(1)                                     # => true
 ```
 
-Or install it directly:
+Adding a duration to an instant makes sense, but adding two instants together
+does not, so it raises an error.
+
+```rb
+instant + instant  # => raises Horologium::DimensionalError
+```
+
+Exact equality is rarely what scientific code wants, so you can compare within a
+tolerance:
+
+```rb
+a = Horologium::Instant.from_tai_julian_date(2_460_000.5)
+near = a + Horologium::Duration.nanoseconds(1)
 
-```sh
-gem install horologium
+a.equal_within?(near, Horologium::Duration.nanoseconds(2))  # => true
 ```
 
+## Precision
+
+A modern Julian Date is around 2.46 million. A single `Float` spends most of its
+digits on that large number and has only tens of microseconds left for the
+fraction of a day. That is too coarse for scientific time. Horologium stores an
+instant across two `Float`s whose sum is the Julian Date, so the second one
+starts where the first runs out of digits. This is the representation [ERFA]
+uses, it keeps the precision below a nanosecond for any date, and it does so
+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.
+- `:exact` keeps the value as a `Rational`, with no rounding. The test suite
+  uses it to check that `:standard` stays within its stated precision.
+
+Set the default once at boot:
+
+```rb
+Horologium.configure do |c|
+  c.default_precision = :exact
+end
+```
+
+Choose it for a single value, or for a scoped block:
+
+```rb
+Horologium::Instant.from_tai_julian_date(2_460_000.5, precision: :exact)
+
+Horologium.with_precision(:exact) do
+  # instants and durations built here default to :exact
+end
+```
+
+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.
+
+## Status
+
+This library is in early development, before its first public release. The
+public API is not stable, so new versions will probably introduce breaking
+changes until a 1.0 release. Changes are documented in the [CHANGELOG].
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run
 `rake` to run the tests and RuboCop, or `rake steep` to type-check the
-signatures in `sig/`. You can also run `bin/console` for an interactive prompt
-that will allow you to experiment.
+signatures in `sig/`. Run `COVERAGE=true rake test` to measure test coverage,
+which is enforced at a 95% line minimum in CI. You can also run `bin/console`
+for an interactive prompt that will allow you to experiment.
+
+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
+fixing at once.
 
 To install this gem onto your local machine, run `bundle exec rake install`. To
 release a new version, update the version number in `version.rb`, and then run
@@ -47,6 +161,9 @@ The gem is available as open source under the terms of the [MIT License].
 Everyone interacting in the Horologium project's codebases, issue trackers, chat
 rooms and mailing lists is expected to follow the [code of conduct].
 
+[Bundler]: https://bundler.io
+[ERFA]: https://github.com/liberfa/erfa
+[CHANGELOG]: https://github.com/rhannequin/horologium/blob/main/CHANGELOG.md
 [rubygems.org]: https://rubygems.org
 [MIT License]: https://opensource.org/licenses/MIT
 [code of conduct]: https://github.com/rhannequin/horologium/blob/main/CODE_OF_CONDUCT.md

data/Rakefile

@@ -2,16 +2,29 @@
 
 require "bundler/gem_tasks"
 require "minitest/test_task"
-
-Minitest::TestTask.create
-
 require "rubocop/rake_task"
+require "yard"
+
+Minitest::TestTask.create do |t|
+  t.framework = %(require "test_helper")
+end
 
 RuboCop::RakeTask.new
+YARD::Rake::YardocTask.new
 
 desc "Type check with Steep"
 task :steep do
   sh "steep check"
 end
 
+desc "Verify YARD documentation coverage is 100%"
+task :yard_coverage do
+  require "open3"
+  output, status = Open3.capture2e("yard", "stats", "--list-undoc")
+  puts output
+  unless status.success? && output.include?("100.00% documented")
+    abort "YARD documentation coverage is below 100%"
+  end
+end
+
 task default: %i[test rubocop]

data/lib/horologium/configuration.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Horologium
+  # Holds the library's settings. Today that is a single value, the default
+  # precision new instants and durations take when none is asked for. It is set
+  # once, inside {Horologium.configure}, and frozen afterwards, so behaviour
+  # does not depend on when in the process' life an object is read.
+  class Configuration
+    # @return [Symbol] the default precision, +:standard+ until configured
+    attr_reader :default_precision
+
+    def initialize
+      @default_precision = :standard
+    end
+
+    # Sets the default precision.
+    #
+    # @param precision [Symbol] +:standard+ or +:exact+
+    # @return [Symbol] the precision that was set
+    # @raise [ConfigurationError] once the configuration is frozen
+    # @raise [UnknownPrecisionError] when the precision is not recognised
+    def default_precision=(precision)
+      if frozen?
+        raise ConfigurationError, "the configuration is already frozen"
+      end
+
+      @default_precision = Numeric::Precision.validate!(precision)
+    end
+  end
+
+  class << self
+    # Configures the library. The yielded configuration is frozen when the
+    # block returns, so it can be set once at boot and not changed again.
+    #
+    # @yieldparam config [Configuration] the configuration to set
+    # @return [Configuration] the frozen configuration
+    # @example
+    #   Horologium.configure do |c|
+    #     c.default_precision = :exact
+    #   end
+    def configure
+      config = configuration
+      yield config if block_given?
+      config.freeze
+    end
+
+    # @return [Configuration] the current configuration, built with defaults if
+    #   the library has not been configured yet
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # @return [Symbol] the configured default precision
+    def default_precision
+      configuration.default_precision
+    end
+
+    # The precision in effect right now: the one set by {with_precision} if a
+    # scope is open, otherwise the default. This is what a constructor consults
+    # when it is not given a precision of its own.
+    #
+    # @return [Symbol] +:standard+ or +:exact+
+    def current_precision
+      Thread.current[:horologium_current_precision] || default_precision
+    end
+
+    # Runs the block with a chosen precision in effect, then restores whatever
+    # was in effect before. The scope is per-fiber, so it is safe to use in a
+    # threaded or fibered context and cannot leak into other work. It does not
+    # touch the frozen default.
+    #
+    # @param precision [Symbol] +:standard+ or +:exact+
+    # @return [Object] the block's return value
+    # @raise [UnknownPrecisionError] when the precision is not recognised
+    # @example
+    #   Horologium.with_precision(:exact) do
+    #     # instants built here default to :exact
+    #   end
+    def with_precision(precision)
+      Numeric::Precision.validate!(precision)
+      previous = Thread.current[:horologium_current_precision]
+      Thread.current[:horologium_current_precision] = precision
+      begin
+        yield
+      ensure
+        Thread.current[:horologium_current_precision] = previous
+      end
+    end
+
+    # Clears the configuration and any open precision scope. Meant for test
+    # isolation, so one test's configuration does not carry into another.
+    #
+    # @api private
+    # @return [void]
+    def reset_configuration!
+      @configuration = nil
+      Thread.current[:horologium_current_precision] = nil
+    end
+  end
+end

data/lib/horologium/duration.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Horologium
+  # An amount of time in SI seconds, with no date and no scale attached.
+  # +Duration.days(1)+ is always 86,400 SI seconds. Because of leap seconds a
+  # civil day can be a second longer or shorter, so a Duration and a calendar
+  # day are different things.
+  #
+  # A Duration is frozen. Its precision is set when it is built, from the
+  # precision in effect unless you pass one. At +:standard+ it holds the
+  # seconds as a {Numeric::TwoPartFloat}, at +:exact+ as a {Numeric::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 day.
+    SECONDS_PER_DAY = 86_400
+
+    # The number of nanoseconds in a second.
+    NANOSECONDS_PER_SECOND = 1_000_000_000
+
+    class << self
+      # A duration of +count+ SI seconds.
+      #
+      # @param count [Numeric] the number of seconds
+      # @param precision [Symbol] +:standard+ or +:exact+, taken from the
+      #   precision in effect when omitted
+      # @return [Horologium::Duration]
+      # @example
+      #   Horologium::Duration.seconds(3600)
+      def seconds(count, precision: Horologium.current_precision)
+        from_seconds(count, precision)
+      end
+
+      # A duration of +count+ days, each of {SECONDS_PER_DAY} SI seconds. This
+      # counts time and is not tied to the calendar.
+      #
+      # @param count [Numeric] the number of days
+      # @param precision [Symbol] +:standard+ or +:exact+, taken from the
+      #   precision in effect when omitted
+      # @return [Horologium::Duration]
+      # @example
+      #   Horologium::Duration.days(1) == Horologium::Duration.seconds(86_400)
+      #   # => true
+      def days(count, precision: Horologium.current_precision)
+        from_seconds(count * SECONDS_PER_DAY, precision)
+      end
+
+      # A duration of +count+ nanoseconds.
+      #
+      # @param count [Numeric] the number of nanoseconds
+      # @param precision [Symbol] +:standard+ or +:exact+, taken from the
+      #   precision in effect when omitted
+      # @return [Horologium::Duration]
+      # @example
+      #   Horologium::Duration.nanoseconds(1)
+      def nanoseconds(count, precision: Horologium.current_precision)
+        from_seconds(Rational(count) / NANOSECONDS_PER_SECOND, precision)
+      end
+
+      private
+
+      # Builds a duration of +seconds+ SI seconds at the given precision. At
+      # +:exact+ the seconds stay a Rational; at +:standard+ they become a
+      # two-part float. Unit scaling happens on the plain input, before this.
+      #
+      # @param seconds [Numeric] the number of SI seconds
+      # @param precision [Symbol] the precision to build
+      # @return [Horologium::Duration]
+      def from_seconds(seconds, precision)
+        value =
+          case Numeric::Precision.validate!(precision)
+          when :exact
+            Numeric::Exact.new(seconds)
+          else
+            Numeric::TwoPartFloat.from_real(seconds)
+          end
+        new(value, precision)
+      end
+    end
+
+    # The same length, never negative.
+    #
+    # @return [Horologium::Duration]
+    # @example
+    #   Horologium::Duration.seconds(-3).abs ==
+    #     Horologium::Duration.seconds(3)
+    #   # => true
+    def abs
+      rational.negative? ? self.class.new(value * -1, precision) : self
+    end
+  end
+end

data/lib/horologium/error.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Horologium
+  # Base class for all errors raised by Horologium. Every error the library
+  # raises descends from it, so a caller can rescue Horologium as a unit.
+  class Error < StandardError; end
+
+  # Raised when the configuration is changed after it has been frozen. The
+  # global default is set once, inside {Horologium.configure}, and locked
+  # afterwards.
+  class ConfigurationError < Error; end
+
+  # Raised when an operation mixes quantities that do not combine, such as
+  # adding two instants. Only a point plus or minus a duration, and the
+  # difference of two points, are meaningful.
+  class DimensionalError < Error; end
+
+  # Raised when a precision the library does not recognise is given, to the
+  # configuration or when building a value. It carries the known precisions so
+  # the caller can see the valid choices.
+  class UnknownPrecisionError < Error
+    # The precisions the library recognises.
+    #
+    # @return [Array<Symbol>]
+    attr_reader :known_precisions
+
+    # @param precision [Object] the unknown precision that was given
+    # @param known_precisions [Array<Symbol>] the recognised precisions
+    def initialize(precision, known_precisions)
+      @known_precisions = known_precisions.dup.freeze
+      super(
+        "unknown precision #{precision.inspect}, " \
+        "expected one of #{known_precisions.map(&:inspect).join(", ")}"
+      )
+    end
+  end
+end

data/lib/horologium/instant.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Horologium
+  # A single point on the timeline, independent of any scale. It is stored as
+  # a TAI Julian Date, in days, at a fixed precision.
+  #
+  # An Instant is frozen. Its precision is set when it is built, from the
+  # precision in effect unless you pass one. At +:standard+ the Julian Date is
+  # a {Numeric::TwoPartFloat}, at +:exact+ a {Numeric::Exact}.
+  #
+  # You can add or subtract a Duration, and subtract another Instant to get
+  # the Duration between them. Adding two instants raises {DimensionalError}.
+  # Mixing a +:standard+ and an +:exact+ operand gives an +:exact+ result.
+  #
+  # @example Shift an instant, then measure back to it
+  #   instant = Horologium::Instant.from_tai_julian_date(2_460_000.5)
+  #   later = instant + Horologium::Duration.seconds(3600)
+  #   (later - instant) == Horologium::Duration.seconds(3600)
+  #   # => true
+  class Instant
+    include PreciseValue
+
+    # Builds an instant from a TAI Julian Date, split into a high and a low
+    # part in days. At +:exact+ the two parts are kept as a Rational, with no
+    # loss. At +:standard+ they are normalized so the high part sits on the
+    # integer-day grid and the low part holds the fraction, in [-0.5, 0.5].
+    #
+    # @param high [Float] the high part of the Julian Date, in days
+    # @param low [Float] the low part, in days
+    # @param precision [Symbol] +:standard+ or +:exact+, taken from the
+    #   precision in effect when omitted
+    # @return [Horologium::Instant]
+    # @example
+    #   Horologium::Instant.from_tai_julian_date(2_443_144.5, 0.000_372_5)
+    def self.from_tai_julian_date(
+      high,
+      low = 0.0,
+      precision: Horologium.current_precision
+    )
+      value =
+        case Numeric::Precision.validate!(precision)
+        when :exact
+          Numeric::Exact.new(Numeric::TwoPartFloat.new(high, low))
+        else
+          Numeric::TwoPartFloat.normalize(high, low)
+        end
+      new(value, precision)
+    end
+
+    # Adds a duration and returns a later instant.
+    #
+    # @param duration [Horologium::Duration] the amount to move forward
+    # @return [Horologium::Instant]
+    # @raise [DimensionalError] when given anything but a Duration
+    # @example
+    #   Horologium::Instant.from_tai_julian_date(2_460_000.5) +
+    #     Horologium::Duration.days(1)
+    def +(duration) # rubocop:disable Naming/BinaryOperatorParameterName
+      unless duration.is_a?(Duration)
+        raise DimensionalError,
+          "cannot add a #{duration.class} to an Instant; " \
+          "only a Duration shifts an Instant"
+      end
+
+      precision = Numeric::Precision.resolve(self.precision, duration.precision)
+      days = seconds_to_days(duration, precision)
+      self.class.new(add(value, days), precision)
+    end
+
+    # Subtracts a duration to get an earlier instant, or another instant to
+    # get the Duration between them.
+    #
+    # @param other [Horologium::Duration, Horologium::Instant]
+    # @return [Horologium::Instant, Horologium::Duration]
+    # @raise [DimensionalError] when given anything else
+    # @example An earlier instant
+    #   Horologium::Instant.from_tai_julian_date(2_460_000.5) -
+    #     Horologium::Duration.days(1)
+    # @example The Duration between two instants
+    #   a = Horologium::Instant.from_tai_julian_date(2_460_000.5)
+    #   b = Horologium::Instant.from_tai_julian_date(2_460_001.5)
+    #   b - a == Horologium::Duration.days(1) # => true
+    def -(other)
+      case other
+      when Duration
+        precision = Numeric::Precision.resolve(self.precision, other.precision)
+        days = seconds_to_days(other, precision)
+        self.class.new(subtract(value, days), precision)
+      when Instant
+        precision = Numeric::Precision.resolve(self.precision, other.precision)
+        gap = subtract(value, other.value)
+        Duration.new(gap * Duration::SECONDS_PER_DAY, precision)
+      else
+        raise DimensionalError,
+          "cannot subtract a #{other.class} from an Instant; " \
+          "subtract a Duration or another Instant"
+      end
+    end
+
+    # Whether two instants fall within a tolerance of each other. Use this
+    # rather than +==+ in scientific code.
+    #
+    # @param other [Horologium::Instant] the instant to compare with
+    # @param tolerance [Horologium::Duration] the largest gap counted as equal
+    # @return [Boolean]
+    # @example
+    #   a = Horologium::Instant.from_tai_julian_date(2_460_000.5)
+    #   b = a + Horologium::Duration.nanoseconds(1)
+    #   a.equal_within?(b, Horologium::Duration.nanoseconds(2)) # => true
+    def equal_within?(other, tolerance)
+      unless other.is_a?(Instant)
+        raise DimensionalError,
+          "cannot compare an Instant with a #{other.class}"
+      end
+      unless tolerance.is_a?(Duration)
+        raise DimensionalError,
+          "a tolerance must be a Duration, got a #{tolerance.class}"
+      end
+
+      (self - other).abs <= tolerance
+    end
+
+    private
+
+    # The duration's seconds counted in days, at the given precision. A Julian
+    # Date counts days, so a duration is scaled before it is added.
+    #
+    # @param duration [Horologium::Duration]
+    # @param precision [Symbol]
+    # @return [Horologium::Numeric::TwoPartFloat, Horologium::Numeric::Exact]
+    def seconds_to_days(duration, precision)
+      Numeric::Precision.coerce(duration.value, to: precision) /
+        Duration::SECONDS_PER_DAY
+    end
+
+    # Adds two values. Two standard values add as two-part floats; if either
+    # is exact, both are promoted to exact Rationals first.
+    def add(left, right)
+      if left.is_a?(Numeric::TwoPartFloat) && right.is_a?(Numeric::TwoPartFloat)
+        left + right
+      else
+        Numeric::Precision.coerce(left, to: :exact) +
+          Numeric::Precision.coerce(right, to: :exact)
+      end
+    end
+
+    # Subtracts two values, promoting to exact the same way {add} does.
+    def subtract(left, right)
+      if left.is_a?(Numeric::TwoPartFloat) && right.is_a?(Numeric::TwoPartFloat)
+        left - right
+      else
+        Numeric::Precision.coerce(left, to: :exact) -
+          Numeric::Precision.coerce(right, to: :exact)
+      end
+    end
+  end
+end