What’s new in version 1.0.0

Version available since June 19, 2026

New functionalities

Energy

Conversion Units - A CHP component is added

The CombinedHeatPower class is a new energy unit inheriting from ConversionUnit. It models a system that consumes fuel to simultaneously generate both thermal and electrical energy.

Description

This unit simplifies the modeling of cogeneration. It takes a fuel input (measured in kg/hr) and outputs electricity and heat based on specific conversion efficiencies. To respect the conservation of energy, the sum of the thermal efficiency (eff_therm) and electrical efficiency (eff_elec) must always be less than or equal to 1. These efficiencies can be provided as constant numeric values or as time-indexed vectors (lists or dictionaries) to simulate variable efficiency over time.

Key Attributes

  • fuel_consumption_unit: Models the fuel intake (generator).

  • elec_production_unit: Models the electricity generated.

  • thermal_production_unit: Models the heat generated.

  • conversion_elec: Dynamic constraint defining the relationship between fuel input and electrical output.

  • conversion_therm: Dynamic constraint defining the relationship between fuel input and thermal output.

  • power_flow: Dynamic constraint ensuring the combined thermal and electrical outputs balance correctly with the fuel input based on total efficiency.

Basic Usage

from omegalpes.energy.units.conversion_units import CombinedHeatPower

# Example initialization
chp_unit = CombinedHeatPower(
    time=time_model,
    name='my_chp',
    fuel_type="Gas",
    eff_therm=0.45,
    eff_elec=0.35
)

Storage Units

  • StorageUnit updated from EnergyUnit to AssemblyUnit.

  • Possibility to assign the capacity without assigning the maximum power of charging and discharging, default value equals to capacity value.

  • e_min and e_max for both charging and discharging can be defined.

  • The issues related to the charging and discharging rates of the storage unit have been resolved.

  • soc_min and soc_max bounds now support lists, enabling the definition of time dynamic soc bounds.

  • A new constraint, ef_geq_e0, has been added to the storage unit to softly enforce that the final state of charge (SOC) is at least equal to the initial SOC.

Utils - Interactive Plotting tool is available and deprecated notice is available below

The display utilities module has been updated to support both static and fully interactive visualizations for your energy models. By leveraging both Matplotlib and Plotly backends, you can now explore energy flows, Pareto fronts, and quantity evolutions dynamically.

Key Plotting Functions

  • plot_node_energy_flows: Visualizes energy flows through an EnergyNode over time (stacked bars for production/storage, dotted lines for consumption/exports).

  • plot_energy_mix: Generates a pie chart displaying the total energy contribution of all production units connected to a node.

  • plot_pareto2D: Plots a 2D Pareto front comparing two optimization quantities to easily visualize trade-offs.

  • plot_quantity / plot_quantity_bar: Plots the evolution of a single optimization quantity over time as a line or bar graph.

  • sum_quantities_in_quantity: A helper function that merges multiple compatible quantities into a single object for unified plotting.

Interactive Mode & Figure Options

All plotting functions now accept an interactive boolean flag.

  • Static Mode (interactive=False, default): Renders standard Matplotlib charts.

  • Interactive Mode (interactive=True): Renders Plotly charts, allowing users to hover over data points, toggle traces on and off, and zoom into specific time periods.

Additionally, you can use the new FigureOptions data class to standardize figure sizes and easily export your plots (both static and interactive) to PNG files.

Basic Usage Example

from omegalpes.general.optimisation.display_utils import plot_node_energy_flows, FigureOptions, plot_quantity

# Define standard options and enable PNG export
opts = FigureOptions(
    figsize=(14, 5),
    save_png=True,
    save_path="results/my_flows.png",
    dpi=200
)

# Generate an interactive Plotly graph of the node's energy flows
fig = plot_node_energy_flows(
    node=my_energy_node,
    interactive=True,
    fig_opts=opts
)

Bug fixed

  • Verbose: Resolved issues with the verbose option for toggling the display of model construction progress.

  • Shiftable Units: Optimized computational performance by reducing the number of constraints and binary variables.

  • e_min and e_max for both charging and discharging can be defined

  • The issues related to the charging and discharging rates of the storage unit have been resolved.

  • The issue causing a KeyError: ‘storage_e_f_min’ when directly specifying e_f — due to the model incorrectly adding constraints involving non-optimization variables—has been resolved.

  • minimize_capacity(initial_soc, max_capacity, …): The function now includes two additional arguments to constrain the model regarding initial SOC and maximum capacity.

Deprecated

  • `ef_eq_e0`: Use the new soft constraint implementation instead.

  • plot_node_energetic_flows is now deprecated and use plot_node_energy_flows instead

Contributors

Mainak Dan, Nana Kofi Baabu Twum Duah