lhorizon
helps you find things in the Solar System. It is built around a thick Python wrapper for the
Jet Propulsion Laboratory (JPL) Horizons service. Horizons, provided by JPL's
Solar System Dynamics Group (SSD), is one of the only sources in the world that offers no-assembly-required
high-precision data on the relative positions and velocities of almost every known body in the Solar System.
lhorizon
offers tools to query Horizons for data, parse its responses into useful Python objects, and smoothly
incorporate them into bulk calculation and transformation workflows.
If you would a quick overview of major package functionality, you can try these example Notebooks on Binder.
lhorizon
began as a fork of astroquery.jplhorizons
(originally written by Michael Mommert around 2016). We wrote it in order to circumvent a bug introduced to jplhorizons
by
serverside changes at JPL that prevented it from correctly parsing queries involving target or observer locations given
in planetodetic coordinates, and more specifically to provide suppport for queries related to arbitrary locations on
the lunar surface. In the process, we extended it to implement a more efficient parser, add support for fast queries in
bulk, and remove the use of astroquery
and astropy
features (for both performance and API compatibility reasons).
At some point, we realized that a fast, standalone interface to Horizons might be useful to the community at large and
decided to polish it into a general-use package.
along the lines of "l'horizon" or "low-ree-zahn;" like "the horizon" in French, or the famous Palm Springs Desert Modern hotel (an easy drive from Pasadena).
lhorizon
is available on conda-forge
, and we recommend installing it using the conda
package manager:
conda install -c conda-forge lhorizon
.
We do not test or officially support the use of non-conda
environments for lhorizon
, but it can also be installed from PyPi:
pip install lhorizon
, or, if you'd like all the bells and whistles, pip install lhorizon[target, examples, tests]
.
If you'd like to install lhorizon
by hand, we again recommend that you use conda
to assemble a Python environment.
If you're already equipped with conda
, you can create an environment (named "lhorizon") for this package by cloning this repository
and running: conda env create -f environment.yml
from the repository root directory.
(You could instead add its dependencies to an existing environment by running conda env update -n existing_env -f environment.yml
).
Then, if you'd likelhorizon
installed as a site package in this environment, activate the environment and run pip install -e .
.
If you're new to conda
or Python environment management in general, please take a look at our easy
conda installation guide.
lhorizon
requires Python >= 3.9 (there are no plans to implement support for older Python versions).
the following packages are required for usage / installation:
more-itertools
numpy
pandas
requests
pyerfa
the following dependencies are optional and could potentially be omitted in restrictive install environments:
jupyter
is only required to run examplespytest
,pytest-cov
, andpytest-mock
are only required to run testsspiceypy
andsympy
are only required forlhorizon.target
and related tests and examples
Some features of lhorizon
can be used without internet connectivity, but much of the library requires you to be able
to dial out to the jpl.nasa.gov domain.
lhorizon
should function in any OS supported by conda
. The baseline system requirements are fairly light.
Counting dependencies and a base miniconda environment,lhorizon
takes up about 2.6 GB of space. The respository itself
is ~75 MB, almost all of which could be pruned in a restrictive install environment that did not require full git
history and the included SPICE kernels. Many uses of lhorizon
are not resource-intensive and will run comfortably on
a small machine like an AWS EC2 t3a.micro instance. Conversely, resource requirements can scale as high as you like if
you are planning to process extremely large sets of geometry data.
The Jupyter Notebooks provided in the examples directory are the best quick-start guides to usage. You can also try these examples out on Binder.
See the API reference for more details on the package's behavior.
Tests can be found in the lhorizon.tests module. You can run them simply by executing pytest
at the command line from the repository root directory.
You can also find some performance benchmarks in the benchmarks directory. Instructions for running them can be found in benchmarks/readme.md
- 2021-06-21: Full 1.0.0 release. Extensive changes from older versions:
- completes and rationalizes interface
- concatenates and standardizes target submodule
- reasonably complete test coverage and documentation
- somewhat more extensive example Notebooks
- 2021-08-13: 1.1.0 release.
- 2021-09-13: 1.1.1 release.
- 2021-09-14: 1.1.2 release. Packaging-only changes.
- 2023-12-17: 1.1.3 release.
- handling for Horizons API changes
- compatibility fixes for Python 3.12 and other library releases
- updated test data for parity with newly-released ephemerides
- 2023-02-26: 1.1.4 release.
- changed some default quantities and updated data accordingly
- handled a variety of edge cases related to timespans and column name formatting
- Exceptions raised in response to parsing failures now attempt to include any relevant failure message from the API response
- query options can now be passed as varkwargs to the
LHorizon
constructor lhorizon.constants.HORIZONS_QUANTITY_NAMES
provides a quick reference to Horizons quantity codes
- do not execute multiple queries to Horizons in parallel using multiprocessing or other
techniques, manual or programmatic. This is a requirement of Horizons, not
lhorizon
: JPL has not designed Horizons to support parallel queries, and will tightly throttle requesters who attempt them. Look at functions inlhorizon.handlers
for polite alternatives. lhorizon
only officially supports observer / ephemeris and vector Horizons queries. Osculating elements queries are not officially supported and may behave in unexpected ways. Support for elements queries is planned.
To report bugs, make feature requests, or get support for case-specific uses of lhorizon
, please file issues in this
GitHub repository. For broader questions about lhorizon
usage, please email mstclair@millionconcepts.com.
We welcome contributions to lhorizon
. They may simply be submitted as pull requests to this repository, although if
you have ideas for large new features or major architectural changes, we encourage you to discuss them with us first;
please email mstclair@millionconcepts.com
The development of lhorizon
has been supported partly by a NASA Solar System Observations grant, "Remote Measurement
of Lunar Heat Flow From Earth Based Radio Astronomy" (PI Matthew Siegler).
You can do almost anything with this software that you like, subject only to the extremely permissive terms of the BSD 3-Clause License.