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**

.. code-block:: python

    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**

.. code-block:: python

    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
---------

Model
*****
- **Verbose:** Resolved issues with the `verbose` option for toggling the display of model construction progress.


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

Storage Units
****************
- 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
----------


Storage Units
**************
- **`ef_eq_e0`**: Use the new soft constraint implementation instead.


Utils - Interactive Plotting tool is available
**********************************************
- `plot_node_energetic_flows` is now deprecated and use `plot_node_energy_flows` instead


Contributors
------------

Mainak Dan, 
Nana Kofi Baabu Twum Duah