Jyotish

A production-ready Flutter library for Vedic astrology calculations using Swiss Ephemeris. Provides high-precision sidereal planetary positions with Lahiri ayanamsa for authentic Jyotish (Vedic astrology) applications.

Features

✨ High-Precision Sidereal Calculations: Uses Swiss Ephemeris with Lahiri ayanamsa for accurate Vedic astrology

🌍 Authentic Vedic System:

• Sidereal zodiac
• Lahiri ayanamsa (default) with support for 40+ other ayanamsas
• Geocentric and topocentric calculations

🪐 Comprehensive Planet Support:

• Traditional Vedic planets (Sun, Moon, Mercury, Venus, Mars, Jupiter, Saturn)
• Rahu and Ketu (Lunar Nodes)
• Optional outer planets (Uranus, Neptune, Pluto)
• Lunar apogees and asteroids

📍 Rich Vedic Data:

• Sidereal longitude, latitude, and distance
• Zodiac sign and position within sign
• 27 Nakshatras with pada (quarter) divisions
• Retrograde detection
• Velocity/speed calculations

🎯 Complete Vedic Chart:

• Birth chart calculation with house cusps
• Rahu and Ketu positions
• Planetary dignities (exaltation, debilitation, own sign, moola trikona)
• Combustion detection
• Whole Sign house system

🎯 Easy to Use: Simple, intuitive API designed for Vedic astrology

🔒 Production Ready: Proper error handling, input validation, and resource management

Platform Support

Platform	Support
Android	✅
iOS	✅
macOS	✅
Linux	✅
Windows	✅

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  jyotish:
    git:
      url: https://github.com/rajsanjib/jyotish-flutter-library.git
      ref: main # or specify a tag/branch

Then run:

flutter pub get

Alternative Installation Methods

You can also specify a specific version or branch:

Using a specific tag/version:

dependencies:
  jyotish:
    git:
      url: https://github.com/rajsanjib/jyotish-flutter-library.git
      ref: v1.0.0 # Replace with desired version tag

Using a specific branch:

dependencies:
  jyotish:
    git:
      url: https://github.com/rajsanjib/jyotish-flutter-library.git
      ref: develop # or any other branch

For local development:

dependencies:
  jyotish:
    path: ../path/to/jyotish # Relative path to local library

Swiss Ephemeris Data Files

The library requires Swiss Ephemeris data files for calculations. You have two options:

1. Include data files in your app (recommended for production):

   • Download ephemeris files from Swiss Ephemeris
   • Place them in your app's assets folder
   • Initialize with the path to the data files

2. Use built-in ephemeris (limited accuracy):

   • The library includes a basic ephemeris for quick testing
   • Not recommended for production use

Usage

Basic Example

import 'package:jyotish/jyotish.dart';

void main() async {
  // Create an instance
  final jyotish = Jyotish();

  // Initialize the library
  await jyotish.initialize();

  // Define a location
  final location = GeographicLocation(
    latitude: 27.7172,  // Kathmandu, Nepal
    longitude: 85.3240,
    altitude: 1400,
  );

  // Calculate Sun's position (always sidereal with Lahiri ayanamsa)
  final sunPosition = await jyotish.getPlanetPosition(
    planet: Planet.sun,
    dateTime: DateTime.now(),
    location: location,
  );

  print('Sun is at ${sunPosition.formattedPosition}'); // Sidereal position
  print('Longitude: ${sunPosition.longitude}°');
  print('Nakshatra: ${sunPosition.nakshatra}');
  print('Is Retrograde: ${sunPosition.isRetrograde}');

  // Clean up
  jyotish.dispose();
}

Calculate Multiple Planets

// Calculate all traditional Vedic planets at once
final positions = await jyotish.getAllPlanetPositions(
  dateTime: DateTime(2024, 1, 1, 12, 0),
  location: location,
);

for (final entry in positions.entries) {
  print('${entry.key.displayName}: ${entry.value.formattedPosition}');
}

Custom Ayanamsa

// Use a different ayanamsa (default is Lahiri)
final flags = CalculationFlags.sidereal(SiderealMode.krishnamurti);

final position = await jyotish.getPlanetPosition(
  planet: Planet.moon,
  dateTime: DateTime.now(),
  location: location,
  flags: flags,
);

Advanced: Custom Calculation Flags

// Create custom calculation flags
final flags = CalculationFlags(
  siderealMode: SiderealMode.krishnamurti,
  useTopocentric: true,
  calculateSpeed: true,
);

final position = await jyotish.getPlanetPosition(
  planet: Planet.mars,
  dateTime: DateTime.now(),
  location: location,
  flags: flags,
);

Vedic Astrology Chart

// Calculate a complete Vedic astrology birth chart
final chart = await jyotish.calculateVedicChart(
  dateTime: DateTime(1990, 5, 15, 14, 30), // Birth time
  location: location, // Birth place
);

// Access Ascendant (Lagna)
print('Ascendant: ${chart.ascendantSign}');
print('Ascendant Degree: ${chart.ascendant}°');

// Access planetary positions with Vedic-specific data
final sunInfo = chart.getPlanet(Planet.sun);
if (sunInfo != null) {
  print('Sun in ${sunInfo.zodiacSign}');
  print('House: ${sunInfo.house}');
  print('Nakshatra: ${sunInfo.nakshatra} (Pada ${sunInfo.pada})');
  print('Dignity: ${sunInfo.dignity.english}'); // e.g., "Exalted", "Debilitated"
  print('Combust: ${sunInfo.isCombust}');
}

// Access Rahu (North Node) and Ketu (South Node)
print('Rahu in ${chart.rahu.zodiacSign} - House ${chart.rahu.house}');
print('Ketu in ${chart.ketu.zodiacSign} - always 180° from Rahu');

// Get planets by house
final firstHousePlanets = chart.getPlanetsInHouse(1);

// Get planets by dignity
final exaltedPlanets = chart.exaltedPlanets;
final debilitatedPlanets = chart.debilitatedPlanets;
final combustPlanets = chart.combustPlanets;
final retrogradePlanets = chart.retrogradePlanets;

// Access house cusps
for (int i = 0; i < 12; i++) {
  print('House ${i + 1}: ${chart.houses.cusps[i]}°');
}

Vedic Features:

• ✨ Sidereal zodiac with Lahiri ayanamsa (authentic Vedic calculations)
• 🏠 Whole Sign house system
• 🌟 Rahu (North Node) and Ketu (South Node) as separate entities
• 🎯 Planetary dignities: Exalted, Debilitated, Own Sign, Moola Trikona, etc.
• 🔥 Combustion detection (planets too close to Sun)
• 📍 27 Nakshatras with pada (quarter) divisions
• ♃ Retrograde motion detection
• 🌍 Support for 40+ different ayanamsas (Lahiri, Krishnamurti, Raman, etc.)

Note: This library is designed specifically for Vedic astrology and uses sidereal calculations. All planetary positions are calculated in the sidereal zodiac, not tropical (Western astrology).

Location from Degrees, Minutes, Seconds

final location = GeographicLocation.fromDMS(
  latDegrees: 27,
  latMinutes: 43,
  latSeconds: 1.92,
  isNorth: true,
  lonDegrees: 85,
  lonMinutes: 19,
  lonSeconds: 26.4,
  isEast: true,
  altitude: 1400,
);

API Reference

Main Classes

Jyotish

The main entry point for the library.

• initialize({String? ephemerisPath}): Initialize the library
• getPlanetPosition(...): Calculate a single planet's position
• getMultiplePlanetPositions(...): Calculate multiple planets
• getAllPlanetPositions(...): Calculate all major planets
• dispose(): Clean up resources

Planet (enum)

Enumeration of supported celestial bodies.

Available planets:

• Planet.sun, Planet.moon
• Planet.mercury, Planet.venus, Planet.mars
• Planet.jupiter, Planet.saturn
• Planet.uranus, Planet.neptune, Planet.pluto
• Planet.meanNode, Planet.trueNode
• Planet.chiron, Planet.ceres, etc.

Static methods:

• Planet.majorPlanets: Sun through Pluto
• Planet.traditionalPlanets: Sun through Saturn
• Planet.asteroids: Chiron, Ceres, Pallas, Juno, Vesta

PlanetPosition

Contains calculated position data.

Properties:

• longitude: Ecliptic longitude (0-360°)
• latitude: Ecliptic latitude
• distance: Distance from Earth in AU
• longitudeSpeed: Degrees per day
• zodiacSign: Name of zodiac sign
• positionInSign: Degrees within sign (0-30°)
• nakshatra: Indian lunar mansion name
• nakshatraPada: Quarter of nakshatra (1-4)
• isRetrograde: Whether planet is in retrograde motion
• formattedPosition: Human-readable position string

GeographicLocation

Represents a location on Earth.

Properties:

• latitude: -90 to 90 (North positive)
• longitude: -180 to 180 (East positive)
• altitude: Meters above sea level

CalculationFlags

Controls calculation behavior.

Factory constructors:

• CalculationFlags.defaultFlags(): Tropical, geocentric
• CalculationFlags.siderealLahiri(): Sidereal with Lahiri ayanamsa
• CalculationFlags.sidereal(SiderealMode): Custom sidereal mode
• CalculationFlags.topocentric(): Topocentric calculations

SiderealMode (enum)

Available ayanamsa systems for sidereal calculations.

Popular modes:

• SiderealMode.lahiri: Most common in Indian astrology
• SiderealMode.faganBradley: Western sidereal astrology
• SiderealMode.krishnamurti: KP astrology
• SiderealMode.raman: Raman ayanamsa
• 40+ other modes available

Error Handling

The library throws specific exception types:

try {
  final position = await jyotish.getPlanetPosition(...);
} on InitializationException catch (e) {
  print('Failed to initialize: $e');
} on CalculationException catch (e) {
  print('Calculation failed: $e');
} on ValidationException catch (e) {
  print('Invalid input: $e');
} on JyotishException catch (e) {
  print('General error: $e');
}

Example App

Run the example app to see the library in action:

cd example
flutter run

The example app demonstrates:

• Calculating all major planet positions
• Switching between tropical and sidereal zodiac
• Displaying position in multiple formats
• Showing nakshatra and retrograde status

Advanced Topics

Custom Ephemeris Path

await jyotish.initialize(
  ephemerisPath: '/path/to/ephemeris/files',
);

Topocentric vs Geocentric

Geocentric positions are calculated from Earth's center (default). Topocentric positions are calculated from a specific location on Earth's surface.

final flags = CalculationFlags(useTopocentric: true);

Understanding Ayanamsa

The ayanamsa is the difference between tropical and sidereal zodiac systems. Different systems use different reference points:

• Lahiri: Official ayanamsa of India
• Fagan-Bradley: Popular in Western sidereal astrology
• Krishnamurti: Used in KP system

Get current ayanamsa value:

final service = EphemerisService();
await service.initialize();
final ayanamsa = await service.getAyanamsa(
  dateTime: DateTime.now(),
  mode: SiderealMode.lahiri,
);
print('Lahiri Ayanamsa: ${ayanamsa.toStringAsFixed(6)}°');

Performance Considerations

1. Initialization: Call initialize() once at app startup
2. Batch Calculations: Use getMultiplePlanetPositions() for multiple planets
3. Caching: Consider caching results if querying the same time repeatedly
4. Resource Management: Always call dispose() when done

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This library is licensed under the MIT License. See the LICENSE file for details.

Swiss Ephemeris is licensed under GNU GPL v2 or Swiss Ephemeris Professional License.

Credits

This library uses:

• Swiss Ephemeris by Astrodienst AG
• Developed with ❤️ for the Flutter community

Support

• Issues: GitHub Issues
• 📖 Documentation: GitHub Wiki
• 💬 Discussions: GitHub Discussions

Changelog

See CHANGELOG.md for version history.

Roadmap

• House calculations
• Aspect calculations
• Transit calculations
• Dasha system support
• Chart drawing utilities
• More example apps

---

Made with ❤️ using Swiss Ephemeris