==============================
SkyAlmanac 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
Skyalmanac is a **Python 3** script that creates the daily pages of the Nautical Almanac (based on the UT timescale).
The generated tables 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.
**NOTE:** The *original* Skyalmanac that was a hybrid version using both Skyfield and Ephem has been abolished and replaced with the Skyfield version. It is now the same as the SFalmanac version (except for the new name). There is no justification for the hybrid version any more.
-------------------------------------------------------------------------------------------------------------------------
|emsp| |emsp| |emsp| |emsp| |emsp| |smiley| |emsp| **Multiprocessing version for increased performance!** |emsp| |smiley|
-------------------------------------------------------------------------------------------------------------------------
Skyalmanac-Py3 can now employ multiprocessing (if your processor has multiple cores) reducing the processing time. Single-processing is also available as an option if required.
Testing has been successfully performed on Windows 10 and Ubuntu 20.04 LTS. (No testing done on Mac OS.) Compared to single-processing, data processing (excluding conversion from TEX to PDF)
* ... of a 6-day Nautical Almanac is **4x faster** on Windows 10; **2x faster** on Linux.
* ... 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).
Quick Overview
--------------
This is the **PyPI edition** of `Skyalmanac-Py3 <https://github.com/aendie/Skyalmanac-Py3>`_ (a Changelog can be viewed here). Version numbering follows the scheme *Major.Minor.Patch*, whereby the *Patch* number represents some small correction to the intended release.
| **NOTE:** Version numbering in PyPI restarted from 1.0 as the previous well-tested versions that exist since early 2019 were never published as PyPI packages.
|
| The astronomical library employed is: `Skyfield <https://rhodesmill.org/skyfield/>`_.
| Skyalmanac uses the Hipparcos catalog as its star database.
If a current version of Skyfield (>= 1.31) is used, you have two options (which one, you specify by manually editing *config.py*):
* if "useIERS = False", the built-in UT1 tables in the installed version of Skyfield will be employed.
* if "useIERS = True", for optimal accuracy (specifically for all GHA data), Earth orientation data from IERS (International Earth Rotation and Reference Systems Service) is downloaded and then used until it 'expires'. It expires after a chosen number of days (also specifiable in *config.py*). Note that IERS specifies the range of Earth Orientation Parameter (EOP) data from 2nd January 1973 and is updated weekly. Refer to the `IERS web site <https://www.iers.org/IERS/EN/Home/home_node.html>`_ for current information.
Software Requirements
=====================
|
| Nearly all of the astronomical computation is done by the Skyfield library.
| Typesetting is done typically by MiKTeX or TeX Live.
| Here are the requirements/recommendations:
* `python <https://www.python.org/downloads/>`_ >= 3.4 (the latest version is recommended)
* `skyfield <https://pypi.org/project/skyfield/>`__ >= v1.48 (the latest is recommended; see the `Skyfield Changelog <https://rhodesmill.org/skyfield/installation.html#changelog>`_)
* `numpy <https://numpy.org/>`_ < 2.0.0 (only for Skyfield versions < 1.48)
* `pandas <https://pandas.pydata.org/>`_ >= 1.0 (to decode the Hipparcos star catalog)
* `pandas <https://pandas.pydata.org/>`_ >= 2.2.2 (if numpy version >= 2.0.0)
* `MiKTeX <https://miktex.org/>`_ |nbsp| |nbsp| or |nbsp| |nbsp| `TeX Live <http://www.tug.org/texlive/>`_
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.
You may check that the latest version of SFalmanac is installed::
python -m pip uninstall skyalmanac
python -m pip install skyalmanac
Installing Skyalmanac ensures that Skyfield and Pandas (and their dependencies) are also installed. If previous versions of Skyalmanac were installed, consider upgrading Skyfield and Pandas thus::
python -m pip install --upgrade skyfield pandas
Thereafter run it with::
python -m skyalmanac
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 whenever Skyalmanac 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, Skyalmanac, 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. However 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/SFalmanac-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`` (for Python 3). 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/aendie/SkyAlmanac-Py3",
"name": "skyalmanac",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.4",
"maintainer_email": null,
"keywords": null,
"author": "Andrew Bauer",
"author_email": "aendie.bauer@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/b9/6d/9db1df2868620b8e9f2694523a3aba4b3c669988e666397bdef1a9d7d214/skyalmanac-1.12.5.tar.gz",
"platform": null,
"description": "==============================\r\nSkyAlmanac Project Description\r\n==============================\r\n\r\n.. |nbsp| unicode:: 0xA0\r\n :trim:\r\n\r\n.. |emsp| unicode:: U+2003\r\n :trim:\r\n\r\n.. |smiley| image:: https://github.githubassets.com/images/icons/emoji/unicode/1f603.png\r\n :height: 24 px\r\n :width: 24 px\r\n\r\nSkyalmanac is a **Python 3** script that creates the daily pages of the Nautical Almanac (based on the UT timescale).\r\nThe generated tables are needed for celestial navigation with a sextant.\r\nAlthough you are strongly advised to purchase the official Nautical Almanac, this program will reproduce the tables with no warranty or guarantee of accuracy.\r\n\r\n**NOTE:** The *original* Skyalmanac that was a hybrid version using both Skyfield and Ephem has been abolished and replaced with the Skyfield version. It is now the same as the SFalmanac version (except for the new name). There is no justification for the hybrid version any more.\r\n\r\n-------------------------------------------------------------------------------------------------------------------------\r\n|emsp| |emsp| |emsp| |emsp| |emsp| |smiley| |emsp| **Multiprocessing version for increased performance!** |emsp| |smiley|\r\n-------------------------------------------------------------------------------------------------------------------------\r\n\r\nSkyalmanac-Py3 can now employ multiprocessing (if your processor has multiple cores) reducing the processing time. Single-processing is also available as an option if required.\r\nTesting has been successfully performed on Windows 10 and Ubuntu 20.04 LTS. (No testing done on Mac OS.) Compared to single-processing, data processing (excluding conversion from TEX to PDF)\r\n\r\n* ... of a 6-day Nautical Almanac is **4x faster** on Windows 10; **2x faster** on Linux.\r\n* ... of 6-day Event Time Tables is almost **5x faster** on Windows 10; **3x faster** on Linux.\r\n\r\nWindows 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).\r\n\r\nQuick Overview\r\n--------------\r\n\r\nThis is the **PyPI edition** of `Skyalmanac-Py3 <https://github.com/aendie/Skyalmanac-Py3>`_ (a Changelog can be viewed here). Version numbering follows the scheme *Major.Minor.Patch*, whereby the *Patch* number represents some small correction to the intended release.\r\n\r\n| **NOTE:** Version numbering in PyPI restarted from 1.0 as the previous well-tested versions that exist since early 2019 were never published as PyPI packages.\r\n|\r\n| The astronomical library employed is: `Skyfield <https://rhodesmill.org/skyfield/>`_.\r\n| Skyalmanac uses the Hipparcos catalog as its star database.\r\n\r\nIf a current version of Skyfield (>= 1.31) is used, you have two options (which one, you specify by manually editing *config.py*):\r\n\r\n* if \"useIERS = False\", the built-in UT1 tables in the installed version of Skyfield will be employed.\r\n* if \"useIERS = True\", for optimal accuracy (specifically for all GHA data), Earth orientation data from IERS (International Earth Rotation and Reference Systems Service) is downloaded and then used until it 'expires'. It expires after a chosen number of days (also specifiable in *config.py*). Note that IERS specifies the range of Earth Orientation Parameter (EOP) data from 2nd January 1973 and is updated weekly. Refer to the `IERS web site <https://www.iers.org/IERS/EN/Home/home_node.html>`_ for current information.\r\n\r\nSoftware Requirements\r\n=====================\r\n\r\n|\r\n| Nearly all of the astronomical computation is done by the Skyfield library.\r\n| Typesetting is done typically by MiKTeX or TeX Live.\r\n| Here are the requirements/recommendations:\r\n\r\n* `python <https://www.python.org/downloads/>`_ >= 3.4 (the latest version is recommended)\r\n* `skyfield <https://pypi.org/project/skyfield/>`__ >= v1.48 (the latest is recommended; see the `Skyfield Changelog <https://rhodesmill.org/skyfield/installation.html#changelog>`_)\r\n* `numpy <https://numpy.org/>`_ < 2.0.0 (only for Skyfield versions < 1.48)\r\n* `pandas <https://pandas.pydata.org/>`_ >= 1.0 (to decode the Hipparcos star catalog)\r\n* `pandas <https://pandas.pydata.org/>`_ >= 2.2.2 (if numpy version >= 2.0.0)\r\n* `MiKTeX <https://miktex.org/>`_ |nbsp| |nbsp| or |nbsp| |nbsp| `TeX Live <http://www.tug.org/texlive/>`_\r\n\r\nInstallation on Windows 10/11; on Linux before Python 3.12; on Mac before MacOS 14\r\n==================================================================================\r\n\r\nInstall a TeX/LaTeX program on your operating system so that ``pdflatex`` is available.\r\n\r\nEnsure that the `pip Python installer tool <https://pip.pypa.io/en/latest/installation/>`_ is installed.\r\nYou may check that the latest version of SFalmanac is installed::\r\n\r\n python -m pip uninstall skyalmanac\r\n python -m pip install skyalmanac\r\n\r\nInstalling Skyalmanac ensures that Skyfield and Pandas (and their dependencies) are also installed. If previous versions of Skyalmanac were installed, consider upgrading Skyfield and Pandas thus::\r\n\r\n python -m pip install --upgrade skyfield pandas\r\n\r\nThereafter run it with::\r\n\r\n python -m skyalmanac\r\n\r\nOn a POSIX system (Linux or Mac OS), use ``python3`` instead of ``python`` in the commands above.\r\n\r\nThis PyPI edition also supports installing and running in a `venv <https://docs.python.org/3/library/venv.html>`_ virtual environment.\r\n\r\nFinally check or change the settings in *config.py*.\r\nIts location is printed immediately whenever Skyalmanac runs.\r\n\r\nInstallation on Linux with Python 3.12 and higher; on MacOS 14 and higher\r\n=========================================================================\r\n\r\nMore recent versions of Python (on specific operating systems) prevent users installating a PyPI package (such as Skyfield, Skyalmanac, 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/>`_. \r\n\r\nThe 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. However it is NOT wise to \"break the rules\" and force package installation in the Python system-wide area.\r\n\r\nTo assist users new to virtual environments, I have provided an `Installation guide for Linux <https://github.com/aendie/SFalmanac-Py3/blob/master/How%20to%20install%20Skyalmanac%20on%20Linux.pdf>`_. (Package installation for MacOS is in principle the same.)\r\n\r\nGuidelines for Linux & Mac OS\r\n-----------------------------\r\n\r\nQuote from `Chris Johnson <https://stackoverflow.com/users/763269/chris-johnson>`_:\r\n\r\nIt's best to not use the system-provided Python directly. Leave that one alone since the OS can change it in undesired ways.\r\n\r\nThe best practice is to configure your own Python version(s) and manage them on a per-project basis using ``venv`` (for Python 3). This eliminates all dependency on the system-provided Python version, and also isolates each project from other projects on the machine.\r\n\r\nEach 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.\r\n",
"bugtrack_url": null,
"license": "GPL-3.0 License",
"summary": "Creates the daily pages of a Nautical Almanac using Skyfield",
"version": "1.12.5",
"project_urls": {
"Homepage": "https://github.com/aendie/SkyAlmanac-Py3"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "953a25eee9e5d2c8dcd7bb2a38918e605f94b87a7b5939044e9f3e73712fd825",
"md5": "01dba76ec91705518f68c1ac515cbe52",
"sha256": "3b17105b79bd5cacf50b42317bd4e2fae93e171c97a50f830f3848329e486699"
},
"downloads": -1,
"filename": "skyalmanac-1.12.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "01dba76ec91705518f68c1ac515cbe52",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.4",
"size": 33641199,
"upload_time": "2024-12-15T19:02:23",
"upload_time_iso_8601": "2024-12-15T19:02:23.505791Z",
"url": "https://files.pythonhosted.org/packages/95/3a/25eee9e5d2c8dcd7bb2a38918e605f94b87a7b5939044e9f3e73712fd825/skyalmanac-1.12.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b96d9db1df2868620b8e9f2694523a3aba4b3c669988e666397bdef1a9d7d214",
"md5": "5faf4a33482e4f5a0b387e23c35e4cda",
"sha256": "5b959b163d49f8b13cf04392cf7a91ae7676825e53aaf103dc8878b4eb4dd423"
},
"downloads": -1,
"filename": "skyalmanac-1.12.5.tar.gz",
"has_sig": false,
"md5_digest": "5faf4a33482e4f5a0b387e23c35e4cda",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.4",
"size": 33059920,
"upload_time": "2024-12-15T19:02:48",
"upload_time_iso_8601": "2024-12-15T19:02:48.327032Z",
"url": "https://files.pythonhosted.org/packages/b9/6d/9db1df2868620b8e9f2694523a3aba4b3c669988e666397bdef1a9d7d214/skyalmanac-1.12.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-15 19:02:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aendie",
"github_project": "SkyAlmanac-Py3",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "skyalmanac"
}
JSON
