flixopt 2.2.0rc2__py3-none-any.whl → 3.0.1__py3-none-any.whl

flixopt/core.py

@@ -3,12 +3,10 @@ This module contains the core functionality of the flixopt framework.
 It provides Datatypes, logging functionality, and some functions to transform data structures.
 """
 
-import inspect
-import json
 import logging
-import pathlib
-from collections import Counter
-from typing import Any, Dict, Iterator, List, Literal, Optional, Tuple, Union
+import warnings
+from itertools import permutations
+from typing import Any, Literal, Union
 
 import numpy as np
 import pandas as pd
@@ -16,14 +14,17 @@ import xarray as xr
 
 logger = logging.getLogger('flixopt')
 
-Scalar = Union[int, float]
-"""A type representing a single number, either integer or float."""
+Scalar = int | float
+"""A single number, either integer or float."""
 
-NumericData = Union[int, float, np.integer, np.floating, np.ndarray, pd.Series, pd.DataFrame, xr.DataArray]
-"""Represents any form of numeric data, from simple scalars to complex data structures."""
+PeriodicDataUser = int | float | np.integer | np.floating | np.ndarray | pd.Series | pd.DataFrame | xr.DataArray
+"""User data which has no time dimension. Internally converted to a Scalar or an xr.DataArray without a time dimension."""
 
-NumericDataTS = Union[NumericData, 'TimeSeriesData']
-"""Represents either standard numeric data or TimeSeriesData."""
+PeriodicData = xr.DataArray
+"""Internally used datatypes for periodic data."""
+
+FlowSystemDimensions = Literal['time', 'period', 'scenario']
+"""Possible dimensions of a FlowSystem."""
 
 
 class PlausibilityError(Exception):
@@ -38,941 +39,607 @@ class ConversionError(Exception):
     pass
 
 
-class DataConverter:
-    """
-    Converts various data types into xarray.DataArray with a timesteps index.
-
-    Supports: scalars, arrays, Series, DataFrames, and DataArrays.
-    """
-
-    @staticmethod
-    def as_dataarray(data: NumericData, timesteps: pd.DatetimeIndex) -> xr.DataArray:
-        """Convert data to xarray.DataArray with specified timesteps index."""
-        if not isinstance(timesteps, pd.DatetimeIndex) or len(timesteps) == 0:
-            raise ValueError(f'Timesteps must be a non-empty DatetimeIndex, got {type(timesteps).__name__}')
-        if not timesteps.name == 'time':
-            raise ConversionError(f'DatetimeIndex is not named correctly. Must be named "time", got {timesteps.name=}')
-
-        coords = [timesteps]
-        dims = ['time']
-        expected_shape = (len(timesteps),)
+class TimeSeriesData(xr.DataArray):
+    """Minimal TimeSeriesData that inherits from xr.DataArray with aggregation metadata."""
 
-        try:
-            if isinstance(data, (int, float, np.integer, np.floating)):
-                return xr.DataArray(data, coords=coords, dims=dims)
-            elif isinstance(data, pd.DataFrame):
-                if not data.index.equals(timesteps):
-                    raise ConversionError(
-                        f"DataFrame index doesn't match timesteps index. "
-                        f'Its missing the following time steps: {timesteps.difference(data.index)}. '
-                        f'Some parameters might need an extra timestep at the end.'
-                    )
-                if not len(data.columns) == 1:
-                    raise ConversionError('DataFrame must have exactly one column')
-                return xr.DataArray(data.values.flatten(), coords=coords, dims=dims)
-            elif isinstance(data, pd.Series):
-                if not data.index.equals(timesteps):
-                    raise ConversionError(
-                        f"Series index doesn't match timesteps index. "
-                        f'Its missing the following time steps: {timesteps.difference(data.index)}. '
-                        f'Some parameters might need an extra timestep at the end.'
-                    )
-                return xr.DataArray(data.values, coords=coords, dims=dims)
-            elif isinstance(data, np.ndarray):
-                if data.ndim != 1:
-                    raise ConversionError(f'Array must be 1-dimensional, got {data.ndim}')
-                elif data.shape[0] != expected_shape[0]:
-                    raise ConversionError(f"Array shape {data.shape} doesn't match expected {expected_shape}")
-                return xr.DataArray(data, coords=coords, dims=dims)
-            elif isinstance(data, xr.DataArray):
-                if data.dims != tuple(dims):
-                    raise ConversionError(f"DataArray dimensions {data.dims} don't match expected {dims}")
-                if data.sizes[dims[0]] != len(coords[0]):
-                    raise ConversionError(
-                        f"DataArray length {data.sizes[dims[0]]} doesn't match expected {len(coords[0])}"
-                    )
-                return data.copy(deep=True)
-            else:
-                raise ConversionError(f'Unsupported type: {type(data).__name__}')
-        except Exception as e:
-            if isinstance(e, ConversionError):
-                raise
-            raise ConversionError(f'Converting data {type(data)} to xarray.Dataset raised an error: {str(e)}') from e
-
-
-class TimeSeriesData:
-    # TODO: Move to Interface.py
-    def __init__(self, data: NumericData, agg_group: Optional[str] = None, agg_weight: Optional[float] = None):
-        """
-        timeseries class for transmit timeseries AND special characteristics of timeseries,
-        i.g. to define weights needed in calculation_type 'aggregated'
-            EXAMPLE solar:
-            you have several solar timeseries. These should not be overweighted
-            compared to the remaining timeseries (i.g. heat load, price)!
-            fixed_relative_profile_solar1 = TimeSeriesData(sol_array_1, type = 'solar')
-            fixed_relative_profile_solar2 = TimeSeriesData(sol_array_2, type = 'solar')
-            fixed_relative_profile_solar3 = TimeSeriesData(sol_array_3, type = 'solar')
-            --> this 3 series of same type share one weight, i.e. internally assigned each weight = 1/3
-            (instead of standard weight = 1)
-
-        Args:
-            data: The timeseries data, which can be a scalar, array, or numpy array.
-            agg_group: The group this TimeSeriesData is a part of. agg_weight is split between members of a group. Default is None.
-            agg_weight: The weight for calculation_type 'aggregated', should be between 0 and 1. Default is None.
-
-        Raises:
-            Exception: If both agg_group and agg_weight are set, an exception is raised.
-        """
-        self.data = data
-        self.agg_group = agg_group
-        self.agg_weight = agg_weight
-        if (agg_group is not None) and (agg_weight is not None):
-            raise ValueError('Either <agg_group> or explicit <agg_weigth> can be used. Not both!')
-        self.label: Optional[str] = None
-
-    def __repr__(self):
-        # Get the constructor arguments and their current values
-        init_signature = inspect.signature(self.__init__)
-        init_args = init_signature.parameters
-
-        # Create a dictionary with argument names and their values
-        args_str = ', '.join(f'{name}={repr(getattr(self, name, None))}' for name in init_args if name != 'self')
-        return f'{self.__class__.__name__}({args_str})'
-
-    def __str__(self):
-        return str(self.data)
-
-
-class TimeSeries:
-    """
-    A class representing time series data with active and stored states.
-
-    TimeSeries provides a way to store time-indexed data and work with temporal subsets.
-    It supports arithmetic operations, aggregation, and JSON serialization.
-
-    Attributes:
-        name (str): The name of the time series
-        aggregation_weight (Optional[float]): Weight used for aggregation
-        aggregation_group (Optional[str]): Group name for shared aggregation weighting
-        needs_extra_timestep (bool): Whether this series needs an extra timestep
-    """
-
-    @classmethod
-    def from_datasource(
-        cls,
-        data: NumericData,
-        name: str,
-        timesteps: pd.DatetimeIndex,
-        aggregation_weight: Optional[float] = None,
-        aggregation_group: Optional[str] = None,
-        needs_extra_timestep: bool = False,
-    ) -> 'TimeSeries':
-        """
-        Initialize the TimeSeries from multiple data sources.
-
-        Args:
-            data: The time series data
-            name: The name of the TimeSeries
-            timesteps: The timesteps of the TimeSeries
-            aggregation_weight: The weight in aggregation calculations
-            aggregation_group: Group this TimeSeries belongs to for aggregation weight sharing
-            needs_extra_timestep: Whether this series requires an extra timestep
-
-        Returns:
-            A new TimeSeries instance
-        """
-        return cls(
-            DataConverter.as_dataarray(data, timesteps),
-            name,
-            aggregation_weight,
-            aggregation_group,
-            needs_extra_timestep,
-        )
-
-    @classmethod
-    def from_json(cls, data: Optional[Dict[str, Any]] = None, path: Optional[str] = None) -> 'TimeSeries':
-        """
-        Load a TimeSeries from a dictionary or json file.
-
-        Args:
-            data: Dictionary containing TimeSeries data
-            path: Path to a JSON file containing TimeSeries data
-
-        Returns:
-            A new TimeSeries instance
-
-        Raises:
-            ValueError: If both path and data are provided or neither is provided
-        """
-        if (path is None and data is None) or (path is not None and data is not None):
-            raise ValueError("Exactly one of 'path' or 'data' must be provided")
-
-        if path is not None:
-            with open(path, 'r') as f:
-                data = json.load(f)
-
-        # Convert ISO date strings to datetime objects
-        data['data']['coords']['time']['data'] = pd.to_datetime(data['data']['coords']['time']['data'])
-
-        # Create the TimeSeries instance
-        return cls(
-            data=xr.DataArray.from_dict(data['data']),
-            name=data['name'],
-            aggregation_weight=data['aggregation_weight'],
-            aggregation_group=data['aggregation_group'],
-            needs_extra_timestep=data['needs_extra_timestep'],
-        )
+    __slots__ = ()  # No additional instance attributes - everything goes in attrs
 
     def __init__(
         self,
-        data: xr.DataArray,
-        name: str,
-        aggregation_weight: Optional[float] = None,
-        aggregation_group: Optional[str] = None,
-        needs_extra_timestep: bool = False,
+        *args: Any,
+        aggregation_group: str | None = None,
+        aggregation_weight: float | None = None,
+        agg_group: str | None = None,
+        agg_weight: float | None = None,
+        **kwargs: Any,
     ):
         """
-        Initialize a TimeSeries with a DataArray.
-
-        Args:
-            data: The DataArray containing time series data
-            name: The name of the TimeSeries
-            aggregation_weight: The weight in aggregation calculations
-            aggregation_group: Group this TimeSeries belongs to for weight sharing
-            needs_extra_timestep: Whether this series requires an extra timestep
-
-        Raises:
-            ValueError: If data doesn't have a 'time' index or has more than 1 dimension
-        """
-        if 'time' not in data.indexes:
-            raise ValueError(f'DataArray must have a "time" index. Got {data.indexes}')
-        if data.ndim > 1:
-            raise ValueError(f'Number of dimensions of DataArray must be 1. Got {data.ndim}')
-
-        self.name = name
-        self.aggregation_weight = aggregation_weight
-        self.aggregation_group = aggregation_group
-        self.needs_extra_timestep = needs_extra_timestep
-
-        # Data management
-        self._stored_data = data.copy(deep=True)
-        self._backup = self._stored_data.copy(deep=True)
-        self._active_timesteps = self._stored_data.indexes['time']
-        self._active_data = None
-        self._update_active_data()
-
-    def reset(self):
-        """
-        Reset active timesteps to the full set of stored timesteps.
-        """
-        self.active_timesteps = None
-
-    def restore_data(self):
-        """
-        Restore stored_data from the backup and reset active timesteps.
-        """
-        self._stored_data = self._backup.copy(deep=True)
-        self.reset()
-
-    def to_json(self, path: Optional[pathlib.Path] = None) -> Dict[str, Any]:
-        """
-        Save the TimeSeries to a dictionary or JSON file.
-
         Args:
-            path: Optional path to save JSON file
-
-        Returns:
-            Dictionary representation of the TimeSeries
-        """
-        data = {
-            'name': self.name,
-            'aggregation_weight': self.aggregation_weight,
-            'aggregation_group': self.aggregation_group,
-            'needs_extra_timestep': self.needs_extra_timestep,
-            'data': self.active_data.to_dict(),
-        }
-
-        # Convert datetime objects to ISO strings
-        data['data']['coords']['time']['data'] = [date.isoformat() for date in data['data']['coords']['time']['data']]
-
-        # Save to file if path is provided
-        if path is not None:
-            indent = 4 if len(self.active_timesteps) <= 480 else None
-            with open(path, 'w', encoding='utf-8') as f:
-                json.dump(data, f, indent=indent, ensure_ascii=False)
-
-        return data
-
-    @property
-    def stats(self) -> str:
-        """
-        Return a statistical summary of the active data.
-
-        Returns:
-            String representation of data statistics
-        """
-        return get_numeric_stats(self.active_data, padd=0)
-
-    def _update_active_data(self):
-        """
-        Update the active data based on active_timesteps.
-        """
-        self._active_data = self._stored_data.sel(time=self.active_timesteps)
+            *args: Arguments passed to DataArray
+            aggregation_group: Aggregation group name
+            aggregation_weight: Aggregation weight (0-1)
+            agg_group: Deprecated, use aggregation_group instead
+            agg_weight: Deprecated, use aggregation_weight instead
+            **kwargs: Additional arguments passed to DataArray
+        """
+        if agg_group is not None:
+            warnings.warn('agg_group is deprecated, use aggregation_group instead', DeprecationWarning, stacklevel=2)
+            aggregation_group = agg_group
+        if agg_weight is not None:
+            warnings.warn('agg_weight is deprecated, use aggregation_weight instead', DeprecationWarning, stacklevel=2)
+            aggregation_weight = agg_weight
+
+        if (aggregation_group is not None) and (aggregation_weight is not None):
+            raise ValueError('Use either aggregation_group or aggregation_weight, not both')
+
+        # Let xarray handle all the initialization complexity
+        super().__init__(*args, **kwargs)
+
+        # Add our metadata to attrs after initialization
+        if aggregation_group is not None:
+            self.attrs['aggregation_group'] = aggregation_group
+        if aggregation_weight is not None:
+            self.attrs['aggregation_weight'] = aggregation_weight
+
+        # Always mark as TimeSeriesData
+        self.attrs['__timeseries_data__'] = True
+
+    def fit_to_coords(
+        self,
+        coords: dict[str, pd.Index],
+        name: str | None = None,
+    ) -> 'TimeSeriesData':
+        """Fit the data to the given coordinates. Returns a new TimeSeriesData object if the current coords are different."""
+        if self.coords.equals(xr.Coordinates(coords)):
+            return self
+
+        da = DataConverter.to_dataarray(self.data, coords=coords)
+        return self.__class__(
+            da,
+            aggregation_group=self.aggregation_group,
+            aggregation_weight=self.aggregation_weight,
+            name=name if name is not None else self.name,
+        )
 
     @property
-    def all_equal(self) -> bool:
-        """Check if all values in the series are equal."""
-        return np.unique(self.active_data.values).size == 1
+    def aggregation_group(self) -> str | None:
+        return self.attrs.get('aggregation_group')
 
     @property
-    def active_timesteps(self) -> pd.DatetimeIndex:
-        """Get the current active timesteps."""
-        return self._active_timesteps
+    def aggregation_weight(self) -> float | None:
+        return self.attrs.get('aggregation_weight')
 
-    @active_timesteps.setter
-    def active_timesteps(self, timesteps: Optional[pd.DatetimeIndex]):
-        """
-        Set active_timesteps and refresh active_data.
-
-        Args:
-            timesteps: New timesteps to activate, or None to use all stored timesteps
-
-        Raises:
-            TypeError: If timesteps is not a pandas DatetimeIndex or None
-        """
-        if timesteps is None:
-            self._active_timesteps = self.stored_data.indexes['time']
-        elif isinstance(timesteps, pd.DatetimeIndex):
-            self._active_timesteps = timesteps
-        else:
-            raise TypeError('active_timesteps must be a pandas DatetimeIndex or None')
-
-        self._update_active_data()
-
-    @property
-    def active_data(self) -> xr.DataArray:
-        """Get a view of stored_data based on active_timesteps."""
-        return self._active_data
-
-    @property
-    def stored_data(self) -> xr.DataArray:
-        """Get a copy of the full stored data."""
-        return self._stored_data.copy()
+    @classmethod
+    def from_dataarray(
+        cls, da: xr.DataArray, aggregation_group: str | None = None, aggregation_weight: float | None = None
+    ):
+        """Create TimeSeriesData from DataArray, extracting metadata from attrs."""
+        # Get aggregation metadata from attrs or parameters
+        final_aggregation_group = (
+            aggregation_group if aggregation_group is not None else da.attrs.get('aggregation_group')
+        )
+        final_aggregation_weight = (
+            aggregation_weight if aggregation_weight is not None else da.attrs.get('aggregation_weight')
+        )
 
-    @stored_data.setter
-    def stored_data(self, value: NumericData):
-        """
-        Update stored_data and refresh active_data.
+        return cls(da, aggregation_group=final_aggregation_group, aggregation_weight=final_aggregation_weight)
 
-        Args:
-            value: New data to store
-        """
-        new_data = DataConverter.as_dataarray(value, timesteps=self.active_timesteps)
+    @classmethod
+    def is_timeseries_data(cls, obj) -> bool:
+        """Check if an object is TimeSeriesData."""
+        return isinstance(obj, xr.DataArray) and obj.attrs.get('__timeseries_data__', False)
 
-        # Skip if data is unchanged to avoid overwriting backup
-        if new_data.equals(self._stored_data):
-            return
+    def __repr__(self):
+        agg_info = []
+        if self.aggregation_group:
+            agg_info.append(f"aggregation_group='{self.aggregation_group}'")
+        if self.aggregation_weight is not None:
+            agg_info.append(f'aggregation_weight={self.aggregation_weight}')
 
-        self._stored_data = new_data
-        self.active_timesteps = None  # Reset to full timeline
+        info_str = f'TimeSeriesData({", ".join(agg_info)})' if agg_info else 'TimeSeriesData'
+        return f'{info_str}\n{super().__repr__()}'
 
     @property
-    def sel(self):
-        return self.active_data.sel
+    def agg_group(self):
+        warnings.warn('agg_group is deprecated, use aggregation_group instead', DeprecationWarning, stacklevel=2)
+        return self.aggregation_group
 
     @property
-    def isel(self):
-        return self.active_data.isel
-
-    def _apply_operation(self, other, op):
-        """Apply an operation between this TimeSeries and another object."""
-        if isinstance(other, TimeSeries):
-            other = other.active_data
-        return op(self.active_data, other)
+    def agg_weight(self):
+        warnings.warn('agg_weight is deprecated, use aggregation_weight instead', DeprecationWarning, stacklevel=2)
+        return self.aggregation_weight
 
-    def __add__(self, other):
-        return self._apply_operation(other, lambda x, y: x + y)
 
-    def __sub__(self, other):
-        return self._apply_operation(other, lambda x, y: x - y)
+TemporalDataUser = (
+    int | float | np.integer | np.floating | np.ndarray | pd.Series | pd.DataFrame | xr.DataArray | TimeSeriesData
+)
+"""User data which might have a time dimension. Internally converted to an xr.DataArray with time dimension."""
 
-    def __mul__(self, other):
-        return self._apply_operation(other, lambda x, y: x * y)
+TemporalData = xr.DataArray | TimeSeriesData
+"""Internally used datatypes for temporal data (data with a time dimension)."""
 
-    def __truediv__(self, other):
-        return self._apply_operation(other, lambda x, y: x / y)
 
-    def __radd__(self, other):
-        return other + self.active_data
-
-    def __rsub__(self, other):
-        return other - self.active_data
-
-    def __rmul__(self, other):
-        return other * self.active_data
-
-    def __rtruediv__(self, other):
-        return other / self.active_data
-
-    def __neg__(self) -> xr.DataArray:
-        return -self.active_data
-
-    def __pos__(self) -> xr.DataArray:
-        return +self.active_data
-
-    def __abs__(self) -> xr.DataArray:
-        return abs(self.active_data)
-
-    def __gt__(self, other):
-        """
-        Compare if this TimeSeries is greater than another.
-
-        Args:
-            other: Another TimeSeries to compare with
+class DataConverter:
+    """
+    Converts various data types into xarray.DataArray with specified target coordinates.
+
+    This converter handles intelligent dimension matching and broadcasting to ensure
+    the output DataArray always conforms to the specified coordinate structure.
+
+    Supported input types:
+    - Scalars: int, float, np.number (broadcast to all target dimensions)
+    - 1D data: np.ndarray, pd.Series, single-column DataFrame (matched by length/index)
+    - Multi-dimensional arrays: np.ndarray, DataFrame (matched by shape)
+    - xr.DataArray: validated and potentially broadcast to target dimensions
+
+    The converter uses smart matching strategies:
+    - Series: matched by exact index comparison
+    - 1D arrays: matched by length to target coordinates
+    - Multi-dimensional arrays: matched by shape permutation analysis
+    - DataArrays: validated for compatibility and broadcast as needed
+    """
 
-        Returns:
-            True if all values in this TimeSeries are greater than other
+    @staticmethod
+    def _match_series_by_index_alignment(
+        data: pd.Series, target_coords: dict[str, pd.Index], target_dims: tuple[str, ...]
+    ) -> xr.DataArray:
         """
-        if isinstance(other, TimeSeries):
-            return self.active_data > other.active_data
-        return self.active_data > other
+        Match pandas Series to target dimension by exact index comparison.
 
-    def __ge__(self, other):
-        """
-        Compare if this TimeSeries is greater than or equal to another.
+        Attempts to find a target dimension whose coordinates exactly match
+        the Series index values, ensuring proper alignment.
 
         Args:
-            other: Another TimeSeries to compare with
+            data: pandas Series to convert
+            target_coords: Available target coordinates {dim_name: coordinate_index}
+            target_dims: Target dimension names to consider for matching
 
         Returns:
-            True if all values in this TimeSeries are greater than or equal to other
-        """
-        if isinstance(other, TimeSeries):
-            return self.active_data >= other.active_data
-        return self.active_data >= other
-
-    def __lt__(self, other):
-        """
-        Compare if this TimeSeries is less than another.
+            DataArray with Series matched to the appropriate dimension
 
-        Args:
-            other: Another TimeSeries to compare with
+        Raises:
+            ConversionError: If Series cannot be matched to any target dimension,
+                           or if no target dimensions provided for multi-element Series
+        """
+        # Handle edge case: no target dimensions
+        if len(target_dims) == 0:
+            if len(data) != 1:
+                raise ConversionError(
+                    f'Cannot convert multi-element Series without target dimensions. '
+                    f'Series has {len(data)} elements but no target dimensions specified.'
+                )
+            return xr.DataArray(data.iloc[0])
+
+        # Attempt exact index matching with each target dimension
+        for dim_name in target_dims:
+            target_index = target_coords[dim_name]
+            if data.index.equals(target_index):
+                return xr.DataArray(data.values.copy(), coords={dim_name: target_index}, dims=dim_name)
+
+        # No exact matches found
+        available_lengths = {dim: len(target_coords[dim]) for dim in target_dims}
+        raise ConversionError(
+            f'Series index does not match any target dimension coordinates. '
+            f'Series length: {len(data)}, available coordinate lengths: {available_lengths}'
+        )
 
-        Returns:
-            True if all values in this TimeSeries are less than other
+    @staticmethod
+    def _match_1d_array_by_length(
+        data: np.ndarray, target_coords: dict[str, pd.Index], target_dims: tuple[str, ...]
+    ) -> xr.DataArray:
         """
-        if isinstance(other, TimeSeries):
-            return self.active_data < other.active_data
-        return self.active_data < other
+        Match 1D numpy array to target dimension by length comparison.
 
-    def __le__(self, other):
-        """
-        Compare if this TimeSeries is less than or equal to another.
+        Finds target dimensions whose coordinate length matches the array length.
+        Requires unique length match to avoid ambiguity.
 
         Args:
-            other: Another TimeSeries to compare with
+            data: 1D numpy array to convert
+            target_coords: Available target coordinates {dim_name: coordinate_index}
+            target_dims: Target dimension names to consider for matching
 
         Returns:
-            True if all values in this TimeSeries are less than or equal to other
-        """
-        if isinstance(other, TimeSeries):
-            return self.active_data <= other.active_data
-        return self.active_data <= other
-
-    def __eq__(self, other):
-        """
-        Compare if this TimeSeries is equal to another.
+            DataArray with array matched to the uniquely identified dimension
 
-        Args:
-            other: Another TimeSeries to compare with
+        Raises:
+            ConversionError: If array length matches zero or multiple target dimensions,
+                           or if no target dimensions provided for multi-element array
+        """
+        # Handle edge case: no target dimensions
+        if len(target_dims) == 0:
+            if len(data) != 1:
+                raise ConversionError(
+                    f'Cannot convert multi-element array without target dimensions. Array has {len(data)} elements.'
+                )
+            return xr.DataArray(data[0])
+
+        # Find all dimensions with matching lengths
+        array_length = len(data)
+        matching_dims = []
+        coordinate_lengths = {}
+
+        for dim_name in target_dims:
+            coord_length = len(target_coords[dim_name])
+            coordinate_lengths[dim_name] = coord_length
+            if array_length == coord_length:
+                matching_dims.append(dim_name)
+
+        # Validate matching results
+        if len(matching_dims) == 0:
+            raise ConversionError(
+                f'Array length {array_length} does not match any target dimension lengths: {coordinate_lengths}'
+            )
+        elif len(matching_dims) > 1:
+            raise ConversionError(
+                f'Array length {array_length} matches multiple dimensions: {matching_dims}. '
+                f'Cannot uniquely determine target dimension. Consider using explicit '
+                f'dimension specification or converting to DataArray manually.'
+            )
 
-        Returns:
-            True if all values in this TimeSeries are equal to other
-        """
-        if isinstance(other, TimeSeries):
-            return self.active_data == other.active_data
-        return self.active_data == other
+        # Create DataArray with the uniquely matched dimension
+        matched_dim = matching_dims[0]
+        return xr.DataArray(data.copy(), coords={matched_dim: target_coords[matched_dim]}, dims=matched_dim)
 
-    def __array_ufunc__(self, ufunc, method, *inputs, **kwargs):
+    @staticmethod
+    def _match_multidim_array_by_shape_permutation(
+        data: np.ndarray, target_coords: dict[str, pd.Index], target_dims: tuple[str, ...]
+    ) -> xr.DataArray:
         """
-        Handle NumPy universal functions.
+        Match multi-dimensional array to target dimensions using shape permutation analysis.
 
-        This allows NumPy functions to work with TimeSeries objects.
-        """
-        # Convert any TimeSeries inputs to their active_data
-        inputs = [x.active_data if isinstance(x, TimeSeries) else x for x in inputs]
-        return getattr(ufunc, method)(*inputs, **kwargs)
+        Analyzes all possible mappings between array shape and target coordinate lengths
+        to find the unique valid dimension assignment.
 
-    def __repr__(self):
-        """
-        Get a string representation of the TimeSeries.
+        Args:
+            data: Multi-dimensional numpy array to convert
+            target_coords: Available target coordinates {dim_name: coordinate_index}
+            target_dims: Target dimension names to consider for matching
 
         Returns:
-            String showing TimeSeries details
-        """
-        attrs = {
-            'name': self.name,
-            'aggregation_weight': self.aggregation_weight,
-            'aggregation_group': self.aggregation_group,
-            'needs_extra_timestep': self.needs_extra_timestep,
-            'shape': self.active_data.shape,
-            'time_range': f'{self.active_timesteps[0]} to {self.active_timesteps[-1]}',
-        }
-        attr_str = ', '.join(f'{k}={repr(v)}' for k, v in attrs.items())
-        return f'TimeSeries({attr_str})'
-
-    def __str__(self):
-        """
-        Get a human-readable string representation.
+            DataArray with array dimensions mapped to target dimensions by shape
 
-        Returns:
-            Descriptive string with statistics
-        """
-        return f"TimeSeries '{self.name}': {self.stats}"
+        Raises:
+            ConversionError: If array shape cannot be uniquely mapped to target dimensions,
+                           or if no target dimensions provided for multi-element array
+        """
+        # Handle edge case: no target dimensions
+        if len(target_dims) == 0:
+            if data.size != 1:
+                raise ConversionError(
+                    f'Cannot convert multi-element array without target dimensions. '
+                    f'Array has {data.size} elements with shape {data.shape}.'
+                )
+            return xr.DataArray(data.item())
+
+        array_shape = data.shape
+        coordinate_lengths = {dim: len(target_coords[dim]) for dim in target_dims}
+
+        # Find all valid dimension permutations that match the array shape
+        valid_mappings = []
+        for dim_permutation in permutations(target_dims, data.ndim):
+            shape_matches = all(
+                array_shape[i] == coordinate_lengths[dim_permutation[i]] for i in range(len(dim_permutation))
+            )
+            if shape_matches:
+                valid_mappings.append(dim_permutation)
+
+        # Validate mapping results
+        if len(valid_mappings) == 0:
+            raise ConversionError(
+                f'Array shape {array_shape} cannot be mapped to any combination of target '
+                f'coordinate lengths: {coordinate_lengths}. Consider reshaping the array '
+                f'or adjusting target coordinates.'
+            )
 
+        if len(valid_mappings) > 1:
+            raise ConversionError(
+                f'Array shape {array_shape} matches multiple dimension combinations: '
+                f'{valid_mappings}. Cannot uniquely determine dimension mapping. '
+                f'Consider using explicit dimension specification.'
+            )
 
-class TimeSeriesCollection:
-    """
-    Collection of TimeSeries objects with shared timestep management.
+        # Create DataArray with the uniquely determined mapping
+        matched_dims = valid_mappings[0]
+        matched_coords = {dim: target_coords[dim] for dim in matched_dims}
 
-    TimeSeriesCollection handles multiple TimeSeries objects with synchronized
-    timesteps, provides operations on collections, and manages extra timesteps.
-    """
+        return xr.DataArray(data.copy(), coords=matched_coords, dims=matched_dims)
 
-    def __init__(
-        self,
-        timesteps: pd.DatetimeIndex,
-        hours_of_last_timestep: Optional[float] = None,
-        hours_of_previous_timesteps: Optional[Union[float, np.ndarray]] = None,
-    ):
-        """
-        Args:
-            timesteps: The timesteps of the Collection.
-            hours_of_last_timestep: The duration of the last time step. Uses the last time interval if not specified
-            hours_of_previous_timesteps: The duration of previous timesteps.
-                If None, the first time increment of time_series is used.
-                This is needed to calculate previous durations (for example consecutive_on_hours).
-                If you use an array, take care that its long enough to cover all previous values!
+    @staticmethod
+    def _broadcast_dataarray_to_target_specification(
+        source_data: xr.DataArray, target_coords: dict[str, pd.Index], target_dims: tuple[str, ...]
+    ) -> xr.DataArray:
         """
-        # Prepare and validate timesteps
-        self._validate_timesteps(timesteps)
-        self.hours_of_previous_timesteps = self._calculate_hours_of_previous_timesteps(
-            timesteps, hours_of_previous_timesteps
-        )
-
-        # Set up timesteps and hours
-        self.all_timesteps = timesteps
-        self.all_timesteps_extra = self._create_timesteps_with_extra(timesteps, hours_of_last_timestep)
-        self.all_hours_per_timestep = self.calculate_hours_per_timestep(self.all_timesteps_extra)
-
-        # Active timestep tracking
-        self._active_timesteps = None
-        self._active_timesteps_extra = None
-        self._active_hours_per_timestep = None
+        Broadcast DataArray to conform to target coordinate and dimension specification.
 
-        # Dictionary of time series by name
-        self.time_series_data: Dict[str, TimeSeries] = {}
-
-        # Aggregation
-        self.group_weights: Dict[str, float] = {}
-        self.weights: Dict[str, float] = {}
-
-    @classmethod
-    def with_uniform_timesteps(
-        cls, start_time: pd.Timestamp, periods: int, freq: str, hours_per_step: Optional[float] = None
-    ) -> 'TimeSeriesCollection':
-        """Create a collection with uniform timesteps."""
-        timesteps = pd.date_range(start_time, periods=periods, freq=freq, name='time')
-        return cls(timesteps, hours_of_previous_timesteps=hours_per_step)
-
-    def create_time_series(
-        self, data: Union[NumericData, TimeSeriesData], name: str, needs_extra_timestep: bool = False
-    ) -> TimeSeries:
-        """
-        Creates a TimeSeries from the given data and adds it to the collection.
+        Performs comprehensive validation and broadcasting to ensure the result exactly
+        matches the target specification. Handles scalar expansion, dimension validation,
+        coordinate compatibility checking, and broadcasting to additional dimensions.
 
         Args:
-            data: The data to create the TimeSeries from.
-            name: The name of the TimeSeries.
-            needs_extra_timestep: Whether to create an additional timestep at the end of the timesteps.
-            The data to create the TimeSeries from.
+            source_data: Source DataArray to broadcast
+            target_coords: Target coordinates {dim_name: coordinate_index}
+            target_dims: Target dimension names in desired order
 
         Returns:
-            The created TimeSeries.
+            DataArray broadcast to target specification with proper dimension ordering
 
-        """
-        # Check for duplicate name
-        if name in self.time_series_data:
-            raise ValueError(f"TimeSeries '{name}' already exists in this collection")
-
-        # Determine which timesteps to use
-        timesteps_to_use = self.timesteps_extra if needs_extra_timestep else self.timesteps
-
-        # Create the time series
-        if isinstance(data, TimeSeriesData):
-            time_series = TimeSeries.from_datasource(
-                name=name,
-                data=data.data,
-                timesteps=timesteps_to_use,
-                aggregation_weight=data.agg_weight,
-                aggregation_group=data.agg_group,
-                needs_extra_timestep=needs_extra_timestep,
-            )
-            # Connect the user time series to the created TimeSeries
-            data.label = name
-        else:
-            time_series = TimeSeries.from_datasource(
-                name=name, data=data, timesteps=timesteps_to_use, needs_extra_timestep=needs_extra_timestep
+        Raises:
+            ConversionError: If broadcasting is impossible due to incompatible dimensions
+                           or coordinate mismatches
+        """
+        # Validate: cannot reduce dimensions
+        if len(source_data.dims) > len(target_dims):
+            raise ConversionError(
+                f'Cannot reduce DataArray dimensionality from {len(source_data.dims)} '
+                f'to {len(target_dims)} dimensions. Source dims: {source_data.dims}, '
+                f'target dims: {target_dims}'
             )
 
-        # Add to the collection
-        self.add_time_series(time_series)
+        # Validate: all source dimensions must exist in target
+        missing_dims = set(source_data.dims) - set(target_dims)
+        if missing_dims:
+            raise ConversionError(
+                f'Source DataArray has dimensions {missing_dims} not present in target dimensions {target_dims}'
+            )
 
-        return time_series
+        # Validate: coordinate compatibility for overlapping dimensions
+        for dim in source_data.dims:
+            if dim in source_data.coords and dim in target_coords:
+                source_coords = source_data.coords[dim]
+                target_coords_for_dim = target_coords[dim]
 
-    def calculate_aggregation_weights(self) -> Dict[str, float]:
-        """Calculate and return aggregation weights for all time series."""
-        self.group_weights = self._calculate_group_weights()
-        self.weights = self._calculate_weights()
+                if not np.array_equal(source_coords.values, target_coords_for_dim.values):
+                    raise ConversionError(
+                        f'Coordinate mismatch for dimension "{dim}". '
+                        f'Source and target coordinates have different values.'
+                    )
 
-        if np.all(np.isclose(list(self.weights.values()), 1, atol=1e-6)):
-            logger.info('All Aggregation weights were set to 1')
+        # Create target template for broadcasting
+        target_shape = [len(target_coords[dim]) for dim in target_dims]
+        target_template = xr.DataArray(np.empty(target_shape), coords=target_coords, dims=target_dims)
 
-        return self.weights
+        # Perform broadcasting and ensure proper dimension ordering
+        broadcasted = source_data.broadcast_like(target_template)
+        return broadcasted.transpose(*target_dims)
 
-    def activate_timesteps(self, active_timesteps: Optional[pd.DatetimeIndex] = None):
-        """
-        Update active timesteps for the collection and all time series.
-        If no arguments are provided, the active timesteps are reset.
+    @classmethod
+    def to_dataarray(
+        cls,
+        data: int
+        | float
+        | bool
+        | np.integer
+        | np.floating
+        | np.bool_
+        | np.ndarray
+        | pd.Series
+        | pd.DataFrame
+        | xr.DataArray,
+        coords: dict[str, pd.Index] | None = None,
+    ) -> xr.DataArray:
+        """
+        Convert various data types to xarray.DataArray with specified target coordinates.
+
+        This is the main conversion method that intelligently handles different input types
+        and ensures the result conforms to the specified coordinate structure through
+        smart dimension matching and broadcasting.
 
         Args:
-            active_timesteps: The active timesteps of the model.
-                If None, the all timesteps of the TimeSeriesCollection are taken.
-        """
-        if active_timesteps is None:
-            return self.reset()
-
-        if not np.all(np.isin(active_timesteps, self.all_timesteps)):
-            raise ValueError('active_timesteps must be a subset of the timesteps of the TimeSeriesCollection')
-
-        # Calculate derived timesteps
-        self._active_timesteps = active_timesteps
-        first_ts_index = np.where(self.all_timesteps == active_timesteps[0])[0][0]
-        last_ts_idx = np.where(self.all_timesteps == active_timesteps[-1])[0][0]
-        self._active_timesteps_extra = self.all_timesteps_extra[first_ts_index : last_ts_idx + 2]
-        self._active_hours_per_timestep = self.all_hours_per_timestep.isel(time=slice(first_ts_index, last_ts_idx + 1))
-
-        # Update all time series
-        self._update_time_series_timesteps()
+            data: Input data to convert. Supported types:
+                - Scalars: int, float, bool, np.integer, np.floating, np.bool_
+                - Arrays: np.ndarray (1D and multi-dimensional)
+                - Pandas: pd.Series, pd.DataFrame
+                - xarray: xr.DataArray
+            coords: Target coordinate specification as {dimension_name: coordinate_index}.
+                   All coordinate indices must be pandas.Index objects.
 
-    def reset(self):
-        """Reset active timesteps to defaults for all time series."""
-        self._active_timesteps = None
-        self._active_timesteps_extra = None
-        self._active_hours_per_timestep = None
-
-        for time_series in self.time_series_data.values():
-            time_series.reset()
-
-    def restore_data(self):
-        """Restore original data for all time series."""
-        for time_series in self.time_series_data.values():
-            time_series.restore_data()
-
-    def add_time_series(self, time_series: TimeSeries):
-        """Add an existing TimeSeries to the collection."""
-        if time_series.name in self.time_series_data:
-            raise ValueError(f"TimeSeries '{time_series.name}' already exists in this collection")
+        Returns:
+            DataArray conforming to the target coordinate specification,
+            with input data appropriately matched and broadcast
 
-        self.time_series_data[time_series.name] = time_series
+        Raises:
+            ConversionError: If data type is unsupported, conversion fails,
+                           or broadcasting to target coordinates is impossible
+
+        Examples:
+            # Scalar broadcasting
+            >>> coords = {'x': pd.Index([1, 2, 3]), 'y': pd.Index(['a', 'b'])}
+            >>> converter.to_dataarray(42, coords)
+            # Returns: DataArray with shape (3, 2), all values = 42
+
+            # Series index matching
+            >>> series = pd.Series([10, 20, 30], index=[1, 2, 3])
+            >>> converter.to_dataarray(series, coords)
+            # Returns: DataArray matched to 'x' dimension, broadcast to 'y'
+
+            # Array shape matching
+            >>> array = np.array([[1, 2], [3, 4], [5, 6]])  # Shape (3, 2)
+            >>> converter.to_dataarray(array, coords)
+            # Returns: DataArray with dimensions ('x', 'y') based on shape
+        """
+        # Prepare and validate target specification
+        if coords is None:
+            coords = {}
+
+        validated_coords, target_dims = cls._validate_and_prepare_target_coordinates(coords)
+
+        # Convert input data to intermediate DataArray based on type
+        if isinstance(data, (int, float, bool, np.integer, np.floating, np.bool_)):
+            # Scalar values - create scalar DataArray
+            intermediate = xr.DataArray(data.item() if hasattr(data, 'item') else data)
+
+        elif isinstance(data, np.ndarray):
+            # NumPy arrays - dispatch based on dimensionality
+            if data.ndim == 0:
+                # 0-dimensional array (scalar)
+                intermediate = xr.DataArray(data.item())
+            elif data.ndim == 1:
+                # 1-dimensional array
+                intermediate = cls._match_1d_array_by_length(data, validated_coords, target_dims)
+            else:
+                # Multi-dimensional array
+                intermediate = cls._match_multidim_array_by_shape_permutation(data, validated_coords, target_dims)
+
+        elif isinstance(data, pd.Series):
+            # Pandas Series - validate and match by index
+            if isinstance(data.index, pd.MultiIndex):
+                raise ConversionError('MultiIndex Series are not supported. Please use a single-level index.')
+            intermediate = cls._match_series_by_index_alignment(data, validated_coords, target_dims)
+
+        elif isinstance(data, pd.DataFrame):
+            # Pandas DataFrame - validate and convert
+            if isinstance(data.index, pd.MultiIndex):
+                raise ConversionError('MultiIndex DataFrames are not supported. Please use a single-level index.')
+            if len(data.columns) == 0 or data.empty:
+                raise ConversionError('DataFrame must have at least one column and cannot be empty.')
+
+            if len(data.columns) == 1:
+                # Single-column DataFrame - treat as Series
+                series_data = data.iloc[:, 0]
+                intermediate = cls._match_series_by_index_alignment(series_data, validated_coords, target_dims)
+            else:
+                # Multi-column DataFrame - treat as multi-dimensional array
+                intermediate = cls._match_multidim_array_by_shape_permutation(
+                    data.to_numpy(), validated_coords, target_dims
+                )
 
-    def insert_new_data(self, data: pd.DataFrame, include_extra_timestep: bool = False):
-        """
-        Update time series with new data from a DataFrame.
+        elif isinstance(data, xr.DataArray):
+            # Existing DataArray - use as-is
+            intermediate = data.copy()
 
-        Args:
-            data: DataFrame containing new data with timestamps as index
-            include_extra_timestep: Whether the provided data already includes the extra timestep, by default False
-        """
-        if not isinstance(data, pd.DataFrame):
-            raise TypeError(f'data must be a pandas DataFrame, got {type(data).__name__}')
-
-        # Check if the DataFrame index matches the expected timesteps
-        expected_timesteps = self.timesteps_extra if include_extra_timestep else self.timesteps
-        if not data.index.equals(expected_timesteps):
-            raise ValueError(
-                f'DataFrame index must match {"collection timesteps with extra timestep" if include_extra_timestep else "collection timesteps"}'
+        else:
+            # Unsupported data type
+            supported_types = [
+                'int',
+                'float',
+                'bool',
+                'np.integer',
+                'np.floating',
+                'np.bool_',
+                'np.ndarray',
+                'pd.Series',
+                'pd.DataFrame',
+                'xr.DataArray',
+            ]
+            raise ConversionError(
+                f'Unsupported data type: {type(data).__name__}. Supported types: {", ".join(supported_types)}'
             )
 
-        for name, ts in self.time_series_data.items():
-            if name in data.columns:
-                if not ts.needs_extra_timestep:
-                    # For time series without extra timestep
-                    if include_extra_timestep:
-                        # If data includes extra timestep but series doesn't need it, exclude the last point
-                        ts.stored_data = data[name].iloc[:-1]
-                    else:
-                        # Use data as is
-                        ts.stored_data = data[name]
-                else:
-                    # For time series with extra timestep
-                    if include_extra_timestep:
-                        # Data already includes extra timestep
-                        ts.stored_data = data[name]
-                    else:
-                        # Need to add extra timestep - extrapolate from the last value
-                        extra_step_value = data[name].iloc[-1]
-                        extra_step_index = pd.DatetimeIndex([self.timesteps_extra[-1]], name='time')
-                        extra_step_series = pd.Series([extra_step_value], index=extra_step_index)
-
-                        # Combine the regular data with the extra timestep
-                        ts.stored_data = pd.concat([data[name], extra_step_series])
-
-                logger.debug(f'Updated data for {name}')
-
-    def to_dataframe(
-        self, filtered: Literal['all', 'constant', 'non_constant'] = 'non_constant', include_extra_timestep: bool = True
-    ) -> pd.DataFrame:
-        """
-        Convert collection to DataFrame with optional filtering and timestep control.
-
-        Args:
-            filtered: Filter time series by variability, by default 'non_constant'
-            include_extra_timestep: Whether to include the extra timestep in the result, by default True
+        # Broadcast intermediate result to target specification
+        return cls._broadcast_dataarray_to_target_specification(intermediate, validated_coords, target_dims)
 
-        Returns:
-            DataFrame representation of the collection
+    @staticmethod
+    def _validate_and_prepare_target_coordinates(
+        coords: dict[str, pd.Index],
+    ) -> tuple[dict[str, pd.Index], tuple[str, ...]]:
         """
-        include_constants = filtered != 'non_constant'
-        ds = self.to_dataset(include_constants=include_constants)
-
-        if not include_extra_timestep:
-            ds = ds.isel(time=slice(None, -1))
-
-        df = ds.to_dataframe()
-
-        # Apply filtering
-        if filtered == 'all':
-            return df
-        elif filtered == 'constant':
-            return df.loc[:, df.nunique() == 1]
-        elif filtered == 'non_constant':
-            return df.loc[:, df.nunique() > 1]
-        else:
-            raise ValueError("filtered must be one of: 'all', 'constant', 'non_constant'")
+        Validate and prepare target coordinate specification for DataArray creation.
 
-    def to_dataset(self, include_constants: bool = True) -> xr.Dataset:
-        """
-        Combine all time series into a single Dataset with all timesteps.
+        Performs comprehensive validation of coordinate inputs and prepares them
+        for use in DataArray construction with appropriate naming and type checking.
 
         Args:
-            include_constants: Whether to include time series with constant values, by default True
+            coords: Raw coordinate specification {dimension_name: coordinate_index}
 
         Returns:
-            Dataset containing all selected time series with all timesteps
-        """
-        # Determine which series to include
-        if include_constants:
-            series_to_include = self.time_series_data.values()
-        else:
-            series_to_include = self.non_constants
-
-        # Create individual datasets and merge them
-        ds = xr.merge([ts.active_data.to_dataset(name=ts.name) for ts in series_to_include])
-
-        # Ensure the correct time coordinates
-        ds = ds.reindex(time=self.timesteps_extra)
-
-        ds.attrs.update(
-            {
-                'timesteps_extra': f'{self.timesteps_extra[0]} ... {self.timesteps_extra[-1]} | len={len(self.timesteps_extra)}',
-                'hours_per_timestep': self._format_stats(self.hours_per_timestep),
-            }
-        )
-
-        return ds
-
-    def _update_time_series_timesteps(self):
-        """Update active timesteps for all time series."""
-        for ts in self.time_series_data.values():
-            if ts.needs_extra_timestep:
-                ts.active_timesteps = self.timesteps_extra
-            else:
-                ts.active_timesteps = self.timesteps
+            Tuple of (validated_coordinates_dict, dimension_names_tuple)
 
-    @staticmethod
-    def _validate_timesteps(timesteps: pd.DatetimeIndex):
-        """Validate timesteps format and rename if needed."""
-        if not isinstance(timesteps, pd.DatetimeIndex):
-            raise TypeError('timesteps must be a pandas DatetimeIndex')
-
-        if len(timesteps) < 2:
-            raise ValueError('timesteps must contain at least 2 timestamps')
-
-        # Ensure timesteps has the required name
-        if timesteps.name != 'time':
-            logger.warning('Renamed timesteps to "time" (was "%s")', timesteps.name)
-            timesteps.name = 'time'
-
-    @staticmethod
-    def _create_timesteps_with_extra(
-        timesteps: pd.DatetimeIndex, hours_of_last_timestep: Optional[float]
-    ) -> pd.DatetimeIndex:
-        """Create timesteps with an extra step at the end."""
-        if hours_of_last_timestep is not None:
-            # Create the extra timestep using the specified duration
-            last_date = pd.DatetimeIndex([timesteps[-1] + pd.Timedelta(hours=hours_of_last_timestep)], name='time')
-        else:
-            # Use the last interval as the extra timestep duration
-            last_date = pd.DatetimeIndex([timesteps[-1] + (timesteps[-1] - timesteps[-2])], name='time')
-
-        # Combine with original timesteps
-        return pd.DatetimeIndex(timesteps.append(last_date), name='time')
-
-    @staticmethod
-    def _calculate_hours_of_previous_timesteps(
-        timesteps: pd.DatetimeIndex, hours_of_previous_timesteps: Optional[Union[float, np.ndarray]]
-    ) -> Union[float, np.ndarray]:
-        """Calculate duration of regular timesteps."""
-        if hours_of_previous_timesteps is not None:
-            return hours_of_previous_timesteps
+        Raises:
+            ConversionError: If any coordinates are invalid, improperly typed,
+                           or have inconsistent naming
+        """
+        validated_coords = {}
+        dimension_names = []
 
-        # Calculate from the first interval
-        first_interval = timesteps[1] - timesteps[0]
-        return first_interval.total_seconds() / 3600  # Convert to hours
+        for dim_name, coord_index in coords.items():
+            # Type validation
+            if not isinstance(coord_index, pd.Index):
+                raise ConversionError(
+                    f'Coordinate for dimension "{dim_name}" must be a pandas.Index, got {type(coord_index).__name__}'
+                )
 
-    @staticmethod
-    def calculate_hours_per_timestep(timesteps_extra: pd.DatetimeIndex) -> xr.DataArray:
-        """Calculate duration of each timestep."""
-        # Calculate differences between consecutive timestamps
-        hours_per_step = np.diff(timesteps_extra) / pd.Timedelta(hours=1)
+            # Non-empty validation
+            if len(coord_index) == 0:
+                raise ConversionError(f'Coordinate for dimension "{dim_name}" cannot be empty')
 
-        return xr.DataArray(
-            data=hours_per_step, coords={'time': timesteps_extra[:-1]}, dims=('time',), name='hours_per_step'
-        )
-
-    def _calculate_group_weights(self) -> Dict[str, float]:
-        """Calculate weights for aggregation groups."""
-        # Count series in each group
-        groups = [ts.aggregation_group for ts in self.time_series_data.values() if ts.aggregation_group is not None]
-        group_counts = Counter(groups)
-
-        # Calculate weight for each group (1/count)
-        return {group: 1 / count for group, count in group_counts.items()}
-
-    def _calculate_weights(self) -> Dict[str, float]:
-        """Calculate weights for all time series."""
-        # Calculate weight for each time series
-        weights = {}
-        for name, ts in self.time_series_data.items():
-            if ts.aggregation_group is not None:
-                # Use group weight
-                weights[name] = self.group_weights.get(ts.aggregation_group, 1)
-            else:
-                # Use individual weight or default to 1
-                weights[name] = ts.aggregation_weight or 1
+            # Ensure coordinate index has consistent naming
+            if coord_index.name != dim_name:
+                coord_index = coord_index.rename(dim_name)
 
-        return weights
+            # Special validation for time dimensions (common pattern)
+            if dim_name == 'time' and not isinstance(coord_index, pd.DatetimeIndex):
+                raise ConversionError(
+                    f'Dimension named "time" should use DatetimeIndex for proper '
+                    f'time-series functionality, got {type(coord_index).__name__}'
+                )
 
-    def _format_stats(self, data) -> str:
-        """Format statistics for a data array."""
-        if hasattr(data, 'values'):
-            values = data.values
-        else:
-            values = np.asarray(data)
+            validated_coords[dim_name] = coord_index
+            dimension_names.append(dim_name)
 
-        mean_val = np.mean(values)
-        min_val = np.min(values)
-        max_val = np.max(values)
+        return validated_coords, tuple(dimension_names)
 
-        return f'mean: {mean_val:.2f}, min: {min_val:.2f}, max: {max_val:.2f}'
 
-    def __getitem__(self, name: str) -> TimeSeries:
-        """Get a TimeSeries by name."""
+def get_dataarray_stats(arr: xr.DataArray) -> dict:
+    """Generate statistical summary of a DataArray."""
+    stats = {}
+    if arr.dtype.kind in 'biufc':  # bool, int, uint, float, complex
         try:
-            return self.time_series_data[name]
-        except KeyError as e:
-            raise KeyError(f'TimeSeries "{name}" not found in the TimeSeriesCollection') from e
-
-    def __iter__(self) -> Iterator[TimeSeries]:
-        """Iterate through all TimeSeries in the collection."""
-        return iter(self.time_series_data.values())
-
-    def __len__(self) -> int:
-        """Get the number of TimeSeries in the collection."""
-        return len(self.time_series_data)
-
-    def __contains__(self, item: Union[str, TimeSeries]) -> bool:
-        """Check if a TimeSeries exists in the collection."""
-        if isinstance(item, str):
-            return item in self.time_series_data
-        elif isinstance(item, TimeSeries):
-            return any([item is ts for ts in self.time_series_data.values()])
-        return False
+            stats.update(
+                {
+                    'min': float(arr.min().values),
+                    'max': float(arr.max().values),
+                    'mean': float(arr.mean().values),
+                    'median': float(arr.median().values),
+                    'std': float(arr.std().values),
+                    'count': int(arr.count().values),  # non-null count
+                }
+            )
 
-    @property
-    def non_constants(self) -> List[TimeSeries]:
-        """Get time series with varying values."""
-        return [ts for ts in self.time_series_data.values() if not ts.all_equal]
+            # Add null count only if there are nulls
+            null_count = int(arr.isnull().sum().values)
+            if null_count > 0:
+                stats['nulls'] = null_count
 
-    @property
-    def constants(self) -> List[TimeSeries]:
-        """Get time series with constant values."""
-        return [ts for ts in self.time_series_data.values() if ts.all_equal]
+        except Exception:
+            pass
 
-    @property
-    def timesteps(self) -> pd.DatetimeIndex:
-        """Get the active timesteps."""
-        return self.all_timesteps if self._active_timesteps is None else self._active_timesteps
+    return stats
 
-    @property
-    def timesteps_extra(self) -> pd.DatetimeIndex:
-        """Get the active timesteps with extra step."""
-        return self.all_timesteps_extra if self._active_timesteps_extra is None else self._active_timesteps_extra
 
-    @property
-    def hours_per_timestep(self) -> xr.DataArray:
-        """Get the duration of each active timestep."""
-        return (
-            self.all_hours_per_timestep if self._active_hours_per_timestep is None else self._active_hours_per_timestep
-        )
+def drop_constant_arrays(ds: xr.Dataset, dim: str = 'time', drop_arrays_without_dim: bool = True) -> xr.Dataset:
+    """Drop variables with constant values along a dimension.
 
-    @property
-    def hours_of_last_timestep(self) -> float:
-        """Get the duration of the last timestep."""
-        return float(self.hours_per_timestep[-1].item())
-
-    def __repr__(self):
-        return f'TimeSeriesCollection:\n{self.to_dataset()}'
-
-    def __str__(self):
-        longest_name = max([time_series.name for time_series in self.time_series_data], key=len)
+    Args:
+        ds: Input dataset to filter.
+        dim: Dimension along which to check for constant values.
+        drop_arrays_without_dim: If True, also drop variables that don't have the specified dimension.
 
-        stats_summary = '\n'.join(
-            [
-                f'  - {time_series.name:<{len(longest_name)}}: {get_numeric_stats(time_series.active_data)}'
-                for time_series in self.time_series_data
-            ]
+    Returns:
+        Dataset with constant variables removed.
+    """
+    drop_vars = []
+
+    for name, da in ds.data_vars.items():
+        # Skip variables without the dimension
+        if dim not in da.dims:
+            if drop_arrays_without_dim:
+                drop_vars.append(name)
+            continue
+
+        # Check if variable is constant along the dimension
+        if (da.max(dim, skipna=True) == da.min(dim, skipna=True)).all().item():
+            drop_vars.append(name)
+
+    if drop_vars:
+        drop_vars = sorted(drop_vars)
+        logger.debug(
+            f'Dropping {len(drop_vars)} constant/dimension-less arrays: {drop_vars[:5]}{"..." if len(drop_vars) > 5 else ""}'
         )
 
-        return (
-            f'TimeSeriesCollection with {len(self.time_series_data)} series\n'
-            f'  Time Range: {self.timesteps[0]} → {self.timesteps[-1]}\n'
-            f'  No. of timesteps: {len(self.timesteps)} + 1 extra\n'
-            f'  Hours per timestep: {get_numeric_stats(self.hours_per_timestep)}\n'
-            f'  Time Series Data:\n'
-            f'{stats_summary}'
-        )
+    return ds.drop_vars(drop_vars)
 
 
-def get_numeric_stats(data: xr.DataArray, decimals: int = 2, padd: int = 10) -> str:
-    """Calculates the mean, median, min, max, and standard deviation of a numeric DataArray."""
-    format_spec = f'>{padd}.{decimals}f' if padd else f'.{decimals}f'
-    if np.unique(data).size == 1:
-        return f'{data.max().item():{format_spec}} (constant)'
-    mean = data.mean().item()
-    median = data.median().item()
-    min_val = data.min().item()
-    max_val = data.max().item()
-    std = data.std().item()
-    return f'{mean:{format_spec}} (mean), {median:{format_spec}} (median), {min_val:{format_spec}} (min), {max_val:{format_spec}} (max), {std:{format_spec}} (std)'
+# Backward compatibility aliases
+# TODO: Needed?
+NonTemporalDataUser = PeriodicDataUser
+NonTemporalData = PeriodicData