kaalavidya 0.3.0

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

---

What is this?

Acharavidya is a platform for Indian traditional time-keeping and dharmic knowledge. The first module — Kaalavidya — is a fully functional Vedic Panchanga (almanac) that computes:

• 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
• 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
• 7 Languages: English, Sanskrit, Hindi, Telugu, Tamil, Kannada, Malayalam

---

Quick Start

Prerequisites

• Python 3.9+ (tested on 3.9, 3.10, 3.11)
• pip (Python package manager)

Setup

# 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 in Browser

Navigate to http://localhost:8000

---

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)
│   ├── vrata.py                    # Festival/Vrata engine (skeleton)
│   └── 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 files
│   ├── test_panchanga.py
│   └── test_surya_siddhanta.py
└── docs/
    └── PRD.md                      # Product Requirements Document

---

API Usage

REST API

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

Python Library

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

# Modular access — compute only what you need
from kaalavidya import compute_tithi, compute_sun_times
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}")

---

Dependencies

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

All dependencies are listed in requirements.txt.

---

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

---

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

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

---

Install as Python Library

pip install kaalavidya

Or install from source:

cd acharavidya
pip install .

With web server dependencies:

pip install kaalavidya[server]

License

MIT License — see LICENSE for details.

---

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