alpinekit 0.1.0

An ultralight optimisation tracking package

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.