persis_times

persis_times is a Dart library for high-precision astronomical calculations used in Islamic timekeeping and calendrical systems.

The package provides computational tools for determining Islamic prayer times, calculating the Qibla direction, Hijri calendars, solar and lunar eclipse events.

The implementation is designed for scientific accuracy while remaining lightweight and usable in Dart and Flutter applications.

Scientific Background

Islamic ritual times are determined from observable astronomical phenomena. For example:

  • Fajr begins when the Sun reaches a specific depression angle below the horizon.
  • Dhuhr begins after the Sun passes the local meridian.
  • Maghrib begins at sunset.
  • Isha begins when twilight disappears.

Accurate determination of these times requires precise computation of the apparent position of the Sun and Moon relative to the observer on Earth.

This library implements modern astronomical models widely used in computational celestial mechanics.

Astronomical Algorithms

The astronomical calculations in this package are based on two well-known analytical theories of celestial motion.

Solar position model

Solar coordinates are computed using the planetary theory:

VSOP87D

VSOP87

VSOP87 (Variations Séculaires des Orbites Planétaires) is a high-precision analytical solution developed by Bretagnon and Francou for computing heliocentric planetary positions.

The VSOP87D variant expresses the coordinates in spherical form and is commonly used for efficient astronomical computation.

This model provides the heliocentric position of Earth which is then converted into the apparent geocentric position of the Sun.

Lunar position model

Lunar coordinates are computed using the analytical lunar theory:

ELPMPP02

ELPMPP02

ELPMPP02 (Éphémérides Lunaire Parisiennes – version MPP02) is a modern refinement of the ELP lunar theory developed by Chapront-Touzé and Chapront.

It provides a high-precision analytical representation of the Moon’s motion using trigonometric series expansions.

Series expansion terms

The implementation used in this package evaluates a total of:

38,326 correction terms

These terms include:

  • periodic perturbations
  • secular variations
  • planetary perturbations
  • Earth–Moon dynamical corrections

Using a large number of correction terms significantly improves positional accuracy for both the Sun and Moon compared to simplified astronomical algorithms.

Mathematical Methods

The library applies several classical astronomical and mathematical techniques:

Time systems

Conversions between:

  • Julian Day (JD)
  • Terrestrial Time (TT)
  • Universal Time (UT)

Coordinate systems

Transformations between:

  • Heliocentric coordinates
  • Ecliptic coordinates
  • Equatorial coordinates
  • Horizontal coordinates

Spherical astronomy

The following calculations are performed using spherical trigonometry:

  • solar altitude
  • hour angle
  • local sidereal time
  • Qibla direction

Features

  • High-precision solar position computation
  • High-precision lunar position computation
  • Prayer time calculation
  • Qibla direction determination
  • Hijri calendar conversion
  • Solar and lunar eclipse even
  • Pure Dart implementation

Installation

Add the package to your Dart or Flutter project:

dart pub add persis_times

Or manually in pubspec.yaml:

dependencies:
  persis_times: ^1.0.0

Then run:

dart pub get

Basic Usage

import 'package:persis_times/persis_times.dart';

void main() {
  print("Persis Times astronomical library initialized.");
}

More examples can be found in:

example/main.dart

Applications

This library can be used to build:

  • Islamic prayer time applications
  • mosque timetable systems
  • Qibla compass tools
  • Hijri calendar software
  • Islamic astronomy educational tools
  • astronomical research tools related to Islamic timekeeping

Accuracy and Limitations

Although the algorithms implemented in this package are based on modern astronomical models, real observations may vary slightly due to:

  • atmospheric refraction
  • local horizon obstruction
  • elevation above sea level
  • observational criteria used by different religious authorities

Users should follow local religious authorities when official prayer times are required.

Contributing

Contributions from developers and researchers interested in astronomical computation and Islamic timekeeping are welcome.

License

MIT License

Libraries

persis_times