kaalavidya 0.3.1

The Science of Time — Accurate Indian Panchanga calculations in Python

Acharavidya (आचारविद्या)

Indian Dharmic Knowledge Platform — Accurate Panchanga, Daily Almanac & More

Built with Kaalavidya (कालविद्या) — The Science of Time

---

Install as Python Library

pip install kaalavidya

from kaalavidya import Panchanga

p = Panchanga(
    year=2026, month=2, day=19,
    latitude=16.5062, longitude=80.648,
    timezone="Asia/Kolkata",
    city="Vijayawada",
    lang="en",
)
result = p.compute()
print(result.summary())

---

What does it compute?

• Pancha Anga: Tithi, Vara, Nakshatra (with pada), Yoga, Karana — all with transition times
• Calendar: Samvatsara, Masa (Amanta + Purnimanta), Paksha, Ritu, Ayana, Era Years
• Sun/Moon: Vedic & Drik sunrise/sunset, moonrise/moonset, day/night durations
• Auspicious: Brahma Muhurta, Abhijit, Amrit Kalam, Vijaya, Godhuli
• Inauspicious: Rahu Kala, Yamagandam, Gulika Kala, Durmuhurta, Varjyam
• Shoola & Vasa: Disha Shoola, Agnivasa, Shivavasa
• Muhurtas: 15 Dina + 15 Ratri muhurtas with names and auspiciousness
• Charts: Sunrise Rashi chart (South & North Indian), Planetary Orrery
• Planetary: Tarabalam, Chandrabalam, Combustion (Maudhya), Hora table
• Eclipses: Solar & Lunar with local visibility
• Surya Siddhanta: Traditional calculation engine as alternative to modern astronomy
• Sankalpa: Desha-kala portion of Hindu sankalpa (Indian locations)
• 7 Languages: English, Sanskrit, Hindi, Telugu, Tamil, Kannada, Malayalam

---

Full App with Web UI

This repo also includes a FastAPI web application with a beautiful Panchanga dashboard.

Prerequisites

• Python 3.9+
• pip

Setup & Run

# Clone the repo
git clone https://github.com/vikranthkorata/acharavidya.git
cd acharavidya

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# venv\Scripts\activate   # Windows

# Install dependencies
pip install -r requirements.txt

# Run the app
PYTHONPATH=. uvicorn app:app --reload --host 0.0.0.0 --port 8000

Open http://localhost:8000 in your browser to see the full Panchanga dashboard.

---

Python Library — Detailed Usage

from kaalavidya import Panchanga

# Full panchanga for a date and location
p = Panchanga(
    year=2026, month=2, day=19,
    latitude=16.5062, longitude=80.648,
    timezone="Asia/Kolkata",
    city="Vijayawada",
    lang="en",
    method="drik",  # or "siddhantic" or "both"
)
result = p.compute()
print(result.summary())

# Access individual fields
print(f"Tithi: {result.tithi[0].name}")
print(f"Nakshatra: {result.nakshatra[0].name} (Pada {result.nakshatra[0].pada})")
print(f"Samvatsara: {result.samvatsara}")
print(f"Disha Shoola: {result.disha_shoola}")
print(f"Agnivasa: {result.agnivasa}")
print(f"Shivavasa: {result.shivavasa}")

# Modular access — compute only what you need
from kaalavidya import compute_tithi, compute_sun_times
from kaalavidya import compute_disha_shoola, compute_agnivasa, compute_shivavasa
from datetime import datetime
from zoneinfo import ZoneInfo

sunrise = datetime(2026, 2, 19, 6, 30, tzinfo=ZoneInfo("Asia/Kolkata"))
next_sunrise = datetime(2026, 2, 20, 6, 30, tzinfo=ZoneInfo("Asia/Kolkata"))
tithis = compute_tithi(sunrise, next_sunrise, "en")
for t in tithis:
    print(f"  {t.name} — Devata: {t.devata}, Group: {t.group}")

# Standalone Shoola / Vasa (weekday: 0=Mon..6=Sun, tithi: 0-29)
print(compute_disha_shoola(3, "en"))     # Thursday
print(compute_agnivasa(1, 3, "en"))      # Tithi index 1 (Dwitiya), Thursday
print(compute_shivavasa(1, "en"))        # Tithi index 1 (Dwitiya)

Install with web server dependencies:

pip install kaalavidya[server]

Or install from source:

cd acharavidya
pip install .

---

REST API (when running the full app)

# Full daily panchanga
curl "http://localhost:8000/api/panchanga?year=2026&month=2&day=19&lat=16.5062&lon=80.648&lang=en&method=drik"

# Chart at specific time
curl "http://localhost:8000/api/chart?year=2026&month=2&day=19&hour=12&minute=0&lat=16.5062&lon=80.648&lang=en"

# City search
curl "http://localhost:8000/api/cities?q=Vijayawada"

---

Project Structure

acharavidya/
├── app.py                          # FastAPI application (API + static serving)
├── requirements.txt                # Python dependencies
├── kaalavidya/                     # Core Panchanga engine (also pip library)
│   ├── __init__.py                 # Public API exports
│   ├── constants.py                # Names, mappings, adhipati data, tables
│   ├── models.py                   # Data structures (dataclasses)
│   ├── panchanga.py                # Main Panchanga class (Drik engine)
│   ├── surya.py                    # Sun/Moon times, muhurtas, hora
│   ├── chandra.py                  # Tithi, nakshatra, yoga, karana, masa
│   ├── lagna.py                    # Ascendant/Lagna table
│   ├── chart.py                    # Rashi chart + planetary orrery
│   ├── grahana.py                  # Eclipse detection
│   ├── sankalpa.py                 # Sankalpa generator (desha-kala)
│   └── surya_siddhanta/            # Traditional Indian astronomy
│       ├── ganita.py               # SS longitude formulas
│       ├── sunrise.py              # SS sunrise/sunset
│       └── panchanga_ss.py         # Full SS panchanga
├── static/                         # Web frontend
│   ├── index.html                  # Main page
│   ├── style.css                   # Styling
│   ├── app.js                      # Main JS (rendering, i18n)
│   ├── chart.js                    # SVG chart renderer
│   └── orrery.js                   # SVG planetary orrery
├── data/
│   └── cities.json                 # Indian cities database
└── tests/
    ├── test_panchanga.py
    └── test_surya_siddhanta.py

---

Calculation Methods

Drik Ganita (Default)

• Uses Swiss Ephemeris (pyswisseph) backed by NASA JPL DE431 ephemeris
• Extremely precise modern astronomical positions
• Lahiri Ayanamsha for sidereal corrections
• Full feature support (Lagna, Maudhya, Eclipses, Charts, Orrery)

Surya Siddhanta

• Traditional Indian astronomical text (~400 CE)
• Mean + manda-corrected longitudes
• Kali Yuga epoch-based calculations
• Most features supported; Lagna/Eclipses/Maudhya require Swiss Eph

---

Languages

Code	Language	How it works
en	English	Transliterated Sanskrit names (Surya, Mesha, Tithi)
sa	संस्कृतम्	Full Sanskrit — every label and data point
hi	हिन्दी	Sanskrit words in Devanagari script
te	తెలుగు	Sanskrit words in Telugu script
ta	தமிழ்	Sanskrit words in Tamil script
kn	ಕನ್ನಡ	Sanskrit words in Kannada script
ml	മലയാളം	Sanskrit words in Malayalam script

---

Dependencies

Package	Version	Purpose
pyswisseph	≥2.10	Swiss Ephemeris (NASA JPL DE431 ephemeris)
astral	≥3.2	Sunrise/sunset/twilight calculations
fastapi	≥0.100	Web framework & API (optional, for full app)
uvicorn	≥0.23	ASGI server (optional, for full app)

---

Running Tests

cd acharavidya
source venv/bin/activate
PYTHONPATH=. python -m pytest tests/ -v

---

Contributing

This project draws from traditional Indian texts including:

• Surya Siddhanta
• Brihat Parashara Hora Shastra
• Dharmasindhu
• Nirnayasindhu
• Tattvadipika
• Muhurta Chintamani

Contributions welcome — especially for Vrata rules, regional variations, and translations.

---

License

MIT License — see LICENSE for details.

---

आचारविद्या — Built with love for Sanatana Dharma