SFalmanac-Py3

SFalmanac-Py3 is a Python 3 script that creates the daily pages of the Nautical Almanac as well as Lunar Distance tables and charts. The daily pages are needed for celestial navigation with a sextant. Although you are strongly advised to purchase the official Nautical Almanac, this program will reproduce the tables with no warranty or guarantee of accuracy.

SFalmanac-Py3 was developed with the intention of having identical output format as Pyalmanac-Py3 to facilitate manual observation of data discrepancies. Also it is based entirely on the newer Skyfield astronomical library: https://rhodesmill.org/skyfield/. SFalmanac uses the star database in Skyfield, which is based on data from the Hipparcos Catalogue.

Users are encouraged to install the Python Package Index (PyPI) edition to be found here:
https://pypi.org/project/sfalmanac/

The results have been crosschecked with USNO data to some extent.

UPDATE: Nov 2019

Declination formatting has been changed to the standard used in Nautical Almanacs. In each 6-hour block of declinations, the degrees value is only printed on the first line if it doesn't change. It is printed whenever the degrees value changes. The fourth line has two dots indicating "ditto". This applies to all planet declinations and for the sun's declination, but not to the moon's declination as this is continuously changing.

This also includes some very minor changes and an improved title page for the full almanac with two star charts that indicate the equatorial navigational stars.

UPDATE: Jan 2020

The Nautical Almanac tables now indicate if the sun never sets or never rises; similarly if the moon never sets or never rises. For better performance, the SunNeverSets or SunNeverRises state is determined only by the month of year and hemisphere. (This is reliable for the set of latitudes printed in the Nautical Almanac tables.) The code also has cosmetic improvements.
P.S. The Overfull \hbox in paragraph... messages can be ignored - the PDF is correctly generated.

UPDATE: Feb 2020

The main focus was on cleaning up the TeX code and eliminating the Overfull/Underfull hbox/vbox messages. Other minor improvements were included. A Skyfield issue with days that have no moonrise or moonset at a specific latitude was resolved.

UPDATE: Mar 2020

A new parameter in config.py enables one to choose between A4 and Letter-sized pages. A new approach to string formatting has been implemented: the old style Python string formatting syntax has been replaced by the new style string formatting syntax.

UPDATE: Jun 2020

The Equation Of Time is shaded whenever EoT is negative indicating that apparent solar time is slow compared to mean solar time (mean solar time > apparent solar time). It is possible to extend the maximum year beyond 2050 by choosing a different ephemeris in config.py. Bugfix applied to correct the Meridian Passage times.

UPDATE: Jul 2020

A new option has been added into config.py: moonimg = True will display a graphic image of the moon phase (making the resulting PDF slightly larger). Use moonimg = False to revert to the previous format without the graphic moon image.

UPDATE: Feb 2021

Minor changes are included here to this original (non-PyPI) edition to reflect some of the adaptation that was required (e.g. integrate increments.py into sfalmanac.py as Option 5) to create a PyPI (Python Package Index) edition making this original (non-PyPI) and the PyPI editions similar. Both editions create identical almanacs and the PyPI edition is the preferred choice for users.

UPDATE: Mar 2021

UT is the timescale now employed in the almanac.

Two new options have been added into config.py: useIERS = True instructs Skyfield (if >= 1.31) to download Earth orientation data from IERS (International Earth Rotation and Reference Systems Service). ageIERS = 30 instructs Skyfield to download fresh data from IERS if older tham that number of days. This implies greater accuracy for the generated almanacs (if Skyfield >= 1.31).

Note that although you may be using the de421.bsp ephemeris (valid from 1900 to 2050), the IERS currently specifies the validity of Earth Orientation Parameters (EOP) from 2nd January 1973 to 15th May 2022. Refer to the IERS web site for current information.

UPDATE: Apr 2021

A double moonrise or moonset on the same day is now highlighted for better legibility. Event Time tables can now be generated - these are the tables containing data in hours:minutes:seconds, e.g. sunrise, sunset, moonrise, moonset and Meridian Passage. Accuracy to to the second of time is not required for navigational purposes, but may be used to compare accuracy with other algorithms. Some internal technical enhancements and minor changes to text are also included. For example, moonrise and moonset times now take into account the lunar distance from the Earth (which varies slightly).

UPDATE: May 2021

The indication of objects (Sun or Moon) continuously above or below the horizon has been corrected.

Regarding Moon Data: ".. .." has been added to indicate that the moonrise/moonset event occurs the following day (at the specified latitude). If there is no moonrise/moonset for two or more consecutive days, black boxes indicate "moon below horizon"; white boxes indicate "moon above horizon". This brings it in line with Nautical Almanacs. (Previously they were only displayed when there was no moonrise and no moonset on a single day.)

The additional calculations required are compensated with a transient Moon Data buffer store that always holds the latest five adjacent days of moon data, eliminating any need to recalculate data for the next or previous day (to determine if "moon above/below horizon" spans a minimum of two days.)

Correction to Sun Data: "Sun continually above/below horizon" now shown if it applies to both Sunrise and Sunset, or additionally to both Civil Twilight Start & End; or additionally to both Astronomical Twilight Start & End, i.e. as two, four or six events per day and latitude. This brings it in line with Nautical Almanacs.

 :smiley: SFalmanac is now available on DockerHub here. :smiley:

The DockerHub image contains a Linux-based OS, TeX Live, the application code, and third party Python imports (including the astronomical libraries). It can be executed "in a container" on Windows 10 Pro, macOS or a Linux-based OS.

UPDATE: Jun 2021

This version introduces multiprocessing and thus a gain in performance. Single-processing is also a selectable option, if required. Testing has been successfully performed on Windows 10 and Ubuntu 20.04 LTS. (No testing can be performed on Mac OS.) Compared to single-processing ...

• Creation (excluding conversion to PDF) of a 6-day Nautical Almanac is 4x faster on Windows 10; 2x faster on Linux.
• Creation (excluding conversion to PDF) of 6-day Event Time Tables is almost 5x faster on Windows 10; 3x faster on Linux.

Windows 10 uses up to 8 threads; Linux uses up to 12 threads in parallel. Testing was performed on a PC with an AMD Ryzen 7 3700X 8-Core (16 threads) Processor. Windows & Mac OS spawn new processes; Linux forks new processes (the code is compatible with both techniques and will also run on CPUs with fewer cores/threads).

This performance gain infers that there is practically no justification to use the original Skyalmanac, which was an interim solution to overcome the poor performance in SFalmanac at the cost of marginally poorer accuracy in event times (sunset/twilight/sunrise; moonrise/moonset).

UPDATE: Jul 2021

The PDF filenames have been revised:

• modna_\<starting date or year>.pdf: for Nautical Almanacs in modern style
• modst_\<starting date or year>.pdf: for Sun Tables in modern style
• tradna_\<starting date or year>.pdf: for Nautical Almanacs in traditional style
• tradst_\<starting date or year>.pdf: for Sun Tables in traditional style

One command line argument may be appended to the run command:

• -v to invoke verbose mode (send pdfTeX execution steps to the console)
• -log to preserve the log file
• -tex to preserve the tex file

de430t and de440 ephemerides have been added to config.py.

UPDATE: Nov 2021

• Enhanced User Interface includes the possibility to generate tables starting at any valid date, or for any month (within -12/+11 months from today).
• It now checks if there is an Internet connection before attempting to update the Earth Orientation Parameters (EOP) from IERS.
• Minor cosmetic improvements ('d'-correction in italics; greek 'nu' replaces 'v'-correction; Minutes-symbol added to SD and d)

Increased accuracy due to the following minor improvements:

• Moon phase (percent illumination) is based on midnight (as opposed to midday)
• Star positions are based on midnight (as opposed to midday)
• Sun's SD (semi-diameter) is based on midnight (as opposed to mid-day)
• Moon v and d for hour ‘n’ are based on “hour ‘n+1’ minus hour ‘n’” as opposed to “hour ‘n’ + 30 minutes minus hour ‘n’ – 30 minutes”
• Moon HP is based on a “volumetric mean radius of earth = 6371.0” as opposed to an “equatorial radius of earth = 6378.0 km”
• Moon SD (semi-diameter) is based on a “volumetric mean radius of moon = 1737.4 km” as opposed to an “equatorial radius of moon = 1738.1 km”
• Planet magnitudes for Venus and Jupiter are obtained from Skyfield (>= 1.26), despite it still being a prototype function

The PDF filenames have been revised (again):

• NAmod_\<starting date or month or year>.pdf: for Nautical Almanacs in modern style
• STmod_\<starting date or month or year>.pdf: for Sun Tables in modern style
• NAtrad_\<starting date or month or year>.pdf: for Nautical Almanacs in traditional style
• STtrad_\<starting date or month or year>.pdf: for Sun Tables in traditional style

BUGFIX (solved here and in PyPI sfalmanac 1.6.1):
The first day in a Nautical Almanac did not initialize the moon state 'above or below horizon' when there was no Moonrise or Moonset at some latitudes on that day in Multiprocessing mode (only).

BUGFIX (solved here and in PyPI sfalmanac 1.6.2):
The Moon Declination on the last hour of the day did not indicate 'N' or 'S' when it had just changed, i.e. since 22h. This rare case occurs, for example, on 14th Jun 2024 and 15th Oct 2024.

BUGFIX (solved here and in PyPI sfalmanac 1.6.3):
Two import statements (essential for Linux and MacOS) were missing.

UPDATE: Apr 2022

Lunar Distance tables have been added as a new option.

Skyfield relies on the IERS, the International Earth Rotation Service, for accurate measurements of UT1 and for the schedule of leap seconds that keeps UTC from straying more than 0.9 seconds away from UT1.

However the IERS server is currently undergoing maintenance and thus unavailable, which causes SFalmanac to fail. This version first tests if the IERS server is available and otherwise downloads the EOP (Earth Orientation Parameters) data from USNO (US Naval Observatory) instead.

BUGFIX: Event Time tables no longer fail on 24.08.2063 (Lower Transit).

UPDATE: May 2022

Lunar Distance charts have been added as a new option to complement the Lunar Distance tables.

SFalmanac in DockerHub has been updated to match this May 2022 release: https://hub.docker.com/r/aendie/sfalmanac

The PDF filenames have been revised (again), where 'A4' (or 'Letter') is the selected papersize:

• NAmod(A4)_\<starting date or month or year>.pdf: for Nautical Almanacs in modern style
• STmod(A4)_\<starting date or month or year>.pdf: for Sun Tables in modern style
• NAtrad(A4)_\<starting date or month or year>.pdf: for Nautical Almanacs in traditional style
• STtrad(A4)_\<starting date or month or year>.pdf: for Sun Tables in traditional style

PATCH1: Sun SD added to Lunar Distance tables when appropriate

UPDATE: Aug 2022

The 'fancyhdr' LaTeX package is now used to format header and footer lines on a page. This is a more professional solution with added features. Footer lines now contain left-, center- and right-justified text.

BUGFIX (solved here and in PyPI sfalmanac 1.9): Previously execution could hang when aborting a multiprocessing task (in nautical.py or eventtables.py) on entering Ctrl-C to kill all processes.

UPDATE: Sep 2022

• Three locations are tried to obtain finals2000A.all IERS EOP data
• The LaTeX fancyhdr package is employed when MiKTeX (or a TeX Live version >= 2020) is detected.
• Better support for Letter-sized pages.
• SFalmanac no longer requires the Ephem astronomical library.
• Hipparcos data (hip_main.dat) and one ephemeris (de421.bsp) are included in the PyPI package.
• Command line options:
  • -v ... 'verbose': to send pdfTeX output to the terminal
  • -q ... quiet mode for LD charts
  • -sky ... stars only in LD charts
  • -log ... to keep the log file
  • -tex ... to keep the tex file
  • -old ... old formatting without the 'fancyhdr' package
  • -a4 ... A4 papersize
  • -let ... Letter papersize
  • -dpo ... data pages only
  • -sbr ... square brackets in Unix filenames

UPDATE: Oct 2022

• UNIX filenames include parentheses unless option '-sbr' is specified
• Date with ordinal number (e.g. 3rd Oct) added into Lunar Distance table

BUGFIX (solved here and in PyPI sfalmanac 1.11.2): A Lunar Distance chart can now be created for 19 August 2038

UPDATE: Dec 2022

second ENHANCEMENT/BUGFIX (solved here and in PyPI sfalmanac 1.11.4): New Command Line options:

• -nao ... HMNAO style hourly Moon d-values
• -dtr ... 'difference-then-round' style hourly Moon d-values The desired default can also be specified using d_valNA in config.py, which takes precedance when neither of the above Command Line options are specified.

Using '-dtr', the Moon's hourly d-value is calculated "difference-then-round":

• the d-value is signed (negative if Declination is decreasing, i.e. away from the Earth's poles). This also applies to the d-values for the Sun and planets.
• its value is the ROUNDED difference of the EXACT hourly Declinations
• the hourly d-value steps are smooth - gradually increasing or decreasing

When using the "HMNAO Nautical Almanac"-compatible mode, e.g. with '-nao':

• the d-values of Sun, planets and Moon are unsigned
• the hourly Moon d-values are calculated as the difference of the ROUNDED Declinations (round-then-difference)
• hence the hourly d-value steps are sometimes irregular

UPDATE: Apr 2023

ENHANCEMENT/BUGFIX (solved here and in PyPI sfalmanac 1.11.5):

• unnecessary duplicate computations of apparent position are now eliminated.
• the program crashed if the 'finals2000A.all' data file containing the IERS Earth Orientation Parameters downloaded only partially. This is now detected and an error message informs the user to delete the file and re-run the program as it will be downloaded anew.
• creating the 'Increments and Corrections' tables with MiKTeX no longer requires extra memory.

UPDATE: Sep 2024

ENHANCEMENT/BUGFIX (solved here and in PyPI sfalmanac 1.12.1):

• moonrise/moonset accuracy increased slightly
• a symbol (4 slanting lines) indicates "twilight lasts all night" within the sun twilight tables
  Note: a missing moonrise or moonset are still indicated by a pair of two dots rather than the convention employed in the official Nautical Almanac by printing hours:minutes greater than 24:00, i.e. in the next day.
• A new command line option has been added to inhibit multi-processing on a single run:
  • -sp ... single-processing
    Note: The results must be identical in both cases. Changing 'MULTIpr' from True to False in config.py enforces single-processing for all future runs. Multiprocessing is only used for Nautical Almanac and Event tables.
• sfalmanac 1.12.3 checks if the pandas version is compatible with the installed numpy version

Some code improvements including code that depends on the Skyfield version installed, e.g. use of ...

• the 'World Geodetic System 1984 Geoid' for latitude and longitude (if Skyfield >= 1.35)
• the latest 'find_risings' & 'find_settings' Skyfield routines (if Skyfield >= 1.48) except for moonrise/moonset.

Requirements

 Most of the computation is done by the Skyfield astronomical library.
 Typesetting is done typically by MiKTeX or TeX Live.
 Here are the requirements/recommendations:

• Python v3.4 or higher (v3.11.x is recommended)
• Skyfield >= 1.31 (the latest is recommended; see the Skyfield Changelog)
• numpy < 2.0.0 (only for Skyfield < 1.48)
• Pandas >= 1.0 (to decode the Hipparcos star catalog)
• Pandas >= 2.2.2 (if numpy version >= 2.0.0; otherwise numpy 1.26.4 is required)
• MiKTeX or TeX Live

Files required in the execution folder:

• *.py
• Ra.jpg
• croppedmoon.png
• A4chart0-180_P.pdf
• A4chart180-360_P.pdf

 If upgrading from an older version of Skyfield to 1.31 or higher, these files may be deleted:
 deltat.data and deltat.preds

INSTALLATION GUIDELINES on Windows 10 or 11:

It is unlikely that the performance improvement with multiprocessing requires specific virtualization settings enabled in the BIOS. (Intel Virtualization Technology or VMM support is not required.) Furthermore Windows 10 Home (without Hyper-V support) is sufficient - Windows 10 Pro/Enterprise/Education is not required. Also Windows 11 Home is sufficient.

 Tested on Windows 10 Pro, Version 21H2 with an AMD Ryzen 7 3700X 8-Core Processor
 A PDF reader is required, e.g. Adobe Acrobat Reader DC

 Install Python 3.11.3 It should be in the system environment variable PATH, e.g.
  C:\Python311\Scripts;C:\Python311; .....
 Install MiKTeX 22.10 from https://miktex.org/
  Run basic-miktex-22.10-x64.exe as administrator
  I prefer to install MiKTeX for all users on a private laptop
  Reboot the computer to avoid the message:
  "- - - Neither TeX Live nor MiKTeX is installed - - -"
 When MiKTeX first runs confirm the installation of additional packages.
 Run Command Prompt as Administrator, go to your Python folder and execute, e.g.:

 cd C:\Python311
 python.exe -m pip install --upgrade pip
 ... for a first install (it's preferable to install wheel first):
 pip3 install wheel
 pip3 install skyfield
 pip3 install pandas
 ... if already installed, check for upgrades explicitly:
 pip3 install --upgrade skyfield pandas

 Put the required files for SFalmanac in a new folder, run Command Prompt in that folder and start with:
 py -3 sfalmanac.py

 If using MiKTeX 21 or higher, executing 'option 6' (Increments and Corrections) will probably fail with
 ! TeX capacity exceeded, sorry [main memory size=3000000].
 To resolve this problem (assuming MiKTeX has been installed for all users),
 open a Command Prompt as Administrator and enter:
 initexmf --admin --edit-config-file=pdflatex
 This opens pdflatex.ini in Notepad. Add the following line:
 extra_mem_top = 1000000
 and save the file. Problem solved. For more details go here

INSTALLATION GUIDELINES on Ubuntu Desktop 19.10 or 20.04 or 22.04:

 Ubuntu 18.04 and higher come with Python 3 preinstalled,
 however pip may need to be installed:
 sudo apt install python3-pip

 Install the following TeX Live package:
 sudo apt install texlive-latex-extra

 Install the required astronomical libraries etc.:
 pip3 install wheel
 pip3 install skyfield
 pip3 install pandas

 Put the SFalmanac files in a folder and start with:
 python3 sfalmanac.py

INSTALLATION GUIDELINES on Mac OS:

 Every Mac comes with python preinstalled.
 (Please choose this version of SFalmanac if Python 3.* is installed.)
 You need to install the Ephem and Skyfield libraries to use SFalmanac.
 Type the following commands at the commandline (terminal app):

 sudo easy_install pip
 pip install wheel
 pip install skyfield
 pip install pandas

 If this command fails, your Mac asks you if you would like to install the header files.
 Do so - you do not need to install the full IDE - and try again.

 Install TeX/LaTeX from http://www.tug.org/mactex/

 Now you are almost ready. Put the SFalmanac files in any directory and start with:
 python sfalmanac
 or
 ./sfalmanac