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

flixopt/__init__.py

@@ -2,68 +2,76 @@
 This module bundles all common functionality of flixopt and sets up the logging
 """
 
-import warnings
+import logging
 from importlib.metadata import PackageNotFoundError, version
 
 try:
     __version__ = version('flixopt')
-except PackageNotFoundError:
+except (PackageNotFoundError, TypeError):
     # Package is not installed (development mode without editable install)
     __version__ = '0.0.0.dev0'
 
-from .commons import (
-    CONFIG,
-    AggregatedCalculation,
-    AggregationParameters,
-    Bus,
-    Effect,
-    Flow,
-    FlowSystem,
-    FullCalculation,
-    InvestParameters,
+# Import commonly used classes and functions
+# Register xarray accessors:
+# - xr.Dataset.plotly / xr.DataArray.plotly (from xarray_plotly package)
+# - xr.Dataset.fxstats (from stats_accessor)
+import xarray_plotly as _xpx  # noqa: F401
+
+from . import clustering, linear_converters, plotting, results, solvers
+from . import stats_accessor as _fxstats  # noqa: F401
+from .carrier import Carrier, CarrierContainer
+from .comparison import Comparison
+from .components import (
     LinearConverter,
-    OnOffParameters,
-    Piece,
-    Piecewise,
-    PiecewiseConversion,
-    PiecewiseEffects,
-    SegmentedCalculation,
     Sink,
     Source,
     SourceAndSink,
     Storage,
-    TimeSeriesData,
     Transmission,
-    change_logging_level,
-    linear_converters,
-    plotting,
-    results,
-    solvers,
 )
+from .config import CONFIG
+from .core import TimeSeriesData
+from .effects import PENALTY_EFFECT_LABEL, Effect
+from .elements import Bus, Flow
+from .flow_system import FlowSystem
+from .interface import InvestParameters, Piece, Piecewise, PiecewiseConversion, PiecewiseEffects, StatusParameters
+from .optimization import Optimization, SegmentedOptimization
+from .plot_result import PlotResult
 
-# === Runtime warning suppression for third-party libraries ===
-# These warnings are from dependencies and cannot be fixed by end users.
-# They are suppressed at runtime to provide a cleaner user experience.
-# These filters match the test configuration in pyproject.toml for consistency.
-
-# tsam: Time series aggregation library
-# - UserWarning: Informational message about minimal value constraints during clustering.
-warnings.filterwarnings('ignore', category=UserWarning, message='.*minimal value.*exceeds.*', module='tsam')
-# TODO: Might be able to fix it in flixopt?
-
-# linopy: Linear optimization library
-# - UserWarning: Coordinate mismatch warnings that don't affect functionality and are expected.
-warnings.filterwarnings(
-    'ignore', category=UserWarning, message='Coordinates across variables not equal', module='linopy'
-)
-# - FutureWarning: join parameter default will change in future versions
-warnings.filterwarnings(
-    'ignore',
-    category=FutureWarning,
-    message="In a future version of xarray the default value for join will change from join='outer' to join='exact'",
-    module='linopy',
-)
+__all__ = [
+    'TimeSeriesData',
+    'CONFIG',
+    'Carrier',
+    'CarrierContainer',
+    'Comparison',
+    'Flow',
+    'Bus',
+    'Effect',
+    'PENALTY_EFFECT_LABEL',
+    'Source',
+    'Sink',
+    'SourceAndSink',
+    'Storage',
+    'LinearConverter',
+    'Transmission',
+    'FlowSystem',
+    'Optimization',
+    'SegmentedOptimization',
+    'InvestParameters',
+    'StatusParameters',
+    'Piece',
+    'Piecewise',
+    'PiecewiseConversion',
+    'PiecewiseEffects',
+    'PlotResult',
+    'clustering',
+    'plotting',
+    'results',
+    'linear_converters',
+    'solvers',
+]
 
-# numpy: Core numerical library
-# - RuntimeWarning: Binary incompatibility warnings from compiled extensions (safe to ignore). numpy 1->2
-warnings.filterwarnings('ignore', category=RuntimeWarning, message='numpy\\.ndarray size changed')
+# Initialize logger with default configuration (silent: WARNING level, NullHandler).
+logger = logging.getLogger('flixopt')
+logger.setLevel(logging.WARNING)
+logger.addHandler(logging.NullHandler())

flixopt/carrier.py

@@ -0,0 +1,159 @@
+"""Carrier class for energy/material type definitions.
+
+Carriers represent types of energy or materials that flow through buses,
+such as electricity, heat, gas, or water. They provide consistent styling
+and metadata across visualizations.
+"""
+
+from __future__ import annotations
+
+from .structure import ContainerMixin, Interface, register_class_for_io
+
+
+@register_class_for_io
+class Carrier(Interface):
+    """Definition of an energy or material carrier type.
+
+    Carriers represent the type of energy or material flowing through a Bus.
+    They provide consistent color, unit, and description across all visualizations
+    and can be shared between multiple buses of the same type.
+
+    Inherits from Interface to provide serialization capabilities.
+
+    Args:
+        name: Identifier for the carrier (e.g., 'electricity', 'heat', 'gas').
+        color: Hex color string for visualizations (e.g., '#FFD700').
+        unit: Unit string for display (e.g., 'kW', 'kW_th', 'm³/h').
+        description: Optional human-readable description.
+
+    Examples:
+        Creating custom carriers:
+
+        ```python
+        import flixopt as fx
+
+        # Define custom carriers
+        electricity = fx.Carrier('electricity', '#FFD700', 'kW', 'Electrical power')
+        district_heat = fx.Carrier('district_heat', '#FF6B6B', 'kW_th', 'District heating')
+        hydrogen = fx.Carrier('hydrogen', '#00CED1', 'kg/h', 'Hydrogen fuel')
+
+        # Register with FlowSystem
+        flow_system.add_carrier(electricity)
+        flow_system.add_carrier(district_heat)
+
+        # Use with buses (just reference by name)
+        elec_bus = fx.Bus('MainGrid', carrier='electricity')
+        heat_bus = fx.Bus('HeatingNetwork', carrier='district_heat')
+        ```
+
+        Using predefined carriers from CONFIG:
+
+        ```python
+        # Access built-in carriers
+        elec = fx.CONFIG.Carriers.electricity
+        heat = fx.CONFIG.Carriers.heat
+
+        # Use directly
+        bus = fx.Bus('Grid', carrier='electricity')
+        ```
+
+        Adding custom carriers to CONFIG:
+
+        ```python
+        # Add a new carrier globally
+        fx.CONFIG.Carriers.add(fx.Carrier('biogas', '#228B22', 'kW', 'Biogas'))
+
+        # Now available as
+        fx.CONFIG.Carriers.biogas
+        ```
+
+    Note:
+        Carriers are compared by name for equality, allowing flexible usage
+        patterns where the same carrier type can be referenced by name string
+        or Carrier object interchangeably.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        color: str = '',
+        unit: str = '',
+        description: str = '',
+    ) -> None:
+        """Initialize a Carrier.
+
+        Args:
+            name: Identifier for the carrier (normalized to lowercase).
+            color: Hex color string for visualizations.
+            unit: Unit string for display.
+            description: Optional human-readable description.
+        """
+        self.name = name.lower()
+        self.color = color
+        self.unit = unit
+        self.description = description
+
+    def transform_data(self, name_prefix: str = '') -> None:
+        """Transform data to match FlowSystem dimensions.
+
+        Carriers don't have time-series data, so this is a no-op.
+
+        Args:
+            name_prefix: Ignored for Carrier.
+        """
+        pass  # Carriers have no data to transform
+
+    @property
+    def label(self) -> str:
+        """Label for container keying (alias for name)."""
+        return self.name
+
+    def __hash__(self):
+        return hash(self.name)
+
+    def __eq__(self, other):
+        if isinstance(other, Carrier):
+            return self.name == other.name
+        if isinstance(other, str):
+            return self.name == other.lower()
+        return False
+
+    def __repr__(self):
+        return f"Carrier('{self.name}', color='{self.color}', unit='{self.unit}')"
+
+    def __str__(self):
+        return self.name
+
+
+class CarrierContainer(ContainerMixin['Carrier']):
+    """Container for Carrier objects.
+
+    Uses carrier.name for keying. Provides dict-like access to carriers
+    registered with a FlowSystem.
+
+    Examples:
+        ```python
+        # Access via FlowSystem
+        carriers = flow_system.carriers
+
+        # Dict-like access
+        elec = carriers['electricity']
+        'heat' in carriers  # True/False
+
+        # Iteration
+        for name in carriers:
+            print(name)
+        ```
+    """
+
+    def __init__(self, carriers: list[Carrier] | dict[str, Carrier] | None = None):
+        """Initialize a CarrierContainer.
+
+        Args:
+            carriers: Initial carriers to add.
+        """
+        super().__init__(elements=carriers, element_type_name='carriers')
+
+    def _get_label(self, carrier: Carrier) -> str:
+        """Extract name from Carrier for keying."""
+        return carrier.name

flixopt/clustering/__init__.py

@@ -0,0 +1,51 @@
+"""
+Time Series Aggregation Module for flixopt.
+
+This module provides wrapper classes around tsam's clustering functionality:
+- Clustering: Top-level class stored on FlowSystem after clustering
+- ClusteringResults: Manages collection of tsam ClusteringResult objects (for IO)
+
+Example usage:
+
+    # Cluster a FlowSystem to reduce timesteps
+    from tsam import ExtremeConfig
+
+    fs_clustered = flow_system.transform.cluster(
+        n_clusters=8,
+        cluster_duration='1D',
+        extremes=ExtremeConfig(method='new_cluster', max_value=['Demand|fixed_relative_profile']),
+    )
+
+    # Access clustering structure (available before AND after IO)
+    clustering = fs_clustered.clustering
+    print(f'Number of clusters: {clustering.n_clusters}')
+    print(f'Dims: {clustering.dims}')  # e.g., ('period', 'scenario')
+    print(f'Coords: {clustering.coords}')  # e.g., {'period': [2024, 2025]}
+
+    # Access tsam AggregationResult for detailed analysis
+    # NOTE: Only available BEFORE saving/loading. Lost after IO.
+    result = clustering.sel(period=2024, scenario='high')
+    result.cluster_representatives  # DataFrame with aggregated time series
+    result.accuracy  # AccuracyMetrics (rmse, mae)
+    result.plot.compare()  # tsam's built-in comparison plot
+
+    # Iterate over all results (only before IO)
+    for key, result in clustering.items():
+        print(f'{key}: {result.n_clusters} clusters')
+
+    # Save and load - structure preserved, AggregationResult access lost
+    fs_clustered.to_netcdf('system.nc')
+    # Use include_original_data=False for smaller files (~38% reduction)
+    fs_clustered.to_netcdf('system.nc', include_original_data=False)
+
+    # Expand back to full resolution
+    fs_expanded = fs_clustered.transform.expand()
+"""
+
+from .base import AggregationResults, Clustering, ClusteringResults
+
+__all__ = [
+    'ClusteringResults',
+    'AggregationResults',
+    'Clustering',
+]