User Guide#

Welcome to the NPAP User Guide! 🚀

This guide covers everything you need to know to use NPAP for network partitioning and aggregation.

Getting Started#

New to NPAP? Start here to get up and running.

Installation

Install NPAP from PyPI or source, including development dependencies.

Installation
Quick Start

A runnable end-to-end example on the real European grid, plus the notebooks.

Quick Start
Available Strategies

Overview of all strategies, key classes, and the strategy pattern architecture.

Available Strategies

Architecture#

Deep dive into each component of the NPAP workflow.

Data Loading

Load networks from CSV files, NetworkX graphs, or voltage-aware power system formats.

Data Loading
Partitioning

Geographical, electrical, and voltage-aware partitioning strategies.

Partitioning
Aggregation

Three-tier aggregation system with topology, physical, and statistical strategies.

Aggregation
Visualization

Interactive Plotly maps with customizable styling.

Visualization

Data Flow Overview#

        flowchart LR
    A[Load Data] --> B[Aggregate Parallel Edges]
    B --> C[Group by Voltage]
    C --> D[Partition]
    D --> E[Aggregate]
    E --> F[Visualize]

    style A fill:#2993B5,stroke:#1d6f8a,color:#fff
    style B fill:#0fad6b,stroke:#076b3f,stroke-dasharray: 5 5,color:#fff
    style C fill:#0fad6b,stroke:#076b3f,stroke-dasharray: 5 5,color:#fff
    style D fill:#2993B5,stroke:#1d6f8a,color:#fff
    style E fill:#2993B5,stroke:#1d6f8a,color:#fff
    style F fill:#2993B5,stroke:#1d6f8a,color:#fff

Dashed boxes indicate optional steps

Working with Graphs#

Graph Types#

NPAP works with NetworkX directed graphs:

  • DiGraph: Simple directed graph (one edge per node pair)

  • MultiDiGraph: Directed graph with parallel edges

import networkx as nx

# Simple directed graph
G = nx.DiGraph()

# Multi-edge directed graph (for parallel lines)
G = nx.MultiDiGraph()

Required Attributes#

Different strategies require specific node and edge attributes:

Strategy Type

Node Attributes

Edge Attributes

Geographical

lat, lon

—

Electrical

ac_island

x (reactance)

Voltage-Aware

lat, lon, voltage, ac_island

x, type

Error Handling#

NPAP provides a comprehensive exception hierarchy:

from npap import (
    NPAPError,  # Base exception
    DataLoadingError,  # Input/loading issues
    PartitioningError,  # Partitioning failures
    AggregationError,  # Aggregation issues
    ValidationError,  # Input validation
    GraphCompatibilityError,  # Partition/graph mismatch
)

try:
    result = manager.partition("unknown_strategy", n_clusters=5)
except PartitioningError as e:
    print(f"Partitioning failed: {e}")
except NPAPError as e:
    print(f"NPAP error: {e}")

Logging#

Configure logging to monitor NPAP operations:

import logging

from npap import configure_logging, disable_logging

# Enable debug logging
configure_logging(level=logging.DEBUG)

# Or disable all logging
disable_logging()

Log categories include: INPUT, PARTITIONING, AGGREGATION, VISUALIZATION, VALIDATION, MANAGER.

On this page