aendie/sfalmanac repository overview

⁠SFalmanac Description

SFalmanac is a Python 3 script that essentially creates the daily pages of the Nautical Almanac (based on the UT1 timescale). These are tables that 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.

This is the dockerhub edition of SFalmanac-Py3⁠, also published as a Python Package in PyPI⁠. SFalmanac was developed using the Skyfield⁠ astronomical library for accuracy. However the Ephem⁠ astronomical library is also required, but only to calculate planet magnitudes. SFalmanac can use the International Earth Rotation and Reference Systems Service (IERS) Earth Orientation Parameters (EOP) data which are forecast for at least the coming 12 months (and updated weekly).

Currently multiprocessing is disabled: Note that multiprocessing (when enabled) is only used in SFalmanac Option 1 and 3. If 12 CPU threads are available then 12 copies of the chosen ephemeris file are downloaded each time when running on Docker (Debian). Neither Windows nor Ubuntu 20.04 as platform do this. Although the calculations are correct when multiprocessing, I've disabled multiprocessing in Docker as it's rather annoying to see one download per process.

⁠Prerequisites

In order to run Docker, your PC/laptop must be capable of Virtualization. This begins by enabling Virtualization at BIOS level (as it is usually disabled by default).

• enable Virtualization for your PC/laptop in the BIOS, e.g. sample Guidelines for Windows⁠
• on Windows 10 Pro: install Docker Desktop⁠ and increase the number of available CPUs (12 is optimal). This will also start the Docker Engine. Currently there is no equivalent for Linux.
• on Linux: install Docker⁠, e.g. on Ubuntu 20.04 essentially only sudo apt install docker.io is required.
• optionally install Docker Compose⁠, e.g. on Ubuntu 20.04 essentially only sudo apt install docker-compose is required. This simplifies the run command somewhat (see below).

⁠Installation

DockerHub provides a convenient 'package' that includes a Linux OS, Python 3.10, TeX Live⁠, the application code, and third party Python imports (including two astronomical libraries). This forms a standardized environment for this application. This DockerHub image has been tested on Windows 10 Pro and on Ubuntu 20.04 LTS. Regrettably no information is available regarding the Mac OS platform. Nevertheless, the client PC/laptop also needs the following simple setup:

• create a 'current working directory' folder, e.g. sfalmanac, (hereafter 'cwd') in which to run this software.
• create an empty folder in here named 'pdf', e.g. in Linux: sfalmanac/pdf; in Windows sfalmanac\pdf. This folder will receive the created almanacs in PDF format (and they may remain here too as they will not be deleted).
• create an empty folder in here named 'astro-data', e.g. in Linux: sfalmanac/astro-data; in Windows sfalmanac\astro-data. This folder receives ephemeris data (de421.bsp, de405.bsp, de406.bsp, de430t.bsp, de440.bsp) downloaded as necessary. Additionally it receives data (hip_main.dat, finals2000A.all) downloaded from the IERS web site⁠ or USNO web site⁠ as necessary. This data only needs to be downloaded once with the exception of finals2000A.all, which may be downloaded frequently (automatically). So do not delete the data in this folder.
• optionally (i.e. if you don't want to use the default values in the file below) create a file named .env in 'cwd' that contains this data as text (you may specify your desired settings in this file). Lines beginning with '#' are comment lines:

# Environment variables are specified here to control preferred functionality
#
# specify page size 'A4' or 'Letter':
PGSZ=A4
#
# specify 'MOONIMG=True' to include a moon image in the Nautical Almanac; otherwise 'False'
MOONIMG=True
#
# choose an ephemeris (EPHNDX=0, EPHNDX=1, EPHNDX=2, EPHNDX=3 or EPHNDX=4):
#   0   de421.bsp   1900 to 2050
#   1   de405.bsp   1600 to 2200
#   2   de406.bsp   1000 to 2750 (Equation of Time may show ??:?? after the year 2750)
#   3   de430t.bsp  1550 to 2650
#   4   de440.bsp   1550 to 2650
EPHNDX=0
#
# specify 'USEIERS=True' to download finals2000A.all;
#  or 'USEIERS=False' to use the Skyfield built-in UT1 tables
USEIERS=True
#
# download a new finals2000A.all version after 'AGEIERS' days if 'USEIERS=True' specified
AGEIERS=30

• open a Command Prompt (Windows) or Terminal (Linux) and set the curent folder to 'cwd' (as chosen above).
• download this DockerHub image with docker pull aendie/sfalmanac on Windows 10 Pro or sudo docker pull aendie/sfalmanac in Linux. Type docker images (Windows) or sudo docker images (Linux) to verify the image is downloaded.

⁠To run SFalmanac using Docker

To execute the image directly, enter the following command (omit --env-file ./.env if no environment file was created) in your 'cwd' folder:

...on Windows 10 Pro: docker run -it -v "%cd%/pdf":/app/tmp -v "%cd%/astro-data":/app/astro-data --env-file ./.env --rm aendie/sfalmanac

...on Linux: sudo docker run -it -v $(pwd)/pdf:/app/tmp -v $(pwd)/astro-data:/app/astro-data --env-file ./.env --rm aendie/sfalmanac

Provide whatever terminal input is requested and await the creation of a PDF file in the 'pdf' subfolder.

⁠To run SFalmanac using Docker Compose

• create a file docker-compose.yml in 'cwd' that contains the following text:

version: "3.7"
services:
  almanac:
    image: aendie/sfalmanac:latest
    volumes:
      - type: bind
        source: ./pdf
        target: /app/tmp
      - type: bind
        source: ./astro-data
        target: /app/astro-data
    env_file:
      - ./.env

• on Windows 10 Pro: the above file may instead contain version: "3.8"

Ensure that the environment file .env exists in 'cwd'; then execute the following command in your 'cwd' folder:

...on Windows 10 Pro: docker-compose run --rm almanac

...on Linux: sudo docker-compose run --rm almanac