Kete Asteroid Survey Tools

Navigation

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for ddahlen from gravatar.com ddahlen

Unverified details

These details have not been verified by PyPI
Meta
Classifiers
Report project as malware

Project description

Kete

Predict orbits of asteroids and comets at large scales.

See the arXiv paper.

Github Actions DOI arXiv

The kete tools are intended to enable the simulation of all-sky surveys of minor planets. This includes multi-body physics orbital dynamics, orbit determination and fitting (IOD, differential correction, and MCMC posterior sampling), thermal and optical modeling of the objects, as well as field of view and light delay corrections. These tools in conjunction with the Minor Planet Centers (MPC) database of known asteroids can be used to not only plan surveys but can also be used to predict what objects are visible for existing or past surveys.

The primary goal for kete is to enable a set of tools that can operate on the entire MPC catalog at once, without having to do queries on specific objects. It has been used to simulate over 10 years of survey time for the NEO Surveyor mission using 10 million main-belt and near-Earth asteroids.

Documentation

https://github.com/user-attachments/assets/a48491d8-9c15-4659-9022-1767a3aa1e94

Here is a simulation of what the ZTF survey would observe during the entirety of 2023. This is every position of every numbered asteroid, along with a calculation of the expected V-band magnitudes. If the expected magnitude is less than ZTF's reported magnitude limit for the specific frame, then the object will flash light grey.

This took about 50 minutes on a desktop computer to compute, and about 40 minutes to generate the movie.

Kete can be used to answer many questions, for example, identifying all known asteroids inside of a given image.

Installation

Kete may be installed using pip:

pip install kete

Example of Code

Here is a small example showing off what programming with kete looks like. This calculates the closest distance that the asteroid Apophis will be at during its very close approach to Earth in April of 2029.

A more in-depth look at this example can be found here.

      import kete
      import numpy as np

      # Date of impact +- 1 day in Julian Date
      jd_center = kete.Time.from_ymd(2029, 4, 13.9066).jd

      # Step the orbit every 1 minute for +- 1 day.
      step_size = 1 / 24 / 60
      jd_range = np.arange(-1, 1, step_size) + jd_center

      # load Apophis from JPL Horizons
      obj = kete.HorizonsProperties.fetch("Apophis")
      cur_state = obj.state

      # keep track the the closest approach
      closest_approach = [np.inf, 0]
      for jd in jd_range:
            # propagate the object, and include the massive main belt asteroids
            cur_state = kete.propagate_n_body(cur_state, jd, include_asteroids=True)

            # calculate position relative to earth
            earth_vec = cur_state.pos - kete.spice.get_state("Earth", cur_state.jd).pos
            earth_dist = earth_vec.r * kete.constants.AU_KM
            if earth_dist < closest_approach[0]:
                  closest_approach = [earth_dist, cur_state.jd]

      print("Closest approach is on:")
      print(kete.Time(closest_approach[1]).iso)
      print(f"At a distance of about {closest_approach[0]:0.0f} km")
      #  Closest approach is on:
      #  2029-04-13T21:45:30.239+00:00
      #  At a distance of about 38015 km

Name

'Kete' comes from ancient greek mythology, meaning sea monsters, and is the root word for Cetaceans (Whales).

Licensing:

The original version of this code was developed while the original author (Dar Dahlen) was working at Caltech IPAC. I have since left Caltech and moved to Germany for a PhD. This is a fork of that repo where the work will continue as a personal project during my PhD. Difference between this fork and previous code is licensed as BSD 3-Clause but copyright to Dar Dahlen & future collaborators.

Units and Reference Frame

Kete uses the ICRF Reference frame as the base coordinate frame, with units of AU, with time in JD with Barycentric Dynamical Time (TDB) scaling. Internally this frame converted to an Ecliptic coordinate system which is defined by the Obliquity Angle definition used by JPL Horizons, which is the defined IAU76/80 model in the J2000 frame.

  - https://en.wikipedia.org/wiki/Axial_tilt#Short_term
  - https://ssd.jpl.nasa.gov/horizons/manual.html#defs

Both JPL Horizons and the Minor Planet Center (MPC) use this coordinate frame, which is essentially equivalent to J2000 Ecliptic coordinates. Conversion tools are available in kete which enable conversion to the Equatorial frame and to various flavors of time.

Cache directory

Many operations in kete result in downloading various files. These files are cached automatically, the directory where this cache is stored may be set by setting the environment variable KETE_CACHE_DIR. The default directory is ~/.kete/.

export KETE_CACHE_DIR="~/.kete/"

Use with Containers - Docker/Podman

Be aware that kete downloads several large SPICE kernel files on first use, which are saved to a cache directory.

Important for Docker/Podman:

  • If you trigger the download during the Docker build (e.g., RUN python -c "import kete"), the files will be baked into the image.
  • If you skip this step, the files will download on first container run but will be lost when the container stops unless you use a volume mount for the cache directory.

Recommended Dockerfile approach:

RUN pip install kete && \
    python -c "import kete"  # Triggers kernel downloads during build

This ensures the SPICE kernels are part of your image and don't need re-downloading.

Developer information:

Information below is aimed for developers, and is not necessary for end users.

Installation - From Source

If kete is built from source, the rust compiler must be installed. Installation instructions may be found here:

https://www.rust-lang.org/learn/get-started

Ensure that your Python is up to date, this code runs on Python 3.9+.

python --version

Ensure that your pip is up to date, this should be at least version 22.0.0.

pip --version

This can be updated using:

python -m pip install "pip>=22.0.0" --upgrade
pip install setuptools --upgrade

Development

If you plan on doing development, it is recommended to install with the following:

pip install '.[dev]'

The [dev] in that line has pip install a number of optional dependencies which are useful for development. Including pytest and documentation tools.

Building Documentation

In order for documentation to be built, some additional Python libraries are needed. These can be installed with:

pip install sphinx sphinx_gallery autodoc

After this has been installed, the documentation can be built by running inside the kete directory.

(cd docs && make html && open html/index.html&)

Once this has completed running, open the file kete/docs/html/index.html for access to the HTML documentation.

To clean the previous docs build:

(cd docs && make clean)

Documentation tests may be run with:

(cd docs && make doctest)

Running tests

Running tests require that the pytest and pytest-cov packages be installed.

Open a terminal in the base of this folder and run the following command:

pytest --cov-report term-missing --cov=kete

Another coverage report type is HTML, this will generate a folder called htmlcov in the directory where the command was run, then you can open the htmlcov/index.html file. This is a user-friendly website representation of the code coverage.

pytest --cov-report html --cov=kete

Running Tutorials

Tutorials are computationally expensive examples which are more indicative of typical expected use. Since these examples are so expensive to run, they are not run unless manually performed. A convenience python script has been provided to do just this.

cd docs
python utils.py

Running Benchmarks

There are a test suite of micro-benchmarks in the rust backend of kete. These require gnuplot to be installed, and may be run using the following command:

cargo bench
open target/criterion/report/index.html

Additionally, Flamegraphs may be produced using the following:

cargo bench --bench propagation -- --profile-time=5
cargo bench --bench spice -- --profile-time=5
cargo bench --bench thermal -- --profile-time=5

These flamegraphs will be put in target/criterion/*/profile/flamegraph.svg. Opening these files in a web browser will show what functions are being used during the bench.

Project details

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for ddahlen from gravatar.com ddahlen

Unverified details

These details have not been verified by PyPI
Meta
Classifiers

Release history Release notifications | RSS feed

This version

3.0.0

2.1.6

2.1.5

2.1.4

2.1.3

2.1.2

2.1.1

2.1.0

2.0.0

1.1.0

1.0.8

1.0.7

1.0.6

1.0.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

kete-3.0.0.tar.gz (566.9 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

kete-3.0.0-cp39-abi3-win_amd64.whl (9.2 MB view details)

Uploaded CPython 3.9+Windows x86-64

kete-3.0.0-cp39-abi3-manylinux_2_35_x86_64.whl (10.3 MB view details)

Uploaded CPython 3.9+manylinux: glibc 2.35+ x86-64

kete-3.0.0-cp39-abi3-manylinux_2_35_aarch64.whl (9.9 MB view details)

Uploaded CPython 3.9+manylinux: glibc 2.35+ ARM64

kete-3.0.0-cp39-abi3-macosx_11_0_arm64.whl (9.0 MB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

kete-3.0.0-cp39-abi3-macosx_10_12_x86_64.whl (9.6 MB view details)

Uploaded CPython 3.9+macOS 10.12+ x86-64

File details

Details for the file kete-3.0.0.tar.gz.

File metadata

  • Download URL: kete-3.0.0.tar.gz
  • Upload date:
  • Size: 566.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for kete-3.0.0.tar.gz
Algorithm Hash digest
SHA256 207c9764706b102ed6c52712febd20b77b5c1afdeacde04a98997cf4605cf513
MD5 66480a8e9239cd2348d71a9704fcfd51
BLAKE2b-256 e0e36482b114eec4039af71e57cdbedb3eecc6b6b126c60a7d1f98f0b350a9a8

See more details on using hashes here.

Provenance

The following attestation bundles were made for kete-3.0.0.tar.gz:

Publisher: release-wheels.yml on dahlend/kete

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file kete-3.0.0-cp39-abi3-win_amd64.whl.

File metadata

  • Download URL: kete-3.0.0-cp39-abi3-win_amd64.whl
  • Upload date:
  • Size: 9.2 MB
  • Tags: CPython 3.9+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for kete-3.0.0-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 641dd525a53353f2244a9e29977b2f0dfd64cd856ae3a88ed2583b09c8363ac5
MD5 1c4c8adabdf49a7a465e562e9ef22af4
BLAKE2b-256 9d0ba206637636b3f4adb0dce697e39c7b80db959e42e0db1807d3eab42d2f3f

See more details on using hashes here.

Provenance

The following attestation bundles were made for kete-3.0.0-cp39-abi3-win_amd64.whl:

Publisher: release-wheels.yml on dahlend/kete

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file kete-3.0.0-cp39-abi3-manylinux_2_35_x86_64.whl.

File metadata

  • Download URL: kete-3.0.0-cp39-abi3-manylinux_2_35_x86_64.whl
  • Upload date:
  • Size: 10.3 MB
  • Tags: CPython 3.9+, manylinux: glibc 2.35+ x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for kete-3.0.0-cp39-abi3-manylinux_2_35_x86_64.whl
Algorithm Hash digest
SHA256 14bde265e45217e42e20a8e4bbe1eb802eef8f36590e00685ad8a22d7745ee02
MD5 53104bd09f688fd74b418495b0d2c5cc
BLAKE2b-256 159d57e33be800d182debf9b29cc8676cf53b89ba395157ea92a242fe98dcd11

See more details on using hashes here.

Provenance

The following attestation bundles were made for kete-3.0.0-cp39-abi3-manylinux_2_35_x86_64.whl:

Publisher: release-wheels.yml on dahlend/kete

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file kete-3.0.0-cp39-abi3-manylinux_2_35_aarch64.whl.

File metadata

File hashes

Hashes for kete-3.0.0-cp39-abi3-manylinux_2_35_aarch64.whl
Algorithm Hash digest
SHA256 806329284db775e1e3bae591f31d5409b52e016ae038c2427968f739203977ad
MD5 56b92e76191fa7992a12740395baf141
BLAKE2b-256 8634eb5e30ff19fec0c5f5447fe63ba53f04985dd74f8304a10800f9b49da951

See more details on using hashes here.

Provenance

The following attestation bundles were made for kete-3.0.0-cp39-abi3-manylinux_2_35_aarch64.whl:

Publisher: release-wheels.yml on dahlend/kete

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file kete-3.0.0-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

  • Download URL: kete-3.0.0-cp39-abi3-macosx_11_0_arm64.whl
  • Upload date:
  • Size: 9.0 MB
  • Tags: CPython 3.9+, macOS 11.0+ ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for kete-3.0.0-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 23bb7685eaa8724655649e86b8b0a61deefa7f3948e5bab51d779f44bb839d32
MD5 79afe6e8973c229f6c941cf87e337c95
BLAKE2b-256 d853c90e9fa4bab043863b24c721ddfc65e0c92b6860055301cf32120041b071

See more details on using hashes here.

Provenance

The following attestation bundles were made for kete-3.0.0-cp39-abi3-macosx_11_0_arm64.whl:

Publisher: release-wheels.yml on dahlend/kete

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file kete-3.0.0-cp39-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for kete-3.0.0-cp39-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 135e42ab49fffe65235172b8572261c559571d9f2c3c5fc89d669602c608d34c
MD5 c0b89c841a71719a2be373f721cffa49
BLAKE2b-256 5f924103dd3823cbb97c12a0c0e1826c8816494a48fb46e24c7bc2955769f578

See more details on using hashes here.

Provenance

The following attestation bundles were made for kete-3.0.0-cp39-abi3-macosx_10_12_x86_64.whl:

Publisher: release-wheels.yml on dahlend/kete

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page