Support for Lunar Calendars Starting New Days at Sunset Instead of Midnight

[khawarizmus]

Lunar Calendars, like the Islamic calendar, begin their new days at sunset rather than midnight. To fully support these calendars, Temporal needs to implement astronomical calculations to determine sunset times, which can vary by location.

Additionally, Temporal should expose astronomical calculation functions and variables, such as sunsetTime and sunriseTime, or any other relevant APIs.

This feature was previously discussed in Temporal V1 and was suggested for inclusion in V2.

Advantages:

Supporting this behaviour in lunar calendars would give more accurate results and help in implementing accurate applications such as calendar applications or in the case of Islamic calendars having some astronomical calculations exposed by Temporal can also help in calculating Muslim Prayer times.

Concerns:

The concerns that i can foresee are:

• Increase Temporal API surface and code by including astronomical calculations
• Temporal not having access to the location or having inaccurate location will lead to incorrect or inaccurate behaviour.

Prior art:

I am not aware of any standard library implementing this behaviour however, here are some libraries that implement astronomical calculations for sunset and sunrise.

• Time4j has an implementation of StartOfDay.
• sunset is a library that calculate Sunrise and Sunset and the phase of the moon accurately based on date and geographic position (written in C++)
• EDSunriseSet Objective-C class to calculate Sunrise/Sunset/Twilight times.
• suncalc A tiny JavaScript library for calculating sun/moon positions and phases.
• Prayers-call is an example of a library that both demonstrate the use astronomical calculation and would benefit from Temporal behaving the correct way with lunar calendars as well as exposing certain astronomical calculations.

Constraints / corner cases:

• Calculating sunset and sunrise accurately requires not only latitude and longitude bus altitude as well.

[MohsenAlyafei]

Correct sunset calculations must include location's elevation (i.e. altitude or height above sea level). This should not be difficult but add to the underlying code.

But will that impact the date calculations and the current algorithms used to calculate and derive the hijri dates in the various islamic calendars?

[khawarizmus]

@MohsenAlyafei I am assuming that if we include altitude then we would need to rely on some offline, standardised, up to date altitude data.

And i was wondering if using elevation data like Aster Global Digital Elevation Model from AppEEARS can do the trick.

This dataset offers an elevation precision of 30m which should be more then accurate for the purpose of calculating sunrise/sunset

[MohsenAlyafei]

Yes this may work assuming always that a location given by lat/long coordinates has only one elevation.

Well this is not always the case.

Let me give you a practical example that it actually happens next door to my country.

In Dubai Burj Khalifa residents at first floor and those at the top floor (2700 feet higher) have different prayer times although same location and geographical coordinates, especially in Ramadan when they have to break the fast.

So, any external library cannot fix this issue and any code must always take 3 parameters as an input to correctly calculate the sunset: latitude, longitude, and elevation.

[MohsenAlyafei]

Existing libraries that calculate sunset without taking into account elevation above sea level are not accurate. You cannot assume that Mexico City is at sea level, for example.

[khawarizmus]

Thanks for @MohsenAlyafei who pointed out that Time4J seems to have a StartOfDay implementation So i am going to add that to the prior art section.