network-visualization 1.0.1

Tools for visualizing and analyzing electrical grid network topology

Network Visualization

Interactive visualization and analysis tools for Calliope energy system models. Extract and visualize network topology with a single line of code.

✨ Features

• Universal Data Extraction: Handles ANY Calliope naming structure and format
• One-Line Visualization: Create interactive HTML visualizations instantly
• Connectivity Analysis: Identify isolated nodes and network components
• Flexible Format Support: Works with any coordinate system (lat/lon, x/y, custom)
• Smart Type Detection: Automatically classifies generation, demand, and transmission nodes

🚀 Quick Start

Installation

# From PyPI
pip install network-visualization

# From source
pip install -e .

Basic Usage

import network_visualization as nv

# Visualize your network
nv.plot_network("path/to/calliope/model")

# Analyze connectivity
analysis = nv.analyze_network("path/to/calliope/model")
print(f"Components: {analysis['num_components']}")
print(f"Isolated nodes: {len(analysis['isolated_nodes'])}")

# Find isolated nodes with demand
isolated = nv.find_isolated_nodes("path/to/model")
print(f"Isolated with demand: {isolated['isolated_with_demand']}")

# Get connection suggestions
suggestions = nv.suggest_connections("path/to/model", max_distance_km=50)

# Quick visualization (fastest)
nv.quick_viz("path/to/model")

📖 API Reference

plot_network(model_path, output_file, auto_open, title)

Create an interactive network visualization.

Parameters:

• model_path (str): Path to Calliope model directory
• output_file (str, optional): Output HTML filename. Default: "network_visualization.html"
• auto_open (bool, optional): Auto-open in browser. Default: True
• title (str, optional): Visualization title. Default: "Energy Network Visualization"

Returns: Path to generated HTML file

Example:

nv.plot_network(
    model_path="models/my_model",
    output_file="my_network.html",
    auto_open=False,
    title="My Energy Network"
)

---

analyze_network(model_path, save_report, output_dir)

Analyze network connectivity and identify issues.

Parameters:

• model_path (str): Path to Calliope model directory
• save_report (bool, optional): Save text report to file. Default: False
• output_dir (str, optional): Report output directory. Default: "outputs/reports"

Returns: Dictionary with analysis results:

{
    'num_components': int,         # Number of connected components
    'isolated_nodes': list,        # List of isolated node names
    'demand_isolated': set,        # Demand substations that are isolated
    'is_fully_connected': bool,    # Whether network is fully connected
    'total_nodes': int,            # Total nodes in graph
    'total_edges': int,            # Total edges in graph
    'components': list             # List of component sets
}

---

find_isolated_nodes(model_path)

Find all isolated nodes in the network.

Returns: Dictionary with isolated node lists:

{
    'all_isolated': list,          # All isolated nodes
    'isolated_with_demand': list   # Isolated nodes with demand
}

---

suggest_connections(model_path, max_distance_km, top_n)

Get smart connection suggestions based on proximity.

Parameters:

• model_path (str): Path to Calliope model directory
• max_distance_km (float, optional): Maximum connection distance. Default: 100
• top_n (int, optional): Number of suggestions to return. Default: 10

Returns: List of suggested connections with distances

---

quick_viz(model_path)

Fastest way to visualize - one function call with all defaults.

---

🎯 Calliope Format Support

This package handles any Calliope model structure:

Standard Format

locations:
  region1:
    coordinates: {lat: 40, lon: -2}
    techs: {ccgt:, demand_power:}

Split Coordinates

locations:
  region1-1.coordinates:  # or region1:coords, region1_position, etc.
    lat: 41
    lon: -2

Shared Technologies

locations:
  "region1-1, region1-2, region1-3":  # or region1-1|region1-2|region1-3
    techs: {csp:}

Any Coordinate System

• Geographic: lat/lon, latitude/longitude
• Cartesian: x/y
• Custom: Any numeric coordinate pairs

Flexible Naming

No restrictions on naming patterns:

• Delimiters: ., :, _, -, |, ,
• Suffixes: coordinates, coords, position, latlon, etc.
• Patterns: Any naming convention (regions, nodes, stations, areas, etc.)

The parser automatically detects and handles all patterns!

📊 Example Output

Visualization

Interactive HTML with:

• Color-coded nodes (generation, demand, transmission)
• Hover info showing technologies
• Zoom and pan navigation
• Network statistics overlay

Analysis Report

================================================================================
NETWORK ANALYSIS REPORT
================================================================================

1. NETWORK SUMMARY
   Total Locations: 9
     - Power Plants: 5
     - Substations with Demand: 0
     - Transmission Nodes: 1

   Total Connections: 9
     - Power Links: 2
     - Transmission Links: 7

2. CONNECTIVITY ANALYSIS
   Connected Components: 1
   [OK] Network is fully connected
   [OK] No isolated nodes

3. DEMAND SUBSTATIONS STATUS
   [OK] All demand substations are connected
================================================================================

📁 Project Structure

network_visualization/
├── network_visualization.py    # Main API module
├── setup.py                    # Package configuration
├── requirements.txt            # Dependencies
├── README.md                   # This file
│
├── utils/                      # Core utilities
│   ├── load_data.py           # Universal data loader
│   ├── graph_builder.py       # Network graph construction
│   ├── geo_utils.py           # Geographic calculations
│   └── report_generator.py    # Report generation
│
├── scripts/                    # Command-line tools
│   ├── visualize_network.py
│   ├── analyze_isolated.py
│   └── suggest_connections.py
│
└── examples/                   # Usage examples
    └── basic_visualization.py

🛠️ Requirements

• Python 3.8+
• Dependencies: networkx, plotly, pyyaml, pandas, numpy, geopy

📝 Development

# Clone repository
git clone <repository-url>
cd network_visualization

# Install in development mode
pip install -e .

# Run tests
python -m pytest tests/

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/improvement)
3. Commit changes (git commit -m 'Add improvement')
4. Push to branch (git push origin feature/improvement)
5. Open a Pull Request

📄 License

MIT License - see LICENSE file for details.

🔗 Links

• PyPI: https://pypi.org/project/network-visualization/
• GitLab: https://mygit.th-deg.de/thd-spatial-ai/example_models/calliope_plots
• Calliope: https://calliope.readthedocs.io/

🙏 Acknowledgments

Built for Calliope energy system modeling framework. Supports any Calliope model structure with universal data extraction.

---

Version: 1.0.1 | Updated: November 2025