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. 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