Installation Guide

Requirements

Python Version: >=3.11 Operating System: Windows, macOS, Linux

Basic Installation

Install with UV (Fastest)

uv add allocator

UV is a modern, fast Python package manager. If you don’t have UV installed:

pip install uv
uv add allocator

Optional Dependencies

allocator supports several optional dependency groups for extended functionality:

Algorithms

# Enhanced algorithms including Christofides TSP
pip install "allocator[algorithms]"

Includes:

  • Christofides ≥1.0.0 - Christofides TSP algorithm for optimal routing

  • scikit-learn ≥1.3.0 - Machine learning algorithms

Geo

# Interactive mapping and route visualization
pip install "allocator[geo]"

Includes:

  • folium ≥0.14.0 - Interactive maps and visualizations

  • polyline ≥2.0.0 - Route encoding for mapping APIs

Dev

# Development and testing tools
pip install "allocator[dev]"

Includes:

  • ruff ≥0.1.0 - Modern linting and formatting

  • mypy ≥1.5.0 - Type checking

  • black ≥23.0.0 - Code formatting

  • isort ≥5.12.0 - Import sorting

  • pre-commit ≥3.0.0 - Git hooks for code quality

Test

# Testing framework and coverage tools
pip install "allocator[test]"

Includes:

  • pytest ≥7.4.0 - Testing framework

  • pytest-cov ≥4.1.0 - Coverage reporting

  • pytest-xdist ≥3.3.0 - Parallel testing

  • coverage ≥7.2.0 - Code coverage analysis

  • hypothesis ≥6.82.0 - Property-based testing

Docs

# Documentation building tools
pip install "allocator[docs]"

Includes:

  • sphinx ≥7.0.0 - Documentation generator

  • furo ≥2023.9.10 - Additional functionality

  • myst-parser ≥2.0.0 - Markdown support for Sphinx

  • linkify-it-py ≥2.0.0 - Additional functionality

  • sphinx-autodoc-typehints ≥1.24.0 - Type hints in API docs

  • sphinx-design ≥0.5.0 - Additional functionality

Complete Installation

All Features

# Install with all optional features
pip install "allocator[all]"

Complete Development Setup

# Install everything for development
pip install "allocator[complete]"

Installation Verification

Quick Test

import allocator
print(f"Allocator version: {allocator.__version__}")

# Test basic functionality
import pandas as pd

# Create sample data
data = pd.DataFrame({
    'longitude': [100.5, 100.6, 100.7],
    'latitude': [13.7, 13.8, 13.9]
})

# Test clustering
result = allocator.cluster(data, n_clusters=2)
print(f"✓ Clustering: Created {result['n_clusters']} clusters")

# Test routing
route = allocator.shortest_path(data)
print(f"✓ Routing: {route['total_distance']:.1f}km route")

print("🎉 Installation successful!")

Command Line Interface

# Test CLI installation
allocator --version

# Test clustering command
echo "longitude,latitude
100.5,13.7
100.6,13.8
100.7,13.9" > test_data.csv

allocator cluster kmeans test_data.csv --n-clusters 2

Troubleshooting

Common Issues

Permission Error on macOS/Linux

# Use --user flag to install in user directory
pip install --user allocator

Package Conflicts

# Create a virtual environment (recommended)
python -m venv allocator_env
source allocator_env/bin/activate  # On Windows: allocator_env\Scripts\activate
pip install allocator

UV Installation Issues

# Install UV using pip if direct install fails
pip install uv
uv add allocator

Core Dependencies

allocator requires these core packages:

  • pandas ≥2.0.0 - Data manipulation and analysis

  • numpy ≥1.24.0 - Numerical computations

  • utm ≥0.7.0 - Coordinate system transformations

  • haversine ≥2.8.0 - Geographic distance calculations

  • networkx ≥3.0 - Graph algorithms

  • click ≥8.0.0 - Command-line interface framework

  • rich ≥13.0.0 - Rich terminal output and formatting

  • requests ≥2.28.0 - HTTP library for API calls

  • googlemaps ≥4.6.0 - Google Maps API integration

  • ortools ≥9.5.0 - High-performance optimization algorithms

  • matplotlib ≥3.6.0 - Basic plotting and visualization

  • seaborn ≥0.13.2 - Statistical data visualization

System Requirements

Memory: 2GB+ recommended for large datasets (1000+ points) Storage: 100MB for package + 50MB per analysis run Network: Optional for OSRM/Google Maps API features

Development Installation

From Source

# Clone the repository
git clone https://github.com/geosensing/allocator.git
cd allocator

# Install in development mode
pip install -e ".[complete]"

# Set up pre-commit hooks
pre-commit install

Using UV

# Clone and install with UV
git clone https://github.com/geosensing/allocator.git
cd allocator
uv sync --all-extras

Docker Installation

Quick Start with Docker

# Run allocator in Docker container
docker run --rm -v $(pwd):/data python:3.11 bash -c "
    pip install allocator &&
    cd /data &&
    allocator --help
"

Custom Dockerfile

FROM python:3.11-slim

# Install allocator with all features
RUN pip install allocator[all]

# Set working directory
WORKDIR /workspace

# Default command
CMD ["allocator", "--help"]

Build and run:

docker build -t allocator .
docker run --rm -v $(pwd):/workspace allocator

Next Steps

Getting Help