flixopt.flow_system ¶

Calculate duration of each timestep in hours as a 1D DataArray.

For RangeIndex (segmented systems), returns None since duration cannot be computed from the index. Use timestep_duration parameter instead.

Calculate weight of each period from period index differences.

Parameters:

Returns:

Convert the FlowSystem to an xarray Dataset. Ensures FlowSystem is connected before serialization.

Data is stored in minimal form (scalars stay scalar, 1D arrays stay 1D) without broadcasting to full model dimensions. This provides significant memory savings for multi-period and multi-scenario models.

If a solution is present and include_solution=True, it will be included in the dataset with variable names prefixed by 'solution|' to avoid conflicts with FlowSystem configuration variables. Solution time coordinates are renamed to 'solution_time' to preserve them independently of the FlowSystem's time coordinates.

Parameters:

Returns:

Create a FlowSystem from an xarray Dataset.

If the dataset contains solution data (variables prefixed with 'solution|'), the solution will be restored to the FlowSystem. Solution time coordinates are renamed back from 'solution_time' to 'time'.

Supports clustered datasets with (cluster, time) dimensions. When detected, creates a synthetic DatetimeIndex for compatibility and stores the clustered data structure for later use.

Parameters:

Returns:

Save the FlowSystem to a NetCDF file. Ensures FlowSystem is connected before saving.

The FlowSystem's name is automatically set from the filename (without extension) when saving.

Parameters:

Raises:

Load a FlowSystem from a NetCDF file.

The FlowSystem's name is automatically derived from the filename (without extension), overriding any name that may have been stored.

Parameters:

Returns:

Load a FlowSystem from old-format Results files (pre-v5 API).

This method loads results saved with the deprecated Results API (which used multiple files: *--flow_system.nc4, *--solution.nc4) and converts them to a FlowSystem with the solution attached.

The method performs the following:

• Loads the old multi-file format
• Renames deprecated parameters in the FlowSystem structure (e.g., on_off_parameters → status_parameters)
• Attaches the solution data to the FlowSystem

Parameters:

Returns:

Examples:

# Load old results
fs = FlowSystem.from_old_results('results_folder', 'my_optimization')

# Access basic solution data
fs.solution['Boiler(Q_th)|flow_rate'].plot()

# Save in new single-file format
fs.to_netcdf('my_optimization.nc')

Load a FlowSystem from an old-format dataset file (pre-v5 API).

This method loads a FlowSystem saved with older versions of flixopt (the *--flow_system.nc4 file) and converts parameter names to the current API. Unlike :meth:from_old_results, this does not require a solution file and returns a FlowSystem without solution data.

The method performs the following:

• Loads the old netCDF format
• Renames deprecated parameters in the FlowSystem structure (e.g., on_off_parameters → status_parameters)

Parameters:

Returns:

Examples:

# Load old FlowSystem file
fs = FlowSystem.from_old_dataset('results/my_run--flow_system.nc4')

# Modify and optimize with current API
fs.optimize(solver)

# Save in new single-file format
fs.to_netcdf('my_run.nc')

Create a copy of the FlowSystem without optimization state.

Creates a new FlowSystem with copies of all elements, but without: - The solution dataset - The optimization model - Element submodels and variable/constraint names

This is useful for creating variations of a FlowSystem for different optimization scenarios without affecting the original.

Returns:

Examples:

>>> original = FlowSystem(timesteps)
>>> original.add_elements(boiler, bus)
>>> original.optimize(solver)  # Original now has solution
>>>
>>> # Create a copy to try different parameters
>>> variant = original.copy()  # No solution, can be modified
>>> variant.add_elements(new_component)
>>> variant.optimize(solver)

Get FlowSystem structure. Ensures FlowSystem is connected before getting structure.

Parameters:

Save the flow system to a JSON file. Ensures FlowSystem is connected before saving.

Parameters:

Fit data to model coordinate system (currently time, but extensible).

Parameters:

Returns:

Transform EffectValues from the user to Internal Datatypes aligned with model coordinates.

Connect the network and transform all element data to model coordinates.

This method performs the following steps:

1. Connects flows to buses (establishing the network topology)
2. Registers any missing carriers from CONFIG defaults
3. Assigns colors to elements without explicit colors
4. Transforms all element data to xarray DataArrays aligned with FlowSystem coordinates (time, period, scenario)
5. Validates system integrity

This is called automatically by :meth:build_model and :meth:optimize.

Add Components(Storages, Boilers, Heatpumps, ...), Buses or Effects to the FlowSystem

Parameters:

Raises:

Register a custom carrier for this FlowSystem.

Custom carriers registered on the FlowSystem take precedence over CONFIG.Carriers defaults when resolving colors and units for buses.

Parameters:

Raises:

Examples:

import flixopt as fx

fs = fx.FlowSystem(timesteps)

# Define and register custom carriers
biogas = fx.Carrier('biogas', '#228B22', 'kW', 'Biogas fuel')
fs.add_carriers(biogas)

# Now buses can reference this carrier by name
bus = fx.Bus('BioGasNetwork', carrier='biogas')
fs.add_elements(bus)

# The carrier color will be used in plots automatically

Get the carrier for a bus or flow.

Parameters:

Returns:

Raises:

Create a linopy model from the FlowSystem.

Parameters:

Build the optimization model for this FlowSystem.

This method prepares the FlowSystem for optimization by: 1. Connecting and transforming all elements (if not already done) 2. Creating the FlowSystemModel with all variables and constraints 3. Adding clustering constraints (if this is a clustered FlowSystem) 4. Adding typical periods modeling (if this is a reduced FlowSystem)

After calling this method, self.model will be available for inspection before solving.

Parameters:

Returns:

Examples:

>>> flow_system.build_model()
>>> print(flow_system.model.variables)  # Inspect variables before solving
>>> flow_system.solve(solver)

Solve the optimization model and populate the solution.

This method solves the previously built model using the specified solver. After solving, self.solution will contain the optimization results, and each element's .solution property will provide access to its specific variables.

Parameters:

Returns:

Raises:

Examples:

>>> flow_system.build_model()
>>> flow_system.solve(HighsSolver())
>>> print(flow_system.solution)

Get variable names matching any of the specified categories.

Parameters:

Returns:

Clear optimization state to allow modifications.

This method unlocks the FlowSystem by clearing: - The solution dataset - The optimization model - All element submodels and variable/constraint names - The connected_and_transformed flag

After calling reset(), the FlowSystem can be modified again (e.g., adding elements or carriers).

Returns:

Examples:

>>> flow_system.optimize(solver)  # FlowSystem is now locked
>>> flow_system.add_elements(new_bus)  # Raises RuntimeError
>>> flow_system.reset()  # Unlock the FlowSystem
>>> flow_system.add_elements(new_bus)  # Now works

Invalidate the model to allow re-transformation after modifying elements.

Call this after modifying existing element attributes (e.g., flow.size, flow.relative_minimum) to ensure changes take effect on the next optimization. The next call to :meth:optimize or :meth:build_model will re-run :meth:connect_and_transform.

Returns:

Raises:

Examples:

Modify a flow's size and re-optimize:

>>> flow_system.optimize(solver)
>>> flow_system.reset()  # Clear solution first
>>> flow_system.components['Boiler'].inputs[0].size = 200
>>> flow_system.invalidate()
>>> flow_system.optimize(solver)  # Re-runs connect_and_transform

Modify before first optimization:

>>> flow_system.connect_and_transform()
>>> # Oops, need to change something
>>> flow_system.components['Boiler'].inputs[0].size = 200
>>> flow_system.invalidate()
>>> flow_system.optimize(solver)  # Changes take effect

Deprecated: Use flow_system.topology.plot() instead.

Visualizes the network structure of a FlowSystem using PyVis.

Deprecated: Use flow_system.topology.start_app() instead.

Visualizes the network structure using Dash and Cytoscape.

Deprecated: Use flow_system.topology.stop_app() instead.

Stop the network visualization server.

Deprecated: Use flow_system.topology.infos() instead.

Get network topology information as dictionaries.

Sum data over temporal dimensions with full temporal weighting.

Applies both timestep_duration and cluster_weight, then sums over temporal dimensions. Use this to convert rates to totals (e.g., flow_rate → total_energy).

Parameters:

Returns:

Select a subset of the flowsystem by label.

.. deprecated:: Use flow_system.transform.sel() instead. Will be removed in v6.0.0.

Parameters:

Returns:

Select a subset of the flowsystem by integer indices.

.. deprecated:: Use flow_system.transform.isel() instead. Will be removed in v6.0.0.

Parameters:

Returns:

Create a resampled FlowSystem by resampling data along the time dimension.

.. deprecated:: Use flow_system.transform.resample() instead. Will be removed in v6.0.0.

Parameters:

Returns:

Return all element labels across all containers.

Return all element objects across all containers.

Return (label, element) pairs for all elements.

Transform the data of the interface to match the FlowSystem's dimensions.

Uses self._prefix (set during link_to_flow_system()) to name transformed data.

Raises:

Link this interface and all nested interfaces to a FlowSystem.

This method is called automatically during element registration to enable elements to access FlowSystem properties without passing the reference through every method call. It also sets the prefix used for naming transformed data.

Subclasses with nested Interface objects should override this method to propagate the link to their nested interfaces by calling super().link_to_flow_system(flow_system, prefix) first, then linking nested objects with appropriate prefixes.

Parameters:

Examples:

Override in a subclass with nested interfaces:

def link_to_flow_system(self, flow_system, prefix: str = '') -> None:
    super().link_to_flow_system(flow_system, prefix)
    if self.nested_interface is not None:
        self.nested_interface.link_to_flow_system(flow_system, f'{prefix}|nested' if prefix else 'nested')

Creating an Interface dynamically during modeling:

# In a Model class
if flow.status_parameters is None:
    flow.status_parameters = StatusParameters()
    flow.status_parameters.link_to_flow_system(self._model.flow_system, f'{flow.label_full}')