An offline sun time calculator

On the final day of eligibility, here's a quick post introducing my project for OFFLFIRSOCH 2025. I kind of liked the extremely understated and utilitarian feel of naming my 2024 project `city`, and so I stuck to that theme and this year's entry is called `day`.

Git repo for `day` at SourceHut

`day` is a simple tool for calculating when the sun rises, reaches it's highest point in the sky (solar noon), and sets in your location and in your local time, as well as telling you how long the day is (defined here as the time between sunrise and sunset). It can, optionally, tell you a few extra things, like the times when the three different kinds of twilight (civil, nautical and astronomical) begin and end, and the duration of "usable light" in the day (you can still see well enough to get around and do things outside without artificial light for a little while before/after the sun itself has become (in)visible), how many degrees above the horizon the sun it at its highest point that day, as well as the solstice and equinox dates for the year. By default it shows you all this information for today, but you can use command line arguments like +5d or -1m to calculate it for, e.g., 5 days in the future or 1 month in the past.

In order for this to work, you need to provide your latitude and longitude via an environment variable, $LATLON. If you don't know your latitude and longitude you could, of course, use `city` to find a usable approximation.

The whole thing is less than 500 lines of Lua, although I do rely on a third party library, luatz, to take care of timezone conversions and account for DST changes and that kind of mucky stuff. The vast majority of the formulae used for these calculations were taken from a hard copy of a 45 year old book (Jean Meeus' "Astronomical Formulae for Calculators") which I bought off eBay for 10 EUR. That is the sum total of what's necessary to replace the entire "Sunrise & Sunset" section of timeanddate.com (who, I kid you not, will tell you sun and moon related times down to the second, rather than the minute, if you give them 15 USD per year!), or an even larger portion of the functionality of e.g. sunrise-and-sunset.com. While debugging `day` (ironically I relied on Wikipedia instead of Meeus in the beginning and was getting bogus results), I at one point double checked my conversions from the Gregorian calendar to Julian Dates (widely used in astronomical calculations) against those at www.juliandate.org. Here's what that site wants to feed you cookies for:

• Store and/or access information on a device (769 partners included)

• Develop and improve services (399 partners included)

• Use limited data to select content (113 partners included)

• Use limited data to select advertising (507 partners included)

• Create profiles for personalised advertising (570 partners included)

• Use profiles to select personalised advertising (565 partners included)

• Create profiles to personalise content (249 partners included)

• Use profiles to select personalised content (222 partners included)

• Measure advertising performance (550 partners included)

• Measure content performance (288 partners included)

• Understand audiences through statistics or combinations of data from different sources (397 partners included)

The function in `day` which provides precisely the same answer as that site is less than 10 lines of code. The ratio of cookie "partners" to lines of equivalent local code here is at least a double digit number, quite possibly a three digit one. This is the world we live in, folks!

There's more I'd like to say and maybe I'll do a follow up post, but unfortunately I don't have much spare time this evening, so this will have to do. If `day` is of interest to you, please give it a whirl and let me know about bugs or glaring usability defects. I am sure they exist! If it predicts sunrise or sunset times for your location which differ by more than, say, 3 minutes either way from some other site or app you use, please let me know. If it is off by 1 minute or 2 minutes I am not really bothered - something I realised early on in this project is that any two seemingly trustworthy sources for this information will in fact always disagree on at least one quantity by a small margin. There's just no way around it. Most of them do not make their code available or explain what methods they use so there is no way to understand why. This is also the world we live in. At the end of the day, I actually trust `day` more than anything else because I know for a fact it at least tries to implement the formula in a book published by a university and written by someone with a degree in mathematics, and that's more than I can say for *any* website.

Let this post also serve as a reminder that you need to announce your OFFLFIRSOCH project via Gopher and/or Gemini before the end of March (in your timezone) to qualify. The clock is ticking by this point! So far I am aware of only two other entries (sorry, you two, that I haven't replied yet!)...