Metadata-Version: 2.4
Name: skyalmanacPP
Version: 0.5.6
Summary: Creates the Planetary Phenomena data and charts for a Nautical Almanac
Author-email: Andrew Bauer <aendie.bauer@gmail.com>
License-Expression: GPL-3.0-or-later
Project-URL: Repo, https://github.com/aendie/SkyAlmanacPP-Py3
Keywords: celestial-navigation,navigation,sailing,sextant,skyfield
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: Microsoft :: Windows :: Windows 11
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Natural Language :: English
Classifier: Intended Audience :: End Users/Desktop
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.9
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: scipy
Requires-Dist: Skyfield>=1.49
Dynamic: license-file

================================
skyalmanacPP Project Description
================================

.. |nbsp| unicode:: 0xA0
   :trim:

.. |emsp| unicode:: U+2003
   :trim:

.. |smiley| image:: https://github.githubassets.com/images/icons/emoji/unicode/1f603.png
   :height: 24 px
   :width:  24 px

.. |Mars2026| image:: https://raw.githubusercontent.com/aendie/SkyAlmanacPP-Py3/main/Mars2026_66N.png
   :height: 541 px
   :width:  806 px

skyalmanacPP is a **Python 3** program that creates the Planetary Phenomena data and charts that accompany a Nautical Almanac.
The generated tables assist 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.

skyalmanacPP employs multiprocessing (if your processor has multiple cores) reducing the processing time. (Single-processing is also available as an option.)

Functionality
=============

skyalmanacPP (AKA "Planetary Phenomena") includes:

* the **"DECLINATION OF SUN AND PLANETS"** chart

* the **"Planet Diagram"** (see "Americal Practical Navigator" originally by Nathaniel Bowditch, L.L.D., Volume 1, 2017 Edition, page 256; also any "Astronomical Phenomena" or "Nautical Almanac" from USNO/HMNAO)

* **"VISIBILITY OF PLANETS"** text (see any "Astronomical Phenomena" or "Nautical Almanac" from USNO/HMNAO) with one notable exception: I assume that the data listed in official almanacs is based on latitude 51.5°N, whereas skyalmanacPP provides planet visibility text based on any latitude you choose (between 60°S and 72°N).

* **"VISIBILITY OF PLANETS IN MORNING AND EVENING TWILIGHT"** table (see any "Astronomical Phenomena" or "Nautical Almanac" from USNO/HMNAO) based on your chosen latitude.

* **Planet Visibility charts**, which I prefer to call "Planet Invisibility" charts, because they show whwn the planet is below the horizon (shaded grey) and when the Sun is higher than 6 degrees below the horizon (shaded gold), i.e. Civil Dawn to Civil Dusk, when it is *generally* too bright to see any planets. (Conversely I maintain that a planet is generally visible during Nautical and Astronomical twilight and night itself, when the Sun is more than 18 degrees below the horizon.) This chart provides the best latitude-specific picture of your chances to observe a given planet. It is based on the pioneering planet visibility work done by the astronomer Rainer Lange, whose web site is now only reachable as an archive: https://web.archive.org/web/20260106175348/https://www.alcyone.de/

Sample Planet Visibility chart: `Mars in 2026 at latitude 66°N <https://raw.githubusercontent.com/aendie/SkyAlmanacPP-Py3/main/Mars2026_66N.png>`_
|Mars2026|

User Documentation
------------------

Please read the following file (also in the 'docs' project folder): `SkyAlmanacPP usage notes <https://raw.githubusercontent.com/aendie/SkyAlmanacPP-Py3/main/SkyalmanacPP_usage_notes.pdf>`_

Technical Note
--------------

This is the **PyPI edition** of `SkyAlmanacPP-Py3 <https://github.com/aendie/SkyAlmanacPP-Py3>`_. Version numbering follows the scheme *Major.Minor.Patch*, whereby the *Patch* number represents some small correction to the intended release.

The PyPI edition has the advantage of easier installation and source code files do not clutter the working folder. The PyPI edition is recommended for general users.

Software Requirements
=====================

|
| The astronomical library employed is: `Skyfield <https://rhodesmill.org/skyfield/>`_.
| Typesetting is done typically with MiKTeX or TeX Live.
| Here are the requirements/recommendations:

* `python <https://www.python.org/downloads/>`_ >= 3.4 (version 3.13 is recommended)
* `Skyfield <https://pypi.org/project/skyfield/>`__ >= v1.55
* `numpy <https://numpy.org/>`_ >= 2.0.0 (valid for Skyfield versions >= 1.48)
* `scipy <https://scipy.org/>`_ >= 1.14.1 (for Planet Visibiliy charts)
* `MiKTeX <https://miktex.org/>`_ |nbsp| |nbsp| or |nbsp| |nbsp| `TeX Live <http://www.tug.org/texlive/>`_

**Skyfield version 1.55 or newer is recommended (versions 1.50 to 1.54 are known to have issues).**

Installation on Windows 10/11; on Linux before Python 3.12; on Mac before MacOS 14
==================================================================================

|
| Install a TeX/LaTeX program on your operating system so that ``pdflatex`` is available.
| Ensure that the `pip Python installer tool <https://pip.pypa.io/en/latest/installation/>`_ is installed. Check that the latest version of skyalmanacPP is installed:

::

  python -m pip install --upgrade skyalmanacPP

Installing skyalmanacPP ensures that Skyfield and scipy (and their dependencies) are also installed. If previous versions of skyalmanacPP were installed, consider upgrading Skyfield and scipy thus::

  python -m pip install --upgrade skyfield scipy

Thereafter run it with::

  python -m skyalmanacPP <options>

|
| On a POSIX system (Linux or Mac OS), use ``python3`` instead of ``python`` in the commands above.
| This PyPI edition also supports installing and running in a `venv <https://docs.python.org/3/library/venv.html>`_ virtual environment.
| Finally check or change the settings in *config.py*. Its location is printed immediately when skyalmanacPP runs.

Installation on Linux with Python 3.12 and higher; on MacOS 14 and higher
=========================================================================

More recent versions of Python (on specific operating systems) prevent users installating a PyPI package (such as Skyfield, skyalmanacPP, numpy, Pandas) in the Python system-wide area. The error message is "*This environment is externally managed*" and this is intended to avoid a conflict between the distribution's package manager and Python package management tools as defined in the `PEP-668 documentation <https://peps.python.org/pep-0668/>`_. 

The intention is to persuade users to install PyPI packages in a virtual environment instead, which functions very well. The downside: a virtual environment is typically created in a project folder, so you may require several vitrual environments. It is NOT wise to "break the rules" and force package installation in the Python system-wide area.

To assist users new to virtual environments, I have provided an `Installation guide for Linux  <https://github.com/aendie/Skyalmanac-Py3/blob/master/How%20to%20install%20Skyalmanac%20on%20Linux.pdf>`_. (Package installation for MacOS is in principle the same.)

Guidelines for Linux & Mac OS
-----------------------------

Quote from `Chris Johnson <https://stackoverflow.com/users/763269/chris-johnson>`_:

It's best to not use the system-provided Python directly. Leave that one alone since the OS can change it in undesired ways.
The best practice is to configure your own Python version(s) and manage them on a per-project basis using ``venv``. This eliminates all dependency on the system-provided Python version, and also isolates each project from other projects on the machine.

Each project can have a different Python point version if needed, and gets its own ``site_packages`` directory so pip-installed libraries can also have different versions by project. This approach is a major problem-avoider.
