NaivePyDECOMP package

Module contents

EELT 7030 — Operation and Expansion Planning of Electric Power Systems Federal University of Paraná (UFPR)

Package: NaivePyDECOMP

Author

Augusto Mathias Adams <augusto.adams@ufpr.br>

Description

The NaivePyDECOMP package provides a modular, extensible, and pedagogically oriented framework for short-term power system operation planning. Inspired by the methodology and architecture of CEPEL’s DESSEM model, it enables the construction, solution, and analysis of mixed-integer optimization models based on Pyomo.

Designed for academic use, the framework supports detailed modeling of thermal, hydraulic, renewable, and storage resources, and integrates these components into a coherent multi-technology dispatch problem, including unit commitment, deficit handling, and economic trade-offs.

Submodules

HydraulicGenerator: Defines the data structures, constraints, and productivity models for hydropower generation units, including reservoir dynamics, turbine flows, and different formulations of head and productivity (constant, specific, exact).
ThermalGenerator: Models thermal units with quadratic or piecewise-linear cost functions, ramping constraints, commitment logic, startup/shutdown dynamics, and reserve provision.
RenewableGenerator: Represents non-dispatchable renewable units such as wind and solar, enforcing production bounds based on availability (gbar).
Storage: Models energy storage systems (e.g., batteries), capturing state-of-charge dynamics, charge/discharge power limits, efficiencies, and optional integration into the balance and objective.
YAMLLoader: Provides the interface for loading problem instances from structured YAML or JSON files, including validation and conversion into dataclass objects.
Builder: Constructs a complete Pyomo model from the YAML data, invoking the appropriate subsystems and assembling the balance constraint and cost-minimizing objective.
Solver: Handles the selection and execution of solvers (e.g., GLPK, IPOPT, MindtPy), with optional reporting and solution validation.
DataFrames: Exports decision variable trajectories and economic indicators to Pandas DataFrames for further analysis and visualization.
PlotSeries: Generates basic time-series plots of dispatch results using Matplotlib.
Utils, Formatters, Reporting: Auxiliary modules for formatting, printing summaries, validating model structure, and providing colored console outputs using Colorama.

Notes

The package is intentionally modular: each subsystem (Thermal, Hydro, Renewable, Storage) can be activated or omitted via the YAML interface.
While conceptually aligned with DESSEM, the implementation is simplified and transparent, allowing students and researchers to explore, extend, and test new ideas.
Extensions such as emission penalties, pumped storage, stochastic scenarios, or multi-area coupling can be added atop this foundation.
Fully compatible with Pyomo’s expressive modeling capabilities and solver interface.

References

[1] CEPEL, DESSEM. Manual de Metodologia, 2023 [2] Unsihuay Vila, C. Introdução aos Sistemas de Energia Elétrica, Lecture Notes, EELT7030/UFPR, 2023.

Subpackages

Submodules

NaivePyDECOMP.Builder module

EELT 7030 — Operation and Expansion Planning of Electric Power Systems Federal University of Paraná (UFPR)

Module: Model Builder from YAML Configuration

Author

Augusto Mathias Adams <augusto.adams@ufpr.br>

Description

This module provides a unified interface for constructing a Pyomo-based economical dispatch model from structured YAML or JSON input files. It supports integration of multiple subsystems, including:

Hydraulic generation units (UHEs)
Thermal generation units (UTs)
Renewable generators
Storage systems (batteries or reservoirs)
Deficit penalty model

The model construction includes:

Validation of structural consistency in input data.
Object-oriented dataclass translation of YAML structures.
Modular assembly of each subsystem’s variables and constraints.
Construction of system-wide power balance constraint.
Cost-based objective function including startup, generation, and deficit costs.

Usage

Use build_model_from_file(path) as the main entry point.

Ensure the YAML file has at least a meta section and one of the technology sections: hydro, thermal, renewable, or storage.

returns:

Pyomo ConcreteModel ready for optimization.
Parsed dictionary representing the structured case.

rtype:

Tuple[ConcreteModel, dict]

References

[1] CEPEL, DESSEM. Manual de Metodologia, 2023 [2] Unsihuay Vila, C. Introdução aos Sistemas de Energia Elétrica, Lecture Notes, EELT7030/UFPR, 2023.

NaivePyDECOMP.Builder.build_balance_and_objective_from_yaml(model: ConcreteModel, yaml_data: Dict[str, Any]) → ConcreteModel[source]

Construct the system-wide power balance constraint and total cost objective.

This function scans the parsed YAML content to determine which technologies (thermal, hydro, storage, renewable) are present, and invokes their respective expression builders to construct:

model.Balance: a time-indexed Constraint for supply-demand balance
model.OBJ: an Objective for cost minimization

Parameters:

model (ConcreteModel) – A Pyomo model with required sets and variables already declared.
yaml_data (dict) – Parsed YAML dictionary with subsections for each technology.

Returns:

The input model with balance constraints and objective function added.

Return type:

ConcreteModel

NaivePyDECOMP.Builder.build_model_from_data(root: Dict) → Tuple[ConcreteModel, Dict][source]

build subsystem models from data.

Parameters:: root (str) – system description.
Returns:: A tuple with the builded model and the parsed case file
Return type:: Tuple[pyomo.environ.ConcreteModel, Dict]
Raises:: ValueError – On structural or validation errors in the input file.

NaivePyDECOMP.Builder.build_model_from_file(path: str) → Tuple[ConcreteModel, Dict][source]

Load master data from YAML/JSON and build subsystem models.

Parameters:: path (str) – Path to a YAML file with sections: meta, demand, and one or more of {hydro, thermal, renewable, storage}.
Returns:: A tuple with the builded model and the parsed case file
Return type:: Tuple[pyomo.environ.ConcreteModel, Dict]
Raises:: ValueError – On structural or validation errors in the input file.

NaivePyDECOMP.BuilderPDDD module

EELT 7030 — Operation and Expansion Planning of Electric Power Systems Federal University of Paraná (UFPR)

Module: Model Builder from YAML Configuration

Author

Augusto Mathias Adams <augusto.adams@ufpr.br>

Description

This module provides a unified interface for constructing a Pyomo-based economical dispatch model from structured YAML or JSON input files. It supports integration of multiple subsystems, including:

Hydraulic generation units (UHEs)
Thermal generation units (UTs)
Renewable generators
Storage systems (batteries or reservoirs)
Deficit penalty model

The model construction includes:

Validation of structural consistency in input data.
Object-oriented dataclass translation of YAML structures.
Modular assembly of each subsystem’s variables and constraints.
Construction of system-wide power balance constraint.
Cost-based objective function including startup, generation, and deficit costs.

Usage

Use build_model_from_file(path) as the main entry point.

Ensure the YAML file has at least a meta section and one of the technology sections: hydro, thermal, renewable, or storage.

returns:

Pyomo ConcreteModel ready for optimization.
Parsed dictionary representing the structured case.

rtype:

Tuple[ConcreteModel, dict]

References

[1] CEPEL, DESSEM. Manual de Metodologia, 2023 [2] Unsihuay Vila, C. Introdução aos Sistemas de Energia Elétrica, Lecture Notes, EELT7030/UFPR, 2023.

NaivePyDECOMP.BuilderPDDD.build_pddd_balance_and_objective_from_yaml(yaml_data: Dict[str, Any], stage: int, cuts: List[Any]) → ConcreteModel[source]

Construct the system-wide power balance constraint and total cost objective along with the model itself.

This function scans the parsed YAML content to determine which technologies (thermal, hydro, storage, renewable) are present, and invokes their respective expression builders to construct:

PDDD Model
model.Balance: a time-indexed Constraint for supply-demand balance
model.OBJ: an Objective for cost minimization

Parameters:

yaml_data (dict) – Parsed YAML dictionary with subsections for each technology.
stage (int) – PDDD Stage

Returns:

The input model with balance constraints and objective function added.

Return type:

ConcreteModel

NaivePyDECOMP.BuilderPDDD.build_pddd_data_from_file(path: str) → Dict[source]

Load master data from YAML/JSON and build subsystem models.

Parameters:: path (str) – Path to a YAML file with sections: meta, demand, and one or more of {hydro, thermal, renewable, storage}.
Returns:: the parsed case file
Return type:: Dict
Raises:: ValueError – On structural or validation errors in the input file.

NaivePyDECOMP.DataFrames module

EELT 7030 — Operation and Expansion Planning of Electric Power Systems Federal University of Paraná (UFPR)

Utility: Build Dispatch DataFrame from Pyomo Model Results

Author

Augusto Mathias Adams <augusto.adams@ufpr.br>

Description

This utility extracts time series of dispatch decisions from a solved Pyomo model and compiles them into a structured pandas DataFrame. It supports hydropower, thermal generation, renewable sources, and storage systems. The output can be used for reporting, visualization, or export to CSV.

Main components extracted: - Hydropower: turbined flow, storage volume, generation, spillage. - Thermal: power output, on/off status, startup/shutdown, reserves. - Renewable: available generation by unit. - Storage: charge/discharge power, net injection, state of charge. - System-wide: demand, deficit, cost components (variable, startup, deficit).

References

[1] CEPEL, DESSEM. Manual de Metodologia, 2023 [2] Unsihuay Vila, C. Introdução aos Sistemas de Energia Elétrica, Lecture Notes, EELT7030/UFPR, 2023.

NaivePyDECOMP.DataFrames.add_cost_to_dataframe(df: DataFrame, model: ConcreteModel) → DataFrame[source]

Append cost components, demand/deficit, total generation, and marginal cost (CMO) to the DataFrame.

Parameters:

df (pd.DataFrame) – The DataFrame to which cost components will be appended.
model (ConcreteModel) – A Pyomo model instance with thermal, hydro, and balance constraints.

Returns:

The updated DataFrame including cost components, energy balance data, and marginal cost of operation (CMO).

Return type:

pd.DataFrame

NaivePyDECOMP.DataFrames.add_hydro_dispatch_to_dataframe(df: DataFrame, model: ConcreteModel) → DataFrame[source]

Append hydropower dispatch results to a pandas DataFrame.

This function extracts the turbined flow, storage volume, hydropower generation, and spillage from a Pyomo model and appends them to the given DataFrame, one column per unit and variable.

Parameters:

df (pd.DataFrame) – The DataFrame to which the results will be appended. It may be empty.
model (ConcreteModel) – A Pyomo model instance containing hydropower variables.

Returns:

The updated DataFrame including hydropower dispatch results.

Return type:

pd.DataFrame

NaivePyDECOMP.DataFrames.add_thermal_dispatch_to_dataframe(df: DataFrame, model: ConcreteModel) → DataFrame[source]

Append thermal dispatch results to a pandas DataFrame.

This function extracts generation, commitment (on/off), startup, shutdown, and reserve values from the Pyomo model and appends them to the given DataFrame. Optional variables such as reserve (r), startup (y), and shutdown (w) are included if present.

Parameters:

df (pd.DataFrame) – The DataFrame to which the results will be appended. It may be empty.
model (ConcreteModel) – A Pyomo model instance containing thermal generation variables.

Returns:

The updated DataFrame including thermal dispatch results.

Return type:

pd.DataFrame

NaivePyDECOMP.DataFrames.build_dispatch_dataframe(model: ConcreteModel) → DataFrame[source]

Build a full dispatch DataFrame with generation, cost, and balance data.

This function aggregates the dispatch results from all subsystems (hydropower, thermal, renewable, storage) along with cost components into a single structured pandas DataFrame.

Parameters:: model (ConcreteModel) – A Pyomo model instance containing subsystem variables and time horizon.
Returns:: A DataFrame with all relevant dispatch results and economic metrics.
Return type:: pd.DataFrame

NaivePyDECOMP.Formatters module

EELT 7030 — Operation and Expansion Planning of Electric Power Systems Federal University of Paraná (UFPR)

Utility: Format Numbers in Brazilian Currency Style

Author

Augusto Mathias Adams <augusto.adams@ufpr.br>

Description

This module provides a helper function to format numerical values in the Brazilian currency style: periods as thousand separators and commas for decimals (e.g., 1234567.89 → ‘1.234.567,89’).

It is intended for producing human-readable cost reports or summaries in energy dispatch problems solved by NaivePyDECOMP.

Examples

>>> format_brl(1234567.89)
'1.234.567,89'

>>> format_brl(42.5)
'42,50'

References

[1] CEPEL, DESSEM. Manual de Metodologia, 2023 [2] Unsihuay Vila, C. Introdução aos Sistemas de Energia Elétrica, Lecture Notes, EELT7030/UFPR, 2023.

NaivePyDECOMP.ModelCheck module

EELT 7030 — Operation and Expansion Planning of Electric Power Systems Federal University of Paraná (UFPR)

Module: Model Component Validators

Author

Augusto Mathias Adams <augusto.adams@ufpr.br>

Description

This module provides a set of utility functions to verify whether a given Pyomo ConcreteModel contains the essential variables, parameters, and sets required for each subsystem in an energy dispatch problem.

The validation is modular and lightweight, designed to support the dynamic assembly of hybrid dispatch models comprising: - Hydropower units - Thermal generation units - Renewable generation sources - Energy storage systems

These functions are typically used to determine the feasibility of operations such as cost extraction, result formatting, or diagnostics on a per-subsystem basis.

Functions

has_hydro_model(model): Checks presence of hydropower-related variables.
has_thermal_model(model): Checks presence of thermal generation variables.
has_renewable_model(model): Checks presence of renewable generation variables.
has_storage_model(model): Checks presence of storage system variables.

Usage Example

>>> if has_thermal_model(m):
>>>     print("Thermal model components detected.")

References

[1] CEPEL, DESSEM. Manual de Metodologia, 2023 [2] Unsihuay Vila, C. Introdução aos Sistemas de Energia Elétrica, Lecture Notes, EELT7030/UFPR, 2023.

NaivePyDECOMP.ModelCheck.has_thermal_model(model: ConcreteModel) → bool[source]

Check whether the given Pyomo model contains all components of a thermal subsystem.

This function validates the existence of typical thermal dispatch variables, including generation, commitment status, and startup/shutdown indicators.

Parameters:: model (ConcreteModel) – The Pyomo model instance to be validated.
Returns:: True if all required thermal components are present, False otherwise.
Return type:: bool

Notes

The required attributes are: - T : Time periods. - TG : Set of thermal units. - thermal_p : Power generation variable. - thermal_Cost : Cost parameter.

NaivePyDECOMP.ModelFormatters module

EELT 7030 — Operation and Expansion Planning of Electric Power Systems Federal University of Paraná (UFPR)

Utility: Welcome Message and Model Summary Printer

Author

Augusto Mathias Adams <augusto.adams@ufpr.br>

Description

This utility provides formatted, color-enhanced terminal output using the colorama library to display a welcome banner, solver configuration, and model characteristics. It is intended to improve the user experience by offering clear diagnostics and summaries prior to model solving.

Features include: - Welcome banner with project and author information. - Display of solver name and strategy. - Pretty-printed summary of subsystems included in the dispatch problem. - Parameter visualization for hydraulic, thermal, renewable, and storage units.

Use this module as part of the pre-solve interface of NaivePyDECOMP to provide clarity and visual feedback about the simulation setup.

References

[1] CEPEL, DESSEM. Manual de Metodologia, 2023 [2] Unsihuay Vila, C. Introdução aos Sistemas de Energia Elétrica, Lecture Notes, EELT7030/UFPR, 2023.

NaivePyDECOMP.ModelFormatters.format_hydro_model(case: Dict) → None[source]

Print formatted information for each hydropower unit.

Parameters:: case (dict) – Dictionary containing ‘hydro’ section with unit definitions.

NaivePyDECOMP.ModelFormatters.format_models(case: Dict) → None[source]

Dispatch model formatting routines to subsystem-specific formatters.

Parameters:: case (dict) – Input data dictionary containing unit-level information.

NaivePyDECOMP.ModelFormatters.format_thermal_model(case: Dict) → None[source]

Print formatted information for each thermal generation unit.

Parameters:: case (dict) – Dictionary containing ‘thermal’ section with unit definitions.

NaivePyDECOMP.ModelFormatters.model_properties(case: Dict) → None[source]

Print a concise list of subsystems included in the case (hydro, thermal, etc.).

Parameters:: case (dict) – Parsed input configuration containing subsystem definitions.

NaivePyDECOMP.ModelFormatters.print_welcome_banner()[source]

Print a formatted welcome banner with project information and author credit.

Uses colored and bold text to enhance readability in the terminal.

NaivePyDECOMP.ModelFormatters.print_welcome_message(model: ConcreteModel, case: Dict) → None[source]

Display the full welcome message and solver configuration.

This includes the banner, solver details, and an overview of the model components based on the input dictionary.

Parameters:

model (ConcreteModel) – The Pyomo model instance.
case (dict) – Configuration dictionary loaded from YAML or JSON input.

NaivePyDECOMP.PlotSeries module

EELT 7030 — Operation and Expansion Planning of Electric Power Systems Federal University of Paraná (UFPR)

Plotting Utilities for Time Series in Power System Studies

Author

Augusto Mathias Adams <augusto.adams@ufpr.br>

Description

This module provides high-level plotting routines to visualize time-indexed variables commonly encountered in short-term operation and planning studies of hydrothermal systems. It offers both line plots and bar plots, supporting grouped or stacked styles.

Functions

plot_series(t, series_dict, title, ylabel, file): Plot one or more time series as line graphs, with LaTeX-compatible labels.
plot_series_bar(t, series_dict, title, ylabel, file, stacked=False, width=0.85): Plot multiple time series as bar charts, either grouped or stacked, with configurable bar width.

Conventions

The time axis is discrete, typically representing hourly stages (e.g., t = 1, …, 24).
Input series must be aligned with the time axis.
Labels provided in series_dict are rendered in math mode to enable LaTeX-style notation in figures.
Output files are saved with 600 dpi resolution and tight bounding boxes.

Notes

Figures are generated using Matplotlib and saved to the given file path (PNG, PDF, or other supported formats).
The functions are designed for clarity in academic and technical reports, especially when documenting hydrothermal dispatch and unit-commitment results.
Grid lines, legends, and axis labels are automatically formatted for readability.

Examples

Render a simple time series plot:

>>> t = range(1, 5)
>>> data = {"U_{1}": [100, 120, 130, 140], "U_{2}": [90, 110, 125, 150]}
>>> plot_series(t, data, title="Hydropower Generation", ylabel="MW",
...             file="generation.png")

Render a stacked bar plot:

>>> data = {"Hydro": [200, 220, 210], "Thermal": [300, 280, 290]}
>>> t = [1, 2, 3]
>>> plot_series_bar(t, data, title="Generation Mix", ylabel="MW",
...                 file="mix.png", stacked=True)

References

[1] CEPEL, DESSEM. Manual de Metodologia, 2023 [2] Unsihuay Vila, C. Introdução aos Sistemas de Energia Elétrica, Lecture Notes, EELT7030/UFPR, 2023.

NaivePyDECOMP.PDDDMergeModels module

EELT 7030 — Operation and Expansion Planning of Electric Power Systems Federal University of Paraná (UFPR)

Utility: PDDD Synthetic Model Generator

Author

Augusto Mathias Adams <augusto.adams@ufpr.br>

Description

This utility provides tools to reconstruct a deterministic representation of a multistage dual dynamic programming (PDDD) solution as a static Pyomo model. It enables post-optimization analysis by aggregating decision variables, dual prices, volumes, and cost structures from multiple stages into a single structured object.

Main Functionality

The primary function exposed by this package is:

generate_dummy_model(pddd_solution, yaml_data): Constructs a fully populated ConcreteModel that mirrors the original optimization trajectory. It fixes all relevant decision variables and duals for each unit (hydro, thermal, renewable, storage), and reassembles cost expressions for reporting, visualization, and interpretation.

Intended Use

This package is not designed to perform optimization itself. Instead, it serves as a post-processing tool for exporting or inspecting results from a PDDD optimization workflow — for example, to be used in scenario analysis, LaTeX export, sensitivity evaluation, or policy verification.

Dependencies

Pyomo
A compatible solver (e.g., GLPK, CPLEX, IPOPT)
Auxiliary model-building functions such as: - add_hydraulic_cost_expression - add_thermal_cost_expression - add_storage_cost_expression - add_renewable_cost_expression

Examples

>>> from naivepydecomp.pddd import generate_dummy_model
>>> model = generate_dummy_model(pddd_solution, yaml_data)
>>> print(value(model.OBJ))

NaivePyDECOMP.Reporting module

EELT 7030 — Operation and Expansion Planning of Electric Power Systems Federal University of Paraná (UFPR)

Utility: Post-Solve Dispatch Summary and Cost Reports

Author

Augusto Mathias Adams <augusto.adams@ufpr.br>

Description

This module contains functions to summarize dispatch results after solving a Pyomo-based optimization problem. It prints total generation, cost breakdowns, and unit-level summaries for hydropower, thermal, renewable, and storage technologies.

Features: - Total cost, demand, deficit and thermal cost components. - Per-unit dispatch summaries with color-enhanced output (via colorama). - Compatible with modular NaivePyDECOMP subsystem architecture.

References

[1] CEPEL, DESSEM. Manual de Metodologia, 2023 [2] Unsihuay Vila, C. Introdução aos Sistemas de Energia Elétrica, Lecture Notes, EELT7030/UFPR, 2023.

NaivePyDECOMP.Reporting.dispatch_summary(model: ConcreteModel) → None[source]

Print a complete dispatch and cost summary including: - Total generation and demand. - Deficit and its monetary cost. - Thermal cost breakdown (start-up, generation). - Overall total cost from the model objective.

Parameters:: model (ConcreteModel) – Solved Pyomo model instance.

NaivePyDECOMP.Reporting.hydro_dispatch_summary(model: ConcreteModel) → None[source]

Print unit-level hydropower generation summary in MWmed.

Parameters:: model (ConcreteModel) – Solved Pyomo model with hydropower subsystem.

NaivePyDECOMP.Reporting.renewable_dispatch_summary(model: ConcreteModel) → None[source]

Print unit-level renewable generation summary in MWmed.

Parameters:: model (ConcreteModel) – Solved Pyomo model with renewable subsystem.

NaivePyDECOMP.Reporting.storage_dispatch_summary(model: ConcreteModel) → None[source]

Print unit-level storage discharge summary in MWmed.

Parameters:: model (ConcreteModel) – Solved Pyomo model with storage subsystem.

NaivePyDECOMP.Reporting.thermal_dispatch_summary(model: ConcreteModel) → None[source]

Print unit-level thermal generation summary in MWmed.

Parameters:: model (ConcreteModel) – Solved Pyomo model with thermal subsystem.

NaivePyDECOMP.SolverPDDD module

EELT 7030 — Operation and Expansion Planning of Electric Power Systems Federal University of Paraná (UFPR)

Utility: Solve PDDD Pyomo Models from YAML Configuration

Author

Augusto Mathias Adams <augusto.adams@ufpr.br>

Description

This utility builds and solves a Pyomo optimization model using input data provided in a YAML or JSON configuration file. The solver is selected based on metadata, and can include support for decomposition strategies (e.g., MIN-DT via MindtPy).

Features: - Automatic model construction via modular subsystems (thermal, hydro, storage, renewable). - Solver selection and configuration via YAML metadata. - Support for MINLP solvers such as MindtPy with strategy and time limits. - Termination condition validation to ensure feasibility or optimality.

References

[1] CEPEL, DESSEM. Manual de Metodologia, 2023 [2] Unsihuay Vila, C. Introdução aos Sistemas de Energia Elétrica, Lecture Notes, EELT7030/UFPR, 2023.

NaivePyDECOMP.SolverPDDD.compute_fcf(cuts: List[Dict], pddd_memory: List[Dict]) → Dict[source]

Compute the Future Cost Function (FCF) values for all stages in the PDDD framework, given a set of Benders cuts.

This function iterates over the memory of the PDDD algorithm, extracting the storage volumes for each stage and evaluating the corresponding FCF approximation using the provided cuts.

Parameters:

cuts (List[Dict]) –
List of Benders cuts. Each cut must be a dictionary with: {

”rhs”: float, # adjusted intercept “coefs”: {unit: float} # coefficients (subgradients)

}
pddd_memory (List[Dict]) –
List of stage-level information from the PDDD algorithm. Each element must include the storage volumes in the key ‘f_volume’, e.g.: {

”f_volume”: {“UHE1”: 50, “UHE2”: 80, …}

}

Returns:

Dictionary of FCF values for each stage, with keys in the format “FCF_{t}” where t denotes the stage index (1-based). Example: {

”FCF_1”: […], “FCF_2”: […], …

}

Return type:

Dict

NaivePyDECOMP.SolverPDDD.fcf_from_cuts(cuts: List[Dict], stage: int, storage_levels: Dict) → List[source]

Compute the Future Cost Function (FCF) value given a set of Benders cuts, assuming that the expansion point (xk) has already been absorbed into the intercept (rhs).

Parameters:

cuts (list of dict) –
List of cuts. Each cut must have the format: {

”stage”: int # stage for calculation “rhs”: float, # adjusted intercept “coefs”: {unit: float} # coefficients (subgradients)

}
stage (int) – The index of the current stage being solved (0-based).
storage_levels (dict) – Dictionary with current storage volumes for each hydro unit. Example: {“UHE1”: 50, “UHE2”: 80}

Returns:

Value of the Future Cost Function (FCF) evaluated at the given storage levels.

Return type:

List[float]

NaivePyDECOMP.SolverPDDD.solve_pddd(path: str, max_iter: int = 500, tol: float = 0.01, verbose: bool = True) → Tuple[ConcreteModel, Dict][source]

Solves the full multi-stage hydrothermal dispatch problem using the Deterministic Dual Dynamic Programming (PDDD) algorithm.

This function implements both the forward and backward passes of the PDDD approach, coordinating the stage-wise resolution of subproblems, the propagation of terminal volumes between stages, and the generation of Benders-like cuts. The process continues until the upper-lower bound convergence criterion is satisfied or the maximum number of iterations is reached.

Parameters:

path (str) – Path to the YAML file containing the problem configuration (system data, hydro parameters, solver options).
max_iter (int, optional) – Maximum number of forward-backward iterations allowed (default is 10).
tol (float, optional) – Convergence tolerance between ZSUP and ZINF values used as stopping criterion (default is 1e-2).
verbose (bool, optional) – Whether to print iteration logs and convergence progress (default is True).

Returns:

model (ConcreteModel) – A dummy Pyomo model representing the structure and solution of the final iteration. This is mainly for completeness and introspection.
case (dict) – The parsed YAML case dictionary used in the PDDD process, containing metadata, hydro data, and solver configurations.
alpha_values (dict) – alpha values of future costs.
ZINF (dict)

Raises:

RuntimeError – If the specified solver is not available or any stage optimization fails.
ValueError – If no hydro data is provided in the YAML configuration.

Notes

The upper bound (ZSUP) is computed cumulatively from all stages, discounting the cost-to-go alpha values.
The lower bound (ZINF) corresponds to the cost of the first stage assuming a myopic (executable) policy.
Cuts are generated in the backward pass and injected into earlier stages to approximate the value function of future stages.
This implementation is pedagogical and emphasizes clarity and modularity over computational performance.

NaivePyDECOMP.SolverPDDD.solve_stage_pddd(yaml_data: Dict, stage_hydros: Dict, stage_storage: Dict, cuts: Dict, stage: int) → Dict[source]

Solves a single stage of the hydrothermal dispatch problem within the Deterministic Dual Dynamic Programming (PDDD) framework.

This function constructs and solves the optimization model for a given stage, incorporating the current state of hydro units, operational cuts from future stages, and the parameters defined in the YAML configuration. It returns the resulting model and relevant economic and operational variables.

Parameters:

yaml_data (dict) – The full configuration dictionary loaded from a YAML file, containing system metadata, solver settings, and model parameters.
stage_hydros (dict) – Dictionary describing the state of the hydro units at the current stage, including initial volumes, inflows, and other relevant characteristics.
stage_storage (dict) – Dictionary describing the state of the storage units at the current stage, including initial energy, energy limits and other relevant characteristics.
cuts (dict) – Dictionary containing Benders-like cuts (affine inequalities) propagated from future stages, used to approximate the future cost function.
stage (int) – The index of the current stage being solved (0-based).

Returns:

results – Dictionary containing:

’model’ConcreteModel
The Pyomo model instance with solved values.
’hydro’dict
The hydro dictionary passed as input, preserved for traceability.
’storage’dict
The storage dictionary passed as input, preserved for traceability.
’total_cost’float
The stage cost including the estimated future cost via alpha.
’alpha’float
The value of the cost-to-go (future cost approximation) variable.
’f_volume’dict
Dictionary mapping each hydro plant to its final volume at the end of the stage.
’cmo’float
The dual variable associated with the system-wide energy balance constraint (marginal cost of operation).
’cma’dict
Dictionary mapping each hydro plant to its marginal water value (dual variable of the volume balance constraint).

Return type:

dict

Raises:

RuntimeError – If the specified solver is not available or if the optimization does not reach an optimal or feasible termination condition.

Notes

This function is used internally in the forward and backward passes of the PDDD algorithm to simulate stage-wise operations and propagate information backward via cuts.

NaivePyDECOMP.Solver module

EELT 7030 — Operation and Expansion Planning of Electric Power Systems Federal University of Paraná (UFPR)

Utility: Solve Pyomo Model from YAML Configuration

Author

Augusto Mathias Adams <augusto.adams@ufpr.br>

Description

This utility builds and solves a Pyomo optimization model using input data provided in a YAML or JSON configuration file. The solver is selected based on metadata, and can include support for decomposition strategies (e.g., MIN-DT via MindtPy).

Features: - Automatic model construction via modular subsystems (thermal, hydro, storage, renewable). - Solver selection and configuration via YAML metadata. - Support for MINLP solvers such as MindtPy with strategy and time limits. - Termination condition validation to ensure feasibility or optimality.

References

[1] CEPEL, DESSEM. Manual de Metodologia, 2023 [2] Unsihuay Vila, C. Introdução aos Sistemas de Energia Elétrica, Lecture Notes, EELT7030/UFPR, 2023.

NaivePyDECOMP.Solver.solve(path: str) → Tuple[ConcreteModel, Dict][source]

Build and solve a Pyomo optimization model from a configuration file.

This function loads a model and its configuration from a structured YAML or JSON file using the build_model_from_file routine. It then selects the appropriate solver based on the ‘meta’ section, applies any solver-specific options (including for MIN-DT decomposition), and executes the optimization.

Parameters:

path (str) – Path to the configuration file containing model metadata and data sections.

Returns:

model (ConcreteModel) – The Pyomo model after the solve routine, with variables populated.
case (dict) – Parsed dictionary containing the original configuration, metadata, solver options, and problem data.

Raises:

RuntimeError – If the solver is not available, solve fails, or model is infeasible.

NaivePyDECOMP.Utils module

EELT 7030 — Operation and Expansion Planning of Electric Power Systems Federal University of Paraná (UFPR)

LaTeX Table Utilities for Pandas DataFrames

Author

Augusto Mathias Adams <augusto.adams@ufpr.br>

Description

This module provides helpers to render pandas DataFrames as LaTeX tables with custom styling aimed at scientific and engineering reports. It includes:

binary_df_to_colored_latex: Renders a binary matrix (0/1) as a colored LaTeX table, highlighting ones and zeros with configurable colors and producing a complete table environment.
custom_df_to_latex: Renders a generic (non-binary) DataFrame as a LaTeX table with bold headers (and bold math within headers), using booktabs rules and producing a complete table environment.

Both functions omit the DataFrame index from the LaTeX output by design, emitting only the column headers and data cells.

Functions

binary_df_to_colored_latex: Render a binary (0/1) DataFrame as a colored LaTeX table. Cells equal to 1 are filled with one_color; cells equal to 0 use zero_color. Non-binary values, if present, are formatted with floatfmt and not color-filled. The index is not included in the output.
custom_df_to_latex: Render a generic DataFrame as a LaTeX table using booktabs rules with a bold header row. Inline math fragments in header cells are additionally set in bold math using bold_math_cmd. The index is not included in the output.

Parameters (Shared)

dfpandas.DataFrame: The input table to render. Only the DataFrame columns are emitted; the index is always omitted from the LaTeX output.
captionstr, optional: Caption text for the LaTeX table environment.
labelstr, optional: Label for cross-referencing with \ref{...}.
column_formatstr or None, optional: Column specification for the LaTeX tabular environment. If None, a default is inferred based on the number of columns (all centered).
size_cmdstr, optional: LaTeX size command applied inside the table (e.g., \small, \scriptsize).

Additional Parameters

one_colorstr, optional: (For binary_df_to_colored_latex) LaTeX color name for cells with value 1.
zero_colorstr, optional: (For binary_df_to_colored_latex) LaTeX background color name for cells with value 0.
floatfmtstr, optional: (For binary_df_to_colored_latex) Format string for numeric entries that are not 0/1 (e.g., "{:d}" or "{:.0f}").
bold_math_cmdstr, optional: (For custom_df_to_latex) Command for bolding inline math in header cells, e.g., \mathbf, \boldsymbol, or \bm. Ensure the corresponding LaTeX package is loaded.

returns:

str – A complete LaTeX table environment (including an inner tabular and a \resizebox{\textwidth}{!}{...} wrapper) ready to paste into a LaTeX document.
Requirements
————
- Python packages (pandas, numpy, re (standard library).)
- LaTeX packages –
- For both functions: graphicx (for \resizebox), booktabs (for custom_df_to_latex).
- For coloring: xcolor with the table option (provides \cellcolor). Colors such as oncell and white must be defined in the preamble.
- For bold math: amsmath, bm, or any package compatible with bold_math_cmd.

Notes

Both functions assume the DataFrame columns represent displayable headers. If numeric, they are commonly used as time periods. Pre-formatting is advised.
binary_df_to_colored_latex coerces values to integers for coloring. Non-binary values are rendered using floatfmt but receive no coloring.
custom_df_to_latex skips escaping in data cells, assuming LaTeX-safe input.

Examples

Render a binary status matrix with colored cells:

>>> import pandas as pd
>>> df = pd.DataFrame([[1, 0, 1], [0, 0, 1]])
>>> tex = binary_df_to_colored_latex(
...     df,
...     caption="Hourly U, Y, and W variables",
...     label="tab:uyw",
...     one_color="oncell",
...     zero_color="white",
...     floatfmt="{:d}"
... )
>>> print(tex.splitlines()[0])
\begin{table}[!ht]

Render a numeric table with bold headers and math-aware bolding:

>>> df2 = pd.DataFrame(
...     [[1.0, 2.0], [3.5, 4.25]],
...     columns=[r"$t=1$", r"\(t=2\)"]
... )
>>> tex2 = custom_df_to_latex(
...     df2,
...     caption="Example Table",
...     label="tab:example",
...     bold_math_cmd="\mathbf"
... )
>>> "\toprule" in tex2
True

NaivePyDECOMP.YAMLLoader module

EELT 7030 — Operation and Expansion Planning of Electric Power Systems Federal University of Paraná (UFPR)

Module: Configuration Pre-Processor for Model Inputs

Author

Augusto Mathias Adams <augusto.adams@ufpr.br>

Description

Utilities to load and normalize model configuration files (YAML/JSON) before instantiating optimization models. The module provides:

A LaTeX-friendly renaming utility for unit identifiers, preserving downstream compatibility with report/plot labels.
A deep-copy pre-processor that standardizes sections and optionally transforms unit names and their upstreams references.
A YAML loader that combines parsing and pre-processing into a single entry point.

This pre-processing ensures consistent, side-effect-free structures that are directly consumable by subsequent builders (hydro, thermal, renewable, storage).

Functions

key_replace(key): Convert identifiers for LaTeX.
pre_process(config_dict, transform_names=True): Deep-copy and normalize a configuration dictionary, optionally transforming unit names and upstream references in sections that contain units.
yaml_loader(file, transform_names=True): Load a YAML file and return a processed configuration dictionary suitable for model building.

Notes

Only the first underscore in an identifier is used to create the subscript; remaining underscores are kept verbatim inside the subscript block.
Sections without a units field are copied verbatim.
All operations are performed on deep copies; the original inputs are not modified.

Examples

>>> cfg = yaml_loader("case.yaml", transform_names=True)
>>> list(cfg["hydro"]["units"].keys())
['{UHE_{1}}', '{UHE_{2}}']

References

[1] CEPEL, DESSEM. Manual de Metodologia, 2023 [2] Unsihuay Vila, C. Introdução aos Sistemas de Energia Elétrica, Lecture Notes, EELT7030/UFPR, 2023.