KepLemon

Citra Space Corporation's Rust-accelerated astrodynamics package built on the shared libraries provided by space-track. Please visit the documentation page for additional details.

Installation

From PyPI (Preferred)

KepLemon can be installed directly for any operating system from a command line using pip install keplemon.

From a Local Build

For python users, the preferred installation method is through PyPI; however, the package can be installed locally by following the steps below.

1. git clone https://github.com/citra-space/keplemon.git
2. cargo install cargo-make
3. cargo make build-<os>-<architecture> (e.g. for Linux x86 cargo make build-linux-x86)
4. pip install target/wheels/*.whl

To avoid potential conflicts with system libraries, you can alternatively build the wheel using Docker.

docker buildx build \
  --build-arg OS="${OS:-linux}" \
  --build-arg ARCH="${ARCH:-x86}" \
  --build-arg PYTHON_VERSION="${PYTHON_VERSION:-310}" \
  --output type=local,dest=./target .

Then install the wheel the same way with: pip install target/wheels/*.whl

Environment Settings

Although not required, it is recommended to explicitly apply the settings in this section before using KepLemon to avoid unexpected behaviors and inaccurate calculations.

CPU Limits

By default, KepLemon will have access to all available cores when performing parallel functions. Limit this by calling set_thread_count before using other KepLemon functions.

from keplemon import set_thread_count, get_thread_count

# Update this to the desired core count
set_thread_count(4)

Time Constants and Earth-Orientation Parameters (EOP)

All astrodynamics packages have a strict dependence on measured changes to time and Earth's orientation. Since KepLemon uses the public Standardized Astrodynamics Algorithms Library (SAAL) at the core, the time and (EOP) data must conform to a specific format required by the underlying binaries. Rather than referencing data directly provided by the USNO, utility scripts are provided in KepLemon to request and export the relevant data.

Global Update

Use the command below from a terminal to update time constants and EOP data package-wide.

keplemon --update-eop global

Local Override

EOP data can also be written to explicit paths for inspection or package overrides using the commands below.

keplemon --update-eop custom_path.txt

!!! note If you intend to use the data written to a local override, you must use the load_time_constants method at the beginning of your scripts. This is not needed if you maintain constants using the global method.

from keplemon.time import load_time_constants

# Update this to reflect the desired override path
load_time_constants("custom_path.txt")

CUDA GPU Acceleration

KepLemon supports optional CUDA GPU acceleration for batch satellite propagation, providing significant performance improvements when processing multiple satellites simultaneously.

Performance Benefits

GPU acceleration becomes beneficial when propagating:

• 40+ satellites with moderate time resolution (45+ time points)
• 100+ satellites with any reasonable time resolution
• Long-term propagations over multiple orbital periods

Key Performance Metrics:

• Up to 41x speedup for large satellite constellations
• GPU crossover point: ~900-1000 total propagations (satellites × time points)
• Typical speedup: 10-40x for 40+ satellites

Quick Start

# Build with CUDA support (Rust users)
cargo build --features cuda

# Run tests with GPU acceleration
cargo test --features cuda --release

Requirements

• CUDA Toolkit 12.6+
• NVIDIA GPU with Compute Capability 5.0+ (Maxwell or newer)
• Set CUDA_PATH environment variable if needed

For detailed information including usage examples, performance benchmarks, crossover analysis, and troubleshooting, see the CUDA GPU Acceleration Guide.

Contributing

Anyone is welcome to contribute to KepLemon. Users are encouraged to start by opening issues or forking the repository. Changes directly to the baseline may be approved by contacting the owner at brandon@citra.space.