Skip to content

MESQUAL

Modular Energy Scenario Comparison Library for Quantitative and Qualitative Analysis

mesqual is a Python framework for multi-scenario analysis of energy market simulations.

mesqual is made for humans and agents alike: its API lets anyone understand, navigate and analyze a study. The describe methods (StudyManager.describe_study(), Dataset.describe_flags(), Dataset.flag_info()) show what a study holds and load no time series data. So people and agents write study code against one documented API, not new pandas code for each study.

Why mesqual

  • Scenarios and comparisons are objects. A study holds scenarios and the comparisons between them. One fetch call gives a variable (a flag) for all scenarios (study.scen), all comparisons (study.comp) or both (study.scen_comp).
  • One API and framework over any simulation platform. A platform package maps the output of one modeling tool to flags. Each flag has a description, a schema and, where it applies, a unit. Study code asks for flags, not for files.
  • KPIs, maps and dashboards. KPI collections, interactive Folium maps and HTML dashboards use the same flags.
  • Energy logic, written once. Units, volume-weighted area prices, area and border accounting, and time series granularity conversion are part of the package. A study does not write them again.
  • Extension in layers. Platform packages extend mesqual. A study extends its platform with its own flags, interpreter overrides and area layers, and does not change the platform code.

Installation

pip install mesqual

mesqual needs Python 3.11 or later. Optional extras:

  • color: colored log output of ConsoleLogging, for example pip install "mesqual[color]"
  • screenshot: map screenshots with FoliumScreenshotter (needs Chrome)

To work on mesqual itself, clone the repository and run uv sync --all-extras. The AGENTS.md of the repository gives the rules for changes and the checks, which include the docs build. To preview the docs, run uv run mkdocs serve.

Quickstart on synthetic data

mesqual.testing is a synthetic platform: it generates small scenarios of a network with countries, nodes, lines, generators and demands. It needs no data files. The comments say what each call returns.

from mesqual.testing import make_dummy_study

study = make_dummy_study()  # scenarios base, high_demand, without_N4, short; comparisons against base

study.describe_study()                      # dict: scenarios, comparisons and their flags
study.scen.flag_info('Node.Results.price')  # FlagInfo: description, unit and schema of one flag

prices = study.scen.fetch('Node.Results.price')        # all scenarios: columns dataset, Node
price_deltas = study.comp.fetch('Node.Results.price')  # all comparisons: variation minus reference

The full runnable example, examples/quickstart.py, builds the synthetic study, describes it and saves a tabbed HTML dashboard.

Documentation

  • Guides, step by step on the synthetic platform:
  • Use mesqual with agents: install the skill with python -m mesqual.skills install ., and add the snippet to the AGENTS.md of your project.
  • Architecture: the parts of mesqual, its principles and its contracts.
  • API reference: the classes and functions of each module, from StudyManager on.
    • Logging: console output with ConsoleLogging; otherwise the logging setup of your application applies.