aendie/skyalmanac repository overview

⁠Skyalmanac Description

Skyalmanac 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 Skyalmanac-Py3⁠, also published as a Python Package in PyPI⁠. Skyalmanac was developed as a hybrid using two astronomical libraries for speed: Skyfield⁠ and Ephem⁠. The fastest is Pyalmanac⁠ and the most accurate is SFalmanac⁠. Skyalmanac 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).

Ephem is only used for calculating twilight (actual, civil and nautical sunrise/sunset) and moonrise/moonset, as Ephem improves performance significantly (over the single-processing version of SFalmanac:V2.h⁠) with only a marginal loss of accuracy in the times stated above (that are rounded to the minute anyway). There is no justification in using Skyalmanac now that a multi-processing version of SFalmanac is available.

⁠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⁠. 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.7, 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. skyalmanac, (hereafter 'cwd') in which to run this software.
• create an empty folder in here named 'pdf', e.g. in Linux: skyalmanac/pdf; in Windows skyalmanac\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: skyalmanac/astro-data; in Windows skyalmanac\astro-data. This folder receives ephemeris data (de421.bsp, de405.bsp, de406.bsp) downloaded as necessary. Additionally it receives data (hip_main.dat, finals2000A.all) downloaded from the IERS 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):

# Environment variables are specified here to control preferred functionality
#
# specify page size 'A4' or 'Letter':
PGSZ=A4
#
# optionally specify a starting date when creating the short (6 days / 30 days) tables
# specify the starting date in format yyyy-mm-dd, e.g. 2021-05-26
# specify 'SDATE=None' if the current date should be the start date
SDATE=None
#
# specify 'MOONIMG=True' to include a moon image in the Nautical Almanac; otherwise 'False'
MOONIMG=True
#
# choose an ephemeris (EPHNDX=0, EPHNDX=1 or EPHNDX=2):
#   0   de421.bsp   1900 to 2050
#   1   de405.bsp   1900 to 2200
#   2   de406.bsp   1900 to 2750 (Equation of Time may show ??:?? after the year 2750)
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 folder to 'cwd' (as chosen above).
• download this DockerHub image with docker pull aendie/skyalmanac on Windows 10 Pro or sudo docker pull aendie/skyalmanac in Linux. Type docker images (Windows) or sudo docker images (Linux) to verify the image is downloaded.

⁠To run Skyalmanac 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/skyalmanac

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

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

⁠To run Skyalmanac using Docker Compose

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

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

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