v0.2.0 update

Author: networmix

.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      test_pypi:
+        description: 'Publish to Test PyPI instead of PyPI'
+        required: false
+        default: false
+        type: boolean
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write  # Required for trusted publishing
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install build twine
+
+      - name: Build package
+        run: python -m build
+
+      - name: Check package
+        run: python -m twine check dist/*
+
+      - name: Publish to Test PyPI
+        if: ${{ github.event.inputs.test_pypi == 'true' }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          print-hash: true
+
+      - name: Publish to PyPI
+        if: ${{ github.event_name == 'release' && github.event.action == 'published' }}
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          print-hash: true

CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2025-12-06
+
+### Changed
+
+- **BREAKING**: Minimum Python version raised to 3.11
+- **Dependencies**: Updated ngraph to >=0.12.0
+
+## [0.1.0] - Previous Release
+
+Initial release of NetLab metrics and analysis tools.

LICENSE

@@ -1,11 +1,30 @@
 # NetLab Development Makefile
 
-.PHONY: help dev install check check-ci lint format test qt clean build check-dist publish-test publish info
+.PHONY: help venv clean-venv dev install check check-ci lint format test qt build clean check-dist publish-test publish info hooks check-python
 
 .DEFAULT_GOAL := help
 
-VENV_BIN := $(PWD)/netlab-venv/bin
-PYTHON := $(if $(wildcard $(VENV_BIN)/python),$(VENV_BIN)/python,python3)
+# --------------------------------------------------------------------------
+# Python interpreter detection
+# --------------------------------------------------------------------------
+# VENV_BIN: path to local virtualenv bin directory
+VENV_BIN := $(PWD)/venv/bin
+
+# PY_BEST: scan for newest supported Python (used when creating new venvs)
+# Supports 3.11-3.13 to match common CI matrix
+PY_BEST := $(shell for v in 3.13 3.12 3.11; do command -v python$$v >/dev/null 2>&1 && { echo python$$v; exit 0; }; done; command -v python3 2>/dev/null || command -v python 2>/dev/null)
+
+# PY_PATH: active python3/python on PATH (respects CI setup-python and activated venvs)
+PY_PATH := $(shell command -v python3 2>/dev/null || command -v python 2>/dev/null)
+
+# PYTHON: interpreter used for all commands
+#   1. Use local venv if present
+#   2. Otherwise use active python on PATH (important for CI)
+#   3. Fall back to best available version
+#   4. Final fallback to 'python3' literal for clear error messages
+PYTHON ?= $(if $(wildcard $(VENV_BIN)/python),$(VENV_BIN)/python,$(if $(PY_PATH),$(PY_PATH),$(if $(PY_BEST),$(PY_BEST),python3)))
+
+# Derived tool commands (always use -m to ensure correct environment)
 PIP := $(PYTHON) -m pip
 PYTEST := $(PYTHON) -m pytest
 RUFF := $(PYTHON) -m ruff
@@ -15,12 +34,14 @@ help:
 	@echo "🔧 NetLab Development Commands"
 	@echo ""
 	@echo "Setup & Installation:"
-	@echo "  make install       - Install package for usage (no dev dependencies)"
+	@echo "  make venv          - Create a local virtualenv (./venv)"
 	@echo "  make dev           - Full development environment (package + dev deps + hooks)"
+	@echo "  make install       - Install package for usage (no dev dependencies)"
+	@echo "  make clean-venv    - Remove virtual environment"
 	@echo ""
 	@echo "Code Quality & Testing:"
-	@echo "  make check         - Run lint + tests"
-	@echo "  make check-ci      - Run non-mutating checks and tests (CI entrypoint)"
+	@echo "  make check         - Run pre-commit (auto-fix) + tests, then lint"
+	@echo "  make check-ci      - Run non-mutating lint + tests (CI entrypoint)"
 	@echo "  make lint          - Run only linting (non-mutating: ruff + pyright)"
 	@echo "  make format        - Auto-format code with ruff"
 	@echo "  make test          - Run tests with coverage"
@@ -35,19 +56,56 @@ help:
 	@echo ""
 	@echo "Utilities:"
 	@echo "  make info          - Show project information"
+	@echo "  make hooks         - Run pre-commit on all files"
+	@echo "  make check-python  - Check if venv Python matches best available"
 
 dev:
 	@echo "🚀 Setting up development environment..."
-	@bash dev/setup-dev.sh
+	@if [ ! -x "$(VENV_BIN)/python" ]; then \
+		if [ -z "$(PY_BEST)" ]; then \
+			echo "❌ Error: No Python interpreter found (python3 or python)"; \
+			exit 1; \
+		fi; \
+		echo "🐍 Creating virtual environment with $(PY_BEST) ..."; \
+		$(PY_BEST) -m venv venv || { echo "❌ Failed to create venv"; exit 1; }; \
+		if [ ! -x "$(VENV_BIN)/python" ]; then \
+			echo "❌ Error: venv creation failed - $(VENV_BIN)/python not found"; \
+			exit 1; \
+		fi; \
+		$(VENV_BIN)/python -m pip install -U pip setuptools wheel; \
+	fi
+	@echo "📦 Installing dev dependencies..."
+	@$(VENV_BIN)/python -m pip install -e .'[dev]'
+	@echo "🔗 Installing pre-commit hooks..."
+	@$(VENV_BIN)/python -m pre_commit install --install-hooks
+	@echo "✅ Dev environment ready. Activate with: source venv/bin/activate"
+	@$(MAKE) check-python
+
+venv:
+	@echo "🐍 Creating virtual environment in ./venv ..."
+	@if [ -z "$(PY_BEST)" ]; then \
+		echo "❌ Error: No Python interpreter found (python3 or python)"; \
+		exit 1; \
+	fi
+	@$(PY_BEST) -m venv venv || { echo "❌ Failed to create venv"; exit 1; }
+	@if [ ! -x "$(VENV_BIN)/python" ]; then \
+		echo "❌ Error: venv creation failed - $(VENV_BIN)/python not found"; \
+		exit 1; \
+	fi
+	@$(VENV_BIN)/python -m pip install -U pip setuptools wheel
+	@echo "✅ venv ready. Activate with: source venv/bin/activate"
+
+clean-venv:
+	@rm -rf venv/
 
 install:
 	@echo "📦 Installing package for usage (no dev dependencies)..."
 	@$(PIP) install -e .
 
 check:
 	@echo "🔍 Running complete code quality checks and tests..."
-	@$(MAKE) lint
 	@PYTHON=$(PYTHON) bash dev/run-checks.sh
+	@$(MAKE) lint
 
 check-ci:
 	@echo "🔍 Running CI checks (non-mutating lint + tests)..."
@@ -83,14 +141,13 @@ build:
 
 clean:
 	@echo "🧹 Cleaning build artifacts and cache files..."
-	@rm -rf build/
-	@rm -rf dist/
-	@rm -rf *.egg-info/
-	@find . -type f -name "*.pyc" -delete
-	@find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
-	@find . -type f -name "*.pyo" -delete
-	@find . -type f -name "*~" -delete
-	@find . -type f -name "*.orig" -delete
+	@rm -rf build/ dist/ *.egg-info/
+	@rm -rf .pytest_cache .ruff_cache .mypy_cache htmlcov .coverage coverage.xml coverage-*.xml .benchmarks .pytest-benchmark || true
+	@find . -path "./venv" -prune -o -type f -name "*.pyc" -delete 2>/dev/null || true
+	@find . -path "./venv" -prune -o -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
+	@find . -path "./venv" -prune -o -type f -name "*.pyo" -delete 2>/dev/null || true
+	@find . -path "./venv" -prune -o -type f -name "*~" -delete 2>/dev/null || true
+	@find . -path "./venv" -prune -o -type f -name "*.orig" -delete 2>/dev/null || true
 	@echo "✅ Cleanup complete!"
 
 check-dist:
@@ -125,7 +182,9 @@ info:
 	@echo "============================="
 	@echo ""
 	@echo "🐍 Python Environment:"
-	@echo "  Python version: $$($(PYTHON) --version)"
+	@echo "  Python (active): $$($(PYTHON) --version)"
+	@echo "  Python (best):   $$($(PY_BEST) --version 2>/dev/null || echo 'missing')"
+	@$(MAKE) check-python
 	@echo "  Package version: $$($(PYTHON) -c 'import importlib.metadata as m; print(m.version("netlab"))' 2>/dev/null || echo 'Not installed')"
 	@echo "  Virtual environment: $$(echo $$VIRTUAL_ENV | sed 's|.*/||' || echo 'None active')"
 	@echo ""
@@ -136,3 +195,17 @@ info:
 	@echo "  Pyright: $$($(PYTHON) -m pyright --version 2>/dev/null | head -1 || echo 'Not installed')"
 	@echo "  Build: $$($(PYTHON) -m build --version 2>/dev/null | sed 's/build //' | sed 's/ (.*//' || echo 'Not installed')"
 	@echo "  Twine: $$($(PYTHON) -m twine --version 2>/dev/null | grep -o 'twine version [0-9.]*' | cut -d' ' -f3 || echo 'Not installed')"
+
+hooks:
+	@echo "🔗 Running pre-commit on all files..."
+	@$(PRECOMMIT) run --all-files || (echo "Some pre-commit hooks failed. Fix and re-run." && exit 1)
+
+check-python:
+	@if [ -x "$(VENV_BIN)/python" ]; then \
+		VENV_VER=$$($(VENV_BIN)/python -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')" 2>/dev/null || echo "unknown"); \
+		BEST_VER=$$($(PY_BEST) -c "import sys; print(f'{sys.version_info.major}.{sys.version_info.minor}')" 2>/dev/null || echo "unknown"); \
+		if [ -n "$$VENV_VER" ] && [ -n "$$BEST_VER" ] && [ "$$VENV_VER" != "$$BEST_VER" ]; then \
+			echo "⚠️  WARNING: venv Python ($$VENV_VER) != best available Python ($$BEST_VER)"; \
+			echo "   Run 'make clean-venv && make dev' to recreate venv if desired"; \
+		fi; \
+	fi

Makefile

@@ -0,0 +1,110 @@
+# NetLab
+
+Metrics aggregation and statistical analysis for [NetGraph](https://github.com/networmix/NetGraph) simulation results.
+
+## Overview
+
+NetLab processes NetGraph workflow outputs (JSON artifacts) to compute statistical metrics across random seeds and failure scenarios. Provides CLI and Python API for batch analysis, cross-seed aggregation, and visualization.
+
+## Features
+
+### Metrics
+
+- **BAC (Bandwidth Availability Curve)**: Delivered bandwidth quantiles, availability at thresholds, AUC normalization
+- **Latency**: Stretch distributions (p50/p99), tail degradation ratios, SLO compliance, WES (Weighted Excess Stretch)
+- **IterationOps**: Per-iteration SPF calls, flows created, reoptimization calls, placement iterations
+- **SPS (Structural Pair Survivability)**: Fraction of src-dst pairs meeting demand under failures
+- **MSD (Maximum Supported Demand)**: Alpha-star multiplier for traffic matrix scaling capacity
+- **CostPower**: CapEx/Power totals, USD/Watt per Gbit (offered and at p99.9 reliability)
+
+### Cross-Seed Analysis
+
+- Positional alignment of time-series data by iteration index
+- Median and IQR (interquartile range) computation
+- Variable-length series handling with NaN padding
+
+### Visualization
+
+- Cross-seed plots with median curves and IQR bands
+- Baseline-normalized delta comparisons
+- Statistical significance heatmaps (p-values)
+
+## Installation
+
+```bash
+pip install netlab
+```
+
+From source:
+
+```bash
+git clone https://github.com/networmix/NetLab
+cd NetLab
+make dev
+```
+
+## Usage
+
+### CLI
+
+```bash
+# Compute metrics for scenarios
+netlab metrics tests/data/scenarios/
+
+# With summary tables and plots
+netlab metrics tests/data/scenarios/ --summary
+
+# Filter specific scenarios
+netlab metrics tests/data/scenarios/ --only small_clos,small_dragonfly
+
+# Skip plot generation
+netlab metrics tests/data/scenarios/ --no-plots
+```
+
+### Python API
+
+```python
+from metrics.bac import compute_bac_metrics
+from metrics.aggregate import summarize_across_seeds
+
+# Compute BAC for a workflow step
+bac = compute_bac_metrics(iterations, offered_bw, step_name="max_demand")
+print(f"p99 availability: {bac['q_pct'][0.99]:.2%}")
+
+# Aggregate across seeds
+summary = summarize_across_seeds(series_by_seed, label="latency_p99")
+```
+
+## Repository Structure
+
+```
+metrics/            # Core metrics modules
+  bac.py            # Bandwidth availability
+  latency.py        # Latency percentiles
+  iterops.py        # Iteration analysis
+  aggregate.py      # Cross-seed aggregation
+  plot_*.py         # Visualization
+netlab/             # CLI
+  cli.py            # Command-line interface
+  metrics_cmd.py    # Metrics command implementation
+tests/              # Test suite
+lib/                # Config files
+```
+
+## Development
+
+```bash
+make dev        # Setup environment
+make check      # Tests and linting
+make test       # Tests only
+make lint       # Linting only
+```
+
+## Requirements
+
+- Python 3.11+
+- Dependencies: numpy, pandas, matplotlib, seaborn, scipy, rich, ngraph
+
+## License
+
+AGPL-3.0-or-later