astronoby 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c5bcfe7077b3772243f90a9c8a9ac8b0b0d90fdce2c777d6f05ab88062bc94c
-  data.tar.gz: ecd3bbbbcf699c1bde1b2fd6a92ccd7dc45ed1839cb3e6e6549ddb2d52002e48
+  metadata.gz: 25e45175dabf69ffa0c98ffdf3e93cb21b9ce004fe4e0ffe61a4cfc92794ae44
+  data.tar.gz: 2d1ad05a74a171c71f6ff0a7fa7c3af1874f07379c8be407ff633d61ad4dd78e
 SHA512:
-  metadata.gz: a97c4ee597dbcd5b3adbb9da8402dd95d413d120e51c263675a8019e839496168d4a893c473b6dbf1687463eb8e2f4749b13a9acab1205488944ae49f160de83
-  data.tar.gz: 70b0f12a52a668e1f3948a20fb5fe38b59e42ed0531381b8a5a03d130d1e64b2e7ba2c56806982d1f0e667dc47776a54609d7a35a5b067594b78295a440cf020
+  metadata.gz: 74cdfbf511e8094bd410c67ed86eaff12f03124bec48c769eb3e6ebf1fd54870145a556cc82214db5147bd2c6e4631d0514973a76648d0e68d8770162401d338
+  data.tar.gz: 7a6c7f98fff52a04d60dc5c4eced47610900aa10a64f8016000b9294276d547d4d350ef0d269a25f42ae9b0078d110ad9b73884f3834e55a12084274f358ae15

data/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## 0.2.0 - 2024-03-24
+
+_If you are upgrading: please see [`UPGRADING.md`]._
+
+[`UPGRADING.md`]: https://github.com/rhannequin/astronoby/blob/main/UPGRADING.md
+
+### Features
+
+* Angle comparison ([#21])
+* Add `#distance` and `#angular_size` to `Astronoby::Sun` ([#30])
+* Add geocentric parallax `Astronoby::GeocentricParallax` ([#31])
+* Ability to calculate equinoxes and solstices times ([#32])
+* Round rising and setting times to the second ([#38])
+* Provide sunrise and sunset times ([#35])
+* Provide sunrise and sunset azimuths ([#39])
+* Ability to calculate the equation of time ([#40])
+
+### Breaking changes
+
+* **breaking:** Accurate setting and rising times for punctual bodies ([#29])
+* **breaking:** Drop `Astronoby::Util::Time` in favor of
+  `Astronoby::GreenwichSiderealTime` and `Astonoby::LocalSiderealTime` ([#36])
+
+### Improvements
+
+* Add Dependabot for Bundler and GitHub Actions ([#24])
+* Add bundler-audit GitHub Action ([#25])
+* Bump actions/checkout from 3 to 4 ([#26])
+* Bump standard from 1.29.0 to 1.35.1 ([#27], [#37])
+* Bump rspec from 3.12.0 to 3.13.0 ([#28])
+
+[#21]: https://github.com/rhannequin/astronoby/pull/21
+[#24]: https://github.com/rhannequin/astronoby/pull/24
+[#25]: https://github.com/rhannequin/astronoby/pull/25
+[#26]: https://github.com/rhannequin/astronoby/pull/26
+[#27]: https://github.com/rhannequin/astronoby/pull/27
+[#28]: https://github.com/rhannequin/astronoby/pull/28
+[#29]: https://github.com/rhannequin/astronoby/pull/29
+[#30]: https://github.com/rhannequin/astronoby/pull/30
+[#31]: https://github.com/rhannequin/astronoby/pull/31
+[#32]: https://github.com/rhannequin/astronoby/pull/32
+[#35]: https://github.com/rhannequin/astronoby/pull/35
+[#36]: https://github.com/rhannequin/astronoby/pull/36
+[#37]: https://github.com/rhannequin/astronoby/pull/37
+[#28]: https://github.com/rhannequin/astronoby/pull/38
+[#39]: https://github.com/rhannequin/astronoby/pull/39
+[#40]: https://github.com/rhannequin/astronoby/pull/40
+
 ## 0.1.0 - 2024-02-28
 
 ### Features

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    astronoby (0.1.0)
+    astronoby (0.2.0)
       matrix (~> 0.4.2)
       rake (~> 13.0)
       rspec (~> 3.0)
@@ -10,61 +10,63 @@ GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.2)
-    diff-lcs (1.5.0)
-    json (2.6.3)
+    diff-lcs (1.5.1)
+    json (2.7.1)
     language_server-protocol (3.17.0.3)
-    lint_roller (1.0.0)
+    lint_roller (1.1.0)
     matrix (0.4.2)
-    parallel (1.23.0)
-    parser (3.2.2.3)
+    parallel (1.24.0)
+    parser (3.3.0.5)
       ast (~> 2.4.1)
       racc
-    racc (1.7.0)
+    racc (1.7.3)
     rainbow (3.1.1)
     rake (13.1.0)
-    regexp_parser (2.8.1)
-    rexml (3.2.5)
-    rspec (3.12.0)
-      rspec-core (~> 3.12.0)
-      rspec-expectations (~> 3.12.0)
-      rspec-mocks (~> 3.12.0)
-    rspec-core (3.12.2)
-      rspec-support (~> 3.12.0)
-    rspec-expectations (3.12.3)
+    regexp_parser (2.9.0)
+    rexml (3.2.6)
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.0)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.12.0)
-    rspec-mocks (3.12.6)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.12.0)
-    rspec-support (3.12.1)
-    rubocop (1.52.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.1)
+    rubocop (1.62.1)
       json (~> 2.3)
+      language_server-protocol (>= 3.17.0)
       parallel (~> 1.10)
-      parser (>= 3.2.0.0)
+      parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
       rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.28.0, < 2.0)
+      rubocop-ast (>= 1.31.1, < 2.0)
       ruby-progressbar (~> 1.7)
       unicode-display_width (>= 2.4.0, < 3.0)
-    rubocop-ast (1.29.0)
-      parser (>= 3.2.1.0)
-    rubocop-performance (1.18.0)
-      rubocop (>= 1.7.0, < 2.0)
-      rubocop-ast (>= 0.4.0)
+    rubocop-ast (1.31.2)
+      parser (>= 3.3.0.4)
+    rubocop-performance (1.20.2)
+      rubocop (>= 1.48.1, < 2.0)
+      rubocop-ast (>= 1.30.0, < 2.0)
     ruby-progressbar (1.13.0)
-    standard (1.29.0)
+    standard (1.35.1)
       language_server-protocol (~> 3.17.0.2)
       lint_roller (~> 1.0)
-      rubocop (~> 1.52.0)
+      rubocop (~> 1.62.0)
       standard-custom (~> 1.0.0)
-      standard-performance (~> 1.1.0)
-    standard-custom (1.0.1)
+      standard-performance (~> 1.3)
+    standard-custom (1.0.2)
       lint_roller (~> 1.0)
-    standard-performance (1.1.0)
-      lint_roller (~> 1.0)
-      rubocop-performance (~> 1.18.0)
-    unicode-display_width (2.4.2)
+      rubocop (~> 1.50)
+    standard-performance (1.3.1)
+      lint_roller (~> 1.1)
+      rubocop-performance (~> 1.20.2)
+    unicode-display_width (2.5.0)
 
 PLATFORMS
   ruby

data/README.md

@@ -24,8 +24,11 @@ executing:
 
 ## Usage
 
-This library is still in heavy development. The following API is likely to 
-change any time.
+This library is still in heavy development. The public is not stable, please
+be aware new minor versions will probably lead to breaking changes until a
+major one is released.
+
+### Sun's location in the sky
 
 ```rb
 time = Time.utc(2023, 2, 17, 11, 0, 0)
@@ -48,6 +51,18 @@ horizontal_coordinates.altitude.str(:dms)
 # => "+27° 30′ 8.5144″"
 ```
 
+### Solstice and Equinox times
+
+```rb
+year = 2024
+
+Astronoby::EquinoxSolstice.march_equinox(year)
+# => 2024-03-20 03:05:00 UTC
+
+Astronoby::EquinoxSolstice.june_solstice(year)
+# => 2024-06-20 20:50:14 UTC
+```
+
 ## Precision
 
 The current precision for the Sun's apparent location in the sky, compared 

data/UPGRADING.md

@@ -0,0 +1,109 @@
+# Upgrading
+
+Astronoby is still in development phase and no major version has been
+released yet. Please consider the public API as unstable and expect breaking
+changes to it as long as a major version has not been released.
+
+If you are already using Astronoby and wish to follow the changes to its
+public API, please read the upgrading notes for each release.
+
+## Upgrading from 0.1.0 to 0.2.0
+
+### `Observer` class added (#29)
+
+The `Observer` class aims to represent an observer's location and local
+parameters such as the temperature and astmospheric pressure.
+
+### `Refraction` constructor changed (#29)
+
+`Refraction.new` now takes the following arguments:
+
+* `coordinates` (`Coordinates::Horizontal`)
+* `observer` (`Observer`)
+
+### `Refraction::for_horizontal_coordinates` removed (#29)
+
+Please now use `Refraction.correct_horizontal_coordinates`.
+
+### `Refraction::angle` added (#29)
+
+This returns a refraction angle (`Angle`) based on an observer (`Observer`)
+and the horizontal coordinates (`Coordinates::Horizontal`) of a body in the sky.
+
+### `apparent` argument added to `Body::rising_time` (#29)
+
+With a default value of `true`, this new argument will make consider a
+default vertical refraction angle or not.
+
+### `apparent` argument added to `Body::setting_time` (#29)
+
+With a default value of `true`, this new argument will make consider a
+default vertical refraction angle or not.
+
+### `Sun::equation_of_time` method added (#40)
+
+Returns the equation of time for a given date.
+
+### `Sun#distance` method added (#30)
+
+Returns the approximate Earth-Sun distance in meters (`Numeric`).
+
+### `Sun#angular_size` method added (#30)
+
+Returns the apparent Sun's angular size (`Angle`).
+
+### `Sun#true_anomaly` method added (#32)
+
+Returns the apparent Sun's true anomaly (`Angle`).
+
+### `Sun#longitude_at_perigee` method added (#32)
+
+Returns the apparent Sun's longitude (`Angle`) at its perigee.
+
+### `Sun#rising_time` method added (#35)
+
+Returns the UTC `Time` of the sunrise.`
+
+### `Sun#rising_azimuth` method added (#39)
+
+Returns the Sun's azimuth (`Angle`) at sunrise.
+
+### `Sun#setting_time` method added (#35)
+
+Returns the UTC `Time` of the sunset.
+
+### `Sun#setting_azimuth` method added (#39)
+
+Returns the Sun's azimuth (`Angle`) at sunset.
+
+### Added comparison methods to `Angle` (#21)
+
+With the inclusion of `Comparable`, comparison methods such as `#==`, `#<`,
+`#>`, `#<=`, `#>=`, `#!=`, `#<=>` have been added to `Angle`.
+
+### `GeocentricParallax` class added
+
+Calculates the equatorial horizontal parallax for an observed body. The
+class provided two class methods:
+- `::angle` which returns the parallax angle
+- `::for_equatorial_coordinates` which correct equatorial coordinates with
+  the parallax correction
+
+### `EquinoxSolstice` class added
+
+This class exposes `::march_equinox`, `::june_solstice`,
+`::september_equinox` and `::december_soltice` that all require a year
+(`Integer`) as parameter and return a date-time (`Time`) computed for the event.
+
+### `Util::Time` class dropped
+
+Time-related utility functions have been deleted, in favor of new classes
+(see below).
+
+### `GreenwichSiderealTime` class added
+
+Enables to instantiate a GST from UTC, or convert a GST to UTC.
+
+### `LocalSiderealTime` class added
+
+Enables to instantiate a LST from GST, or convert a LST to GST.

data/lib/astronoby/angle.rb

@@ -4,6 +4,8 @@ require "bigdecimal/math"
 
 module Astronoby
   class Angle
+    include Comparable
+
     PRECISION = 14
     PI = BigMath.PI(PRECISION)
     PI_IN_DEGREES = BigDecimal("180")

data/lib/astronoby/bodies/sun.rb

@@ -2,16 +2,46 @@
 
 module Astronoby
   class Sun
+    SEMI_MAJOR_AXIS_IN_METERS = 149_598_500_000
+    ANGULAR_DIAMETER = Angle.as_degrees(0.533128)
+    INTERPOLATION_FACTOR = BigDecimal("24.07")
+
+    # Source:
+    #  Title: Practical Astronomy with your Calculator or Spreadsheet
+    #  Authors: Peter Duffett-Smith and Jonathan Zwart
+    #  Edition: Cambridge University Press
+    #  Chapter: 51 - The equation of time
+
+    # @param date [Date] Requested date
+    # @return [Integer] Equation of time in seconds
+    def self.equation_of_time(date:)
+      noon = Time.utc(date.year, date.month, date.day, 12)
+      epoch_at_noon = Epoch.from_time(noon)
+      sun_at_noon = new(epoch: epoch_at_noon)
+      equatorial_hours = sun_at_noon
+        .ecliptic_coordinates
+        .to_equatorial(epoch: epoch_at_noon)
+        .right_ascension
+        .hours
+      gst = GreenwichSiderealTime
+        .new(date: date, time: equatorial_hours)
+        .to_utc
+
+      (noon - gst).to_i
+    end
+
     # Source:
     #  Title: Celestial Calculations
     #  Author: J. L. Lawrence
     #  Edition: MIT Press
     #  Chapter: 6 - The Sun
 
+    # @param epoch [Numeric] Considered epoch, in Julian days
     def initialize(epoch:)
       @epoch = epoch
     end
 
+    # @return [Astronoby::Coordinates::Ecliptic] Sun's ecliptic coordinates
     def ecliptic_coordinates
       Coordinates::Ecliptic.new(
         latitude: Angle.zero,
@@ -21,6 +51,11 @@ module Astronoby
       )
     end
 
+    # Computes the Sun's horizontal coordinates
+    #
+    # @param latitude [Astronoby::Angle] Latitude of the observer
+    # @param longitude [Astronoby::Angle] Longitude of the observer
+    # @return [Astronoby::Coordinates::Horizontal] Sun's horizontal coordinates
     def horizontal_coordinates(latitude:, longitude:)
       time = Epoch.to_utc(@epoch)
 
@@ -29,14 +64,69 @@ module Astronoby
         .to_horizontal(time: time, latitude: latitude, longitude: longitude)
     end
 
-    private
+    # @param observer [Astronoby::Observer] Observer of the event
+    # @return [Time] Time of sunrise
+    def rising_time(observer:)
+      event_date = Epoch.to_utc(@epoch).to_date
+      lst1 = event_local_sidereal_time_for_date(event_date, observer, :rising)
+      next_day = event_date.next_day(1)
+      lst2 = event_local_sidereal_time_for_date(next_day, observer, :rising)
+      time = (INTERPOLATION_FACTOR * lst1) / (INTERPOLATION_FACTOR + lst1 - lst2)
 
-    def mean_anomaly
-      Angle.as_degrees(
-        (longitude_at_base_epoch - longitude_at_perigee).degrees % 360
+      LocalSiderealTime.new(
+        date: event_date,
+        time: time,
+        longitude: observer.longitude
+      ).to_gst.to_utc
+    end
+
+    # @param observer [Astronoby::Observer] Observer of the event
+    # @return [Astronoby::Angle, nil] Azimuth of sunrise
+    def rising_azimuth(observer:)
+      equatorial_coordinates = ecliptic_coordinates.to_equatorial(epoch: @epoch)
+      Body.new(equatorial_coordinates).rising_azimuth(
+        latitude: observer.latitude,
+        vertical_shift: vertical_shift
       )
     end
 
+    # @param observer [Astronoby::Observer] Observer of the event
+    # @return [Time] Time of sunset
+    def setting_time(observer:)
+      event_date = Epoch.to_utc(@epoch).to_date
+      lst1 = event_local_sidereal_time_for_date(event_date, observer, :setting)
+      next_day = event_date.next_day(1)
+      lst2 = event_local_sidereal_time_for_date(next_day, observer, :setting)
+      time = (INTERPOLATION_FACTOR * lst1) / (INTERPOLATION_FACTOR + lst1 - lst2)
+
+      LocalSiderealTime.new(
+        date: event_date,
+        time: time,
+        longitude: observer.longitude
+      ).to_gst.to_utc
+    end
+
+    # @param observer [Astronoby::Observer] Observer of the event
+    # @return [Astronoby::Angle, nil] Azimuth of sunset
+    def setting_azimuth(observer:)
+      equatorial_coordinates = ecliptic_coordinates.to_equatorial(epoch: @epoch)
+      Body.new(equatorial_coordinates).setting_azimuth(
+        latitude: observer.latitude,
+        vertical_shift: vertical_shift
+      )
+    end
+
+    # @return [Numeric] Earth-Sun distance in meters
+    def earth_distance
+      SEMI_MAJOR_AXIS_IN_METERS / distance_angular_size_factor
+    end
+
+    # @return [Astronoby::Angle] Apparent Sun's angular size
+    def angular_size
+      Angle.as_degrees(ANGULAR_DIAMETER.degrees * distance_angular_size_factor)
+    end
+
+    # @return [Astronoby::Angle] Sun's true anomaly
     def true_anomaly
       eccentric_anomaly = Util::Astrodynamics.eccentric_anomaly_newton_raphson(
         mean_anomaly,
@@ -52,6 +142,28 @@ module Astronoby
       Angle.as_degrees((Angle.atan(tan).degrees * 2) % 360)
     end
 
+    # @return [Astronoby::Angle] Sun's longitude at perigee
+    def longitude_at_perigee
+      Angle.as_degrees(
+        (281.2208444 + 1.719175 * centuries + 0.000452778 * centuries**2) % 360
+      )
+    end
+
+    # @return [Astronoby::Angle] Sun's orbital eccentricity
+    def orbital_eccentricity
+      Angle.as_degrees(
+        (0.01675104 - 0.0000418 * centuries - 0.000000126 * centuries**2) % 360
+      )
+    end
+
+    private
+
+    def mean_anomaly
+      Angle.as_degrees(
+        (longitude_at_base_epoch - longitude_at_perigee).degrees % 360
+      )
+    end
+
     def days_since_epoch
       Epoch::DEFAULT_EPOCH - @epoch
     end
@@ -66,16 +178,49 @@ module Astronoby
       )
     end
 
-    def longitude_at_perigee
-      Angle.as_degrees(
-        (281.2208444 + 1.719175 * centuries + 0.000452778 * centuries**2) % 360
-      )
+    def distance_angular_size_factor
+      term1 = 1 + orbital_eccentricity.degrees * true_anomaly.cos
+      term2 = 1 - orbital_eccentricity.degrees**2
+
+      term1 / term2
     end
 
-    def orbital_eccentricity
-      Angle.as_degrees(
-        (0.01675104 - 0.0000418 * centuries - 0.000000126 * centuries**2) % 360
-      )
+    def event_local_sidereal_time_for_date(date, observer, event)
+      midnight_utc = Time.utc(date.year, date.month, date.day)
+      epoch = Epoch.from_time(midnight_utc)
+      sun_at_midnight = self.class.new(epoch: epoch)
+      shift = Body::DEFAULT_REFRACTION_VERTICAL_SHIFT +
+        GeocentricParallax.angle(distance: sun_at_midnight.earth_distance) +
+        Angle.as_degrees(sun_at_midnight.angular_size.degrees / 2)
+      ecliptic_coordinates = sun_at_midnight.ecliptic_coordinates
+      equatorial_coordinates = ecliptic_coordinates.to_equatorial(epoch: epoch)
+
+      event_time = if event == :rising
+        Body.new(equatorial_coordinates).rising_time(
+          latitude: observer.latitude,
+          longitude: observer.longitude,
+          date: midnight_utc.to_date,
+          vertical_shift: shift
+        )
+      else
+        Body.new(equatorial_coordinates).setting_time(
+          latitude: observer.latitude,
+          longitude: observer.longitude,
+          date: midnight_utc.to_date,
+          vertical_shift: shift
+        )
+      end
+
+      GreenwichSiderealTime
+        .from_utc(event_time.utc)
+        .to_lst(longitude: observer.longitude)
+        .time
+    end
+
+    def vertical_shift
+      Astronoby::Body::DEFAULT_REFRACTION_VERTICAL_SHIFT +
+        Astronoby::GeocentricParallax.angle(distance: earth_distance) +
+        Astronoby::Angle.as_degrees(angular_size.degrees / 2)
     end
   end
 end