NaivePyDESSEM Logo

NaivePyDESSEM — A Pedagogical Framework for Hydrothermal Operation and Expansion Planning

—

NaivePyDESSEM documentation

Official Documentation of NaivePyDESSEM Project — A Pedagogical and Modular Framework for Hydrothermal Economic Dispatch and Expansion Planning in Pyomo (DESSEM, DECOMP, and MDI-like Solvers)

Executive Summary / Sumário Executivo

English Version 🇬🇧

NaivePyDESSEM is an educational and modular framework designed for teaching and research in hydrothermal operation and expansion planning of electric power systems. Developed as part of the graduate course EELT7030 – Planning of Operation and Expansion of Electric Power Systems at the Federal University of Paraná (UFPR), this initiative aims to bridge the gap between academic theory and computational practice.

The framework implements simplified versions of Brazil’s main optimization models — DESSEM, DECOMP, and MDI — using Pyomo as the modeling environment. It provides transparent access to mathematical formulations, datasets, and solver configurations, supporting both didactic exploration and research replication.

This documentation consolidates the theoretical foundation of the course, covering:

  • The mathematical modeling of DESSEM, DECOMP, and MDI;

  • The hierarchy of short-, medium-, and long-term operation planning;

  • Key optimization paradigms (LP, MILP, MIQP, MINLP, etc.);

  • Advanced topics such as uncertainty modeling, stochastic programming, and D-OPF formulations.

By unifying theory, models, and reproducible examples, NaivePyDESSEM aspires to serve as an open reference for energy planning education worldwide, fostering knowledge exchange between academia, research centers, and the power industry.

Versão em Português 🇧🇷

O NaivePyDESSEM é um framework educacional e modular voltado ao ensino e à pesquisa em planejamento da operação e expansão hidrotérmica de sistemas elétricos de potência. Desenvolvido no contexto da disciplina EELT7030 – Planejamento da Operação e Expansão de Sistemas Elétricos de Potência da Universidade Federal do Paraná (UFPR), o projeto busca conectar a teoria acadêmica à prática computacional.

O framework implementa versões didáticas dos principais modelos de otimização do setor elétrico brasileiro — DESSEM, DECOMP e MDI — utilizando o ambiente Pyomo para formulação e resolução. Oferece acesso transparente às formulações matemáticas, conjuntos de dados e configurações de solver, permitindo a exploração didática e a reprodução de experimentos de pesquisa.

Esta documentação reúne os fundamentos teóricos da disciplina, abrangendo:

  • A modelagem matemática dos modelos DESSEM, DECOMP e MDI;

  • A hierarquia do planejamento de operação de curto, médio e longo prazo;

  • Os principais paradigmas de otimização (LP, MILP, MIQP, MINLP, etc.);

  • Tópicos avançados como incertezas, programação estocástica e formulações D-OPF.

Ao unificar teoria, modelos e exemplos reprodutíveis, o NaivePyDESSEM busca consolidar-se como uma referência aberta e global para o ensino de planejamento energético, promovendo o intercâmbio de conhecimento entre universidades, centros de pesquisa e o setor elétrico.

Institutional Credits / Créditos Institucionais

Developed within the Federal University of Paraná (UFPR) – Post-Graduate Program in Electrical Engineering (PPGEE) Department of Electrical Engineering (DELT)

Supervised by faculty of the professor Dr. Clodomiro Unsihuay Vila, Phd, in collaboration with a student of the course EELT7030, Augusto Mathias Adams.

Desenvolvido no âmbito da Universidade Federal do Paraná (UFPR) – Programa de Pós-Graduação em Engenharia Elétrica (PPGEE) Departamento de Engenharia Elétrica (DELT)

Com orientação docente do professor Dr. Clodomiro Unsihuay Vila, Phd, em colaboração com o discente da disciplina EELT7030, Augusto Mathias Adams.

License / Licença

This project is licensed under the GNU General Public License, version 3 (GPL-3.0). You may freely use, modify, and distribute this work, provided that all copies and derivative works remain under the same license. No warranty of any kind is provided. For more information, see: https://www.gnu.org/licenses/gpl-3.0.html

Este projeto está licenciado sob a Licença Pública Geral GNU, versão 3 (GPL-3.0). É permitido o uso, modificação e redistribuição deste trabalho, desde que todas as cópias e obras derivadas mantenham a mesma licença. Nenhuma garantia é fornecida. Para mais informações, consulte: https://www.gnu.org/licenses/gpl-3.0.html

NaivePyDESSEM — A Pedagogical and Modular Framework for Hydrothermal Economic Dispatch and Expansion Planning in Pyomo (DESSEM, DECOMP, and MDI-like Solvers)

License: GPL v3 PyPI Downloads Docs GitHub Repo

NaivePyDESSEM is a pedagogical project that brings together three complementary packages for teaching and research in power system operation planning:

  • NaivePyDESSEM — inspired by DESSEM, it models the short-term (daily/hourly) operation with detailed individual plant representation.

  • NaivePyDECOMP — inspired by DECOMP, it models the medium-term (weekly/monthly) operation with deterministic dual dynamic programming (PDDD).

  • MDI — Generation Expansion Planning inspired by MDI methodology.

Both are implemented in Pyomo, with modular architecture and integrated documentation via Sphinx.

🔎 Overview

NaivePyDESSEM is a pedagogical and modular project that consolidates three complementary packages designed for teaching, research, and experimentation in operation and expansion planning of electric power systems. The suite draws direct inspiration from the CEPEL models DESSEM, DECOMP, and MDI, reinterpreting their conceptual formulations within a transparent, open-source framework based on Pyomo.

This initiative seeks to replicate the key methodological elements of the Brazilian short-term (DESSEM), medium-term (DECOMP), and long-term investment (MDI) planning models, ensuring consistency with real-world methodologies while maintaining academic accessibility and pedagogical clarity.

⚙️ Framework Composition

  • NaivePyDESSEM — A short-term (hourly/daily) hydrothermal dispatch model, implementing detailed unit-level formulations for hydro, thermal, renewable, and storage subsystems, analogous to CEPEL’s DESSEM.

  • NaivePyDECOMP — A medium-term (weekly/monthly) aggregated dispatch model, incorporating Deterministic Dual Dynamic Programming (DDDP) and drawing structural parallels with DECOMP.

  • MDI — A long-term generation expansion planning model, representing investment decisions under uncertainty, inspired by the Investment Decision Model (MDI) used in national PDE studies.

All packages share a common data interface and modeling philosophy, enabling coherent analysis across temporal horizons and integrated experimentation with energy balance problems.

🧩 Shared Characteristics

  • Modular architecture with standardized builder, solver, and reporting modules.

  • Command-line interfaces (CLI) for model execution, reporting, and visualization.

  • YAML/JSON-based configuration files for data and scenario specification.

  • Seamless interoperability between subsystems (hydro, thermal, renewable, and storage).

  • Direct export of results to Pandas DataFrames, LaTeX tables, and graphical outputs.

  • Full compatibility with Pyomo, NumPy, Pandas, Matplotlib, and Colorama.

📘 NaivePyDESSEM Package

Purpose

The NaivePyDESSEM package provides a transparent and instructive framework for the short-term hydrothermal operation problem, reproducing the fundamental structure of CEPEL’s DESSEM. It enables the formulation, solution, and analysis of mixed-integer linear and quadratic optimization models, allowing detailed representation of individual generating units and system-level constraints.

Core Functionalities

  • Individual Unit Modeling: Comprehensive representation of hydroelectric units (with reservoirs, flows, and variable productivity formulations) and thermal units (linear/quadratic costs, startup/shutdown dynamics, ramping, and minimum up/down times). Data classes such as HydraulicGenerator, ThermalGenerator, RenewableGenerator, and Storage define the physical and operational parameters.

  • Multi-Technology Dispatch: Incorporates non-dispatchable renewable generation (wind and solar) and storage technologies (state-of-charge tracking, round-trip efficiency). Supports the inclusion or omission of subsystems through YAML configuration, enabling modular experimentation.

  • Automated Model Construction: The Builder module parses YAML/JSON data via the YAMLLoader class and automatically assembles the Pyomo model with all constraints and the total cost minimization objective.

  • Post-Solution Analysis: Results are exported to Pandas DataFrames and visualized through time-series plots using the PlotSeries module. The Formatters and Reporting utilities generate well-structured tabular and graphical summaries for comprehensive cost and dispatch analysis.

  • Command-Line Execution: CLI commands (pydessem-solve, pydessem-plot) facilitate the execution and visualization of simulation results, ensuring accessibility for educational use.

📗 NaivePyDECOMP Package

Purpose

The NaivePyDECOMP package mirrors the DECOMP model, addressing medium-term operation planning through Deterministic Dual Dynamic Programming (DDDP) and linear optimization. It provides a modular structure for decomposing long-horizon energy scheduling problems and facilitates analytical exploration of temporal and spatial coupling.

Core Functionalities

  • Medium-Term Dispatch: Models aggregated hydro and thermal subsystems across extended time horizons. Hydroelectric plants are grouped into regional subsystems (REEs) with constant productivity, while thermal generation is modeled through aggregated cost and capacity parameters.

  • DDDP-Based Optimization: Implements both single-stage linear programming and multi-stage decomposition via the BuilderPDDD and SolverPDDD modules. Enables the generation of future cost functions, convergence limits, and deterministic scenario analyses.

  • Shared Submodules: Adopts a consistent modular structure with Builder, ModelCheck, PlotSeries, Formatters, and Reporting modules — ensuring interoperability with NaivePyDESSEM.

  • CLI and Configurability: Commands such as pydecomp-solve, pydecomp-pddd-solve, and pydecomp-plot simplify experimentation. Input data are handled through YAML configuration validated by the YAMLLoader.

📙 MDI Package

Purpose

The MDI package implements a simplified but methodologically coherent framework for long-term generation expansion planning, drawing on the Investment Decision Model (MDI) used in Brazilian PDE studies. It integrates investment and operational decisions into a unified mixed-integer linear optimization problem.

Core Functionalities

  • Investment Planning: Formulates a multi-period optimization problem minimizing investment and operational costs under uncertainty. Incorporates candidate projects for thermal, hydro, renewable, and storage technologies, as well as transmission reinforcements.

  • Specialized Submodules: Subpackages MDI.Generator and MDI.Storage define project-level variables, constraints, and cost components. The Builder module consolidates these into a system-wide energy balance, while YAMLLoader manages structured scenario data.

  • Solution and Analysis: Supports a variety of Pyomo solvers (GLPK, CPLEX, IPOPT, MindtPy) and provides post-solution tools (Reporting, DataFrames, PlotSeries) for sensitivity and scenario analysis.

  • Educational Design: Preserves the key structural and economic principles of real-world expansion models while maintaining tractability for academic exercises.

📂 Project Structure

├── src
│   ├── MDI
│   │   ├── cli
│   │   │   ├── __init__.py
│   │   │   ├── cli.py
│   │   │   └── plot_cli.py
│   │   ├── Generator
│   │   │   ├── __init__.py
│   │   │   ├── GeneratorBuilder.py
│   │   │   ├── GeneratorConstraints.py
│   │   │   ├── GeneratorDataTypes.py
│   │   │   ├── GeneratorEquations.py
│   │   │   ├── GeneratorObjectives.py
│   │   │   └── GeneratorVars.py
│   │   ├── Storage
│   │   │   ├── __init__.py
│   │   │   ├── StorageBuilder.py
│   │   │   ├── StorageConstraints.py
│   │   │   ├── StorageDataTypes.py
│   │   │   ├── StorageEquations.py
│   │   │   ├── StorageObjective.py
│   │   │   └── StorageVars.py
│   │   ├── __init__.py
│   │   ├── Builder.py
│   │   ├── DataFrames.py
│   │   ├── Formatters.py
│   │   ├── ModelCheck.py
│   │   ├── ModelFormatters.py
│   │   ├── PlotSeries.py
│   │   ├── Reporting.py
│   │   ├── Solver.py
│   │   ├── Utils.py
│   │   └── YAMLLoader.py
│   ├── NaivePyDECOMP
│   │   ├── cli
│   │   │   ├── __init__.py
│   │   │   ├── cli.py
│   │   │   ├── pddd_cli.py
│   │   │   └── plot_cli.py
│   │   ├── HydraulicGenerator
│   │   │   ├── __init__.py
│   │   │   ├── HydraulicConstraints.py
│   │   │   ├── HydraulicDataTypes.py
│   │   │   ├── HydraulicEquations.py
│   │   │   ├── HydraulicGeneratorBuilder.py
│   │   │   ├── HydraulicObjectives.py
│   │   │   ├── HydraulicVars.py
│   │   │   └── SimplifiedConstantProductivityFPH.py
│   │   ├── RenewableGenerator
│   │   │   ├── __init__.py
│   │   │   ├── RenewableConstraints.py
│   │   │   ├── RenewableDataTypes.py
│   │   │   ├── RenewableEquations.py
│   │   │   ├── RenewableGeneratorBuilder.py
│   │   │   ├── RenewableObjectives.py
│   │   │   └── RenewableVars.py
│   │   ├── Storage
│   │   │   ├── __init__.py
│   │   │   ├── StorageBuilder.py
│   │   │   ├── StorageConstraints.py
│   │   │   ├── StorageDataTypes.py
│   │   │   ├── StorageEquations.py
│   │   │   ├── StorageObjective.py
│   │   │   └── StorageVars.py
│   │   ├── ThermalGenerator
│   │   │   ├── __init__.py
│   │   │   ├── ThermalConstraints.py
│   │   │   ├── ThermalDataTypes.py
│   │   │   ├── ThermalEquations.py
│   │   │   ├── ThermalGeneratorBuilder.py
│   │   │   ├── ThermalObjectives.py
│   │   │   └── ThermalVars.py
│   │   ├── __init__.py
│   │   ├── Builder.py
│   │   ├── BuilderPDDD.py
│   │   ├── DataFrames.py
│   │   ├── Formatters.py
│   │   ├── ModelCheck.py
│   │   ├── ModelFormatters.py
│   │   ├── PDDDMergeModels.py
│   │   ├── PlotSeries.py
│   │   ├── Reporting.py
│   │   ├── Solver.py
│   │   ├── SolverPDDD.py
│   │   ├── Utils.py
│   │   └── YAMLLoader.py
│   ├── NaivePyDESSEM
│   │   ├── cli
│   │   │   ├── __init__.py
│   │   │   ├── cli.py
│   │   │   └── plot_cli.py
│   │   ├── HydraulicGenerator
│   │   │   ├── __init__.py
│   │   │   ├── ConstantProductivityFPH.py
│   │   │   ├── ExactFPH.py
│   │   │   ├── HydraulicConstraints.py
│   │   │   ├── HydraulicDataTypes.py
│   │   │   ├── HydraulicEquations.py
│   │   │   ├── HydraulicGeneratorBuilder.py
│   │   │   ├── HydraulicObjectives.py
│   │   │   ├── HydraulicVars.py
│   │   │   ├── PEFPH.py
│   │   │   └── SimplifiedConstantProductivityFPH.py
│   │   ├── RenewableGenerator
│   │   │   ├── __init__.py
│   │   │   ├── RenewableConstraints.py
│   │   │   ├── RenewableDataTypes.py
│   │   │   ├── RenewableEquations.py
│   │   │   ├── RenewableGeneratorBuilder.py
│   │   │   ├── RenewableObjectives.py
│   │   │   └── RenewableVars.py
│   │   ├── Storage
│   │   │   ├── __init__.py
│   │   │   ├── StorageBuilder.py
│   │   │   ├── StorageConstraints.py
│   │   │   ├── StorageDataTypes.py
│   │   │   ├── StorageEquations.py
│   │   │   ├── StorageObjective.py
│   │   │   └── StorageVars.py
│   │   ├── ThermalGenerator
│   │   │   ├── __init__.py
│   │   │   ├── ThermalConstraints.py
│   │   │   ├── ThermalDataTypes.py
│   │   │   ├── ThermalEquations.py
│   │   │   ├── ThermalGeneratorBuilder.py
│   │   │   ├── ThermalObjectives.py
│   │   │   ├── ThermalPieceWise.py
│   │   │   └── ThermalVars.py
│   │   ├── __init__.py
│   │   ├── Builder.py
│   │   ├── DataFrames.py
│   │   ├── Formatters.py
│   │   ├── ModelCheck.py
│   │   ├── ModelFormatters.py
│   │   ├── PlotSeries.py
│   │   ├── Reporting.py
│   │   ├── Solver.py
│   │   ├── Utils.py
│   │   └── YAMLLoader.py
│   └── naivepydessem.egg-info
│       ├── dependency_links.txt
│       ├── entry_points.txt
│       ├── PKG-INFO
│       ├── requires.txt
│       ├── SOURCES.txt
│       └── top_level.txt
├── tests
├── LICENSE
├── MANIFEST.in
├── pyproject.toml
├── README.md
├── requirements.txt
└── setup.cfg

🛠 Dependencies

The following Python packages are required to run NaivePyDESSEM:

Package

Version Requirement

PyPI Link

colorama

>=0.4.6

colorama

matplotlib

>=3.10.5

matplotlib

numpy

>=2.2.6

numpy

pandas

>=2.3.2

pandas

pyomo

>=6.9.3

pyomo

🛠 Installation

pip install naivepydessem

Optionally, install with some open-source solvers:

pip install naivepydessem[solvers]

You can install from source:

git clone https://github.com/superflanker/NaivePyDESSEM.git
cd NaivePyDESSEM
pip install -e .

Similarly, using git ssh clone url:

git clone git@github.com:superflanker/NaivePyDESSEM.git
cd NaivePyDESSEM
pip install -e .

▶️ Usage

Solving a model

DESSEM-like dispatch (short-term)

pydessem-solve path/to/case.yaml --out_dir results/ --out_file dispatch.csv

DECOMP-like dispatch (medium-term)

Single-LP:

pydecomp-solve path/to/case.yaml --out_dir results/ --out_file dispatch.csv

Using PDDD:

pydecomp-pddsolve path/to/case.yaml --out_dir results/ --out_file dispatch.csv

MDI Like Generation Expansion Planning

mdi-solve path/to/case.yaml --out_dir results/ --out_file dispatch.csv

Plotting results

pydessem-plot results/dispatch.csv --mode plot --category G V --plot-style line

pydecomp-plot results/dispatch.csv --mode plot --category G V --plot-style line

mdi-plot results/dispatch.csv --mode plot --category G --plot-style line

📄 References

This implementation is aligned with the pedagogical materials of UFPR (Federal University of Paraná) and official CEPEL/EPE documentation:

  • Unsihuay Vila, C. Introdução aos Sistemas de Energia Elétrica, Lecture Notes, EELT7030, UFPR, 2023.

  • CEPEL. Manual de Metodologia do DESSEM, 2023.

  • EPE. Plano Decenal de Expansão de Energia (PDE) — Metodologia MDI, 2023.

📚 Documentation

Full API and usage documentation is built with Sphinx and available here: 👉 NaivePyDessem Documentation

This project is hosted on GitHub at:

👉 NaivePyDessem GitHub Repo

📚 How to Cite

If you use NaivePyDessem in teaching or research, please cite:

@misc{adams2025naivepydessem,
  author       = {Augusto Mathias Adams},
  title        = {NaivePyDESSEM — A Pedagogical and Modular Framework for Hydrothermal Economic Dispatch and Expansion Planning in Pyomo (DESSEM, DECOMP, and MDI-like Solvers)},
  year         = {2025},
  howpublished = {\url{https://github.com/superflanker/NaivePyDESSEM}}
}

Main modules (DESSEM/DECOMP/MDI):

Indexes