npap 1.1.0

NPAP is an open-source Python library for partitioning and aggregating network graphs, with a special focus on electrical power systems. Built on top of NetworkX, it provides a clean strategy-based architecture that makes it easy to cluster networks and reduce their complexity while preserving essential properties.

Whether you're working with power grids, transportation networks, or any graph-based spatial data, NPAP helps you simplify complex networks into manageable pieces.

[!NOTE] Project contributors from IEE (Institute of Electricity Economics and Energy Innovation) at the Technical University of Graz are supported by the Research Center Energetic and funded by the European Union (ERC, NetZero-Opt, 101116212).

Documentation

For comprehensive guides, API reference, and tutorials, visit the official documentation:

https://npap.readthedocs.io

Features

• Multiple Partitioning Algorithms - K-means, K-medoids, DBSCAN, HDBSCAN, and hierarchical clustering
• Distance Metrics - Euclidean for local coordinates, Haversine for geographic data
• Electrical Distance - Partition based on PTDF-derived electrical proximity
• Voltage-Aware Clustering - Respects voltage levels and transformer boundaries
• Flexible Aggregation - Sum, average, or custom strategies for node/edge properties
• Extensible Design - Easy to add your own partitioning or aggregation strategies

Installation

pip install npap

Quick Start

from npap import PartitionAggregatorManager, AggregationProfile, AggregationMode

# 1. Initialize the manager
manager = PartitionAggregatorManager()

# 2. Load data (voltage-aware loader for power systems)
manager.load_data(
    strategy="va_loader",
    node_file="buses.csv",
    line_file="lines.csv",
    transformer_file="transformers.csv",
    converter_file="converters.csv",
    link_file="dc_links.csv",
)

# 3. Aggregate parallel edges (optional)
manager.aggregate_parallel_edges(
    edge_properties={"x": "equivalent_reactance", "type": "first"}, default_strategy="average"
)

# 4. Partition the network
manager.partition(strategy="electrical_kmedoids", n_clusters=50)

# 5. Visualize the partitioned network
manager.plot_network(style="clustered", title="Partitioned Network")

# 6. Aggregate with a custom profile
profile = AggregationProfile(
    mode=AggregationMode.GEOGRAPHICAL,
    topology_strategy="simple",
    node_properties={"lat": "average", "lon": "average", "voltage": "average"},
    edge_properties={"p_max": "sum", "x": "equivalent_reactance"},
    default_node_strategy="average",
    default_edge_strategy="average",
)
aggregated_network = manager.aggregate(profile=profile)

# 7. Visualize the reduced network
manager.plot_network(style="simple", title="Aggregated Network")

Contributing

We warmly welcome contributions from everyone! Whether it's fixing a typo, improving documentation, reporting bugs, or implementing new features — every contribution matters.

Please read our Contributing Guide to get started, or visit the full Contributing Documentation for detailed guidelines.

Reporting Issues and Asking Questions

Found a bug, want to request a feature, or have a question about using NPAP? Open an issue — the template picker will guide you to the right form. Please search the existing issues first, in case it has already been reported.

License

NPAP is released under the MIT License.

Acknowledgements

Funded by the European Union (ERC, NetZero-Opt, 101116212). Views and opinions expressed are however those of the author(s) only and do not necessarily reflect those of the European Union or the European Research Council. Neither the European Union nor the granting authority can be held responsible for them.

Built with care for the open-source community 🫰