flixopt.calculation

This module contains the Calculation functionality for the flixopt framework. It is used to calculate a FlowSystemModel for a given FlowSystem through a solver. There are three different Calculation types: 1. FullCalculation: Calculates the FlowSystemModel for the full FlowSystem 2. AggregatedCalculation: Calculates the FlowSystemModel for the full FlowSystem, but aggregates the TimeSeriesData. This simplifies the mathematical model and usually speeds up the solving process. 3. SegmentedCalculation: Solves a FlowSystemModel for each individual Segment of the FlowSystem.

Attributes

Classes

Calculation

Calculation(name: str, flow_system: FlowSystem, active_timesteps: Annotated[DatetimeIndex | None, 'DEPRECATED: Use flow_system.sel(time=...) or flow_system.isel(time=...) instead'] = None, folder: Path | None = None, normalize_weights: bool = True)

class for defined way of solving a flow_system optimization

Parameters:

Name	Type	Description	Default
`name`	`str`	name of calculation	required
`flow_system`	`FlowSystem`	flow_system which should be calculated	required
`folder`	`Path \| None`	folder where results should be saved. If None, then the current working directory is used.	`None`
`normalize_weights`	`bool`	Whether to automatically normalize the weights (periods and scenarios) to sum up to 1 when solving.	`True`
`active_timesteps`	`Annotated[DatetimeIndex \| None, 'DEPRECATED: Use flow_system.sel(time=...) or flow_system.isel(time=...) instead']`	Deprecated. Use FlowSystem.sel(time=...) or FlowSystem.isel(time=...) instead.	`None`

FullCalculation

FullCalculation(name: str, flow_system: FlowSystem, active_timesteps: Annotated[DatetimeIndex | None, 'DEPRECATED: Use flow_system.sel(time=...) or flow_system.isel(time=...) instead'] = None, folder: Path | None = None, normalize_weights: bool = True)

Bases: Calculation

FullCalculation solves the complete optimization problem using all time steps.

This is the most comprehensive calculation type that considers every time step in the optimization, providing the most accurate but computationally intensive solution.

Parameters:

Name	Type	Description	Default
`name`	`str`	name of calculation	required
`flow_system`	`FlowSystem`	flow_system which should be calculated	required
`folder`	`Path \| None`	folder where results should be saved. If None, then the current working directory is used.	`None`
`normalize_weights`	`bool`	Whether to automatically normalize the weights (periods and scenarios) to sum up to 1 when solving.	`True`
`active_timesteps`	`Annotated[DatetimeIndex \| None, 'DEPRECATED: Use flow_system.sel(time=...) or flow_system.isel(time=...) instead']`	Deprecated. Use FlowSystem.sel(time=...) or FlowSystem.isel(time=...) instead.	`None`

Functions

fix_sizes

fix_sizes(ds: Dataset, decimal_rounding: int | None = 5) -> FullCalculation

Fix the sizes of the calculations to specified values.

Parameters:

Name	Type	Description	Default
`ds`	`Dataset`	The dataset that contains the variable names mapped to their sizes. If None, the dataset is loaded from the results.	required
`decimal_rounding`	`int \| None`	The number of decimal places to round the sizes to. If no rounding is applied, numerical errors might lead to infeasibility.	`5`

AggregatedCalculation

AggregatedCalculation(name: str, flow_system: FlowSystem, aggregation_parameters: AggregationParameters, components_to_clusterize: list[Component] | None = None, active_timesteps: Annotated[DatetimeIndex | None, 'DEPRECATED: Use flow_system.sel(time=...) or flow_system.isel(time=...) instead'] = None, folder: Path | None = None)

Bases: FullCalculation

AggregatedCalculation reduces computational complexity by clustering time series into typical periods.

This calculation approach aggregates time series data using clustering techniques (tsam) to identify representative time periods, significantly reducing computation time while maintaining solution accuracy.

Note

The quality of the solution depends on the choice of aggregation parameters. The optimal parameters depend on the specific problem and the characteristics of the time series data. For more information, refer to the tsam documentation.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the calculation	required
`flow_system`	`FlowSystem`	FlowSystem to be optimized	required
`aggregation_parameters`	`AggregationParameters`	Parameters for aggregation. See AggregationParameters class documentation	required
`components_to_clusterize`	`list[Component] \| None`	list of Components to perform aggregation on. If None, all components are aggregated. This equalizes variables in the components according to the typical periods computed in the aggregation	`None`
`active_timesteps`	`Annotated[DatetimeIndex \| None, 'DEPRECATED: Use flow_system.sel(time=...) or flow_system.isel(time=...) instead']`	DatetimeIndex of timesteps to use for calculation. If None, all timesteps are used	`None`
`folder`	`Path \| None`	Folder where results should be saved. If None, current working directory is used	`None`

Attributes:

Name	Type	Description
`aggregation`	`Aggregation \| None`	Contains the clustered time series data
`aggregation_model`	`AggregationModel \| None`	Contains Variables and Constraints that equalize clusters of the time series data

Functions

calculate_aggregation_weights `classmethod`

calculate_aggregation_weights(ds: Dataset) -> dict[str, float]

Calculate weights for all datavars in the dataset. Weights are pulled from the attrs of the datavars.

fix_sizes

fix_sizes(ds: Dataset, decimal_rounding: int | None = 5) -> FullCalculation

Fix the sizes of the calculations to specified values.

Parameters:

Name	Type	Description	Default
`ds`	`Dataset`	The dataset that contains the variable names mapped to their sizes. If None, the dataset is loaded from the results.	required
`decimal_rounding`	`int \| None`	The number of decimal places to round the sizes to. If no rounding is applied, numerical errors might lead to infeasibility.	`5`

SegmentedCalculation

SegmentedCalculation(name: str, flow_system: FlowSystem, timesteps_per_segment: int, overlap_timesteps: int, nr_of_previous_values: int = 1, folder: Path | None = None)

Bases: Calculation

Solve large optimization problems by dividing time horizon into (overlapping) segments.

This class addresses memory and computational limitations of large-scale optimization problems by decomposing the time horizon into smaller overlapping segments that are solved sequentially. Each segment uses final values from the previous segment as initial conditions, ensuring dynamic continuity across the solution.

Key Concepts

Temporal Decomposition: Divides long time horizons into manageable segments Overlapping Windows: Segments share timesteps to improve storage dynamics Value Transfer: Final states of one segment become initial states of the next Sequential Solving: Each segment solved independently but with coupling

Limitations and Constraints

Investment Parameters: InvestParameters are not supported in segmented calculations as investment decisions must be made for the entire time horizon, not per segment.

Global Constraints: Time-horizon-wide constraints (flow_hours_total_min/max, load_factor_min/max) may produce suboptimal results as they cannot be enforced globally across segments.

Storage Dynamics: While overlap helps, storage optimization may be suboptimal compared to full-horizon solutions due to limited foresight in each segment.

Parameters:

Name	Type	Description	Default
`name`	`str`	Unique identifier for the calculation, used in result files and logging.	required
`flow_system`	`FlowSystem`	The FlowSystem to optimize, containing all components, flows, and buses.	required
`timesteps_per_segment`	`int`	Number of timesteps in each segment (excluding overlap). Must be > 2 to avoid internal side effects. Larger values provide better optimization at the cost of memory and computation time.	required
`overlap_timesteps`	`int`	Number of additional timesteps added to each segment. Improves storage optimization by providing lookahead. Higher values improve solution quality but increase computational cost.	required
`nr_of_previous_values`	`int`	Number of previous timestep values to transfer between segments for initialization. Typically 1 is sufficient.	`1`
`folder`	`Path \| None`	Directory for saving results. Defaults to current working directory + 'results'.	`None`

Examples:

Annual optimization with monthly segments:

# 8760 hours annual data with monthly segments (730 hours) and 48-hour overlap
segmented_calc = SegmentedCalculation(
    name='annual_energy_system',
    flow_system=energy_system,
    timesteps_per_segment=730,  # ~1 month
    overlap_timesteps=48,  # 2 days overlap
    folder=Path('results/segmented'),
)
segmented_calc.do_modeling_and_solve(solver='gurobi')

Weekly optimization with daily overlap:

# Weekly segments for detailed operational planning
weekly_calc = SegmentedCalculation(
    name='weekly_operations',
    flow_system=industrial_system,
    timesteps_per_segment=168,  # 1 week (hourly data)
    overlap_timesteps=24,  # 1 day overlap
    nr_of_previous_values=1,
)

Large-scale system with minimal overlap:

# Large system with minimal overlap for computational efficiency
large_calc = SegmentedCalculation(
    name='large_scale_grid',
    flow_system=grid_system,
    timesteps_per_segment=100,  # Shorter segments
    overlap_timesteps=5,  # Minimal overlap
)

Design Considerations

Segment Size: Balance between solution quality and computational efficiency. Larger segments provide better optimization but require more memory and time.

Overlap Duration: More overlap improves storage dynamics and reduces end-effects but increases computational cost. Typically 5-10% of segment length.

Storage Systems: Systems with large storage components benefit from longer overlaps to capture charge/discharge cycles effectively.

Investment Decisions: Use FullCalculation for problems requiring investment optimization, as SegmentedCalculation cannot handle investment parameters.

Common Use Cases

Annual Planning: Long-term planning with seasonal variations
Large Networks: Spatially or temporally large energy systems
Memory-Limited Systems: When full optimization exceeds available memory
Operational Planning: Detailed short-term optimization with limited foresight
Sensitivity Analysis: Quick approximate solutions for parameter studies

Performance Tips

Start with FullCalculation and use this class if memory issues occur
Use longer overlaps for systems with significant storage
Monitor solution quality at segment boundaries for discontinuities

Warning

The evaluation of the solution is a bit more complex than FullCalculation or AggregatedCalculation due to the overlapping individual solutions.

Attributes

start_values_of_segments `property`

start_values_of_segments: list[dict[str, Any]]

Gives an overview of the start values of all Segments

flixopt.calculation

Attributes

Classes

Calculation

FullCalculation

Functions

fix_sizes

AggregatedCalculation

Functions

calculate_aggregation_weights classmethod

fix_sizes

SegmentedCalculation

Attributes

start_values_of_segments property

Functions

calculate_aggregation_weights `classmethod`

start_values_of_segments `property`