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

Complete workflow example using a voltage-aware power network.

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:

from npap.logging import configure_logging, LogCategory
import logging

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

# Or disable all logging
from npap.logging import disable_logging
disable_logging()

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

On this page