astronoby 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1c5bcfe7077b3772243f90a9c8a9ac8b0b0d90fdce2c777d6f05ab88062bc94c
-  data.tar.gz: ecd3bbbbcf699c1bde1b2fd6a92ccd7dc45ed1839cb3e6e6549ddb2d52002e48
+  metadata.gz: 2ab8b9191b1b2452c678389fbc4c1750c4080c8f3cddf55cf7aebad2d99a0da7
+  data.tar.gz: f823456f556792e1d2ea3747f3665c84442a907c3a08271df5f871204bd09f10
 SHA512:
-  metadata.gz: a97c4ee597dbcd5b3adbb9da8402dd95d413d120e51c263675a8019e839496168d4a893c473b6dbf1687463eb8e2f4749b13a9acab1205488944ae49f160de83
-  data.tar.gz: 70b0f12a52a668e1f3948a20fb5fe38b59e42ed0531381b8a5a03d130d1e64b2e7ba2c56806982d1f0e667dc47776a54609d7a35a5b067594b78295a440cf020
+  metadata.gz: b14d2a19972991fecc5b0a12c15fe18f3a9a07d0e9fc705fe2d984af14e45ae82962332361e65dace20c27b5f6e05e19483385731770abe463a3bf28adcfb354
+  data.tar.gz: 725810244872e539789b23d2b28ce656781a1f9121fabc76c3e2ebc5c9e6616900bff852290cf8719a10feb7a06afa42f7d02f4e00ac3ba2dadc4dea47d6a24c

data/CHANGELOG.md

@@ -1,5 +1,70 @@
 # Changelog
 
+## 0.3.0 - 2024-03-29
+
+_If you are upgrading: please see [`UPGRADING.md`]._
+
+### Improvements
+
+* Drop `Angle#==` ([#42])
+* Improved accuracy with Sun's location predictions ([#41])
+
+### Breaking changes
+
+* **breaking:** Difference between true and apparent ecliptic and equatorial
+  coordinates ([#41])
+* **breaking:** Rename `Angle::as_*` into `Angle::from_*` ([#43])
+
+[#41]: https://github.com/rhannequin/astronoby/pull/41
+[#42]: https://github.com/rhannequin/astronoby/pull/42
+[#43]: https://github.com/rhannequin/astronoby/pull/43
+
+## 0.2.0 - 2024-03-24
+
+_If you are upgrading: please see [`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
@@ -26,3 +91,5 @@
 
 * Add `Astronoby::Angle`
 * Support angles in degrees and radians
+
+[`UPGRADING.md`]: https://github.com/rhannequin/astronoby/blob/main/UPGRADING.md

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    astronoby (0.1.0)
+    astronoby (0.3.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,15 +24,57 @@ 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.
+
+### Angle manipulation
+
+```rb
+angle1 = Astronoby::Angle.from_degrees(90)
+angle2 = Astronoby::Angle.from_radians(Astronoby::Angle::PI / 2)
+angle3 = Astronoby::Angle.from_hours(12)
+
+angle1 == angle2
+# => true
+
+angle1 < angle3
+# => true
+
+angle = angle1 + angle2 + angle3
+angle.cos
+# => 1.0
+```
+
+### Coordinates conversion
+
+```rb
+equatorial = Astronoby::Coordinates::Equatorial.new(
+  right_ascension: Astronoby::Angle.from_hms(17, 43, 54),
+  declination: Astronoby::Angle.from_dms(-22, 10, 0)
+)
+
+horizontal = equatorial.to_horizontal(
+  time: Time.new(2016, 1, 21, 21, 30, 0, "-05:00"),
+  latitude: Astronoby::Angle.from_degrees(38),
+  longitude: Astronoby::Angle.from_degrees(-78)
+)
+
+horizontal.altitude.str(:dms)
+# => "-73° 27′ 19.1557″"
+
+horizontal.azimuth.str(:dms)
+# => "+341° 33′ 21.587″"
+```
+
+### Sun's location in the sky
 
 ```rb
 time = Time.utc(2023, 2, 17, 11, 0, 0)
 epoch = Astronoby::Epoch.from_time(time)
 
-latitude = Astronoby::Angle.as_degrees(48.8566)
-longitude = Astronoby::Angle.as_degrees(2.3522)
+latitude = Astronoby::Angle.from_degrees(48.8566)
+longitude = Astronoby::Angle.from_degrees(2.3522)
 
 sun = Astronoby::Sun.new(epoch: epoch)
 
@@ -42,10 +84,46 @@ horizontal_coordinates = sun.horizontal_coordinates(
 )
 
 horizontal_coordinates.altitude.degrees.to_f
-# => 27.502365130176567
+# => 27.50008242057459
 
 horizontal_coordinates.altitude.str(:dms)
-# => "+27° 30′ 8.5144″"
+# => "+27° 30′ 0.2967″"
+```
+
+### Sunrise and sunset times and azimuths
+
+```rb
+date = Date.new(2015, 2, 5)
+epoch = Astronoby::Epoch.from_time(date)
+observer = Astronoby::Observer.new(
+  latitude: Astronoby::Angle.from_degrees(38),
+  longitude: Astronoby::Angle.from_degrees(-78)
+)
+sun = Astronoby::Sun.new(epoch: epoch)
+
+sun.rising_time(observer: observer)
+# => 2015-02-05 12:13:26 UTC
+
+sun.rising_azimuth(observer: observer).str(:dms)
+# => "+109° 41′ 22.2585″"
+
+sun.setting_time(observer: observer)
+# => 2015-02-05 22:35:12 UTC
+
+sun.setting_azimuth(observer: observer).str(:dms)
+# => "+250° 18′ 37.7414″"
+```
+
+### Solstice and Equinox times
+
+```rb
+year = 2024
+
+Astronoby::EquinoxSolstice.march_equinox(year)
+# => 2024-03-20 03:05:08 UTC
+
+Astronoby::EquinoxSolstice.june_solstice(year)
+# => 2024-06-20 20:50:18 UTC
 ```
 
 ## Precision

data/UPGRADING.md

@@ -0,0 +1,159 @@
+# 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.2.0 to 0.3.0
+
+### `Sun#ecliptic_coordinates` method removed (#41)
+
+Removed in favor of `#true_ecliptic_coordinates` and
+`#apparent_ecliptic_coordinates`.
+
+### `Coordinates::Ecliptic#to_horizontal` method removed (#41)
+
+Removed in favor of `#to_true_horizontal` and
+`#to_apparent_horizontal`.
+
+### `Sun#true_ecliptic_coordinates` method added (#41)
+
+Returns the true ecliptic coordinates for the date's epoch.
+
+### `Sun#apparent_ecliptic_coordinates` method added (#41)
+
+Returns the apparent ecliptic coordinates for the date's epoch, including
+corrections for the nutation and aberration.
+
+### `Coordinates::Ecliptic#to_true_horizontal` method added (#41)
+
+Returns the true equatorial coordinates for ths date's epoch.
+
+### `Coordinates::Ecliptic#to_apparent_horizontal` method added (#41)
+
+Returns the apparent equatorial coordinates for the date's epoch, including
+corrections for the obliquity.
+
+### `Angle::as_radians` renamed into `Angle::from_radians` (#43)
+
+Behaviour not changed.
+
+### `Angle::as_degrees` renamed into `Angle::from_degrees` (#43)
+
+Behaviour not changed.
+
+### `Angle::as_hours` renamed into `Angle::from_hours` (#43)
+
+Behaviour not changed.
+
+### `Angle::as_dms` renamed into `Angle::from_dms` (#43)
+
+Behaviour not changed.
+
+### `Angle::as_hms` renamed into `Angle::from_hms` (#43)
+
+Behaviour not changed.
+
+## 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/aberration.rb

@@ -17,13 +17,13 @@ module Astronoby
     #  Edition: Cambridge University Press
     #  Chapter: 36 - Aberration
     def apply
-      delta_longitude = Angle.as_degrees(
+      delta_longitude = Angle.from_degrees(
         -20.5 * (
           sun_longitude - @coordinates.longitude
         ).cos / @coordinates.latitude.cos / 3600
       )
 
-      delta_latitude = Angle.as_degrees(
+      delta_latitude = Angle.from_degrees(
         -20.5 *
         (sun_longitude - @coordinates.longitude).sin *
         @coordinates.latitude.sin / 3600
@@ -36,7 +36,10 @@ module Astronoby
     end
 
     def sun_longitude
-      @_sun_longitude ||= Sun.new(epoch: @epoch).ecliptic_coordinates.longitude
+      @_sun_longitude ||= Sun
+        .new(epoch: @epoch)
+        .true_ecliptic_coordinates
+        .longitude
     end
   end
 end

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")
@@ -23,45 +25,45 @@ module Astronoby
         new(0)
       end
 
-      def as_radians(radians)
+      def from_radians(radians)
         normalized_radians = radians.remainder(FULL_CIRCLE_IN_RADIANS)
         new(normalized_radians)
       end
 
-      def as_degrees(degrees)
+      def from_degrees(degrees)
         radians = degrees / PI_IN_DEGREES * PI
-        as_radians(radians)
+        from_radians(radians)
       end
 
-      def as_hours(hours)
+      def from_hours(hours)
         radians = hours * RADIAN_PER_HOUR
-        as_radians(radians)
+        from_radians(radians)
       end
 
-      def as_hms(hour, minute, second)
+      def from_hms(hour, minute, second)
         hours = hour + minute / MINUTES_PER_HOUR + second / SECONDS_PER_HOUR
-        as_hours(hours)
+        from_hours(hours)
       end
 
-      def as_dms(degree, minute, second)
+      def from_dms(degree, minute, second)
         sign = degree.negative? ? -1 : 1
         degrees = degree.abs + minute / MINUTES_PER_HOUR + second / SECONDS_PER_HOUR
-        as_degrees(sign * degrees)
+        from_degrees(sign * degrees)
       end
 
       def asin(ratio)
         radians = Math.asin(ratio)
-        as_radians(radians)
+        from_radians(radians)
       end
 
       def acos(ratio)
         radians = Math.acos(ratio)
-        as_radians(radians)
+        from_radians(radians)
       end
 
       def atan(ratio)
         radians = Math.atan(ratio)
-        as_radians(radians)
+        from_radians(radians)
       end
     end
 
@@ -85,11 +87,11 @@ module Astronoby
     end
 
     def +(other)
-      self.class.as_radians(radians + other.radians)
+      self.class.from_radians(radians + other.radians)
     end
 
     def -(other)
-      self.class.as_radians(@radians - other.radians)
+      self.class.from_radians(@radians - other.radians)
     end
 
     def sin
@@ -116,20 +118,16 @@ module Astronoby
       radians.zero?
     end
 
-    def ==(other)
-      other.is_a?(self.class) && radians == other.radians
-    end
-    alias_method :eql?, :==
-
     def hash
       [radians, self.class].hash
     end
 
     def <=>(other)
-      return nil unless other.is_a?(self.class)
+      return unless other.is_a?(self.class)
 
       radians <=> other.radians
     end
+    alias_method :eql?, :==
 
     def str(format)
       case format