Twilight times - rhannequin/astronoby GitHub Wiki

In astronomy, twilight is a period of time when the Sun is still/already set but some of its light illuminates the atmosphere, making the sky brighter than during full night.

We usually define 4 moments when talking about twilight:

sunrise/sunset: right when before the Sun goes above the horizon on right after it goes below the horizon. The Sun's horizon angle is 0°.
civil twilight: when the horizon angle is between 0° and -6°. Usually, during this time, artificial light is not needed yet.
nautical twilight: when the horizon angle is between 6° and -12°. When the nautical twilight starts, the difference between the horizon at sea and the sky cannot be seen clearly anymore.
astronomical twilight: when the horizon angle is between 12° and -18°. Some stars can been seen during this time.

These moments change every day and depend on the observer's location. They can be computed using Astronoby::TwilightCalculator.

Initialization

Once instantiated, the calculator doesn't do any anything yet, it waits for your instruction.

It takes as key arguments:

observer (Astronoby::Observer): location on Earth of the observer
ephem: ephemeris to provide the initial raw data

You can learn more about ephemerides on the Ephem page.

ephem = Astronoby::Ephem.load("inpop19a.bsp")

observer = Astronoby::Observer.new(
  latitude: Astronoby::Angle.from_degrees(41.0082),
  longitude: Astronoby::Angle.from_degrees(28.9784),
  elevation: Astronoby::Distance.from_meters(40)
)

calculator = Astronoby::TwilightCalculator.new(
  observer: observer,
  ephem: ephem
)

You can learn more about observers on the Observer page.

`#event_on`

The calculator exposes the instance method #event_on to compute the twilight times for a given date (Date) parameter.

It returns a Astronoby::TwilightEvent object which exposes the 6 following instance methods:

#morning_astronomical_twilight_time: when the rising Sun reaches 18° below the horizon
#morning_nautical_twilight_time: when the rising Sun reaches 12° below the horizon
#morning_civil_twilight_time: when the rising Sun reaches 6° below the horizon
#evening_civil_twilight_time: when the setting Sun reaches 6° below the horizon
#evening_nautical_twilight_time: when the setting Sun reaches 12° below the horizon
#evening_astronomical_twilight_time: when the setting Sun reaches 18° below the horizon

event = calculator.event_on(Date.new(2025, 5, 1))

event.morning_astronomical_twilight_time
# => 2025-05-01 01:17:18 UTC

event.morning_nautical_twilight_time
# => 2025-05-01 01:56:48 UTC

event.evening_civil_twilight_time
# => 2025-05-01 17:29:41 UTC

event.evening_nautical_twilight_time
# => 2025-05-01 18:06:08 UTC

event.evening_astronomical_twilight_time
# => 2025-05-01 18:45:38 UTC