Skip to content

Commit

Permalink
Add Astronoby::Moon#current_phase_fraction (#115)
Browse files Browse the repository at this point in the history
While `#illuminated_fraction` already provides a valid information on how much the Moon seems illuminated as observed from the Earth, it doesn't help deduce the current phase name. When the Moon is 45% illuminated, it can be either the First Quarter or the Last Quarter, there is no way of knowing without calculating when is was the previous Full Moon and when is the next one.

To help with this, we introduce `#current_phase_fraction`, based on the mean elongation, which is a number from 0 to 1 which always increase while we're getting closer to the next New Moon.

As it is using `#mean_elongation`, the result is not extremely precise, however it is precise enough to deduce the current phase name for a given day.

For a user wanting to get accurate phase times, it is preferred to use `::monthly_phase_events`.

```rb
# ~ time of first quarter in December 2024
time = Time.utc(2024, 12, 8, 15, 26)

Astronoby::Moon.new(time: time)
  .illuminated_fraction
  .round(2)
# => 0.5

Astronoby::Moon.new(time: time)
  .current_phase_fraction
  .round(2)
# => 0.26

# ~ time of last quarter in December 2024
time = Time.utc(2024, 12, 22, 22, 18)

Astronoby::Moon.new(time: time)
  .illuminated_fraction
  .round(2)
# => 0.5

Astronoby::Moon.new(time: time)
  .current_phase_fraction
  . round(2)
# => 0.74
```

Fixes #101
  • Loading branch information
rhannequin authored Dec 10, 2024
1 parent c4dbb11 commit 1ea6600
Show file tree
Hide file tree
Showing 3 changed files with 28 additions and 0 deletions.
3 changes: 3 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -249,6 +249,9 @@ moon = Astronoby::Moon.new(time: time)
moon.illuminated_fraction.round(2)
# => 0.31

moon.current_phase_fraction.round(2)
# => 0.82

moon.distance.km.round
# => 368409

Expand Down
5 changes: 5 additions & 0 deletions lib/astronoby/bodies/moon.rb
Original file line number Diff line number Diff line change
Expand Up @@ -167,6 +167,11 @@ def illuminated_fraction
@illuminated_fraction ||= (1 + phase_angle.cos) / 2
end

# @return [Float] Phase fraction, from 0 to 1
def current_phase_fraction
mean_elongation.degrees / Constants::DEGREES_PER_CIRCLE
end

# @param observer [Astronoby::Observer] Observer of the event
# @return [Astronoby::Events::ObservationEvents] Moon's observation events
def observation_events(observer:)
Expand Down
20 changes: 20 additions & 0 deletions spec/astronoby/bodies/moon_spec.rb
Original file line number Diff line number Diff line change
Expand Up @@ -398,6 +398,26 @@
end
end

describe "#current_phase_fraction" do
it "returns the mean elongation's fraction" do
moon = described_class.new(time: Time.new)
allow(moon).to receive(:mean_elongation)
.and_return(Astronoby::Angle.from_degrees(90))

phase_fraction = moon.current_phase_fraction

expect(phase_fraction).to eq 0.25
end

it "returns the mean elongation's fraction for 2024-01-01" do
moon = described_class.new(time: Time.utc(2024, 1, 1))

phase_fraction = moon.current_phase_fraction

expect(phase_fraction.round(2)).to eq 0.66
end
end

describe "#observation_events" do
describe "#rising_time" do
it "returns the moonrise time on 1991-03-14" do
Expand Down

0 comments on commit 1ea6600

Please sign in to comment.