# KepLemon

[Citra Space Corporation's](https://citra.space) Rust-accelerated astrodynamics package built on the shared libraries
provided by [space-track](https://space-track.org). Please visit the [documentation](https://keplemon.citra.space)
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](https://www.pypi.org)_**; 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.

```bash
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.

```python
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](https://maia.usno.navy.mil/), 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.

```bash
keplemon --update-eop global
```

#### Local Override

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

```bash
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_**.

```python
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

```bash
# 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](CUDA_README.md).

## 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>.
