The Pythonic Framework for Energy Scenario Comparison & Analysis

MESQUAL — Modular Energy Scenario Comparison Library for Quantitative and Qualitative Analysis

Fully Modular Platform-Independent Built to Extend

Compare, visualize, and analyze simulation results and market data across any energy modeling platform.

Try now in Colab
① Setup StudyManager Feed it with scenarios from any platform interface
② Analyze with MESQUAL Same API and modules across all platforms — only the setup flags change

Modules and Data Classes

MESQUAL gives you atomic building blocks that enable you to build up intuitive representations of real-world energy assets with expressive notation.

StudyManager

StudyManager
.scen .comp
.scen_comp

Central orchestrator with three-tier DatasetCollection access: scenarios, comparisons, and unified views.

View code Docs

Datasets & Interpreters

PlatformDataset DatasetMergeCollection DatasetConcatCollection

"Everything is a Dataset" — unified .fetch(flag) interface with pluggable, platform-agnostic interpreters.

View code Docs

Energy Data Handling

AreaBorderGeometryCalculator BorderFlowCalculator TradeBalanceCalculator

Energy-domain utilities for border visualizations, area accounting, trade balances, model mixing and much more.

View code Docs

Time Series Dashboards

TimeSeriesDashboardGenerator HTMLDashboard

Build faceted heatmap and line dashboards from MultiIndex DataFrames using Plotly.

View code Docs

Folium Viz System

AreaGenerator PropertyMapper FeatureResolver ...

Create rich, interactive geospatial maps with KPI-driven styling and animated flows.

View code Docs

KPI Framework

FlagAggKPIBuilder KPICollection Aggregations

Fluent builder API for defining, computing, and filtering KPIs across scenarios.

View code Docs

And so many more

Utilities, custom aggregations, color systems, plotting helpers, data export tools, and a growing ecosystem of platform adapters.

Explore the full API

Make It Yours

MESQUAL's layered architecture lets you leverage the full generic framework while freely adding study-specific logic — custom data sources, variables, KPIs, and visual themes.

Your Study

Study-specific datasources, custom interpreters, variables, KPIs, color themes, merging fragmented simulations — anything specific to your analysis

CustomRESShareInterpreter CustomExternalEntsoePriceData MyStudySpecificFoliumMap ...
Platform Interface

Connect your modeling tool — or build your own adapter in a few lines

mesqual-pypsa mesqual-plexos mesqual-???
MESQUAL Core

Platform-agnostic foundation — StudyManager, KPIs, Visualizations, Utilities

mesqual
.fetch(flag)
Same API
across all layers
Same modules
across all layers
Same framework
for any study

Extend anything with a few lines of Python

Custom Data Sources

Import external data alongside simulation results — ENTSO-E market data, weather feeds, or any DataFrame that is not included in the output of your simulation platform.

class EntsoeHistPriceInterpreter(Interpreter):
    accepted_flags = {'BZ.ETP.hist_price'}

    def _fetch(self, flag, config):
        parent = self.parent_dataset
        idx = parent.fetch('BZ.Results.market_price').index
        return load_historic_entsoe_data(idx)

# study.scen.fetch('BZ.ETP.hist_price')  # now works!

Custom Variables

Every study has unique formulas — compute RES shares, curtailment rates, or any derived metric your way.

class RESCurtailment(Interpreter):
    accepted_flags = {'countries_t.res_curtailment'}

    def _fetch(self, flag, config):
        parent = self.parent_dataset
        gen = parent.fetch('countries_t.res_gen')
        avail = parent.fetch('generators_t.availability')
        return avail - gen

# study.scen.fetch('countries_t.res_curtailment')  # now works!

Auto-Generate Border Models

Detect area borders from granular topology — hundreds of individual transmission lines get grouped into clean border objects between countries or bidding zones.

# 500+ branches across 30 countries? No problem.
gen = AreaBorderModelGenerator(
    nodes, branches,
    area_column='country',
    node_from_col='bus0',
    node_to_col='bus1',
)
borders = gen.generate_area_border_model()
# → DataFrame: DE-FR, DE-PL, FR-ES, ...
# with direction, opposite_border, sorted_border
# and per-border branch membership

Auto-Compute Border Geometry

Borders know their area pairs, but need positions for visualization. Auto-compute line paths, midpoints, and angles from area geometries — ready for animated flow arrows.

# Borders exist but have no spatial information yet
geo_calc = AreaBorderGeometryCalculator(countries_gdf)
borders = gen.enhance_with_geometry(borders, geo_calc)

# Each border now carries:
#   projection_point  → optimal arrow/label placement
#   azimuth_angle     → directional angle for flow arrows
#   geo_line_string   → LineString connecting the areas
#   is_physical       → True if areas share a boundary

# Plug directly into folviz.ArrowIconGenerator!

Geo-Enrich Your Model

Extend simulation models with external data — here, an existing country model gets extended with GeoJSON geometries for map visualizations.

class CountriesInterpreter(PyPSAInterpreter):
    accepted_flags = {'countries'}

    def _fetch(self, flag, config):
        countries = self.parent_dataset.fetch('countries')
        gdf = gpd.GeoDataFrame(
            countries,
            geometry=[get_geo(c) for c in countries.index],
        )
        self.add_projection_point_column(gdf)
        return gdf

# study.scen.fetch('countries') → GeoDataFrame with shapes and projection_points

Custom KPI Definition

Define domain-specific KPIs — subclass, implement compute_batch, and the framework handles aggregation, comparison deltas, and collection management.

class AnnualizedRESShare(kpis.CustomKPIDefinition):
    def get_unit(self):
        return Units.percent

    def compute_batch(self, dataset, objects):
        gen = dataset.fetch('countries_t.generation')
        res = dataset.fetch('countries_t.res_generation')
        return (res.sum() / gen.sum() * 100).to_dict()

kpi_def = AnnualizedRESShare(kpi_flag='countries_t.annualized_res_gen')
study.scen.add_kpis_from_definitions_to_all_child_datasets([kpi_def])

Explore hands-on example studies

The mesqual-vanilla-studies repository demonstrates MESQUAL's capabilities through practical examples and serves as a template for organizing your own energy modeling studies.

Study 01: Intro to MESQUAL

Uses a PyPSA example network to introduce the core MESQUAL modules and framework.

View code Docs

Study 02: PyPSA Eur Example

Shows typical study workflow including custom data, variables and visuals.

View code Docs

Study 03: PLEXOS Example

Shows the platform-agnostic nature of MESQUAL using PLEXOS simulation outputs.

View code Docs

Extended MESQUAL Family

Explore other standalone and integrated libraries from the MESQUAL ecosystem.

mesqual-ai

An extension for AI context, agents and MCPs within the MESQUAL framework.

energy-repset

A unified framework and modular package for representative time-series subset selection.

captain-arro

Create beautiful, customizable, animated SVG arrows for web interfaces with just a few lines of code.