Muslim Prayer Times Library for Dart #

Quick Start #

1. Open your `pubspec.yaml` file and add this entry:

`````` libpray: ^0.1.0
``````
2. Then run `pub get`.

3. Import this library into your code:

`````` import 'package:libpray/libpray.dart';
``````

Building From Source #

Dependencies #

1. Dart SDK version 2.0.0-dev.52.0 or newer.

Steps #

1. Clone this git repo into your machine.
2. Run this command: `pub run build_runner build`

How Prayer Times Are Calculated #

Astronomical Measures #

Equation of Time #

The equation of time describes the difference of mean solar time (as shown by the clock) and apparent solar time (as shown by sundial). The equation of time is due to two phenomena; the Earth's rotational axis tilt of 23.5° and the elliptical orbit of the Earth [2].

As shown in the graph, apparent time can be ahead of mean time by as much as 16 minutes and 33 seconds (around November 3rd) or can be behind by as much as 14 minutes and 6 seconds (around February 12th).

The equation of time can be calculated using the following formula [3]:

1. Compute the numbers of days and fraction, denoted as `D`, from J2000.0 epoch which is equivalent to January 1.5, 2000 in Gregorian or 2451545.0 in Julian Date:

`````` D = JD - 2451545.0
``````

where `JD` is the Julian Date of interest.

2. Then, compute:

`````` // The mean anomaly of the sun, `g`.
g = 357.529 + (0.98560028 * D)

// The mean longitude of the sun, `q`.
q = 280.459 + (0.98564736 * D)

// The geocentric apparent ecliptic longitude of the sun (adjusted for aberration), L.
L = q + (1.915 * sin(g)) + (0.020 * sin(2 * g))
``````

All constants are in degrees therefore `g`, `q` and `L`. Computed `g`, `q` and `L` must be reduced to the range of `0°` to `360°`.

3. Compute the mean obliquity of the ecliptic in degrees, `e`:

`````` e = 23.439 - (0.0000003.6 * D)
``````
4. Once the apparent ecliptic longitude of the sun, `L`, and the mean obliquity of the ecliptic, `e` have been computed, the right ascension, `RA` of the sun can be calculated:

`````` RA = atan2(cos(e) * sin(L), cos(L))
``````
5. Thus, equation of time can be obtained as follows:

`````` EqT = (q / 15) - RA
``````

Declination of Sun #

The declination of the Sun is the measurement of the angle between the Sun’s rays and the Earth’s equatorial plane. This principle is used to explain why the earth experience different seasons which are four in some countries and only two in the others.

The Earth’s axis is tilted by 23.5 degrees away from the solar plane. The Sun’s declination varies throughout the year. Its declination becomes zero during the spring equinox and reaches the maximum declination angle of 23.5 degrees during the summer solstice. It reverts to zero declination when fall equinox comes and drops to the negative 23.5 declination during the winter solstice [4][5].

The sun's declination can be computed using the formula stated above from step 1 until step 3. Then, the declination, `d` can be obtained by:

``````d = asin(sin(e) * sin(L))
``````

Time of Sun at Given Angle Below Horizon #

The following formula can be used to calculate the difference of time between the mid day and the time when the sun reaches the `α` angle below the horizon, `T(α)` [1]:

``````T(α) = acos((-sin(α) - (sin(d) * sin(latitude))) / (cos(d) * cos(latitude))) / 15
``````

This library uses the following formula for applying adjustment to the calculated prayer times (denoted as `adj`):

``````adj = timezone - longitude / 15
``````

Dhuhr #

Dhuhr prayer time arrives when the sun begins to decline after reaching its highest point on the sky [1]. To compute dhuhr prayer time, first, the time of the mid day is calculated:

``````midday = 12 - EqT
``````

Then, by adding adjustment, `adj` to the calculated mid day time, we can obtained the dhuhr prayer time:

``````dhuhr = midday + adj
``````

This library, additionally, added 65 seconds to the calculated dhuhr time above as we use the following fiqh method:

Dhuhr is when the Sun's disk comes out of its zenith line, which is a line between the observer and the center of the Sun when it is at the highest point [6].

Fajr and Isha #

To calculate fajr and isha prayer times, these parameters are required:

• The sun declination, `d`.
• The midday time, `midday`.
• Sun angle, `α` for fajr and isha.
• Location's latitude, `latitude`.

First, `T(α)` is calculated using this formula. Then, the fajr time can be obtained by subtracting calculated `T(α)` from the `midday`:

``````fajr = midday - T(α)
``````

The isha time can be obtained by adding calculated `T(α)` to the `midday`:

``````isha = midday + T(α)
``````

There are several opinions about the angle to be used for calculating fajr and isha prayer times. The following table shows the methods offered by this library including their fajr and isha angles used:

MethodFajr angleIsha angle
Muslim World League18.017.0
Islamic Society of North America15.015.0
Egyptian General Authority of Survey19.517.5
Umm Al-Qura University, Mecca18.5*N/A**
University of Islamic Sciences, Karachi18.018.0
Union des Organisations Islamiques de France12.012.0
Majlis Ugama Islam Singapura20.018.0
Department of Islamic Advancement, Malaysia (JAKIM)20.018.0
Ithna Ashari16.014.0
Institute of Geophysics, University of Tehran17.714.0***

* Umm Al-Qura University, Mecca uses fajr angle of 19.0 before year 1430 in Islamic calendar.

** Umm Al-Qura University, Mecca does not specifies isha angle as it just add 90 minutes (120 in Ramadan) to the maghrib prayer time for obtaining isha prayer time.

*** Isha angle is not explicitly defined in method by Institute of Geophysics, University of Tehran.

Sunrise and Sunset #

The astronomical sunrise and sunset occur at `α = 0`. Due to the refraction of light by terrestrial atmosphere, actual sunrise appears slightly before astronomical sunrise and actual sunset occurs slightly after astronomical sunset. Thus, to get the actual sunrise and sunset, the angle `α` starts from a value of `0.833` [1]. If the elevation is greater than `0`, the angle can be calculated as follows:

``````α = 0.833 + (0.0347 * sqrt(elevation))
``````

Then, the actual sunrise and sunset can be calculated as follows:

``````// Sunrise.
sunrise = midday - T(α)

// Sunset.
sunset = midday + T(α)
``````

Asr #

There are two main opinions for computing asr prayer time. Majority of fiqh's school (Shafi'i, Maliki and Hanbali) say that the asr prayer time is when the shadow's length of any object is equal to the length of the object itself plus the shadow's length of that object at noon [1].

First, the angle, `α` is calculated using this formula:

``````// For shafi'i, maliki and hanbali, t = 1 while hanafi, t = 2
t = 1
α = -arccot(t + tan(latitude - d))
``````

Then, asr prayer time is obtained using the following formula:

``````asr = midday + T(α)
``````

Maghrib #

From point view of Sunni, the beginning of the maghrib prayer time is once the sun has completely set beneath the horizon, which can be deduced as the same as the sunset time. This library add 1 minute to the sunset time as precaution. In Shia's point of view, the dominant opinion is that as long as the redness of the eastern sky which appears after sunset has not passed overhead, maghrib prayer should not be performed [1]. Usually, the calculate maghrib prayer time like the isha prayer time is calculated except the angle is replaced with the twilight angle:

``````α = twilight_angle
maghrib = midday + T(α)
``````

The following table shows the angle used by Shia method:

MethodTwilight angle
Ithna Ashari4.0
Institute of Geophysics, University of Tehran4.5

Dhuha #

Dhuha time arrives when a third of sunrise and fajr time difference is added to the sunrise time [7]. Thus, this library calculate the dhuha time as follows:

``````diff = sunrise - fajr
dhuha = sunrise + (diff / 3)
``````

Midnight #

Midnight is generally calculated as the mean time from sunset to sunrise of the next day [1]:

``````diff = sunrise - sunset
midnight = sunset + (diff / 2)
``````

However, in Shia point of view, the midnight (juridical midnight, the ending time for performing isha prayer) is calculated as the mean time from sunset to fajr [1]:

``````diff = fajr - sunset
midnight = sunset + (diff / 2)
``````

Example #

``````import 'package:libpray/libpray.dart';

void main() {
// Use April 12th, 2018.
const int year = 2018;
const int month = 4;
const int day = 12;
final DateTime when = DateTime.utc(year, month, day);

// Init settings.
final PrayerCalculationSettings settings = PrayerCalculationSettings();

// Set calculation method to JAKIM (Fajr: 18.0 and Isha: 20.0).

// Init location info.
const Geocoordinate geo = const Geocoordinate(2.0, 101.0, 2.0);
const double timezone = 8.0;

// Generate prayer times for one day on April 12th, 2018.
final Prayers prayers = Prayers.on(when, settings, geo, timezone);
print(prayers.imsak);
print(prayers.fajr);
print(prayers.sunrise);
print(prayers.dhuha);
print(prayers.dhuhr);
print(prayers.asr);
print(prayers.sunset);
print(prayers.maghrib);
print(prayers.isha);
print(prayers.midnight);

// Generate current prayer time
final Prayer current = Prayer.now(settings, geo, timezone);
print('\${current.type}: \${current.time}');

// Generate next prayer time
final Prayer next = Prayer.next(settings, geo, timezone);
print('\${next.type}: \${next.time}');

// Generate later prayer time
final Prayer later = Prayer.later(settings, geo, timezone);
print('\${later.type}: \${later.time}');

// Generate after later prayer time
final Prayer afterLater = Prayer.afterLater(settings, geo, timezone);
print('\${afterLater.type}: \${afterLater.time}');
}
``````

References #

1. "Prayer Times Calculation", Pray Times, 2018. [Online]. Available: http://praytimes.org/calculation. [Accessed: 13- Apr- 2018].

2. "Equation of time", Wikipedia, 2018. [Online]. Available: https://en.wikipedia.org/wiki/Equation_of_time. [Accessed: 13- Apr- 2018].

3. "Approximate Solar Coordinates", Astronomical Applications Department of the U.S. Naval Observatory, 2018. [Online]. Available: http://aa.usno.navy.mil/faq/docs/SunApprox.php. [Accessed: 13- Apr- 2018].

4. J. Rocheleau, "Declination Of The Sun", Planet Facts, 2018. [Online]. Available: http://planetfacts.org/declination-of-the-sun/. [Accessed: 13- Apr- 2018].

5. "Position of the Sun", Wikipedia, 2018. [Online]. Available: https://en.wikipedia.org/wiki/Position_of_the_Sun. [Accessed: 13- Apr- 2018].

6. "A note on Dhuhr", Pray Times, 2018. [Online]. Available: http://praytimes.org/wiki/A_note_on_Dhuhr. [Accessed: 13- Apr- 2018].

7. "Tafsiran Astronomi Untuk Waktu Solat", e-Solat: Sistem Panduan Solat, 2014. [Online]. Available: http://www.e-solat.gov.my/web/index1.php?id=55&type=A. [Accessed: 13- Apr- 2018].

Features and Bugs #

Please file feature requests and bugs at the issue tracker.

Changelog #

0.0.1 #

• Initial version.
• [NEW]: Prayer times calculation for various methods.

0.0.2 #

• Updated to Dart 2.
• Updated dependencies.

0.1.0 #

• [BREAKING CHANGE]: Various types have been updated to take advantages of source generation by `built_value` package.
• Updated dependencies.

example/libpray_example.dart

``````import 'package:libpray/libpray.dart';

void main() {
// Use April 12th, 2018.
const int year = 2018;
const int month = 4;
const int day = 12;
final DateTime when = DateTime.utc(year, month, day);

// Init settings.
// Set calculation method to JAKIM (Fajr: 18.0 and Isha: 20.0).
final PrayerCalculationSettings settings = PrayerCalculationSettings((PrayerCalculationSettingsBuilder b) =>

// Init location info.
final Geocoordinate geo = Geocoordinate((GeocoordinateBuilder b) => b
..latitude = 2.0
..longitude = 101.0
..altitude = 2.0);
const double timezone = 8.0;

// Generate prayer times for one day on April 12th, 2018.
final Prayers prayers = Prayers.on(date: when, settings: settings, coordinate: geo, timeZone: timezone);
print(prayers.imsak);
print(prayers.fajr);
print(prayers.sunrise);
print(prayers.dhuha);
print(prayers.dhuhr);
print(prayers.asr);
print(prayers.sunset);
print(prayers.maghrib);
print(prayers.isha);
print(prayers.midnight);

// Generate current prayer time
final Prayer current = Prayer.now(settings: settings, coordinate: geo, timeZone: timezone);
print('\${current.type}: \${current.time}');

// Generate next prayer time
final Prayer next = Prayer.next(settings: settings, coordinate: geo, timeZone: timezone);
print('\${next.type}: \${next.time}');

// Generate later prayer time
final Prayer later = Prayer.later(settings: settings, coordinate: geo, timeZone: timezone);
print('\${later.type}: \${later.time}');

// Generate after later prayer time
final Prayer afterLater = Prayer.afterLater(settings: settings, coordinate: geo, timeZone: timezone);
print('\${afterLater.type}: \${afterLater.time}');
}
``````

Use this package as a library

1. Depend on it

``````
dependencies:
libpray: ^0.1.0

``````

2. Install it

You can install packages from the command line:

with pub:

``````
\$ pub get

``````

Alternatively, your editor might support `pub get`. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

``````
import 'package:libpray/libpray.dart';
``````
 Popularity: Describes how popular the package is relative to other packages. [more] 64 Health: Code health derived from static analysis. [more] 0 Maintenance: Reflects how tidy and up-to-date the package is. [more] 53 Overall: Weighted score of the above. [more] 43

We analyzed this package on Oct 8, 2019, and provided a score, details, and suggestions below. Analysis was completed with status completed using:

• Dart: 2.5.1
• pana: 0.12.21

Platforms

Detected platforms:

Error(s) prevent platform classification:

Fix dependencies in `pubspec.yaml`.

Analysis issues and suggestions

Fix dependencies in `pubspec.yaml`.

Running `pub upgrade` failed with the following output:

``````ERR: The current Dart SDK version is 2.5.1.

Because libpray depends on libcalendar ^0.0.2 which requires SDK version >=1.20.1 <2.0.0, version solving failed.
``````

Health suggestions

Format `lib/src/maths/astronomy_math.dart`.

Run `dartfmt` to format `lib/src/maths/astronomy_math.dart`.

Format `lib/src/models/calculation_method.dart`.

Run `dartfmt` to format `lib/src/models/calculation_method.dart`.

Format `lib/src/models/high_latitude_adjustment.dart`.

Run `dartfmt` to format `lib/src/models/high_latitude_adjustment.dart`.

Fix additional 4 files with analysis or formatting issues.

Additional issues in the following files:

• `lib/src/models/juristic_method.dart` (Run `dartfmt` to format `lib/src/models/juristic_method.dart`.)
• `lib/src/models/location.dart` (Run `dartfmt` to format `lib/src/models/location.dart`.)
• `lib/src/models/prayer_calculation_settings.dart` (Run `dartfmt` to format `lib/src/models/prayer_calculation_settings.dart`.)
• `lib/src/models/prayers.dart` (Run `dartfmt` to format `lib/src/models/prayers.dart`.)

Maintenance issues and suggestions

Fix platform conflicts. (-20 points)

Error(s) prevent platform classification:

Fix dependencies in `pubspec.yaml`.

Make sure `dartdoc` successfully runs on your package's source files. (-10 points)

Dependencies were not resolved.

Package is getting outdated. (-17.26 points)

The package was last published 61 weeks ago.

Dependencies

Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.0.0-dev.52.0 <3.0.0