astronoby 0.0.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d5ac807296bab40ecf868557f3a6a7a1022360f78860b46332e87e5a2fd2697
-  data.tar.gz: 26682e9092af30150eff0b47edb5a1476341f0d133c39ced8754148e6a4b0927
+  metadata.gz: 25e45175dabf69ffa0c98ffdf3e93cb21b9ce004fe4e0ffe61a4cfc92794ae44
+  data.tar.gz: 2d1ad05a74a171c71f6ff0a7fa7c3af1874f07379c8be407ff633d61ad4dd78e
 SHA512:
-  metadata.gz: 5ae6f829d9c23476edd3c24411426a2c8c1aa6e432c19ee999889b01d9b7843476ea14c163bd083659e768a12a6b772cf46488dfebfa5c5c8f7449a2580bc420
-  data.tar.gz: 54e3f4ce4090c120b3156d4429fb3fbc6c2830ec816355931d8b416b734210a4d82af3ef5c058a4795b27e753b748f524a0419c2f3696603c5b05ee2b60a71cd
+  metadata.gz: 74cdfbf511e8094bd410c67ed86eaff12f03124bec48c769eb3e6ebf1fd54870145a556cc82214db5147bd2c6e4631d0514973a76648d0e68d8770162401d338
+  data.tar.gz: 7a6c7f98fff52a04d60dc5c4eced47610900aa10a64f8016000b9294276d547d4d350ef0d269a25f42ae9b0078d110ad9b73884f3834e55a12084274f358ae15

data/.tool-versions

@@ -0,0 +1 @@
+ruby 3.2.2

data/CHANGELOG.md

@@ -1,6 +1,76 @@
-## [Unreleased]
+# Changelog
 
-## [0.0.1] - 2022-04-20
+## 0.2.0 - 2024-03-24
 
-- Add `Astronoby::Angle`
-- Support angles in degrees and radians
+_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
+
+* Support angles in hours
+* Support coordinates
+  * `Astronoby::Coordinates::Horizontal`
+  * `Astronoby::Coordinates::Equatorial`
+  * `Astronoby::Coordinates::Ecliptic`
+* Add new body `Astronoby::Sun`
+* Add `Astronoby::Aberration`
+* Add `Astronoby::Epoch`
+* Add `Astronoby::MeanObliquity`
+* Add `Astronoby::TrueObliquity`
+* Add `Astronoby::Nutation`
+* Add `Astronoby::Precession`
+* Add `Astronoby::Refraction`
+* Add utils
+  * `Astronoby::Util::Astrodynamics`
+  * `Astronoby::Util::Time`
+  * `Astronoby::Util::Trigonometry`
+
+## 0.0.1 - 2022-04-20
+
+* Add `Astronoby::Angle`
+* Support angles in degrees and radians

data/CONTRIBUTING.md

@@ -0,0 +1,86 @@
+# Contributing to Astronoby
+
+By participating in this project, you agree to follow the [code of conduct].
+
+[code of conduct]: https://github.com/rhannequin/astronoby/blob/main/CODE_OF_CONDUCT.md
+
+Here are some ways *you* can contribute:
+
+* by reporting bugs
+* by suggesting new features
+* by writing or editing documentation
+* by writing specifications
+* by writing code (**no patch is too small** : fix typos, add comments, etc.)
+* by refactoring code
+* by closing [issues]
+* by reviewing patches
+
+[issues]: https://github.com/rhannequin/astronoby/issues
+
+## Submitting an Issue
+
+* We use the [GitHub issue tracker][issues] to track bugs and features.
+* Before submitting a bug report or feature request, check to make sure it hasn't
+  already been submitted.
+* When submitting a bug report, please include any other details that may be
+  necessary to reproduce the bug, including your gem version, Ruby version, and
+  operating system.
+
+## Cleaning up issues
+
+* Issues that have no response from the submitter will be closed after 30 days.
+* Issues will be closed once they're assumed to be fixed or answered. If the
+  maintainer is wrong, it can be opened again.
+* If your issue is closed by mistake, please understand and explain the issue.
+  We will happily reopen the issue.
+
+## Submitting a Pull Request
+
+1. [Fork][fork] the [official repository][repo].
+1. [Create a topic branch.][branch]
+1. Implement your feature or bug fix.
+1. Add, commit, and push your changes.
+1. [Submit a pull request.][pr]
+
+### Notes
+
+* Please add tests if you changed code. Contributions without tests won't be accepted.
+* If you don't know how to add tests, please put in a PR and leave a comment
+  asking for help. We love helping!
+* Please don't update the Gem version.
+
+## Setting up
+
+```sh
+bin/setup
+```
+
+## Running the test suite
+
+The default rake task will run the full test suite:
+
+```sh
+bundle exec rake
+```
+
+To run an individual rspec test, you can provide a path and line number:
+
+```sh
+bundle exec rspec spec/path/to/spec.rb:123
+```
+
+## Formatting
+
+Use [standard] to automatically format your code:
+
+```sh
+bundle exec standardrb --fix
+```
+
+[repo]: https://github.com/rhannequin/astronoby/tree/main
+[fork]: https://help.github.com/articles/fork-a-repo/
+[branch]: https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/
+[pr]: https://help.github.com/articles/using-pull-requests/
+[standard]: https://github.com/testdouble/standard
+
+Inspired by https://github.com/thoughtbot/factory_bot/blob/main/CONTRIBUTING.md

data/Gemfile.lock

@@ -1,7 +1,8 @@
 PATH
   remote: .
   specs:
-    astronoby (0.0.1)
+    astronoby (0.2.0)
+      matrix (~> 0.4.2)
       rake (~> 13.0)
       rspec (~> 3.0)
 
@@ -9,54 +10,70 @@ GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.2)
-    diff-lcs (1.5.0)
-    parallel (1.22.1)
-    parser (3.1.2.0)
+    diff-lcs (1.5.1)
+    json (2.7.1)
+    language_server-protocol (3.17.0.3)
+    lint_roller (1.1.0)
+    matrix (0.4.2)
+    parallel (1.24.0)
+    parser (3.3.0.5)
       ast (~> 2.4.1)
-    prettier (2.1.0)
+      racc
+    racc (1.7.3)
     rainbow (3.1.1)
-    rake (13.0.6)
-    regexp_parser (2.3.0)
-    rexml (3.2.5)
-    rspec (3.11.0)
-      rspec-core (~> 3.11.0)
-      rspec-expectations (~> 3.11.0)
-      rspec-mocks (~> 3.11.0)
-    rspec-core (3.11.0)
-      rspec-support (~> 3.11.0)
-    rspec-expectations (3.11.0)
+    rake (13.1.0)
+    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.11.0)
-    rspec-mocks (3.11.1)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.11.0)
-    rspec-support (3.11.0)
-    rubocop (1.27.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.1.0.0)
+      parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
       regexp_parser (>= 1.8, < 3.0)
-      rexml
-      rubocop-ast (>= 1.16.0, < 2.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.31.1, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.17.0)
-      parser (>= 3.1.1.0)
-    rubocop-performance (1.13.3)
-      rubocop (>= 1.7.0, < 2.0)
-      rubocop-ast (>= 0.4.0)
-    ruby-progressbar (1.11.0)
-    standard (1.10.0)
-      rubocop (= 1.27.0)
-      rubocop-performance (= 1.13.3)
-    unicode-display_width (2.1.0)
+      unicode-display_width (>= 2.4.0, < 3.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.35.1)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.62.0)
+      standard-custom (~> 1.0.0)
+      standard-performance (~> 1.3)
+    standard-custom (1.0.2)
+      lint_roller (~> 1.0)
+      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
   x86_64-linux
 
 DEPENDENCIES
   astronoby!
-  prettier (~> 2.0)
   standard (~> 1.3)
 
 BUNDLED WITH

data/README.md

@@ -1,6 +1,15 @@
-# Astronoby ![specs](https://github.com/rhannequin/astronoby/workflows/Ruby/badge.svg)
+# Astronoby
 
-Ruby library to provide a useful API to compute astronomical calculations, based on _Astronomical Algorithms_ by Jean Meeus.
+[![Tests](https://github.com/rhannequin/astronoby/workflows/Ruby/badge.svg)](https://github.com/rhannequin/astronoby/actions?query=workflow%3ARuby)
+
+Ruby library to provide a useful API to compute astronomical calculations, based
+on astrometry books.
+
+The main reference is:
+- _Astronomical Algorithms_ by Jean Meeus
+- _Celestial Calculations_ by J. L. Lawrence
+- _Practical Astronomy with your Calculator or Spreadsheet_ by Peter
+  Duffet-Smith and Jonathan Zwart
 
 ## Installation
 
@@ -8,28 +17,91 @@ Install the gem and add to the application's Gemfile by executing:
 
     $ bundle add astronoby
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+If bundler is not being used to manage dependencies, install the gem by
+executing:
 
     $ gem install astronoby
 
 ## Usage
 
-Library still heavily in development.
+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)
+epoch = Astronoby::Epoch.from_time(time)
+
+latitude = Astronoby::Angle.as_degrees(48.8566)
+longitude = Astronoby::Angle.as_degrees(2.3522)
+
+sun = Astronoby::Sun.new(epoch: epoch)
+
+horizontal_coordinates = sun.horizontal_coordinates(
+  latitude: latitude,
+  longitude: longitude
+)
+
+horizontal_coordinates.altitude.degrees.to_f
+# => 27.502365130176567
+
+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 
+to values computed by the [IMCCE] is approximately 1 arc minute. It corresponds
+to twice the apparent size of Jupiter when it is the closest to Earth.
+
+While the precision is not enough for very high accuracy computations, it is
+equal to the Human naked eye's angular resolution.
+
+[IMCCE]: https://www.imcce.fr
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake spec` to run the tests. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
+
+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
+`bundle exec rake release`, which will create a git tag for the version, push
+git commits and the created tag, and push the `.gem` file to [rubygems.org].
 
-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 `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+[rubygems.org]: https://rubygems.org
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/rhannequin/astronoby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/rhannequin/astronoby/blob/main/CODE_OF_CONDUCT.md).
+Please see [CONTRIBUTING.md](https://github.com/rhannequin/astronoby/blob/main/CONTRIBUTING.md).
+
+[code of conduct]: https://github.com/rhannequin/astronoby/blob/main/CODE_OF_CONDUCT.md
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License].
+
+[MIT License]: https://opensource.org/licenses/MIT
 
 ## Code of Conduct
 
-Everyone interacting in the Astronoby project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/rhannequin/astronoby/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the Astronoby project's codebases, issue trackers, chat
+rooms and mailing lists is expected to follow the [code of conduct].
+
+[code of conduct]: https://github.com/rhannequin/astronoby/blob/main/CODE_OF_CONDUCT.md

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/aberration.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Astronoby
+  class Aberration
+    def self.for_ecliptic_coordinates(coordinates:, epoch:)
+      new(coordinates, epoch).apply
+    end
+
+    def initialize(coordinates, epoch)
+      @coordinates = coordinates
+      @epoch = epoch
+    end
+
+    # Source:
+    #  Title: Practical Astronomy with your Calculator or Spreadsheet
+    #  Authors: Peter Duffett-Smith and Jonathan Zwart
+    #  Edition: Cambridge University Press
+    #  Chapter: 36 - Aberration
+    def apply
+      delta_longitude = Angle.as_degrees(
+        -20.5 * (
+          sun_longitude - @coordinates.longitude
+        ).cos / @coordinates.latitude.cos / 3600
+      )
+
+      delta_latitude = Angle.as_degrees(
+        -20.5 *
+        (sun_longitude - @coordinates.longitude).sin *
+        @coordinates.latitude.sin / 3600
+      )
+
+      Coordinates::Ecliptic.new(
+        latitude: @coordinates.latitude + delta_latitude,
+        longitude: @coordinates.longitude + delta_longitude
+      )
+    end
+
+    def sun_longitude
+      @_sun_longitude ||= Sun.new(epoch: @epoch).ecliptic_coordinates.longitude
+    end
+  end
+end