flixopt 3.1.1__tar.gz → 3.2.0__tar.gz

{flixopt-3.1.1 → flixopt-3.2.0}/CHANGELOG.md

@@ -21,8 +21,9 @@ Please keep the format of the changelog consistent with the other releases, so t
 
 ## [Template] - ????-??-??
 
-If upgrading from v2.x, see the [v3.0.0 release notes](https://github.com/flixOpt/flixOpt/releases/tag/v3.0.0) and [Migration Guide](https://flixopt.github.io/flixopt/latest/user-guide/migration-guide-v3/).
+**Summary**:
 
+If upgrading from v2.x, see the [v3.0.0 release notes](https://github.com/flixOpt/flixOpt/releases/tag/v3.0.0) and [Migration Guide](https://flixopt.github.io/flixopt/latest/user-guide/migration-guide-v3/).
 
 ### ✨ Added
 
@@ -50,6 +51,8 @@ If upgrading from v2.x, see the [v3.0.0 release notes](https://github.com/flixOp
 
 ## [Unreleased] - ????-??-??
 
+**Summary**:
+
 If upgrading from v2.x, see the [v3.0.0 release notes](https://github.com/flixOpt/flixOpt/releases/tag/v3.0.0) and [Migration Guide](https://flixopt.github.io/flixopt/latest/user-guide/migration-guide-v3/).
 
 ### ✨ Added
@@ -78,6 +81,61 @@ If upgrading from v2.x, see the [v3.0.0 release notes](https://github.com/flixOp
 
 Until here -->
 
+## [3.2.0] - 2025-10-26
+
+**Summary**: Enhanced plotting capabilities with consistent color management, custom plotting kwargs support, and centralized I/O handling.
+
+If upgrading from v2.x, see the [v3.0.0 release notes](https://github.com/flixOpt/flixOpt/releases/tag/v3.0.0) and [Migration Guide](https://flixopt.github.io/flixopt/latest/user-guide/migration-guide-v3/).
+
+### ✨ Added
+
+**Color management:**
+- **`setup_colors()` method** for `CalculationResults` and `SegmentedCalculationResults` to configure consistent colors across all plots
+  - Group components by colorscales: `results.setup_colors({'CHP': 'reds', 'Storage': 'blues', 'Greys': ['Grid', 'Demand']})`
+  - Automatically propagates to all segments in segmented calculations
+  - Colors persist across all plot calls unless explicitly overridden
+- **Flexible color inputs**: Supports colorscale names (e.g., 'turbo', 'plasma'), color lists, or label-to-color dictionaries
+- **Cross-backend compatibility**: Seamless color handling for both Plotly and Matplotlib
+
+**Plotting customization:**
+- **Plotting kwargs support**: Pass additional arguments to plotting backends via `px_kwargs`, `plot_kwargs`, and `backend_kwargs` parameters
+- **New `CONFIG.Plotting` configuration section**:
+  - `default_show`: Control default plot visibility
+  - `default_engine`: Choose 'plotly' or 'matplotlib'
+  - `default_dpi`: Set resolution for saved plots
+  - `default_facet_cols`: Configure default faceting columns
+  - `default_sequential_colorscale`: Default for heatmaps (now 'turbo')
+  - `default_qualitative_colorscale`: Default for categorical plots (now 'plotly')
+
+**I/O improvements:**
+- Centralized JSON/YAML I/O with auto-format detection
+- Enhanced NetCDF handling with consistent engine usage
+- Better numeric formatting in YAML exports
+
+### ♻️ Changed
+- **Default colorscale**: Changed from 'viridis' to 'turbo' for better perceptual uniformity
+- **Color terminology**: Standardized from "colormap" to "colorscale" throughout for Plotly consistency
+- **Plotting internals**: Now use `xr.Dataset` as primary data type (DataFrames automatically converted)
+- **NetCDF engine**: Switched back to netcdf4 engine following xarray updates and performance benchmarks
+
+### 🔥 Removed
+- Removed unused `plotting.pie_with_plotly()` method
+
+### 🐛 Fixed
+- Improved error messages when using `engine='matplotlib'` with multidimensional data
+- Better dimension validation in `results.plot_heatmap()`
+
+### 📝 Docs
+- Enhanced examples demonstrating `setup_colors()` usage
+- Updated terminology from "colormap" to "colorscale" in docstrings
+
+### 👷 Development
+- Fixed concurrency issue in CI
+- Centralized color processing logic into dedicated module
+- Refactored to function-based color handling for simpler API
+
+---
+
 ## [3.1.1] - 2025-10-20
 **Summary**: Fixed a bug when acessing the `effects_per_component` dataset in results without periodic effects.
 

{flixopt-3.1.1/flixopt.egg-info → flixopt-3.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flixopt
-Version: 3.1.1
+Version: 3.2.0
 Summary: Vector based energy and material flow optimization framework in Python.
 Author-email: "Chair of Building Energy Systems and Heat Supply, TU Dresden" <peter.stange@tu-dresden.de>, Felix Bumann <felixbumann387@gmail.com>, Felix Panitz <baumbude@googlemail.com>, Peter Stange <peter.stange@tu-dresden.de>
 Maintainer-email: Felix Bumann <felixbumann387@gmail.com>, Peter Stange <peter.stange@tu-dresden.de>
@@ -24,7 +24,7 @@ Requires-Dist: numpy<3,>=1.21.5
 Requires-Dist: pandas<3,>=2.0.0
 Requires-Dist: xarray<2026.0,>=2024.2.0
 Requires-Dist: linopy<0.6,>=0.5.1
-Requires-Dist: h5netcdf<2,>=1.0.0
+Requires-Dist: netcdf4<2,>=1.6.1
 Requires-Dist: pyyaml<7,>=6.0.0
 Requires-Dist: rich<15,>=13.0.0
 Requires-Dist: tomli<3,>=2.0.1; python_version < "3.11"

{flixopt-3.1.1 → flixopt-3.2.0}/flixopt/aggregation.py

@@ -20,7 +20,9 @@ try:
 except ImportError:
     TSAM_AVAILABLE = False
 
+from .color_processing import process_colors
 from .components import Storage
+from .config import CONFIG
 from .structure import (
     FlowSystemModel,
     Submodel,
@@ -141,7 +143,7 @@ class Aggregation:
     def use_extreme_periods(self):
         return self.time_series_for_high_peaks or self.time_series_for_low_peaks
 
-    def plot(self, colormap: str = 'viridis', show: bool = True, save: pathlib.Path | None = None) -> go.Figure:
+    def plot(self, colormap: str | None = None, show: bool = True, save: pathlib.Path | None = None) -> go.Figure:
         from . import plotting
 
         df_org = self.original_data.copy().rename(
@@ -150,13 +152,20 @@ class Aggregation:
         df_agg = self.aggregated_data.copy().rename(
             columns={col: f'Aggregated - {col}' for col in self.aggregated_data.columns}
         )
-        fig = plotting.with_plotly(df_org, 'line', colors=colormap)
+        colors = list(
+            process_colors(colormap or CONFIG.Plotting.default_qualitative_colorscale, list(df_org.columns)).values()
+        )
+        fig = plotting.with_plotly(df_org.to_xarray(), 'line', colors=colors, xlabel='Time in h')
         for trace in fig.data:
             trace.update(dict(line=dict(dash='dash')))
-        fig = plotting.with_plotly(df_agg, 'line', colors=colormap, fig=fig)
+        fig2 = plotting.with_plotly(df_agg.to_xarray(), 'line', colors=colors, xlabel='Time in h')
+        for trace in fig2.data:
+            fig.add_trace(trace)
 
         fig.update_layout(
-            title='Original vs Aggregated Data (original = ---)', xaxis_title='Index', yaxis_title='Value'
+            title='Original vs Aggregated Data (original = ---)',
+            xaxis_title='Time in h',
+            yaxis_title='Value',
         )
 
         plotting.export_figure(

{flixopt-3.1.1 → flixopt-3.2.0}/flixopt/calculation.py

@@ -22,7 +22,6 @@ import numpy as np
 import yaml
 
 from . import io as fx_io
-from . import utils as utils
 from .aggregation import Aggregation, AggregationModel, AggregationParameters
 from .components import Storage
 from .config import CONFIG
@@ -144,7 +143,7 @@ class Calculation:
             ],
         }
 
-        return utils.round_nested_floats(main_results)
+        return fx_io.round_nested_floats(main_results)
 
     @property
     def summary(self):
@@ -253,7 +252,7 @@ class FullCalculation(Calculation):
             logger.info(
                 f'{" Main Results ":#^80}\n'
                 + yaml.dump(
-                    utils.round_nested_floats(self.main_results),
+                    self.main_results,
                     default_flow_style=False,
                     sort_keys=False,
                     allow_unicode=True,

flixopt-3.2.0/flixopt/color_processing.py

@@ -0,0 +1,261 @@
+"""Simplified color handling for visualization.
+
+This module provides clean color processing that transforms various input formats
+into a label-to-color mapping dictionary, without needing to know about the plotting engine.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import matplotlib.colors as mcolors
+import matplotlib.pyplot as plt
+import plotly.express as px
+from plotly.exceptions import PlotlyError
+
+logger = logging.getLogger('flixopt')
+
+
+def _rgb_string_to_hex(color: str) -> str:
+    """Convert Plotly RGB/RGBA string format to hex.
+
+    Args:
+        color: Color in format 'rgb(R, G, B)', 'rgba(R, G, B, A)' or already in hex
+
+    Returns:
+        Color in hex format '#RRGGBB'
+    """
+    color = color.strip()
+
+    # If already hex, return as-is
+    if color.startswith('#'):
+        return color
+
+    # Try to parse rgb() or rgba()
+    try:
+        if color.startswith('rgb('):
+            # Extract RGB values from 'rgb(R, G, B)' format
+            rgb_str = color[4:-1]  # Remove 'rgb(' and ')'
+        elif color.startswith('rgba('):
+            # Extract RGBA values from 'rgba(R, G, B, A)' format
+            rgb_str = color[5:-1]  # Remove 'rgba(' and ')'
+        else:
+            return color
+
+        # Split on commas and parse first three components
+        components = rgb_str.split(',')
+        if len(components) < 3:
+            return color
+
+        # Parse and clamp the first three components
+        r = max(0, min(255, int(round(float(components[0].strip())))))
+        g = max(0, min(255, int(round(float(components[1].strip())))))
+        b = max(0, min(255, int(round(float(components[2].strip())))))
+
+        return f'#{r:02x}{g:02x}{b:02x}'
+    except (ValueError, IndexError):
+        # If parsing fails, return original
+        return color
+
+
+def process_colors(
+    colors: None | str | list[str] | dict[str, str],
+    labels: list[str],
+    default_colorscale: str = 'turbo',
+) -> dict[str, str]:
+    """Process color input and return a label-to-color mapping.
+
+    This function takes flexible color input and always returns a dictionary
+    mapping each label to a specific color string. The plotting engine can then
+    use this mapping as needed.
+
+    Args:
+        colors: Color specification in one of four formats:
+            - None: Use the default colorscale
+            - str: Name of a colorscale (e.g., 'turbo', 'plasma', 'Set1', 'portland')
+            - list[str]: List of color strings (hex, named colors, etc.)
+            - dict[str, str]: Direct label-to-color mapping
+        labels: List of labels that need colors assigned
+        default_colorscale: Fallback colorscale name if requested scale not found
+
+    Returns:
+        Dictionary mapping each label to a color string
+
+    Examples:
+        >>> # Using None - applies default colorscale
+        >>> process_colors(None, ['A', 'B', 'C'])
+        {'A': '#0d0887', 'B': '#7e03a8', 'C': '#cc4778'}
+
+        >>> # Using a colorscale name
+        >>> process_colors('plasma', ['A', 'B', 'C'])
+        {'A': '#0d0887', 'B': '#7e03a8', 'C': '#cc4778'}
+
+        >>> # Using a list of colors
+        >>> process_colors(['red', 'blue', 'green'], ['A', 'B', 'C'])
+        {'A': 'red', 'B': 'blue', 'C': 'green'}
+
+        >>> # Using a pre-made mapping
+        >>> process_colors({'A': 'red', 'B': 'blue'}, ['A', 'B', 'C'])
+        {'A': 'red', 'B': 'blue', 'C': '#0d0887'}  # C gets color from default scale
+    """
+    if not labels:
+        return {}
+
+    # Case 1: Already a mapping dictionary
+    if isinstance(colors, dict):
+        return _fill_missing_colors(colors, labels, default_colorscale)
+
+    # Case 2: None or colorscale name (string)
+    if colors is None or isinstance(colors, str):
+        colorscale_name = colors if colors is not None else default_colorscale
+        color_list = _get_colors_from_scale(colorscale_name, len(labels), default_colorscale)
+        return dict(zip(labels, color_list, strict=False))
+
+    # Case 3: List of colors
+    if isinstance(colors, list):
+        if len(colors) == 0:
+            logger.warning(f'Empty color list provided. Using {default_colorscale} instead.')
+            color_list = _get_colors_from_scale(default_colorscale, len(labels), default_colorscale)
+            return dict(zip(labels, color_list, strict=False))
+
+        if len(colors) < len(labels):
+            logger.debug(
+                f'Not enough colors provided ({len(colors)}) for all labels ({len(labels)}). Colors will cycle.'
+            )
+
+        # Cycle through colors if we don't have enough
+        return {label: colors[i % len(colors)] for i, label in enumerate(labels)}
+
+    raise TypeError(f'colors must be None, str, list, or dict, got {type(colors)}')
+
+
+def _fill_missing_colors(
+    color_mapping: dict[str, str],
+    labels: list[str],
+    default_colorscale: str,
+) -> dict[str, str]:
+    """Fill in missing labels in a color mapping using a colorscale.
+
+    Args:
+        color_mapping: Partial label-to-color mapping
+        labels: All labels that need colors
+        default_colorscale: Colorscale to use for missing labels
+
+    Returns:
+        Complete label-to-color mapping
+    """
+    missing_labels = [label for label in labels if label not in color_mapping]
+
+    if not missing_labels:
+        return color_mapping.copy()
+
+    # Log warning about missing labels
+    logger.debug(f'Labels missing colors: {missing_labels}. Using {default_colorscale} for these.')
+
+    # Get colors for missing labels
+    missing_colors = _get_colors_from_scale(default_colorscale, len(missing_labels), default_colorscale)
+
+    # Combine existing and new colors
+    result = color_mapping.copy()
+    result.update(dict(zip(missing_labels, missing_colors, strict=False)))
+    return result
+
+
+def _get_colors_from_scale(
+    colorscale_name: str,
+    num_colors: int,
+    fallback_scale: str,
+) -> list[str]:
+    """Extract a list of colors from a named colorscale.
+
+    Tries to get colors from the named scale (Plotly first, then Matplotlib),
+    falls back to the fallback scale if not found.
+
+    Args:
+        colorscale_name: Name of the colorscale to try
+        num_colors: Number of colors needed
+        fallback_scale: Fallback colorscale name if first fails
+
+    Returns:
+        List of color strings (hex format)
+    """
+    # Try to get the requested colorscale
+    colors = _try_get_colorscale(colorscale_name, num_colors)
+
+    if colors is not None:
+        return colors
+
+    # Fallback to default
+    logger.warning(f"Colorscale '{colorscale_name}' not found. Using '{fallback_scale}' instead.")
+
+    colors = _try_get_colorscale(fallback_scale, num_colors)
+
+    if colors is not None:
+        return colors
+
+    # Ultimate fallback: just use basic colors
+    logger.warning(f"Fallback colorscale '{fallback_scale}' also not found. Using basic colors.")
+    basic_colors = [
+        '#1f77b4',
+        '#ff7f0e',
+        '#2ca02c',
+        '#d62728',
+        '#9467bd',
+        '#8c564b',
+        '#e377c2',
+        '#7f7f7f',
+        '#bcbd22',
+        '#17becf',
+    ]
+    return [basic_colors[i % len(basic_colors)] for i in range(num_colors)]
+
+
+def _try_get_colorscale(colorscale_name: str, num_colors: int) -> list[str] | None:
+    """Try to get colors from Plotly or Matplotlib colorscales.
+
+    Tries Plotly colorscales first (both qualitative and sequential),
+    then falls back to Matplotlib colorscales.
+
+    Args:
+        colorscale_name: Name of the colorscale
+        num_colors: Number of colors needed
+
+    Returns:
+        List of color strings (hex format) if successful, None if colorscale not found
+    """
+    # First try Plotly qualitative (discrete) color sequences
+    colorscale_title = colorscale_name.title()
+    if hasattr(px.colors.qualitative, colorscale_title):
+        color_list = getattr(px.colors.qualitative, colorscale_title)
+        # Convert to hex format for matplotlib compatibility
+        return [_rgb_string_to_hex(color_list[i % len(color_list)]) for i in range(num_colors)]
+
+    # Then try Plotly sequential/continuous colorscales
+    try:
+        colorscale = px.colors.get_colorscale(colorscale_name)
+        # Sample evenly from the colorscale
+        if num_colors == 1:
+            sample_points = [0.5]
+        else:
+            sample_points = [i / (num_colors - 1) for i in range(num_colors)]
+        colors = px.colors.sample_colorscale(colorscale, sample_points)
+        # Convert to hex format for matplotlib compatibility
+        return [_rgb_string_to_hex(c) for c in colors]
+    except (PlotlyError, ValueError):
+        pass
+
+    # Finally try Matplotlib colorscales
+    try:
+        cmap = plt.get_cmap(colorscale_name)
+
+        # Sample evenly from the colorscale
+        if num_colors == 1:
+            colors = [cmap(0.5)]
+        else:
+            colors = [cmap(i / (num_colors - 1)) for i in range(num_colors)]
+
+        # Convert RGBA tuples to hex strings
+        return [mcolors.rgb2hex(color[:3]) for color in colors]
+
+    except (ValueError, KeyError):
+        return None

{flixopt-3.1.1 → flixopt-3.2.0}/flixopt/config.py

@@ -8,7 +8,6 @@ from pathlib import Path
 from types import MappingProxyType
 from typing import Literal
 
-import yaml
 from rich.console import Console
 from rich.logging import RichHandler
 from rich.style import Style
@@ -54,6 +53,16 @@ _DEFAULTS = MappingProxyType(
                 'big_binary_bound': 100_000,
             }
         ),
+        'plotting': MappingProxyType(
+            {
+                'default_show': True,
+                'default_engine': 'plotly',
+                'default_dpi': 300,
+                'default_facet_cols': 3,
+                'default_sequential_colorscale': 'turbo',
+                'default_qualitative_colorscale': 'plotly',
+            }
+        ),
     }
 )
 
@@ -185,6 +194,42 @@ class CONFIG:
         epsilon: float = _DEFAULTS['modeling']['epsilon']
         big_binary_bound: int = _DEFAULTS['modeling']['big_binary_bound']
 
+    class Plotting:
+        """Plotting configuration.
+
+        Configure backends via environment variables:
+        - Matplotlib: Set `MPLBACKEND` environment variable (e.g., 'Agg', 'TkAgg')
+        - Plotly: Set `PLOTLY_RENDERER` or use `plotly.io.renderers.default`
+
+        Attributes:
+            default_show: Default value for the `show` parameter in plot methods.
+            default_engine: Default plotting engine.
+            default_dpi: Default DPI for saved plots.
+            default_facet_cols: Default number of columns for faceted plots.
+            default_sequential_colorscale: Default colorscale for heatmaps and continuous data.
+            default_qualitative_colorscale: Default colormap for categorical plots (bar/line/area charts).
+
+        Examples:
+            ```python
+            # Set consistent theming
+            CONFIG.Plotting.plotly_template = 'plotly_dark'
+            CONFIG.apply()
+
+            # Configure default export and color settings
+            CONFIG.Plotting.default_dpi = 600
+            CONFIG.Plotting.default_sequential_colorscale = 'plasma'
+            CONFIG.Plotting.default_qualitative_colorscale = 'Dark24'
+            CONFIG.apply()
+            ```
+        """
+
+        default_show: bool = _DEFAULTS['plotting']['default_show']
+        default_engine: Literal['plotly', 'matplotlib'] = _DEFAULTS['plotting']['default_engine']
+        default_dpi: int = _DEFAULTS['plotting']['default_dpi']
+        default_facet_cols: int = _DEFAULTS['plotting']['default_facet_cols']
+        default_sequential_colorscale: str = _DEFAULTS['plotting']['default_sequential_colorscale']
+        default_qualitative_colorscale: str = _DEFAULTS['plotting']['default_qualitative_colorscale']
+
     config_name: str = _DEFAULTS['config_name']
 
     @classmethod
@@ -253,13 +298,15 @@ class CONFIG:
         Raises:
             FileNotFoundError: If the config file does not exist.
         """
+        # Import here to avoid circular import
+        from . import io as fx_io
+
         config_path = Path(config_file)
         if not config_path.exists():
             raise FileNotFoundError(f'Config file not found: {config_file}')
 
-        with config_path.open() as file:
-            config_dict = yaml.safe_load(file) or {}
-            cls._apply_config_dict(config_dict)
+        config_dict = fx_io.load_yaml(config_path)
+        cls._apply_config_dict(config_dict)
 
         cls.apply()
 
@@ -319,6 +366,14 @@ class CONFIG:
                 'epsilon': cls.Modeling.epsilon,
                 'big_binary_bound': cls.Modeling.big_binary_bound,
             },
+            'plotting': {
+                'default_show': cls.Plotting.default_show,
+                'default_engine': cls.Plotting.default_engine,
+                'default_dpi': cls.Plotting.default_dpi,
+                'default_facet_cols': cls.Plotting.default_facet_cols,
+                'default_sequential_colorscale': cls.Plotting.default_sequential_colorscale,
+                'default_qualitative_colorscale': cls.Plotting.default_qualitative_colorscale,
+            },
         }
 
 

{flixopt-3.1.1 → flixopt-3.2.0}/flixopt/flow_system.py

@@ -4,7 +4,6 @@ This module contains the FlowSystem class, which is used to collect instances of
 
 from __future__ import annotations
 
-import json
 import logging
 import warnings
 from typing import TYPE_CHECKING, Any, Literal, Optional
@@ -13,6 +12,7 @@ import numpy as np
 import pandas as pd
 import xarray as xr
 
+from .config import CONFIG
 from .core import (
     ConversionError,
     DataConverter,
@@ -484,7 +484,7 @@ class FlowSystem(Interface):
         | list[
             Literal['nodes', 'edges', 'layout', 'interaction', 'manipulation', 'physics', 'selection', 'renderer']
         ] = True,
-        show: bool = False,
+        show: bool | None = None,
     ) -> pyvis.network.Network | None:
         """
         Visualizes the network structure of a FlowSystem using PyVis, saving it as an interactive HTML file.
@@ -514,7 +514,9 @@ class FlowSystem(Interface):
         from . import plotting
 
         node_infos, edge_infos = self.network_infos()
-        return plotting.plot_network(node_infos, edge_infos, path, controls, show)
+        return plotting.plot_network(
+            node_infos, edge_infos, path, controls, show if show is not None else CONFIG.Plotting.default_show
+        )
 
     def start_network_app(self):
         """Visualizes the network structure of a FlowSystem using Dash, Cytoscape, and networkx.

{flixopt-3.1.1 → flixopt-3.2.0}/flixopt/interface.py

@@ -712,6 +712,8 @@ class InvestParameters(Interface):
             Combinable with effects_of_investment and effects_of_investment_per_size.
         effects_of_retirement: Costs incurred if NOT investing (demolition, penalties).
             Dict: {'effect_name': value}.
+        linked_periods: Describes which periods are linked. 1 means linked, 0 means size=0. None means no linked periods.
+            For convenience, pass a tuple containing the first and last period (2025, 2039), linking them and those in between
 
     Deprecated Args:
         fix_effects: **Deprecated**. Use `effects_of_investment` instead.
@@ -724,7 +726,6 @@ class InvestParameters(Interface):
             Will be removed in version 4.0.
         optional: DEPRECATED. Use `mandatory` instead. Opposite of `mandatory`.
             Will be removed in version 4.0.
-        linked_periods: Describes which periods are linked. 1 means linked, 0 means size=0. None means no linked periods.
 
     Cost Annualization Requirements:
         All cost values must be properly weighted to match the optimization model's time horizon.