kosmorro / lib

Kosmorrolib, a library to calculate ephemerides.

Kosmorro is a program that calculates your astronomical ephemerides.

Installation

Installing Kosmorro is documented on the official website. Just select your operating system and follow the instructions!

Development environment

To contribute to Kosmorrolib, you will need Poetry, a software to manage the project from development to publishing.

Clone this repository and run poetry install to install the dependencies. And that's all, your development environment is ready!

To run Kosmorro, invoke poetry run kosmorro. For comfort, you may also want to invoke poetry shell, which will expose the kosmorro command directly.

Using Kosmorro

Using Kosmorro is as simple as invoking kosmorro in your terminal!

By default, it will give you the current Moon phase and, if any, the events that will occur today.

Kosmorro has a lot of available options to get exactly what you want, including the possibility to get planets rise and set. To get a list of them, run kosmorro --help, or read its manual with man kosmorro. You can also find usage examples in the tldr manual with tldr kosmorro.

Help translating Kosmorro!

Kosmorro is translated on Weblate, a popular free platform for crowd-sourced internationalization. If you speak a language that is not supported yet, feel free to contribute!

lib's Issues

Earth seasons changes

Event type: earth seasons changes
Involved objects (check the boxes):

• Sun
• Earth
• Earth's moon
• Planets

Definition of the event:

A season is a division of the year based on changes in […] and the number of daylight hours in a given region. On Earth, seasons are the result of Earth's orbit around the Sun and Earth's axial tilt relative to the ecliptic plane.
— Wikipedia

The four astronomical seasons on Earth are:

• Winter solstice
• Spring equinox
• Summer solstice
• Autumn equinox

A solstice is an event that occurs when the Sun appears to reach its most northerly or southerly excursion relative to the celestial equator on the celestial sphere.
— Wikipedia

An equinox is the instant of time when the plane of Earth's equator passes through the geometric center of the Sun's disk
— Wikipedia

Other useful information (implementation proposal, etc):
Skyfield library has built-in capabilities to determine when a season change occurs.
This should be integrated to the get_events() function.

rise_time and set_time are sometimes None with some timezones

I have searched for an opened issue and didn't find my bug

• I confirm I didn't find any issue regarding my bug

Version of Kosmorrolib

1.0

Version of Python

3.10

Operating system

Linux

Bug description

When trying to get ephemerids from Kosmorrolib, sometimes it returns None rise_time and set_times

Reproducer

import kosmorrolib
import datetime

print("Timezone UTC :")
print(kosmorrolib.get_ephemerides(kosmorrolib.Position(36.6794, 4.8555), datetime.date(2022, 7, 7), timezone=0)[5])
print("Timezone UTC+1 :")
print(kosmorrolib.get_ephemerides(kosmorrolib.Position(36.6794, 4.8555), datetime.date(2022, 7, 7), timezone=1)[5])

Expected result

Timezone UTC :
<AsterEphemerides rise_time=2022-07-07 22:59:00 culmination_time=2022-07-07 05:11:00 set_time=2022-07-07 11:20:00 aster=<Object type=PLANET name=JUPITER />>
Timezone UTC+1 :
<AsterEphemerides rise_time=2022-07-07 23:59:00 culmination_time=2022-07-07 06:11:00 set_time=2022-07-07 12:20:00 aster=<Object type=PLANET name=JUPITER />>

Actual result

Timezone UTC :
<AsterEphemerides rise_time=2022-07-07 22:59:00 culmination_time=2022-07-07 05:11:00 set_time=2022-07-07 11:20:00 aster=<Object type=PLANET name=JUPITER />>
Timezone UTC+1 :
<AsterEphemerides rise_time=None culmination_time=2022-07-07 06:11:00 set_time=None aster=<Object type=PLANET name=JUPITER />>

False positive on oppositions

Describe the bug
Sometimes, false positives happen on oppositions.

To Reproduce

>>> import kosmorrolib
>>> from datetime import date
>>> kosmorrolib.get_events(date(2021, 3, 20))
[<Event type=OPPOSITION objects=[<Object type=PLANET name=MARS />] start=2021-03-20 16:40:20.957700+00:00 end=None details=None />, <Event type=OPPOSITION objects=[<Object type=PLANET name=URANUS />] start=2021-03-20 16:40:20.957700+00:00 end=None details=None />]

Expected behavior

>>> import kosmorrolib
>>> from datetime import date
>>> kosmorrolib.get_events(date(2021, 3, 20))
[]

Actual behavior
Two oppositions are found.

Your configuration (please complete the following information):

• OS: Linux
• Python version: 3.9.2
• Kosmorro version: 0.9.0

False positive on occultation detection

I have searched for an opened issue and didn't find my bug

• I confirm I didn't find any issue regarding my bug

Version of Kosmorrolib

1.0

Version of Python

3.9

Operating system

Linux

Bug description

The kosmorrolib.get_events() sometimes reports occultations that actually are conjunctions.

Reproducer

import kosmorrolib
from datetime import date

kosmorrolib.get_events(date(2021, 12, 4))

Expected result

A Moon perigee and a conjunction:

[
    <Event type=PERIGEE objects=[<Object type=SATELLITE name=MOON />] start=2021-12-04 09:58:00.991755+00:00 end=None details={'distance_km': 356794.63662967435} />,
    <Event type=CONJUNCTION objects=[<Object type=SATELLITE name=MOON />, <Object type=PLANET name=MERCURY />] start=2021-12-04 12:43:02.012201+00:00 end=None details=None />
]

Actual result

A moon perigee and an occultation of Mercury by the Moon:

[
    <Event type=PERIGEE objects=[<Object type=SATELLITE name=MOON />] start=2021-12-04 09:58:00.991755+00:00 end=None details={'distance_km': 356794.63662967435} />,
    <Event type=OCCULTATION objects=[<Object type=SATELLITE name=MOON />, <Object type=PLANET name=MERCURY />] start=2021-12-04 12:43:02.012201+00:00 end=None details=None />
]

Add the objects magnitudes

Is your feature request related to a problem? Please describe.
An object being risen does not necessarily mean it is visible enough for an observation. Its visibility actually heavily depends on its apparent magnitude.

Describe the solution you'd like
Provide a function that gives, for given date and object, the apparent magnitude of that object from the point of view of the Earth.

The function would look like this:

def get_apparent_magnitude(object: Object, date = date.today()) -> float

The returned value is a float that represents the apparent magnitude of the given object.

Additional context

• We should use Skyfield's planetary_magnitude() function to compute this, and return the average value for the date.
• There are currently some limitations in the algorithm, as explained in the docs of Skyfield. When it returns NaN, we should throw an exception.

Use skyfield-data to get the needed files

As noted in readme, "the first time it runs, Kosmorro will download some important files needed to make the computations".
These files (e.g. de421.bsp) could be available after installation of https://github.com/brunobord/skyfield-data (also available from https://pypi.org/project/skyfield-data/ ).

False positive on oppositions

I have searched for an opened issue and didn't find my bug

• I confirm I didn't find any issue regarding my bug

Version of Kosmorrolib

0.11 and 1.0

Version of Python

3.10

Operating system

Linux

Bug description

kosmorrolib.get_events() finds planet opposition at times when they're not.
For instance, it finds a Jupiter opposition on both September 26 and on December 24, 2022, but only the first one is expected.

Reproducer

>>> import kosmorrolib
>>> from datetime import date
>>> kosmorrolib.get_events(date(2022, 12, 24))

Expected result

[<Event type=PERIGEE objects=[<Object type=SATELLITE name=MOON />] start=2022-12-24 08:19:50.082689+00:00 end=None details={'distance_km': 358278.1722580132} />, <Event type=CONJUNCTION objects=[<Object type=SATELLITE name=MOON />, <Object type=PLANET name=VENUS />] start=2022-12-24 12:16:04.630107+00:00 end=None details=None />, <Event type=CONJUNCTION objects=[<Object type=SATELLITE name=MOON />, <Object type=PLANET name=MERCURY />] start=2022-12-24 19:32:19.571054+00:00 end=None details=None />]

Actual result

[<Event type=OPPOSITION objects=[<Object type=PLANET name=JUPITER />] start=2022-12-24 00:26:17.376210+00:00 end=None details=None />, <Event type=PERIGEE objects=[<Object type=SATELLITE name=MOON />] start=2022-12-24 08:19:50.082689+00:00 end=None details={'distance_km': 358278.1722580132} />, <Event type=CONJUNCTION objects=[<Object type=SATELLITE name=MOON />, <Object type=PLANET name=VENUS />] start=2022-12-24 12:16:04.630107+00:00 end=None details=None />, <Event type=CONJUNCTION objects=[<Object type=SATELLITE name=MOON />, <Object type=PLANET name=MERCURY />] start=2022-12-24 19:32:19.571054+00:00 end=None details=None />]

Add support for twilights

Is your feature request related to a problem? Please describe.
When the sun sets, the sky is not immediately dark. Consequently, most of the objects are not visible until it is. The same happens when the sun is rising.

Describe the solution you'd like
A function that gives, for a date and a position, the end times of the three dawns and twilights of the day:

• civil dawn/twilight (geometric center of the Sun passes 6° under the horizon): Venus and the Moon are the only visible objects
• nautical dawn/twilight (geometric center of the Sun passes 12° under the horizon): the light of the Sun is still visible, but is not enough to hide the brightest stars.
• astronomical dawn/twilight (geometric center of the Sun passes 18° under the horizon), or full night: all the objects are visible (depending on the ambient light pollution).

The function would look like this:

def get_dawns_twilights(position: Position, date: date = date.today) -> (DawnsInformation, TwilightsInformation)

The TwilightsInformation type would be a class that handles the datetimes of the three dawns and twilights.
The DawnsInformation type may be an alias of TwilightsInformation.

Additional context

• Not sure for the name of the Dawns/TwilightInformation class. We might want a better name.
• We might want to take profit of Slyfield's skyfield.almanac.dark_twilight_day() function for better performances.
• Even though the function is named twilight, is should also take care about dawns the same way, as the logic is exactly the same.

Perihelion/aphelion

Event type: perihelion/aphelion
Involved objects (check the boxes):

• Sun
• Earth's moon
• Planets

Definition of the event:

• The perihelion is the nearest points of a body's direct orbit around the Sun.
• The aphelion is the farthest points of a body's direct orbit around the Sun.

Other useful information (implementation proposal, etc):
There is no point of computing the perihelion for all the planets here. Just the Earth's perihelion should be computed.

Add a function to localize the SEASON_CHANGE event

Is your feature request related to a problem? Please describe.
When a SEASON_CHANGE happens, the details contains the name of the month only. Even though it is expected to make it position-independent, it would be appreciated to provide a way to localize it depending on the latitude.

Describe the solution you'd like
Add a new function taking a SeasonType value and a position in arguments and returning a localized event depending on the position:

class LocalizedSeasonType(SeasonType):
    WINTER
    SPRING
    SUMMER
    AUTUMN

def get_localized_season(season: SeasonType, position: Position) -> LocalizedSeasonType

The returned value depends on the latitude. If it is exactly zero, then an exception explaining that the season cannot be localized should be thrown.

Describe alternatives you've considered
Currently, the only way to localize he season is to do it in user code.

Add a function to search for events

Add a way to search conveniently for events types between two dates:

# kosmorrolib/events.py
def search_events(event_types: [EventType], until: date, from: date = date.today()) -> [Event]

When used, this function searches for the given EventType values between the from and the until dates (both inclusive), and returns a list of Event objects that correspond to the request.

In some ways, this function's behavior is very similar to the get_events(), but it filters out the unwanted EventTypes.

Lunar eclipse

Event type: Lunar eclipse
Involved objects (check the boxes):

• Sun
• Earth's moon
• Planets

Definition of the event:

A lunar eclipse occurs when the Moon passes directly behind Earth and into its shadow. This can occur only when the Sun, Earth, and Moon are exactly or very closely aligned […], with Earth between the other two. A lunar eclipse can occur only on the night of a full moon. The type and length of a lunar eclipse depend on the Moon's proximity to either node of its orbit.

— Wikipedia, Lunar eclipse

There are five kinds of lunar eclipses:

• Penumbral lunar eclipse: the Moon passes through Earth's penumbra. The penumbra causes a subtle dimming of the lunar surface.
  • Total penumbral lunar eclipse: the entire Moon passes within Earth's penumbra. The portion of the Moon closest to the umbra may appear slightly darker than the rest of the lunar disk.
• Partial lunar eclipse: only a portion of the Moon enters Earth's umbra.
  • Total lunar eclipse: the entire Moon enters Earth's umbra.
    • Central lunar eclipse: the Moon passes through the center of Earth's shadow.

Solar eclipse

Event type: solar eclipse
Involved objects (check the boxes):

• Sun
• Earth's moon
• Planets

Definition of the event:

A solar eclipse occurs when a portion of the Earth is engulfed in a shadow cast by the Moon which fully or partially blocks sunlight. This occurs when the Sun, Moon and Earth are aligned. Such alignment coincides with a new moon (syzygy) indicating the Moon is closest to the ecliptic plane. In a total eclipse, the disk of the Sun is fully obscured by the Moon. In partial and annular eclipses, only part of the Sun is obscured.
— Wikipedia

Other useful information (implementation proposal, etc): three kinds of solar eclipses have to be taken in account:

• Total eclipse: the disk of the Sun is fully obscured by the Moon
• Partial eclipse: the moon obscures only a part of the Sun's disk, forming a solar crescent
• Annular eclipse: very similar to total eclipses, but the Moon is to far away to cover the entire solar disk, making it appear as a ring.

Extreme coordinates: IndexError: index 0 is out of bounds for axis 0 with size 0

Describe the bug
When using coordinates near the poles, the following error is thrown:

Traceback (most recent call last):
  File "/home/jerome/workspace/kosmorro/./kosmorro", line 27, in <module>
    sys.exit(main())
  File "/home/jerome/workspace/kosmorro/kosmorrolib/main.py", line 76, in main
    output = get_information(compute_date, position, timezone, output_format,
  File "/home/jerome/workspace/kosmorro/kosmorrolib/main.py", line 104, in get_information
    eph = ephemerides.get_ephemerides(date=compute_date, position=position, timezone=timezone)
  File "/home/jerome/workspace/kosmorro/kosmorrolib/ephemerides.py", line 138, in get_ephemerides
    rise_time = rise_times[0] if arr[0] else None
IndexError: index 0 is out of bounds for axis 0 with size 0

The error seems to be due the the lack of asters rise and set.

To Reproduce
Steps to reproduce the behavior:

1. North pole: ./kosmorro --latitude=69.85 --longitude=24.61 --date=2021-01-11 (bug on the Sun)
2. South pole: ./kosmorro --latitude=-67.32 --longitude=24.61 --date=2021-01-11 (bug on the Moon)

Expected behavior
Show the ephemerides normally (with no rise, culmination and set time when they can't be calculated).

Your configuration (please complete the following information):

• OS: Linux
• Python version: 3.9.1
• Kosmorro version: 0.8.1