1.0.2

What's Changed

• [pre-commit.ci] pre-commit autoupdate by @pre-commit-ci[bot] in #18
• [pre-commit.ci] pre-commit autoupdate by @pre-commit-ci[bot] in #26
• chore(deps): bump the github-actions group with 2 updates by @dependabot[bot] in #27
• Change edge type fallback in visualization by @yannickwerner in #32
• [pre-commit.ci] pre-commit autoupdate by @pre-commit-ci[bot] in #28
• chore(deps): bump sphinxcontrib-mermaid from 2.0.0 to 2.0.1 in the dependencies group by @dependabot[bot] in #29
• chore(deps): bump codecov/codecov-action from 5 to 6 in the github-actions group by @dependabot[bot] in #30
• 25 add example library by @yannickwerner in #34

New Contributors

• @yannickwerner made their first contribution in #32

Full Changelog: 1.0.1...1.0.2

1.0.1

New Features

• Per-type edge aggregation: Aggregate edge properties independently by edge type (e.g., line, trafo, link), returning a
  MultiDiGraph with one edge per type per cluster pair. Supports per-type strategy configuration with fallback to default edge
  strategies.

Edge Case Fixes

• AverageNodeStrategy: Warns and falls back to first available value for non-numeric properties instead of silently returning
  0.0
• EquivalentReactanceStrategy: Warns when returning inf due to non-numeric values; raises AggregationError when the property
  is entirely missing
• VA partitioning strategies: Reject single voltage level graphs with a clear ValidationError instead of proceeding silently

Maintenance

• Pre-commit hooks updated
• GitHub Actions dependencies bumped

Full Changelog: 1.0.0...1.0.1

Production-Ready Release

🚀 NPAP v1.0.0 — Production-Ready Release

The first production-ready release of NPAP (Network Partitioning & Aggregation Package). Since the initial v0.1.0, the library has undergone a massive expansion — 98 commits, 80 files changed, ~19,000 lines added — covering new strategies, comprehensive testing, full documentation, performance optimizations, and CI/CD infrastructure.

📖 Full documentation: npap.readthedocs.io

---

✨ What's New since v0.1.0

⚡ New Features

• Electrical Distance Partitioning — New partitioning strategy based on PTDF-derived electrical proximity using the network susceptance matrix. Supports multi-island grids.
• AC-Island Awareness in Geographical Partitioning — Geographical strategies now automatically detect and respect AC island boundaries when voltage-aware data is loaded. Supported by K-Medoids, DBSCAN, HDBSCAN, and Hierarchical (non-ward) clustering.
• Voltage-Aware Electrical Partitioning — New VAElectricalPartitioning strategy that combines AC-island and voltage-level awareness with electrical distance clustering.
• Spherical-to-Cartesian Coordinate Conversion — K-Means geographical partitioning now converts spherical (lat/lon) coordinates to Cartesian space to avoid distorted clusters at high latitudes.
• Configurable Visualization — New PlotConfig dataclass to override default Plotly map styling (tile layer, zoom, center, colors).
• Centralized Logging — Structured logging across all modules (input, partitioning, aggregation, managers) for better debugging and traceability.
• Input Validation — Partition methods now validate that required node/edge attributes exist before execution, with clear error messages.

🏎️ Performance

• Vectorized Data Loading — Data loaders and topology checks optimized with NumPy/Pandas vectorized operations.
• Vectorized Partitioning — Partitioning strategies refactored to use NumPy array operations instead of Python loops.
• Faster Aggregation — Graph aggregation pipeline optimized for reduced overhead.

🐛 Bug Fixes

• Fixed electrical partitioning for multi-island grids — PTDF computation now correctly handles disconnected AC islands instead of failing on singular matrices.

📖 Documentation

• Full Sphinx documentation hosted on ReadTheDocs (npap.readthedocs.io) with pydata-sphinx-theme.
• User Guide — Installation, quick start, data loading, partitioning (geographical, electrical, VA-geographical, VA-electrical), aggregation, visualization, and extending NPAP.
• API Reference — Auto-generated from NumPy-style docstrings for all public classes and functions.
• Contributing Guide — Getting started, development workflow, extending NPAP, pull requests, reporting issues, and code of conduct.
• Comprehensive docstrings — All public API updated to NumPy docstring convention.

🧪 Testing

• Comprehensive test suite with pytest covering:
  • All partitioning strategies (geographical, electrical, VA-geographical, VA-electrical)
  • All input strategies (CSV, NetworkX, voltage-aware loader)
  • All aggregation strategies (topology, property, equivalent reactance)
  • Utility functions
  • AC-island detection and DC-island isolation
• Coverage reporting via Codecov integration.

🔧 CI/CD & Infrastructure

• GitHub Actions CI — Lint (Ruff + Codespell) and test (Python 3.10, 3.11, 3.12) on every push/PR.
• PyPI publish workflow — Automated publishing via trusted publishing on GitHub Release.
• Pre-commit hooks — Ruff linting/formatting, Codespell, and standard file checks.
• Dependabot — Automated dependency and GitHub Actions updates.
• Issue templates — Structured bug report and feature request forms.
• Pull request template — Standardized PR checklist.

---

📦 Installation

pip install npap

v0.1.0

Initial Release: Network Partitioning & Aggregation Package (NPAP)

This is the initial release of NPAP, a Python library designed for the partitioning and aggregation of spatial network data, with a specific focus on electrical power systems.

Module Breakdown

🔌 Input Module (npap.input)

Handles data ingestion through flexible strategies.

• Standard Loading: Supports loading graph data from CSV files or existing NetworkX objects.
• Voltage-Aware Loader: A specialized strategy (va_loader) for power systems that parses nodes, lines, transformers, and DC links. It automatically detects DC islands and validates network connectivity before processing.

🧩 Partitioning Module (npap.partitioning)

Implements clustering algorithms to group network nodes based on physical or spatial metrics.

• Geographical: Clusters nodes based on spatial coordinates using K-Means, K-Medoids, DBSCAN, or Hierarchical clustering.
• Electrical: Groups nodes based on electrical distance derived from the network's susceptance matrix (PTDF approach).
• Voltage-Aware Geographical: A specialized strategy that strictly respects DC island boundaries and voltage levels during geographical clustering. Available in "Standard" and "Proportional" modes.

📦 Aggregation Module (npap.aggregation)

Manages the reduction of graph topology and nodes/edges attributes through a configurable pipeline.

• Strategies: Includes custom Topology Strategies (Simple, Electrical) and Property Strategies (Sum, Average, First).
• Power System Specifics: Features an EquivalentReactance strategy to correctly calculate the parallel impedance 1/sum(1/x) of aggregated lines.

📊 Visualization Module (npap.visualization)

Provides high-performance, interactive network visualization using Plotly.

• Simple Style: Uniform styling for quick structural overviews.
• Voltage-Aware Style: Edges colored by edge type (Line, Transformer, DC Link) and voltage level.
• Clustered Style: Nodes colored by their assigned partition cluster for easy visual validation.

⚙️ Core Managers (npap.managers)

Contains the PartitionAggregatorManager, the central orchestrator of the library. It provides a unified API to load data, execute partitioning strategies, and perform aggregation workflows in a single seamless process.

Installation

pip install npap