Skip to content

Quick Start Guide

This guide will help you get started with NDAstro engine quickly.

Basic Usage

1. Calculate Ayanamsa

Calculate the ayanamsa (precession correction) for a given date:

from datetime import datetime
from ndastro_engine.ayanamsa import get_ayanamsa

# Calculate Lahiri ayanamsa for a date
date = datetime(2026, 1, 11, 12, 0, 0)
ayanamsa = get_ayanamsa(date, "lahiri")
print(f"Lahiri Ayanamsa: {ayanamsa:.6f}°")
# Output: Lahiri Ayanamsa: 24.260000°

2. Get Planet Positions

Get the longitude of a planet for a specific date and location:

from datetime import datetime
from ndastro_engine.core import get_planet_position
from ndastro_engine.enums.planet_enum import Planets

# New Delhi coordinates
latitude = 28.6139
longitude = 77.2090
date = datetime(2026, 1, 11, 12, 0, 0)

# Get Sun's position
sun_position = get_planet_position(Planets.SUN, latitude, longitude, date)
print(f"Sun's longitude: {sun_position:.6f}°")

# Get Moon's position
moon_position = get_planet_position(Planets.MOON, latitude, longitude, date)
print(f"Moon's longitude: {moon_position:.6f}°")

3. Calculate Sunrise and Sunset

Find sunrise and sunset times for any location:

from datetime import datetime, timezone
from ndastro_engine.core import get_sunrise_sunset

# New Delhi coordinates
latitude = 28.6139
longitude = 77.2090
date = datetime(2026, 1, 11, tzinfo=timezone.utc)

sunrise, sunset = get_sunrise_sunset(latitude, longitude, date)
print(f"Sunrise: {sunrise}")
print(f"Sunset: {sunset}")

# Optional: pass explicit elevation in meters
sunrise, sunset = get_sunrise_sunset(latitude, longitude, date, elevation=216.0)

4. Get Planet Rise and Set Times

Find rise and set times for any physical planet (including the Moon) using get_planet_rise_set:

from datetime import datetime, timezone
import pytz
from ndastro_engine.core import get_planet_rise_set
from ndastro_engine.enums import Planets

# Bangalore coordinates
latitude = 12.971667
longitude = 77.593611
date = datetime(2026, 5, 24, tzinfo=timezone.utc)

moonrise, moonset = get_planet_rise_set(Planets.MOON, latitude, longitude, date)

ist = pytz.timezone('Asia/Kolkata')
print(f"Moonrise: {moonrise.astimezone(ist).strftime('%H:%M')} IST")
print(f"Moonset:  {moonset.astimezone(ist).strftime('%H:%M')} IST")

Note

Rahu, Kethu, Ascendant, and Empty return (None, None) as they are not physical bodies. Either value may also be None when no rise or set occurs on the given date.

5. Calculate Dasa Periods

Compute multi-level dasa periods for a birth chart:

from datetime import datetime
import pytz
from ndastro_engine.dasa import DasaContext, get_dasa_birth_info, get_running_dasa

# Birth details (e.g., Chennai, India)
birth_datetime = datetime(1985, 10, 24, 6, 30, 0, tzinfo=pytz.timezone('Asia/Kolkata'))
latitude = 13.0827
longitude = 80.2707

# Create dasa context
context = DasaContext(
    birth_datetime=birth_datetime,
    lat=latitude,
    lon=longitude,
    ayanamsa_system="lahiri",
    dasa_type="vimshottari"
)

# Get birth info (nakshatra, lord, progress)
birth_info = get_dasa_birth_info(context)
print(f"Nakshatra: {birth_info.janma_nakshatra.name}")
print(f"Start Lord: {birth_info.start_lord}")

# Get running dasa at a specific date
query_datetime = datetime(2026, 4, 18, 12, 0, 0, tzinfo=pytz.UTC)
running_dasa = get_running_dasa(query_datetime, context)
print(f"Current Mahadasa: {running_dasa.maha.lord}")
print(f"Current Antardasa: {running_dasa.antara.lord}")

5. Check Retrograde Motion

Determine if a planet is in retrograde motion:

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

check_date = datetime(2023, 12, 20, 12, 0, 0)
latitude = Angle(degrees=28.6139)
longitude = Angle(degrees=77.2090)

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")

6. Available Ayanamsa Systems

NDAstro engine supports 16 different ayanamsa calculation methods:

from datetime import datetime
from ndastro_engine.ayanamsa import get_ayanamsa

date = datetime(2026, 1, 11, 12, 0, 0)

# Popular systems
lahiri = get_ayanamsa(date, "lahiri")
kp_new = get_ayanamsa(date, "krishnamurti_new")
kp_old = get_ayanamsa(date, "krishnamurti_old")
raman = get_ayanamsa(date, "raman")
fagan_bradley = get_ayanamsa(date, "fagan_bradley")

# Traditional systems
kali = get_ayanamsa(date, "kali")
yukteshwar = get_ayanamsa(date, "yukteshwar")
aryabhatta = get_ayanamsa(date, "aryabhatta")

print(f"Lahiri: {lahiri:.6f}°")
print(f"KP New: {kp_new:.6f}°")
print(f"Raman: {raman:.6f}°")

Planet Enums

All planets are available through the Planets enum:

from ndastro_engine.enums.planet_enum import Planets

# Available planets
planets = [
    Planets.SUN,
    Planets.MOON,
    Planets.MERCURY,
    Planets.VENUS,
    Planets.MARS,
    Planets.JUPITER,
    Planets.SATURN,
    Planets.URANUS,
    Planets.NEPTUNE,
    Planets.PLUTO,
    Planets.RAHU,
    Planets.KETHU,
]

# Get planet codes
print(Planets.JUPITER.code)  # Output: "JU" (short code)
print(Planets.RAHU.code)     # Output: "RA" (short code)

# Get astronomical codes (for API functions)
print(Planets.JUPITER.astronomical_code)  # Output: "jupiter barycenter"
print(Planets.RAHU.astronomical_code)     # Output: "rahu"

Utility Functions

Degree Normalization

from ndastro_engine.utils import normalize_degree

# Normalize degrees to 0-360 range
angle = normalize_degree(450.0)
print(angle)  # Output: 90.0

angle = normalize_degree(-30.0)
print(angle)  # Output: 330.0

DMS Conversion

from ndastro_engine.utils import dd2dms, dms2dd, dd2dmsstr

# Decimal degrees to DMS
degrees, minutes, seconds, sign = dd2dms(45.5)
print(f"{degrees}° {minutes}' {seconds:.2f}\"")  # Output: 45° 30' 0.00"

# DMS to decimal degrees
decimal = dms2dd(45, 30, 0)
print(decimal)  # Output: 45.5

# Formatted string
dms_str = dd2dmsstr(45.5)
print(dms_str)  # Output: 45° 30' 0.00"

Elevation Lookup by Coordinates

from ndastro_engine.utils import get_elevation_by_latlon

latitude = 12.97
longitude = 77.59

elevation = get_elevation_by_latlon(latitude, longitude)
print(f"Elevation: {elevation} m")

The elevation utility calls an online elevation API with latitude and longitude. If lookup fails, it safely returns 0.0.

You can use this directly, or let get_sunrise_sunset() auto-resolve elevation when elevation is not provided.

Next Steps