kaalavidya 0.3.2
The Science of Time — Accurate Indian Panchanga calculations in Python
License: MIT
Requires Python: >=3.9
Keywords: panchanga, panchangam, hindu-calendar, vedic, jyotish, astrology, vedic-astrology, tithi, nakshatra, yoga, karana, lagna, hora, surya-siddhanta, indian-calendar, sankalpa, muhurta, rahu-kala, indian-almanac, sunrise-sunset, festival-calendar, hindu, dharma, ephemeris, sidereal, lahiri, ayanamsha

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

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

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

---

## Install as Python Library

```bash
pip install kaalavidya
```

```python
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

```bash
# 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

```python
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:

```bash
pip install kaalavidya[server]
```

Or install from source:

```bash
cd acharavidya
pip install .
```

---

## REST API (when running the full app)

```bash
# 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

```bash
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](https://github.com/vikranthkorata/acharavidya/blob/main/LICENSE) for details.

---

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