PyPSA Explorer
Interactive dashboard for visualizing and analyzing PyPSA energy system networks. Built with Dash and Plotly, PyPSA Explorer provides a comprehensive web interface for exploring energy system models with powerful filtering and visualization capabilities.
Features
📊 Interactive Visualizations
- Energy Balance Analysis: Timeseries and aggregated views of energy flows
- Capacity Planning: Visualize optimal capacity distribution by carrier and region
- Economic Analysis: CAPEX and OPEX breakdowns across the system
- Network Maps: Interactive geographical visualization of network topology
- Multi-Network Support: Load and compare multiple networks seamlessly
🎯 Advanced Filtering
- Filter by energy carrier (sector)
- Filter by country/region
- Dynamic updates across all visualizations
- Tab-specific filter behavior
🚀 Production Ready
- Well-structured, modular codebase
- Comprehensive type hints
- Extensive test coverage
- CI/CD pipeline integration
- Professional documentation
Installation
From PyPI (Recommended)
pip install pypsa-explorer
From Source
git clone https://github.com/openenergytransition/pypsa-explorer.git
cd pypsa-explorer
pip install -e .
Development Installation
git clone https://github.com/openenergytransition/pypsa-explorer.git
cd pypsa-explorer
pip install -e ".[dev]"
pre-commit install
Quick Start
Command Line Interface
Launch the landing page and drag-and-drop networks or load the bundled example:
pypsa-explorer
Run with your own network:
pypsa-explorer /path/to/network.nc
Run with multiple networks:
pypsa-explorer /path/to/network1.nc:Label1 /path/to/network2.nc:Label2
Custom host and port:
pypsa-explorer --host 0.0.0.0 --port 8080
Production mode (no debug):
pypsa-explorer --no-debug
Python API
from pypsa_explorer import run_dashboard
# Run with default network
run_dashboard()
# Run with custom network
run_dashboard("/path/to/network.nc")
# Run with multiple networks
networks = {
"Scenario A": "/path/to/network1.nc",
"Scenario B": "/path/to/network2.nc",
}
run_dashboard(networks, debug=True, host="0.0.0.0", port=8050)
# Run with Network objects
import pypsa
n1 = pypsa.Network("network1.nc")
n2 = pypsa.Network("network2.nc")
run_dashboard({"Network 1": n1, "Network 2": n2})
Programmatic App Creation
from pypsa_explorer import create_app
# Create app instance
app = create_app(networks_input="/path/to/network.nc", title="My Dashboard")
# Run with custom server
app.run(debug=True, host="0.0.0.0", port=8050)
Project Structure
pypsa-explorer/
├── src/
│ └── pypsa_explorer/
│ ├── __init__.py # Package initialization
│ ├── app.py # Main application factory
│ ├── cli.py # Command-line interface
│ ├── config.py # Configuration and theming
│ ├── callbacks/ # Dash callbacks
│ │ ├── __init__.py
│ │ ├── filters.py # Filter callbacks
│ │ ├── navigation.py # Navigation callbacks
│ │ ├── network.py # Network callbacks
│ │ └── visualizations.py # Visualization callbacks
│ ├── layouts/ # UI layouts
│ │ ├── __init__.py
│ │ ├── components.py # Reusable components
│ │ ├── dashboard.py # Main dashboard layout
│ │ ├── tabs.py # Tab definitions
│ │ └── welcome.py # Welcome page
│ └── utils/ # Utility functions
│ ├── __init__.py
│ ├── helpers.py # Helper functions
│ └── network_loader.py # Network loading utilities
├── tests/ # Test suite
├── docs/ # Documentation
├── examples/ # Example notebooks and scripts
├── pyproject.toml # Project configuration
├── README.md # This file
├── LICENSE # MIT License
└── CHANGELOG.md # Version history
Development
Setup Development Environment
# Clone repository
git clone https://github.com/openenergytransition/pypsa-explorer.git
cd pypsa-explorer
# Install with dev dependencies
pip install -e ".[dev]"
# Install pre-commit hooks
pre-commit install
Running Tests
# Run all tests
pytest
# Run with coverage
pytest --cov=pypsa_explorer --cov-report=html
# Run specific test file
pytest tests/test_app.py
Code Quality
# Format code
black src/ tests/
ruff format src/ tests/
# Lint code
ruff check src/ tests/ --fix
# Type checking
mypy src/
Building Documentation
cd docs
make html
Configuration
Custom Styling
The dashboard theme can be customized by modifying src/pypsa_explorer/config.py:
COLORS = {
"primary": "#2c3e50",
"secondary": "#3498db",
"accent": "#2ecc71",
# ... more colors
}
Default Settings
- Port: 8050
- Host: 127.0.0.1 (localhost)
- Debug Mode: True (disable with
--no-debug) - Default Carriers: AC, Hydrogen Storage, Low Voltage
Requirements
- Python >= 3.12
- PyPSA (from GitHub master)
- Dash >= 2.14
- Plotly >= 5.0
- Folium >= 0.14
- dash-bootstrap-components >= 1.5
See pyproject.toml for complete dependency list.
Contributing
Contributions are welcome! Please follow these steps:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Make your changes
- Run tests and linting (
pytest && ruff check) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Please ensure:
- All tests pass
- Code is properly formatted (black/ruff)
- Type hints are included
- Documentation is updated
License
This project is licensed under the MIT License - see the LICENSE file for details.
Citation
If you use PyPSA Explorer in your research, please cite:
@software{pypsa_explorer,
title = {PyPSA Explorer: Interactive Dashboard for Energy System Analysis},
author = {Open Energy Transition},
year = {2024},
url = {https://github.com/openenergytransition/pypsa-explorer}
}
Acknowledgments
- Built on PyPSA - Python for Power System Analysis
- Powered by Dash and Plotly
- Developed by Open Energy Transition
Support
- Documentation: https://pypsa-explorer.readthedocs.io
- Issues: GitHub Issues
- Discussions: GitHub Discussions
Roadmap
- Export functionality (PNG, PDF, data export)
- Advanced comparison mode for multiple networks
- Custom calculation and plotting plugins
- Real-time data streaming support
- Collaborative features and sharing
- Integration with cloud storage (S3, GCS)
Related Projects
- PyPSA - The core power system analysis framework
- PyPSA-Eur - Open energy system model for Europe
- PyPSA-Earth - Global energy system model
Metadata
Release files for pypsa-explorer 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pypsa_explorer-0.1.2.tar.gz | 56.8 kB | Without provenance | Details for pypsa_explorer-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pypsa_explorer-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for pypsa_explorer-0.1.2-py3-none-any.whl |
Total release size: 103.9 kB
Release files / pypsa_explorer-0.1.2.tar.gz
| Download URL | pypsa_explorer-0.1.2.tar.gz |
|---|---|
| Size | 56.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a387f73f53c07c49f0c2edceddcfd6ac599549487c6f8e69bfffbf7f2d2daf5f
|
|
BLAKE2b-256 checksum How to use checksums |
d61ad0d4a6804983179aa94de1387703fdd4c6539b34d2d37423e3a9f0484f04
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Release files / pypsa_explorer-0.1.2-py3-none-any.whl
| Download URL | pypsa_explorer-0.1.2-py3-none-any.whl |
|---|---|
| Size | 47.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
b68f9fec0e3643b9cbb39348a29108ddf62e4a4321726f96f0ac19b6ddff65db
|
|
BLAKE2b-256 checksum How to use checksums |
7eab040cba95dfb9516bd981069a5715f7e621837ebfeb3c2cfb11dadf38d222
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.14
|
Security for pypsa-explorer 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.