Skip to content

API Reference: Retrograde Module

Overview

This module provides functions to detect and track planetary retrograde motion from any location on Earth.

Functions

retrograde

Provides functions to determine if a planet is in retrograde motion.

RetrogradeFunction

A class to determine if a planet is in retrograde motion from a given location on Earth.

Attributes:

Name Type Description
astronomical_code str

The astronomical code of the planet to observe.
latitude float

The latitude of the observer's location.
longitude float

The longitude of the observer's location.
step_days int

The number of days to step back for comparison (default is 7).

Methods:

Name Description
__call__

Time) -> bool: Determines if the planet is in retrograde motion at the given time t. Returns True if the planet is in retrograde motion, otherwise False.
Source code in ndastro_engine/retrograde.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
class RetrogradeFunction:
    """A class to determine if a planet is in retrograde motion from a given location on Earth.

    Attributes:
        astronomical_code (str): The astronomical code of the planet to observe.
        latitude (float): The latitude of the observer's location.
        longitude (float): The longitude of the observer's location.
        step_days (int): The number of days to step back for comparison (default is 7).

    Methods:
        __call__(t: Time) -> bool:
            Determines if the planet is in retrograde motion at the given time `t`.
            Returns True if the planet is in retrograde motion, otherwise False.

    """

    def __init__(self, astronomical_code: AstronomicalCode, latitude: float, longitude: float) -> None:
        """Initialize a new instance of the retrograde class.

        Args:
            astronomical_code (AstronomicalCode): The astronomical code of the planet.
            latitude (float): The latitude coordinate.
            longitude (float): The longitude coordinate.

        """
        self.astronomical_code: AstronomicalCode = astronomical_code
        self.latitude = latitude
        self.longitude = longitude
        self.step_days = 7

    def __call__(self, t: Time) -> bool:
        """Determine if the planet is in retrograde motion at a given time.

        This method calculates the ecliptic longitude of the planet at the given time `t`
        and compares it with the ecliptic longitude of the planet at the previous time `t-1`.
        If the longitude decreases, the planet is in retrograde motion.

        Args:
            t (Time): The time at which to check for retrograde motion.

        Returns:
            bool: True if the planet is in retrograde motion, False otherwise.

        """
        lon_now = get_planet_position(
            Planets.from_astronomical_code(self.astronomical_code), self.latitude, self.longitude, cast("datetime", t.utc_datetime())
        )
        lon_prev = get_planet_position(
            Planets.from_astronomical_code(self.astronomical_code), self.latitude, self.longitude, cast("datetime", (t - 1).utc_datetime())
        )

        return cast("float", lon_now.longitude) < cast(
            "float",
            lon_prev.longitude,
        )  # Retrograde if longitude decreases

__call__(t)

Determine if the planet is in retrograde motion at a given time.

This method calculates the ecliptic longitude of the planet at the given time t and compares it with the ecliptic longitude of the planet at the previous time t-1. If the longitude decreases, the planet is in retrograde motion.

Parameters:

Name Type Description Default
t Time

The time at which to check for retrograde motion.

 required

Returns:

Name Type Description
bool bool

True if the planet is in retrograde motion, False otherwise.
Source code in ndastro_engine/retrograde.py 
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
def __call__(self, t: Time) -> bool:
    """Determine if the planet is in retrograde motion at a given time.

    This method calculates the ecliptic longitude of the planet at the given time `t`
    and compares it with the ecliptic longitude of the planet at the previous time `t-1`.
    If the longitude decreases, the planet is in retrograde motion.

    Args:
        t (Time): The time at which to check for retrograde motion.

    Returns:
        bool: True if the planet is in retrograde motion, False otherwise.

    """
    lon_now = get_planet_position(
        Planets.from_astronomical_code(self.astronomical_code), self.latitude, self.longitude, cast("datetime", t.utc_datetime())
    )
    lon_prev = get_planet_position(
        Planets.from_astronomical_code(self.astronomical_code), self.latitude, self.longitude, cast("datetime", (t - 1).utc_datetime())
    )

    return cast("float", lon_now.longitude) < cast(
        "float",
        lon_prev.longitude,
    )  # Retrograde if longitude decreases

__init__(astronomical_code, latitude, longitude)

Initialize a new instance of the retrograde class.

Parameters:

Name Type Description Default
astronomical_code AstronomicalCode

The astronomical code of the planet.

 required
latitude float

The latitude coordinate.

 required
longitude float

The longitude coordinate.

 required
Source code in ndastro_engine/retrograde.py 
30
31
32
33
34
35
36
37
38
39
40
41
42
def __init__(self, astronomical_code: AstronomicalCode, latitude: float, longitude: float) -> None:
    """Initialize a new instance of the retrograde class.

    Args:
        astronomical_code (AstronomicalCode): The astronomical code of the planet.
        latitude (float): The latitude coordinate.
        longitude (float): The longitude coordinate.

    """
    self.astronomical_code: AstronomicalCode = astronomical_code
    self.latitude = latitude
    self.longitude = longitude
    self.step_days = 7

__get_retrograde_function(astronomical_code, latitude, longitude)

Create a RetrogradeFunction instance for a given planet and location.

Parameters:

Name Type Description Default
astronomical_code AstronomicalCode

The astronomical code of the planet.

 required
latitude float

The latitude of the location.

 required
longitude float

The longitude of the location.

 required

Returns:

Name Type Description
RetrogradeFunction RetrogradeFunction

An instance of RetrogradeFunction for the specified planet and location.
Source code in ndastro_engine/retrograde.py 
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
def __get_retrograde_function(
    astronomical_code: AstronomicalCode,
    latitude: float,
    longitude: float,
) -> RetrogradeFunction:
    """Create a RetrogradeFunction instance for a given planet and location.

    Args:
        astronomical_code (AstronomicalCode): The astronomical code of the planet.
        latitude (float): The latitude of the location.
        longitude (float): The longitude of the location.

    Returns:
        RetrogradeFunction: An instance of RetrogradeFunction for the specified planet and location.

    """
    return RetrogradeFunction(astronomical_code, latitude, longitude)

find_retrograde_periods(start_date, end_date, astronomical_code, latitude, longitude)

Calculate the retrograde periods for a given planet within a specified date range and location.

Parameters:

Name Type Description Default
start_date datetime

The start date of the period to check for retrograde motion.

 required
end_date datetime

The end date of the period to check for retrograde motion.

 required
astronomical_code AstronomicalCode

The astronomical code of the planet to check for retrograde motion.

 required
latitude float

The latitude of the observation location.

 required
longitude float

The longitude of the observation location.

 required

Returns:

Type Description
list[tuple[datetime, datetime]]

list[tuple[datetime, datetime]]: A list of tuples, each containing the start and end datetime of a retrograde period.
Source code in ndastro_engine/retrograde.py 
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
def find_retrograde_periods(
    start_date: datetime,
    end_date: datetime,
    astronomical_code: AstronomicalCode,
    latitude: float,
    longitude: float,
) -> list[tuple[datetime, datetime]]:
    """Calculate the retrograde periods for a given planet within a specified date range and location.

    Args:
        start_date (datetime): The start date of the period to check for retrograde motion.
        end_date (datetime): The end date of the period to check for retrograde motion.
        astronomical_code (AstronomicalCode): The astronomical code of the planet to check for retrograde motion.
        latitude (float): The latitude of the observation location.
        longitude (float): The longitude of the observation location.

    Returns:
        list[tuple[datetime, datetime]]: A list of tuples, each containing the start and end datetime of a retrograde period.

    """
    # Time range for 2025
    t0 = ts.utc(start_date)
    t1 = ts.utc(end_date)

    # Find times where Venus changes direction
    times, values = find_discrete(
        t0,
        t1,
        __get_retrograde_function(astronomical_code, latitude, longitude),
    )
    retrograde_periods = []
    in_retrograde = False
    retro_start = None

    for t, retro in zip(times, values, strict=False):
        if retro:
            if not in_retrograde:
                retro_start = cast("Time", t).utc_datetime()
                in_retrograde = True
        elif in_retrograde:
            retrograde_periods.append((retro_start, t.utc_datetime()))
            in_retrograde = False

    if in_retrograde:
        retrograde_periods.append((retro_start, t1.utc_datetime()))

    return retrograde_periods

is_planet_in_retrograde(check_date, astronomical_code, latitude, longitude)

Check if a planet is in retrograde motion on a specific date.

Parameters:

Name Type Description Default
check_date datetime

The date to check for retrograde motion.

 required
astronomical_code AstronomicalCode

The astronomical code of the planet to check.

 required
latitude float

The latitude in decimal degrees of the observation location.

 required
longitude float

The longitude in decimal degrees of the observation location.

 required

Returns:

Type Description
tuple[bool, datetime | None, datetime | None]

tuple[bool, datetime | None, datetime | None]: A tuple containing: - bool: True if the planet is in retrograde motion on the given date, otherwise False. - datetime | None: The start date of the retrograde period (None if not in retrograde). - datetime | None: The end date of the retrograde period (None if not in retrograde).
Source code in ndastro_engine/retrograde.py 
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
def is_planet_in_retrograde(
    check_date: datetime,
    astronomical_code: AstronomicalCode,
    latitude: float,
    longitude: float,
) -> tuple[bool, datetime | None, datetime | None]:
    """Check if a planet is in retrograde motion on a specific date.

    Args:
        check_date (datetime): The date to check for retrograde motion.
        astronomical_code (AstronomicalCode): The astronomical code of the planet to check.
        latitude (float): The latitude in decimal degrees of the observation location.
        longitude (float): The longitude in decimal degrees of the observation location.

    Returns:
        tuple[bool, datetime | None, datetime | None]: A tuple containing:
            - bool: True if the planet is in retrograde motion on the given date, otherwise False.
            - datetime | None: The start date of the retrograde period (None if not in retrograde).
            - datetime | None: The end date of the retrograde period (None if not in retrograde).

    """
    if astronomical_code not in [
        Planets.SUN.astronomical_code,
        Planets.MOON.astronomical_code,
        Planets.ASCENDANT.astronomical_code,
        Planets.EMPTY.astronomical_code,
    ]:
        start_date = check_date - timedelta(days=365)
        end_date = check_date + timedelta(days=365)
        retrograde_periods = find_retrograde_periods(
            start_date,
            end_date,
            astronomical_code,
            latitude,
            longitude,
        )

        for period_start, period_end in retrograde_periods:
            if period_start <= check_date <= period_end:
                return (True, period_start, period_end)

    return (False, None, None)

RetrogradeFunction Class

RetrogradeFunction

A class to determine if a planet is in retrograde motion from a given location on Earth.

Attributes:

Name Type Description
astronomical_code str

The astronomical code of the planet to observe.
latitude float

The latitude of the observer's location.
longitude float

The longitude of the observer's location.
step_days int

The number of days to step back for comparison (default is 7).

Methods:

Name Description
__call__

Time) -> bool: Determines if the planet is in retrograde motion at the given time t. Returns True if the planet is in retrograde motion, otherwise False.
Source code in ndastro_engine/retrograde.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
class RetrogradeFunction:
    """A class to determine if a planet is in retrograde motion from a given location on Earth.

    Attributes:
        astronomical_code (str): The astronomical code of the planet to observe.
        latitude (float): The latitude of the observer's location.
        longitude (float): The longitude of the observer's location.
        step_days (int): The number of days to step back for comparison (default is 7).

    Methods:
        __call__(t: Time) -> bool:
            Determines if the planet is in retrograde motion at the given time `t`.
            Returns True if the planet is in retrograde motion, otherwise False.

    """

    def __init__(self, astronomical_code: AstronomicalCode, latitude: float, longitude: float) -> None:
        """Initialize a new instance of the retrograde class.

        Args:
            astronomical_code (AstronomicalCode): The astronomical code of the planet.
            latitude (float): The latitude coordinate.
            longitude (float): The longitude coordinate.

        """
        self.astronomical_code: AstronomicalCode = astronomical_code
        self.latitude = latitude
        self.longitude = longitude
        self.step_days = 7

    def __call__(self, t: Time) -> bool:
        """Determine if the planet is in retrograde motion at a given time.

        This method calculates the ecliptic longitude of the planet at the given time `t`
        and compares it with the ecliptic longitude of the planet at the previous time `t-1`.
        If the longitude decreases, the planet is in retrograde motion.

        Args:
            t (Time): The time at which to check for retrograde motion.

        Returns:
            bool: True if the planet is in retrograde motion, False otherwise.

        """
        lon_now = get_planet_position(
            Planets.from_astronomical_code(self.astronomical_code), self.latitude, self.longitude, cast("datetime", t.utc_datetime())
        )
        lon_prev = get_planet_position(
            Planets.from_astronomical_code(self.astronomical_code), self.latitude, self.longitude, cast("datetime", (t - 1).utc_datetime())
        )

        return cast("float", lon_now.longitude) < cast(
            "float",
            lon_prev.longitude,
        )  # Retrograde if longitude decreases

__call__(t)

Determine if the planet is in retrograde motion at a given time.

This method calculates the ecliptic longitude of the planet at the given time t and compares it with the ecliptic longitude of the planet at the previous time t-1. If the longitude decreases, the planet is in retrograde motion.

Parameters:

Name Type Description Default
t Time

The time at which to check for retrograde motion.

 required

Returns:

Name Type Description
bool bool

True if the planet is in retrograde motion, False otherwise.
Source code in ndastro_engine/retrograde.py 
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
def __call__(self, t: Time) -> bool:
    """Determine if the planet is in retrograde motion at a given time.

    This method calculates the ecliptic longitude of the planet at the given time `t`
    and compares it with the ecliptic longitude of the planet at the previous time `t-1`.
    If the longitude decreases, the planet is in retrograde motion.

    Args:
        t (Time): The time at which to check for retrograde motion.

    Returns:
        bool: True if the planet is in retrograde motion, False otherwise.

    """
    lon_now = get_planet_position(
        Planets.from_astronomical_code(self.astronomical_code), self.latitude, self.longitude, cast("datetime", t.utc_datetime())
    )
    lon_prev = get_planet_position(
        Planets.from_astronomical_code(self.astronomical_code), self.latitude, self.longitude, cast("datetime", (t - 1).utc_datetime())
    )

    return cast("float", lon_now.longitude) < cast(
        "float",
        lon_prev.longitude,
    )  # Retrograde if longitude decreases

__init__(astronomical_code, latitude, longitude)

Initialize a new instance of the retrograde class.

Parameters:

Name Type Description Default
astronomical_code AstronomicalCode

The astronomical code of the planet.

 required
latitude float

The latitude coordinate.

 required
longitude float

The longitude coordinate.

 required
Source code in ndastro_engine/retrograde.py 
30
31
32
33
34
35
36
37
38
39
40
41
42
def __init__(self, astronomical_code: AstronomicalCode, latitude: float, longitude: float) -> None:
    """Initialize a new instance of the retrograde class.

    Args:
        astronomical_code (AstronomicalCode): The astronomical code of the planet.
        latitude (float): The latitude coordinate.
        longitude (float): The longitude coordinate.

    """
    self.astronomical_code: AstronomicalCode = astronomical_code
    self.latitude = latitude
    self.longitude = longitude
    self.step_days = 7

Examples

Check if a Planet is Retrograde

from datetime import datetime
from skyfield.units import Angle
from ndastro_engine.utils import is_planet_in_retrograde
from ndastro_engine.enums import Planets

# Location: Chennai, India
latitude = Angle(degrees=13.0827)
longitude = Angle(degrees=80.2707)

# Check Mercury retrograde on a specific date
check_date = datetime(2023, 12, 20, 12, 0, 0)
is_retro, start_date, end_date = is_planet_in_retrograde(
    check_date,
    Planets.MERCURY.astronomical_code,
    latitude,
    longitude
)

if is_retro:
    print(f"Mercury is retrograde from {start_date} to {end_date}")
else:
    print("Mercury is in direct motion")

Get Retrograde Period for Multiple Planets

from datetime import datetime
from skyfield.units import Angle
from ndastro_engine.utils import is_planet_in_retrograde
from ndastro_engine.enums import Planets

latitude = Angle(degrees=28.6139)  # New Delhi
longitude = Angle(degrees=77.2090)
check_date = datetime(2026, 4, 18, 12, 0, 0)

planets_to_check = [
    Planets.MERCURY,
    Planets.VENUS,
    Planets.MARS,
    Planets.JUPITER,
    Planets.SATURN
]

for planet in planets_to_check:
    is_retro, start, end = is_planet_in_retrograde(
        check_date,
        planet.astronomical_code,
        latitude,
        longitude
    )
    status = "Retrograde" if is_retro else "Direct"
    print(f"{planet.name}: {status}")
    if is_retro and start and end:
        print(f"  Period: {start.date()} to {end.date()}")

See Also