NPAP: Network Partitioning and Aggregation Package for Python

Marco Anarmo, Benjamin Stöckl, Yannick Werner, Sonja Wogrin · 2026

Read NPAP: Network Partitioning and Aggregation Package for Python by Marco Anarmo, Benjamin Stöckl, Yannick Werner, Sonja Wogrin (2026) in the Tower of Babel, a free online library of public-domain works preserved in clean, searchable text. No sign-up. The full text is served as a plain-text file at a predictable URL, where text is present: https://antarctic-labs.com/tower-of-babel/arxiv-2605-12137.txt.

Introduction

Marco Anarmo and three colleagues present NPAP, an open-source Python tool that shrinks network maps. Built on NetworkX, it splits the job in two: grouping nodes into clusters, then shrinking the net under that grouping. Its strategy design lets users add their own grouping and shrinking rules without touching core code. NPAP now ships 13 grouping rules and two set shrink profiles, built first for power grids but open to any network map.

Catalog record

CREATORMarco Anarmo, Benjamin Stöckl, Yannick Werner, Sonja Wogrin
YEAR2026
COLLECTIONPAPERS
FORMATTXT
FILE SIZE13684
LICENSEhttp://creativecommons.org/licenses/by/4.0/
RIGHTSCC BY
SOURCEarXiv

Source: https://arxiv.org/abs/2605.12137

Browse the full library · About the Tower of Babel

Full text

The opening of the work, from the library's hosted text:

NPAP: Network Partitioning and Aggregation Package for Python Marco Anarmo, Benjamin Stöckl, Yannick Werner, Sonja Wogrin Abstract Summary NPAP (Network Partitioning and Aggregation Package) is an open-source Python library for reducing the spatial complexity of network graphs. Built on NetworkX ( [ ref-NetworkX ] ), it provides an accessible standalone package designed to be readily integrated with other software and frameworks. Instead of treating the spatial reduction process as a single action, NPAP explicitly splits it into two distinct steps: partitioning, which assigns vertices (nodes) to groups (clusters), and aggregation, which reduces the network based on a given assignment. NPAP’s strategy pattern architecture allows users to employ and register custom partitioning and aggregation strategies seamlessly without modifying the core code. Currently, NPAP provides 13 different partitioning strategies and two pre-defined aggregation profiles. Although initially developed with a focus on power systems, its architecture is general-purpose and applicable to any network graph. Statement of need Real-world electricity grids have grown significantly in size and complexity, potentially spanning many thousands of nodes and edges. Consequently, energy system optimization models representing those networks have become computationally intractable and challenging to solve. To regain tractability and computational efficiency, modelers frequently apply temporal and spatial aggregation techniques ( [ ref-Kotzur2021 ] ). Today, temporal complexity reduction, known as time series aggregation, is a well-established field ( [ ref-Hoffmann2020 ] ; [ ref-Teichgraeber2022 ] ; [ ref-Wogrin2023 ] ). Tools like tsam (Time Series Aggregation Module) ( [ ref-Hoffmann2022 ] ) have consolidated multiple temporal aggregation algorithms into a single, reusable Python library that has become a standard component in many energy system optimization modeling frameworks. Before tsam, modelers implemented these methods individually and ad hoc for each project, challenging reusability and comparability. This is exactly where the research on spatial complexity reduction is at: While there is some research on network partitioning ( [ ref-frysztacki_comparison_2022 ] ) and aggregation ( [ ref-colonetti_ward_2025 ] ) methods available, there exists no standalone tool that brings all methods together and is easy to use, extend, and does not rely on framework-specific data structures. NPAP fills this gap as a standalone package that works with any NetworkX ( [ ref-NetworkX ] ) graph. The target audience includes power systems researchers, energy modelers, network analysts, and more broadly, anyone interested in reducing the spatial complexity of a graph. State of the field Within the energy system optimization community, existing implementations of network partitioning and aggregation methods are usually tightly rooted to the respective frameworks’ internal data structure and cannot be reused independently or by other tools and frameworks. The built-in spatial clustering module of PyPSA ( [ ref-Brown2018a ] ), for example, provides busmap-based spatial aggregation using methods such as k-means or hierarchical clustering on geographical coordinates of buses, based on PyPSA’s Network object and buses DataFrame. As another example, ETHOS.FINE ( [ ref-Kluetz2025 ] ) implements spatial reduction through string-, distance-, and parameter-based partitioning modes ( [ ref-Patil2022 ] ), which are strictly tied to the framework’s internal region-based data model. Researchers working with other frameworks or custom network representations cannot leverage these implementations without significant adaptation to the core code structure. The analogy with temporal complexity reduction and the tsam package ( [ ref-Hoffmann2022 ] ) is instructive. NPAP extends this paradigm to the spatial dimension. Its unique contributions include: • Standalone Architecture: A pip-installable library decoupled from any specific energy system modeling framework. • Extensibility: A strategy pattern architecture that allows new functionalities to be added without modifying core code. • Pipeline Control: An explicit conceptual separation between partitioning and aggregation, enabling rigorous control over each stage of the reduction pipeline. • Advanced Physical Constraints: Built-in support for voltage-aware and AC-island-aware partitioning for real-world electricity networks. Pipeline architecture Figure 1: NPAP pipeline architecture. The full NPAP pipeline is shown in Figure 1 . Initially, NPAP performs two stages, preparing the network graph. In the first stage, data is loaded and a NetworkX graph — used for the reduction process — is created and validated. In the second stage, NPAP provides optional pre-processing steps that prepare the network graph for the reduction process. The network can be illustrated throughout the pipeline using the visualization component. A key design decision in NPAP is the explicit separation of the network reduction process into two stages: 1. Partitioning: A partitioning strategy maps each node in the original network to a node in the aggregated network. This step only determines group “membership”; it does not modify the graph itself. 2. Aggregation: An aggregation strategy reduces the network topology based on a given partitioning result (mapping) by aggregating nodes, edges, and their associated properties. This separation was identified early in the design process as a fundamental distinction. It gives users fine-grained control: they can swap partitioning algorithms independently of the aggregation method, apply different aggregation strategies to the same partitioning result, compose custom pipelines that combine strategies from different domains, or simply use any of them in isolation. The next section explains the software design in more detail. Software design Figure 2: NPAP general class diagram. A broad overview of NPAP’s design is shown in Figure 2 . The whole workflow is orchestrated and accessed by the PartitionAggregatorManager . NPAP follows a strategy pattern with four categories — data loading, partitioning, topology aggregation, and property aggregation — all orchestrated by three manager classes, shown at the bottom of the Figure. New strategies inherit from abstract base classes and register with their respective managers, enabling users to seamlessly add custom strategies without modifying core code. To reduce entry barriers for contributing to NPAP, the whole library is built on well-established Python packages, such as NetworkX ( [ ref-NetworkX ] ) for graph representation, NumPy ( [ ref-Harris2020 ] ), SciPy ( [ ref-Virtanen2020 ] ), and scikit-learn ( [ ref-scikit-learn ] ) for numerical computation, and Plotly ( [ ref-plotly ] ) for interactive map-based visualization of results. In the following sections, we introduce the loading and pre-processing of input data, partitioning, and the aggregation processes in more detail. Data loading and pre-processing As NPAP is designed to work with NetworkX graphs, they can be directly passed as input data, facilitating an easy integration into other frameworks or software. Besides, NPAP currently supports importing data from CSV files with two main strategies. The first one works with general node and edge data targeting generic graph structures. The second one is a domain-dependent strategy focused on power grids and includes buses, lines, transformers, converters, and DC links. User-specific data loading strategies can be registered straightforward as shown in Figure 2 . Afterward, optional pre-processing steps are carried out through the PartitionAggregatorManager , such as the aggregation of parallel edges. For power grids, voltage-level grouping separates the network into independent sub-graphs per voltage level, enabling voltage-aware partitioning strategies. Partitioning strategies NPAP currently provides four families of partitioning strategies combining geographical and electrical node distance with the option of partitioning voltage levels independently (voltage-awareness). Each family supports 13 different partitioning strategies, such as k-means ( [ ref-lloyd1982least ] ), k-medoids ( [ ref-schubert2021fast ] ), DBSCAN ( [ ref-ester1996density ] ), HDBSCAN ( [ ref-campello2013density ] ), and hierarchical clustering ( [ ref-ward1963hierarchical ] ). Geographical distance

Read the complete text