mars-time-utils 0.1.10
Utilities for converting Martian time (Mars24, Piqueux, SolCal...)
Requires Python: >=3.8
Keywords: mars, time, conversion, planetary, astronomy

# mars_time_utils

Python tools for converting between Earth and Martian time. This package provides time conversion algorithms based on Mars24, Piqueux et al. (2015), and SolCal for space exploration applications.

## Installation

To install the package, use the command:

```bash
pip install mars_time_utils
```

## Usage

### Basic conversion between date formats

```python
import datetime
from mars_time_utils import calendarConversion

# Convert an Earth date to Martian SolCal time
date_terrestre = datetime.datetime(2025, 10, 16, 10, 0, 0)
temps_solcal = calendarConversion(date_terrestre, "solcal")
print(f"Date SolCal: MY {temps_solcal[0]}, Sol {temps_solcal[1]}, {temps_solcal[2]}")

# Conversion to tropical format (Ls, MY)
temps_tropical = calendarConversion(date_terrestre, "tropical")
print(f"Date tropicale: Ls={temps_tropical[0]:.2f}°, MY {temps_tropical[1]}")

# Conversion to Julian Days
jd = calendarConversion(date_terrestre, "ed_jd")
print(f"Julian Day: {jd}")
```

### Supported Formats

- `"ed_dt"`: Earth Dates (datetime.datetime)
- `"ed_jd"`: Earth Julian Days (float)
- `"solcal"`: Martian SolCal format (MY, Sol, MUT)
- `"solcal_m"`: SolCal format with Martian months
- `"tropical"`: Martian Tropical Format (Ls, MY)

### Available Algorithms

The package supports several calculation algorithms:
- **Mars24**: NASA Reference Algorithm
- **Piqueux et al. (2015)**: Improved algorithm for calculating Ls
- **SolCal**: Standardized Martian Calendar System

### Advanced Options

```python
# Use the Piqueux algorithm for greater precision
temps_tropical = calendarConversion(date_terrestre, "tropical", piqueuxEtAl=True)

# Also obtain Martian Mean Universal Time (MUT)
result = calendarConversion(date_terrestre, "tropical", giveMUT=True)

# Calculate Local True Solar Time (LTST) for a given longitude
ltst = calendarConversion(date_terrestre, "tropical", giveLTST=True, planeto_longitude=137.4)
```

## Prerequisites

- Python 3.8+
- NumPy >= 1.25
- SciPy >= 1.11
- Astropy >= 6.0

## Description

The `mars_time_utils` package provides utility functions for converting between Earth time and Martian time. It is primarily intended for developers, researchers, and space exploration enthusiasts who need to manipulate Mars-related time formats in their Python applications.

The conversions support all time formats commonly used in Martian planetology, with an accuracy suitable for space missions.

## Documentation

For more information on the algorithms used:
- [Mars24 Algorithm](https://www.giss.nasa.gov/tools/mars24/)
- Piqueux et al. (2015) "Enumeration of Mars years and seasons since 1874"

## Contribution

"to be defined"

## Licence

This project is licensed under a "to be defined" license. See the [LICENSE](LICENSE) file for more details.

## Authors

- **Victorien Guyon** - Lead Algorithm Developer - victorien.guyon@protonmail.com
- **University Group of the University of Savoie Mont-Blanc, First Year Master's in Computer Science**
    Development of the Python, CLI, and executable packages
    - **Timéo Chatelain** - chatelain.timeo@gmail.com
    - **Nathan Roi** - nathan.roi@etu.univ-savoie.fr
    - **Guillaume Boissier** - guillaume.boissier@etu.univ-savoie.fr
    - **Ronan Mcmanus** - ronan.mcmanus@etu.univ-savoie.fr
    - **Jonathan Thca** - jonathan.tcha@etu.univ-savoie.frfr