Solar-Based Scheduling

To schedule tasks based on solar events such as sunrise, sunset, or various stages of dawn and dusk, you can use the solar schedule class. This is particularly useful for location-aware periodic tasks that need to align with natural light cycles.

Prerequisites

Solar scheduling requires the ephem library to perform astronomical calculations. You must install it in your environment:

pip install ephem

Basic Solar Scheduling

To schedule a task, instantiate the solar class with a specific event and the geographic coordinates (latitude and longitude) of the observer.

The following example schedules a task to run every sunrise in Madrid, Spain:

from celery import Celery
from celery.schedules import solar

app = Celery('tasks')

app.conf.beat_schedule = {
    'morning-inventory-check': {
        'task': 'tasks.process_morning_data',
        'schedule': solar('sunrise', 40.4168, -3.7038),
    },
}

Supported Solar Events

The solar schedule supports the following event strings:

Event	Description
dawn_astronomical	The sun is 18 degrees below the horizon.
dawn_nautical	The sun is 12 degrees below the horizon.
dawn_civil	The sun is 6 degrees below the horizon.
sunrise	The sun's upper limb touches the horizon.
solar_noon	The sun is at its highest point in the sky.
sunset	The sun's upper limb disappears below the horizon.
dusk_civil	The sun is 6 degrees below the horizon in the evening.
dusk_nautical	The sun is 12 degrees below the horizon in the evening.
dusk_astronomical	The sun is 18 degrees below the horizon in the evening.

Geographic Constraints

When instantiating solar(event, lat, lon), the coordinates must fall within valid ranges:

• Latitude: Must be between -90 and 90.
• Longitude: Must be between -180 and 180.

If coordinates are outside these ranges, the class will raise a ValueError using the SOLAR_INVALID_LATITUDE or SOLAR_INVALID_LONGITUDE templates defined in celery/schedules.py.

Handling Circumpolar Regions

In regions near the poles (e.g., the Arctic Circle), certain solar events may not occur for weeks or months (such as the sun never setting in summer).

The solar class handles this internally. If the ephem library raises a CircumpolarError (meaning the event won't happen today), the scheduler will automatically calculate the next check time to be one minute after the next "anti-transit" (the moment the sun is at its lowest point).

# Example for a location where the sun might not set
app.conf.beat_schedule = {
    'arctic-sunset-task': {
        'task': 'tasks.arctic_cleanup',
        'schedule': solar('sunset', 78.2232, 15.6267), # Longyearbyen, Norway
    },
}

Troubleshooting

• ImportError: If you attempt to use solar without the ephem library installed, an ImportError will be raised during the initialization of the solar instance in celery/schedules.py.
• Elevation and Pressure: Note that the implementation in celery/schedules.py hardcodes elev = 0 (sea level) and pressure = 0 (no atmospheric refraction) for the ephem.Observer. This may result in a slight discrepancy (usually a few minutes) compared to local weather service tables that account for altitude and atmospheric conditions.