Installation Guide

This guide explains the installation process for the HSI Mars package.

Prerequisites

Before installing this package, ensure you have:

Python 3.12 or higher installed on your system
- Download from python.org
- Verify installation: python --version

Installation Methods

Two main installation methods: using uv (recommended) or using pip (traditional).

Using uv (recommended)

uv is a fast Python package manager.

Step 1: Install uv

If you haven’t installed uv yet:

On macOS and Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

On Windows (PowerShell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

For alternative installation methods, see the uv documentation.

Step 2: Install the Package

Option A: Install from GitHub (for end users)

mkdir hsi_mars && cd hsi_mars
uv init --python=3.12
uv add git+https://github.com/thesfinox/mars-reconnaissance-orbiter.git

Option B: Install for Development (for contributors)

# Clone the repository
git clone https://github.com/thesfinox/mars-reconnaissance-orbiter.git hsi_mars
cd hsi_mars

# Create a virtual environment and install dependencies
uv sync

# Install with development dependencies (optional)
uv sync --group dev

# Activate the virtual environment
source .venv/bin/activate  # On Linux/macOS
# or
.venv\Scripts\activate  # On Windows

Using pip

If you prefer the traditional pip workflow:

Step 1: Create a Virtual Environment

# Create a new virtual environment
mkdir hsi_mars && cd hsi_mars
python -m venv .venv

# Activate the virtual environment
source .venv/bin/activate  # On Linux/macOS
# or
.venv\Scripts\activate  # On Windows

# Upgrade pip to the latest version
pip install --upgrade pip

Step 2: Install the Package

Option A: Install from GitHub (for end users)

pip install git+https://github.com/thesfinox/mars-reconnaissance-orbiter.git

Option B: Install for Development (for contributors)

# Clone the repository
git clone https://github.com/thesfinox/mars-reconnaissance-orbiter.git
cd mars-reconnaissance-orbiter

# Install in editable mode
pip install -e .

# Or install with development dependencies
pip install -e ".[dev]"

Development Setup

For contributors who want to set up a complete development environment:

# Clone the repository
git clone https://github.com/thesfinox/mars-reconnaissance-orbiter.git
cd mars-reconnaissance-orbiter

# Using uv (recommended)
uv sync --group dev --group test --group docs

# Or using pip
pip install -e ".[dev,test,docs]"

# Install pre-commit hooks
pre-commit install

# Run tests
pytest tests/

# Build documentation
cd docs
make html

Verifying Installation

To verify that the package is installed correctly, run:

python -c "from hsimars import HSIMars; print(HSIMars.__module__)"

If this command runs without errors, the installation was successful!

Troubleshooting

Python Version Issues

If you encounter issues related to Python version:

Ensure you have Python 3.12 or higher installed
You may need to use python3.12 instead of python in commands
Consider using pyenv to manage multiple Python versions

Installation Failures

If installation fails:

Ensure your pip is up to date: pip install --upgrade pip
Try installing in a fresh virtual environment
Check that you have sufficient permissions (avoid using sudo with pip)
On Linux, you may need to install development headers: sudo apt-get install python3-dev

Dependency Conflicts

If you encounter dependency conflicts:

Try installing in a fresh virtual environment
Use uv which handles dependency resolution more robustly
Check the pyproject.toml file for specific dependency versions

Getting Help

If you continue to have issues:

Check the GitHub Issues
Open a new issue with details about your system and the error message
Contact the maintainer: riccardo.finotello@cea.fr

Next Steps

Now that you have installed the package, see the Quick Start Guide guide to learn how to use it!