⚡ MCP-NetSim

Market Clearing Problem - Power Network Simulation

A professional research and engineering tool for electricity market optimization coupled with power network analysis

Features • Installation • Quick Start • Documentation • Contributing

---

📋 Table of Contents

• Overview
• Features
• Architecture
• Installation
• Quick Start
• Usage
• Project Structure
• Configuration
• Troubleshooting
• Documentation
• Contributing
• License

---

🎯 Overview

MCP-NetSim is a comprehensive simulation platform that solves the Market Clearing Problem (MCP) for electricity markets while ensuring physical feasibility of power network operations. The project implements an iterative coupling between economic optimization (PyPSA) and physical network analysis (pandapower) to deliver optimal and feasible solutions.

Key Problem Solved

Electricity market operators must:

• ✅ Minimize generation costs (economic optimization)
• ✅ Ensure physical feasibility (network constraints)
• ✅ Handle congestion (line capacity limits)
• ✅ Maintain voltage stability (voltage limits)
• ✅ Integrate renewables (variable generation)

MCP-NetSim solves this complex optimization problem automatically through an iterative algorithm that converges to an economically optimal and physically feasible solution.

Use Cases

• 🔬 Academic Research: Market design, congestion management, renewable integration
• 🏭 Industrial Applications: Production planning, network analysis, contingency studies
• 📚 Education: Teaching electricity markets and power system optimization
• 🔍 Analysis: Scenario evaluation, sensitivity analysis, policy impact studies

---

✨ Features

Core Capabilities

• 🔌 Network Modeling: AC power flow analysis with pandapower
• 💰 Market Optimization: Economic dispatch with PyPSA (Market Clearing Problem)
• 🔄 Iterative Coupling: Automatic convergence to optimal and feasible solutions
• 🌱 Renewable Integration: Wind and solar generation with variable profiles
• 🔋 Storage Modeling: Battery storage with charge/discharge constraints
• 📊 Multiple Scenarios: Normal, congestion, renewables, N-1 contingency
• 📈 Interactive Visualization: Real-time plots with Plotly
• 🌐 Web Interface: Modern Streamlit dashboard
• 💾 Results Export: CSV and Excel export with structured data

Advanced Features

• Multi-timestep Simulation: Hourly or 15-minute resolution
• LMP Calculation: Locational Marginal Prices per bus
• Congestion Detection: Automatic identification of overloaded lines
• Voltage Monitoring: Real-time voltage violation detection
• Scenario Management: Easy switching between test cases
• Configuration Management: YAML-based centralized configuration
• Structured Logging: JSON-formatted logs for analysis
• Unit Testing: Comprehensive test suite with pytest

---

🏗️ Architecture

System Architecture

┌───────────────────────────────────────────────────┐
│                    MCP-NetSim Platform            │        
├───────────────────────────────────────────────────│
│                                                   │          
│  ┌──────────────┐         ┌──────────────┐        │         
│  │   Economic   │         │   Physical   │        │ 
│  │ Optimization │◄───────►│   Network    │        │         
│  │   (PyPSA)    │Iterative│   Analysis   │        │          
│  │              │Coupling │ (pandapower) │        │          
│  └──────────────┘         └──────────────┘        │          
│         │                        │                │       
│         └──────────┬─────────────┘                │          
│                    │                              │        
│              ┌─────▼─────┐                        │          
│              │  Results  │                        │          
│              │  Export   │                        │          
│              └───────────┘                        │          
│                                                   │          
└───────────────────────────────────────────────────┘

Technology Stack

Component	Technology	Purpose
Optimization	PyPSA	Market clearing problem solver
Network Analysis	pandapower	AC power flow calculations
Visualization	Plotly	Interactive charts and graphs
Web Interface	Streamlit	Modern dashboard UI
Data Processing	Pandas, NumPy	Data manipulation and analysis
Configuration	YAML	Centralized settings
Testing	pytest	Unit and integration tests
Logging	Python logging	Structured JSON logs

---

📦 Installation

Prerequisites

• Python: 3.8 or higher
• Operating System: macOS, Linux, or Windows (with WSL)
• Package Manager: pip (Python package installer)

Step 1: Clone the Repository

git clone https://github.com/yourusername/MCP-NetSim.git
cd MCP-NetSim

Step 2: Install Python Dependencies

# Install all required packages
pip install -r requirements.txt

# Or with trusted hosts (if SSL issues)
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org -r requirements.txt

Step 3: Install Optimization Solver (REQUIRED)

MCP-NetSim requires an optimization solver for PyPSA to work.

macOS

brew install cbc

Linux (Ubuntu/Debian)

sudo apt-get update
sudo apt-get install coinor-cbc

Linux (Fedora/RHEL)

sudo dnf install coin-or-Cbc

Windows (with WSL)

# In WSL Ubuntu
sudo apt-get update
sudo apt-get install coinor-cbc

Step 4: Verify Installation

# Test Python imports
python3 -c "import pypsa, pandapower; print('✓ All imports successful')"

# Test solver availability
python3 -c "
import pypsa
n = pypsa.Network()
n.set_snapshots([0])
n.add('Bus', 'bus1', v_nom=110)
n.add('Generator', 'gen1', bus='bus1', p_nom=100, marginal_cost=30)
n.add('Load', 'load1', bus='bus1', p_set=50)
n.optimize()
print('✓ Solver works!')
"

---

🚀 Quick Start

Option 1: Web Interface (Recommended)

1. Launch the web interface:

   python3 -m streamlit run app.py

2. Open your browser:

   • The interface will automatically open at http://localhost:8501
   • If not, navigate manually to the URL shown in the terminal

3. Run a simulation:

   • Select a scenario from the sidebar (e.g., "Normal")
   • Click "🚀 Run Simulation"
   • View results in the interactive tabs

Option 2: Command Line Interface

# Run normal scenario
python3 main.py --scenario normal

# Run with verbose output
python3 main.py --scenario normal --verbose

# Run multi-timestep simulation (24 hours)
python3 main.py --scenario normal --multi-timestep --hours 24

Option 3: Programmatic Usage

from src.data.network_data import NetworkDataGenerator
from src.network.network_model import NetworkModel
from src.market.market_model import MarketModel
from src.coupling.coupling_logic import CouplingLogic

# Create network data
generator = NetworkDataGenerator()
network_data = generator.create_ieee_14_bus_network()

# Initialize models
network_model = NetworkModel(network_data)
market_model = MarketModel(network_data)
coupling_logic = CouplingLogic(network_model, market_model)

# Solve coupled problem
results = coupling_logic.solve_coupled_problem(verbose=True)

# Access results
print(f"Converged: {results['converged']}")
print(f"Total Cost: {results['total_cost']:.2f} €")
print(f"Generation: {results['generation_schedule']}")
print(f"LMPs: {results['lmps']}")

---

📖 Usage

Available Scenarios

Scenario	Description	Use Case
Normal	Standard network operation	Baseline analysis
Congestion	High demand scenario	Congestion management
Renewables	High renewable penetration	Renewable integration
N-1 Outage	Line contingency analysis	Security assessment

Web Interface Features

• 📊 Real-time Visualization: Interactive charts for prices, generation, loading, and voltage
• 💾 Export Results: Download results as CSV or Excel files
• ⚙️ Configuration: Adjust simulation parameters via sidebar
• 📈 Multiple Views: Switch between different visualization tabs

Command Line Options

python3 main.py [OPTIONS]

Options:
  --scenario SCENARIO     Scenario to run (normal, congestion, renewable_heavy, n1_outage)
  --verbose               Enable verbose output
  --multi-timestep        Enable multi-timestep simulation
  --hours HOURS           Number of hours for multi-timestep (default: 24)
  --output-dir DIR        Output directory for results (default: results/)

---

📁 Project Structure

MCP-NetSim/
├── src/                          # Source code
│   ├── data/                    # Network data generation
│   │   └── network_data.py      # IEEE 14-bus and custom networks
│   ├── network/                 # Network modeling
│   │   └── network_model.py     # pandapower integration
│   ├── market/                  # Market optimization
│   │   └── market_model.py      # PyPSA MCP solver
│   ├── coupling/                # Coupling logic
│   │   └── coupling_logic.py    # Iterative algorithm
│   ├── renewables/              # Renewable integration
│   │   ├── renewable_integration.py
│   │   └── storage_model.py
│   ├── scenarios/               # Scenario management
│   │   └── scenario_manager.py
│   ├── visualization/           # Plotting functions
│   │   └── visualizer.py
│   ├── results/                 # Results export
│   │   └── results_export.py
│   └── utils/                   # Utilities
│       ├── config_loader.py     # Configuration management
│       ├── logger.py            # Structured logging
│       └── exceptions.py        # Custom exceptions
├── config/                      # Configuration files
│   └── config.yaml             # Centralized configuration
├── tests/                       # Test suite
│   ├── test_network_model.py
│   ├── test_market_model.py
│   └── conftest.py
├── results/                     # Output directory
│   └── data/                    # Exported results
├── logs/                        # Log files
├── app.py                       # Streamlit web interface
├── main.py                      # CLI entry point
├── requirements.txt             # Python dependencies
├── pytest.ini                   # pytest configuration
├── presentation.html            # Project presentation
└── README.md                    # This file

---

⚙️ Configuration

Configuration is managed through config/config.yaml. Key sections:

Network Configuration

network:
  base_voltage_kv: 110.0
  voltage_min_pu: 0.95
  voltage_max_pu: 1.05

Market Configuration

market:
  solver: cbc  # or glpk
  tolerance: 1e-6

Coupling Configuration

coupling:
  max_iterations: 20
  convergence_tolerance: 1e-3
  congestion_threshold: 90.0  # Percentage

Logging Configuration

logging:
  level: INFO
  format: json
  file: logs/mcpsim.log

---

🔧 Troubleshooting

Problem: Simulation Not Converging (0 MW Generation)

Symptoms:

• Convergence: ✗ No
• Total Generation: 0.00 MW
• Total Cost: 0.00 €

Solution: This usually means PyPSA solver is not installed. Install CBC:

# macOS
brew install cbc

# Linux
sudo apt-get install coinor-cbc

Then restart the application.

Problem: "No module named 'pypsa'"

Solution:

pip install pypsa

Problem: "No module named 'pandapower'"

Solution:

pip install pandapower

Problem: Power Flow Not Converging

Possible Causes:

• Network data issues
• Voltage setpoints out of range
• Line parameters invalid

Solution:

• Check network data validity
• Verify voltages are between 0.9-1.1 pu
• Review line resistance/reactance values

Problem: Market Optimization Fails

Possible Causes:

• Solver not installed
• Generation capacity < Load
• Invalid generator costs

Solution:

• Verify solver installation (see above)
• Check that total generation capacity ≥ total load
• Ensure all generator costs are positive

Getting Help

• Check the error message in the web interface (red box)
• Enable verbose mode: python3 main.py --scenario normal --verbose
• Review logs in logs/mcpsim.log
• See presentation.html for detailed project explanation

---

📚 Documentation

Documentation Files

• presentation.html: Complete project presentation (open in browser)
• README.md: This file - main documentation
• config/config.yaml: Configuration reference
• Code comments: Inline documentation in source files

Key Concepts

Market Clearing Problem (MCP)

The MCP minimizes total generation cost subject to:

• Power balance: Σ P_gen = Σ P_load
• Generator limits: P_min ≤ P ≤ P_max
• Network constraints: Line limits, voltage bounds

Locational Marginal Prices (LMPs)

LMPs represent the marginal cost of electricity at each bus, accounting for:

• Generation costs
• Transmission congestion
• Losses

Iterative Coupling

The algorithm iteratively:

1. Optimizes economically (PyPSA)
2. Verifies physically (pandapower)
3. Adjusts constraints if violations detected
4. Repeats until convergence

---

🧪 Testing

Run Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test file
pytest tests/test_network_model.py -v

Test Coverage

Current test coverage targets:

• Network model: AC power flow calculations
• Market model: Optimization solver integration
• Coupling logic: Convergence algorithm

---

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes with tests
4. Run tests: pytest
5. Commit changes: git commit -m 'Add amazing feature'
6. Push to branch: git push origin feature/amazing-feature
7. Open a Pull Request

Code Style

• Follow PEP 8 Python style guide
• Use type hints for function signatures
• Add docstrings to all functions and classes
• Write unit tests for new features

---

📊 Results Interpretation

Key Metrics

Metric	Description	Normal Range
Convergence	Algorithm converged successfully	✓ Yes
Iterations	Number of iterations needed	1-5
Total Cost	Total generation cost	Scenario-dependent
LMPs	Locational Marginal Prices	20-50 €/MWh
Congested Lines	Lines loaded >90%	0 (ideal)
Voltage Violations	Buses outside limits	0 (ideal)

Understanding Results

• LMP Maps: Show price differences due to congestion
• Generation Schedules: Optimal dispatch per generator
• Line Loading: Identify bottlenecks in the network
• Voltage Profiles: Ensure system stability

---

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• PyPSA: Python for Power System Analysis
• pandapower: An easy-to-use power system analysis tool
• Streamlit: For the web interface framework
• Plotly: For interactive visualizations

---

📧 Contact & Support

• Email: zaksab98@gmail.com

---

Made with ⚡ for power system research and engineering

⬆ Back to Top