AlpineKit

An ultralight optimisation tracking package for Python. Track metrics, timing and memory usage with minimal overhead.

Quick Start

import time
from alpinekit import Metric, Track, history

# Define a metric to track
x_val = Metric("x")

# Track iterations with automatic timing and progress bars
x = 1
for i in Track(range(5)):
    time.sleep(0.1)
    x += x + i
    x_val.add(x)  # Add metric value

# View results as DataFrame
history.df

# View summary statistics
history.summary

Installation

From PyPI:

# Core package
pip install alpinekit

# With examples (optional)
pip install alpinekit[examples]

With uv:

# Core package
uv pip install alpinekit

# With examples (optional)
uv pip install alpinekit[examples]

From GitHub source:

git clone https://github.com/hconnorh/alpinekit.git
cd alpinekit

# With pip
pip install -e ".[examples]"

# With uv
uv sync --extra examples
source .venv/bin/activate

Requirements: Python >= 3.13

Key Features

Metric - Track custom values

• Metric(name) - Create a metric tracker
• .add(value) - Record a value
• .add_norm(array) - Track array norm
• .add_mem(*arrays) - Track memory usage

Track - Enhanced iteration tracking

• Automatic progress bars (tqdm)
• CPU time per iteration
• Wall-clock time per iteration
• Memory (RSS) tracking per iteration
• Thread-safe operation

History - Access and analyze results

• history.df - Get all metrics as a Polars DataFrame
• history.summary - Get statistics (mean, std, min, max) for all metrics
• history.merge_runs() - Merge results from parallel runs with run_id column

Check out the examples/ directory for basic usage guides and parallel batch processing examples.

License

This project is licensed under the MIT License. See LICENSE.md for details.