aendie/pyalmanac repository overview

⁠Pyalmanac Description

Pyalmanac is a Python 3 script that essentially creates the daily pages of the Nautical Almanac. 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 Pyalmanac-Py3⁠, also published as a Python Package in PyPI⁠. Pyalmanac was developed based on the original Pyalmanac by Enno Rodegerdts.

Pyalmanac is implemented using Ephem (originally named PyEphem), which in turn uses XEphem that uses the VSOP87D algorithms for the planets. XEphem is 'end of life' as no further updates are planned. Although Pyalmanac is very fast, Skyalmanac or SFalmanac have better accuracy and 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).

⁠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 an astronomical library). This forms a standardized environment for this application. This DockerHub image has been tested on Windows 10 Pro and on Ubuntu 20.04 LTS. Nevertheless, the client PC/laptop also needs the following simple setup:

• create a 'current working directory' folder, e.g. pyalmanac, (hereafter 'cwd') in which to run this software.
• create an empty folder in here named 'pdf', e.g. in Linux: pyalmanac/pdf; in Windows pyalmanac\pdf. This folder will receive the created almanacs in PDF format (and they may remain here too as they will not be deleted).
• 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
#
# set SNRS (search_next_rising_sun) to 'True' or 'False'
# 'True'  = search for next sunrise (slower to calculate)
# 'False' = base it only on month and hemisphere (works for the chosen latitudes)
SNRS=False
#
# 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

• 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/pyalmanac on Windows 10 Pro or sudo docker pull aendie/pyalmanac in Linux. Type docker images (Windows) or sudo docker images (Linux) to verify the image is downloaded.

⁠To run Pyalmanac 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 --env-file ./.env --rm aendie/pyalmanac

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

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

⁠To run Pyalmanac using Docker Compose

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

version: "3.7"
services:
  almanac:
    image: aendie/pyalmanac:latest
    volumes:
      - type: bind
        source: ./pdf
        target: /app/tmp
    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