Metadata-Version: 2.1
Name: network-visualization
Version: 1.0.1
Summary: Tools for visualizing and analyzing electrical grid network topology
Home-page: https://gitlab.com/yourusername/network_visualization
Author: Ricardo Energy Model Team
Author-email: Ricardo Energy Model Team <your.email@example.com>
License: MIT
Project-URL: Homepage, https://gitlab.com/yourusername/network_visualization
Project-URL: Documentation, https://gitlab.com/yourusername/network_visualization/-/blob/main/README.md
Project-URL: Repository, https://gitlab.com/yourusername/network_visualization.git
Project-URL: Issues, https://gitlab.com/yourusername/network_visualization/-/issues
Keywords: network,visualization,graph,energy,electrical-grid
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: networkx>=3.1
Requires-Dist: plotly>=5.14.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: geopy>=2.3.0
Requires-Dist: kaleido>=0.2.1

# Network Visualization

[![PyPI](https://img.shields.io/badge/PyPI-v1.0.1-blue)](https://pypi.org/project/network-visualization/)
[![Python](https://img.shields.io/badge/Python-3.8%2B-brightgreen)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-MIT-orange)](LICENSE)

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

```bash
# From PyPI
pip install network-visualization

# From source
pip install -e .
```

### Basic Usage

```python
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:**
```python
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:
```python
{
    '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:
```python
{
    '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
```yaml
locations:
  region1:
    coordinates: {lat: 40, lon: -2}
    techs: {ccgt:, demand_power:}
```

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

### Shared Technologies
```yaml
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

```bash
# 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](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
