flixopt 3.0.1__py3-none-any.whl → 6.0.0rc7__py3-none-any.whl

flixopt/clustering/intercluster_helpers.py

@@ -0,0 +1,201 @@
+"""Helper utilities for inter-cluster storage linking.
+
+This module provides utilities for building inter-cluster storage linking
+constraints following the S-N model from Blanke et al. (2022).
+
+Background
+----------
+When time series are clustered (aggregated into representative periods), storage
+behavior needs special handling. The S-N linking model introduces:
+
+- **SOC_boundary**: Absolute state-of-charge at the boundary between original periods.
+  With N original periods, there are N+1 boundary points.
+
+- **Linking**: SOC_boundary[d+1] = SOC_boundary[d] + delta_SOC[cluster_assignments[d]]
+  Each boundary is connected to the next via the net charge change of the
+  representative cluster for that period.
+
+These utilities help construct the coordinates and bounds for SOC_boundary variables.
+
+References
+----------
+- Blanke, T., et al. (2022). "Inter-Cluster Storage Linking for Time Series
+  Aggregation in Energy System Optimization Models."
+- Kotzur, L., et al. (2018). "Time series aggregation for energy system design:
+  Modeling seasonal storage."
+
+See Also
+--------
+:class:`flixopt.components.InterclusterStorageModel`
+    The storage model that uses these utilities.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import numpy as np
+import xarray as xr
+
+from ..interface import InvestParameters
+
+if TYPE_CHECKING:
+    from ..flow_system import FlowSystem
+
+logger = logging.getLogger('flixopt')
+
+# Default upper bound for unbounded storage capacity.
+# Used when no explicit capacity or InvestParameters.maximum_size is provided.
+# Set to 1e6 to avoid numerical issues with very large bounds while still
+# being effectively unbounded for most practical applications.
+DEFAULT_UNBOUNDED_CAPACITY = 1e6
+
+
+@dataclass
+class CapacityBounds:
+    """Bounds for SOC_boundary variable creation.
+
+    This dataclass holds the lower and upper bounds for the SOC_boundary variable,
+    along with a flag indicating whether investment sizing is used.
+
+    Attributes:
+        lower: Lower bound DataArray (typically zeros).
+        upper: Upper bound DataArray (capacity or maximum investment size).
+        has_investment: True if the storage uses InvestParameters for sizing.
+    """
+
+    lower: xr.DataArray
+    upper: xr.DataArray
+    has_investment: bool
+
+
+def extract_capacity_bounds(
+    capacity_param: InvestParameters | int | float | None,
+    boundary_coords: dict,
+    boundary_dims: list[str],
+) -> CapacityBounds:
+    """Extract capacity bounds from storage parameters for SOC_boundary variable.
+
+    This function determines the appropriate bounds for the SOC_boundary variable
+    based on the storage's capacity parameter:
+
+    - **Fixed capacity** (numeric): Upper bound is the fixed value.
+    - **InvestParameters**: Upper bound is maximum_size (or fixed_size if set).
+      The actual bound is enforced via separate constraints linked to investment.size.
+    - **None/Unbounded**: Upper bound is set to a large value (1e6).
+
+    The lower bound is always zero (SOC cannot be negative).
+
+    Args:
+        capacity_param: Storage capacity specification. Can be:
+            - Numeric (int/float): Fixed capacity
+            - InvestParameters: Investment-based sizing with min/max
+            - None: Unbounded storage
+        boundary_coords: Coordinate dictionary for SOC_boundary variable.
+            Must contain 'cluster_boundary' key.
+        boundary_dims: Dimension names for SOC_boundary variable.
+            First dimension must be 'cluster_boundary'.
+
+    Returns:
+        CapacityBounds with lower/upper bounds and investment flag.
+
+    Example:
+        >>> coords, dims = build_boundary_coords(14, flow_system)
+        >>> bounds = extract_capacity_bounds(InvestParameters(maximum_size=10000), coords, dims)
+        >>> bounds.has_investment
+        True
+        >>> bounds.upper.max()
+        10000.0
+    """
+    n_boundaries = len(boundary_coords['cluster_boundary'])
+    lb_shape = [n_boundaries] + [len(boundary_coords[d]) for d in boundary_dims[1:]]
+
+    lb = xr.DataArray(np.zeros(lb_shape), coords=boundary_coords, dims=boundary_dims)
+
+    # Determine has_investment and cap_value
+    has_investment = isinstance(capacity_param, InvestParameters)
+    using_default_bound = False
+
+    if isinstance(capacity_param, InvestParameters):
+        if capacity_param.fixed_size is not None:
+            cap_value = capacity_param.fixed_size
+        elif capacity_param.maximum_size is not None:
+            cap_value = capacity_param.maximum_size
+        else:
+            cap_value = DEFAULT_UNBOUNDED_CAPACITY
+            using_default_bound = True
+    elif isinstance(capacity_param, (int, float)):
+        cap_value = capacity_param
+    else:
+        cap_value = DEFAULT_UNBOUNDED_CAPACITY
+        using_default_bound = True
+
+    if using_default_bound:
+        logger.warning(
+            f'No explicit capacity bound provided for inter-cluster storage linking. '
+            f'Using default upper bound of {DEFAULT_UNBOUNDED_CAPACITY:.0e}. '
+            f'Consider setting capacity_in_flow_hours or InvestParameters.maximum_size explicitly.'
+        )
+
+    # Build upper bound
+    if isinstance(cap_value, xr.DataArray) and cap_value.dims:
+        ub = cap_value.expand_dims({'cluster_boundary': n_boundaries}, axis=0)
+        ub = ub.assign_coords(cluster_boundary=np.arange(n_boundaries))
+        ub = ub.transpose('cluster_boundary', ...)
+    else:
+        if hasattr(cap_value, 'item'):
+            cap_value = float(cap_value.item())
+        else:
+            cap_value = float(cap_value)
+        ub = xr.DataArray(np.full(lb_shape, cap_value), coords=boundary_coords, dims=boundary_dims)
+
+    return CapacityBounds(lower=lb, upper=ub, has_investment=has_investment)
+
+
+def build_boundary_coords(
+    n_original_clusters: int,
+    flow_system: FlowSystem,
+) -> tuple[dict, list[str]]:
+    """Build coordinates and dimensions for SOC_boundary variable.
+
+    Creates the coordinate dictionary and dimension list needed to create the
+    SOC_boundary variable. The primary dimension is 'cluster_boundary' with
+    N+1 values (one for each boundary between N original periods).
+
+    Additional dimensions (period, scenario) are included if present in the
+    FlowSystem, ensuring the SOC_boundary variable has the correct shape for
+    multi-period or stochastic optimizations.
+
+    Args:
+        n_original_clusters: Number of original (non-aggregated) time periods.
+            For example, if a year is clustered into 8 typical days but originally
+            had 365 days, this would be 365.
+        flow_system: The FlowSystem containing optional period/scenario dimensions.
+
+    Returns:
+        Tuple of (coords, dims) where:
+            - coords: Dictionary mapping dimension names to coordinate arrays
+            - dims: List of dimension names in order
+
+    Example:
+        >>> coords, dims = build_boundary_coords(14, flow_system)
+        >>> dims
+        ['cluster_boundary']  # or ['cluster_boundary', 'period'] if periods exist
+        >>> coords['cluster_boundary']
+        array([ 0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11, 12, 13, 14])
+    """
+    n_boundaries = n_original_clusters + 1
+    coords = {'cluster_boundary': np.arange(n_boundaries)}
+    dims = ['cluster_boundary']
+
+    if flow_system.periods is not None:
+        dims.append('period')
+        coords['period'] = np.array(list(flow_system.periods))
+
+    if flow_system.scenarios is not None:
+        dims.append('scenario')
+        coords['scenario'] = np.array(list(flow_system.scenarios))
+
+    return coords, dims

flixopt/color_processing.py

@@ -0,0 +1,372 @@
+"""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')
+
+# Type alias for flexible color input
+ColorType = str | list[str] | dict[str, str]
+"""Flexible color specification type supporting multiple input formats for visualization.
+
+Color specifications can take several forms to accommodate different use cases:
+
+**Named colorscales** (str):
+    - Standard colorscales: 'turbo', 'plasma', 'cividis', 'tab10', 'Set1'
+    - Energy-focused: 'portland' (custom flixopt colorscale for energy systems)
+    - Backend-specific maps available in Plotly and Matplotlib
+
+**Color Lists** (list[str]):
+    - Explicit color sequences: ['red', 'blue', 'green', 'orange']
+    - HEX codes: ['#FF0000', '#0000FF', '#00FF00', '#FFA500']
+    - Mixed formats: ['red', '#0000FF', 'green', 'orange']
+
+**Label-to-Color Mapping** (dict[str, str]):
+    - Explicit associations: {'Wind': 'skyblue', 'Solar': 'gold', 'Gas': 'brown'}
+    - Ensures consistent colors across different plots and datasets
+    - Ideal for energy system components with semantic meaning
+
+Examples:
+    ```python
+    # Named colorscale
+    colors = 'turbo'  # Automatic color generation
+
+    # Explicit color list
+    colors = ['red', 'blue', 'green', '#FFD700']
+
+    # Component-specific mapping
+    colors = {
+        'Wind_Turbine': 'skyblue',
+        'Solar_Panel': 'gold',
+        'Natural_Gas': 'brown',
+        'Battery': 'green',
+        'Electric_Load': 'darkred'
+    }
+    ```
+
+Color Format Support:
+    - **Named Colors**: 'red', 'blue', 'forestgreen', 'darkorange'
+    - **HEX Codes**: '#FF0000', '#0000FF', '#228B22', '#FF8C00'
+    - **RGB Tuples**: (255, 0, 0), (0, 0, 255) [Matplotlib only]
+    - **RGBA**: 'rgba(255,0,0,0.8)' [Plotly only]
+
+References:
+    - HTML Color Names: https://htmlcolorcodes.com/color-names/
+    - Matplotlib colorscales: https://matplotlib.org/stable/tutorials/colors/colorscales.html
+    - Plotly Built-in Colorscales: https://plotly.com/python/builtin-colorscales/
+"""
+
+
+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 color_to_rgba(color: str | None, alpha: float = 1.0) -> str:
+    """Convert any valid color to RGBA string format.
+
+    Handles hex colors (with or without #), named colors, and rgb/rgba strings.
+
+    Args:
+        color: Color in any valid format (hex '#FF0000' or 'FF0000',
+               named 'red', rgb 'rgb(255,0,0)', rgba 'rgba(255,0,0,1)').
+        alpha: Alpha/opacity value between 0.0 and 1.0.
+
+    Returns:
+        Color in RGBA format 'rgba(R, G, B, A)'.
+
+    Examples:
+        >>> color_to_rgba('#FF0000')
+        'rgba(255, 0, 0, 1.0)'
+        >>> color_to_rgba('FF0000')
+        'rgba(255, 0, 0, 1.0)'
+        >>> color_to_rgba('red', 0.5)
+        'rgba(255, 0, 0, 0.5)'
+        >>> color_to_rgba('forestgreen', 0.4)
+        'rgba(34, 139, 34, 0.4)'
+        >>> color_to_rgba(None)
+        'rgba(200, 200, 200, 1.0)'
+    """
+    if not color:
+        return f'rgba(200, 200, 200, {alpha})'
+
+    try:
+        # Use matplotlib's robust color conversion (handles hex, named, etc.)
+        rgba = mcolors.to_rgba(color)
+    except ValueError:
+        # Try adding # prefix for bare hex colors (e.g., 'FF0000' -> '#FF0000')
+        if len(color) == 6 and all(c in '0123456789ABCDEFabcdef' for c in color):
+            try:
+                rgba = mcolors.to_rgba(f'#{color}')
+            except ValueError:
+                return f'rgba(200, 200, 200, {alpha})'
+        else:
+            return f'rgba(200, 200, 200, {alpha})'
+    except TypeError:
+        return f'rgba(200, 200, 200, {alpha})'
+
+    r = int(round(rgba[0] * 255))
+    g = int(round(rgba[1] * 255))
+    b = int(round(rgba[2] * 255))
+    return f'rgba({r}, {g}, {b}, {alpha})'
+
+
+# Alias for backwards compatibility
+hex_to_rgba = color_to_rgba
+
+
+def process_colors(
+    colors: None | str | list[str] | dict[str, str],
+    labels: list[str],
+    default_colorscale: str | None = None,
+) -> 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.
+            Defaults to CONFIG.Plotting.default_qualitative_colorscale.
+
+    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 {}
+
+    # Resolve default colorscale from CONFIG if not provided
+    if default_colorscale is None:
+        from .config import CONFIG
+
+        default_colorscale = CONFIG.Plotting.default_qualitative_colorscale
+
+    # 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