Skip to content

Mathematical Notation

This section provides the mathematical formulations underlying FlixOpt's optimization models. It is intended as reference documentation for users who want to understand the mathematical details behind the high-level FlixOpt API described in the FlixOpt Concepts guide.

For typical usage, refer to the FlixOpt Concepts guide, Examples, and API Reference - you don't need to understand these mathematical formulations to use FlixOpt effectively.


Naming Conventions

FlixOpt uses the following naming conventions:

  • All optimization variables are denoted by italic letters (e.g., \(x\), \(y\), \(z\))
  • All parameters and constants are denoted by non italic small letters (e.g., \(\text{a}\), \(\text{b}\), \(\text{c}\))
  • All Sets are denoted by greek capital letters (e.g., \(\mathcal{F}\), \(\mathcal{E}\))
  • All units of a set are denoted by greek small letters (e.g., \(\mathcal{f}\), \(\mathcal{e}\))
  • The letter \(i\) is used to denote an index (e.g., \(i=1,\dots,\text n\))
  • All time steps are denoted by the letter \(\text{t}\) (e.g., \(\text{t}_0\), \(\text{t}_1\), \(\text{t}_i\))

Dimensions and Time Steps

FlixOpt supports multi-dimensional optimization with up to three dimensions: time (mandatory), period (optional), and scenario (optional).

All mathematical formulations in this documentation are independent of whether periods or scenarios are present. The equations shown are written with time index \(\text{t}_i\) only, but automatically expand to additional dimensions when periods/scenarios are added.

For complete details on dimensions, their relationships, and influence on formulations, see Dimensions.

Time Steps

Time steps are defined as a sequence of discrete time steps \(\text{t}_i \in \mathcal{T} \quad \text{for} \quad i \in \{1, 2, \dots, \text{n}\}\) (left-aligned in its timespan). From this sequence, the corresponding time intervals \(\Delta \text{t}_i \in \Delta \mathcal{T}\) are derived as

\[\Delta \text{t}_i = \text{t}_{i+1} - \text{t}_i \quad \text{for} \quad i \in \{1, 2, \dots, \text{n}-1\}\]

The final time interval \(\Delta \text{t}_\text n\) defaults to \(\Delta \text{t}_\text n = \Delta \text{t}_{\text n-1}\), but is of course customizable. Non-equidistant time steps are also supported.


Documentation Structure

This reference is organized to match the FlixOpt API structure:

Elements

Mathematical formulations for core FlixOpt elements (corresponding to flixopt.elements):

  • Flow - Flow rate constraints and bounds
  • Bus - Nodal balance equations
  • Storage - Storage balance and charge state evolution
  • LinearConverter - Linear conversion relationships

User API: When you create a Flow, Bus, Storage, or LinearConverter in your FlixOpt model, these mathematical formulations are automatically applied.

Features

Mathematical formulations for optional features (corresponding to parameters in FlixOpt classes):

User API: When you pass invest_parameters or on_off_parameters to a Flow or component, these formulations are applied.

System-Level

User API: When you create Effect objects and set effects_per_flow_hour, these formulations govern how costs are calculated.

Modeling Patterns (Advanced)

Internal implementation details - These low-level patterns are used internally by Elements and Features. They are documented here for:

  • Developers extending FlixOpt
  • Advanced users debugging models or understanding solver behavior
  • Researchers comparing mathematical formulations

Normal users do not need to read this section - the patterns are automatically applied when you use Elements and Features:


Quick Reference

Components Cross-Reference

Concept Documentation Python Class
Flow rate bounds Flow Flow
Bus balance Bus Bus
Storage balance Storage Storage
Linear conversion LinearConverter LinearConverter

Features Cross-Reference

Concept Documentation Python Class
Binary investment InvestParameters InvestParameters
On/off operation OnOffParameters OnOffParameters
Piecewise segments Piecewise Piecewise

Modeling Patterns Cross-Reference

Pattern Documentation Implementation
Basic bounds bounds-and-states BoundingPatterns.basic_bounds()
Bounds with state bounds-and-states BoundingPatterns.bounds_with_state()
Scaled bounds bounds-and-states BoundingPatterns.scaled_bounds()
Duration tracking duration-tracking ModelingPrimitives.consecutive_duration_tracking()
State transitions state-transitions BoundingPatterns.state_transition_bounds()

Python Class Lookup

Class Documentation API Reference
Flow Flow Flow
Bus Bus Bus
Storage Storage Storage
LinearConverter LinearConverter LinearConverter
InvestParameters InvestParameters InvestParameters
OnOffParameters OnOffParameters OnOffParameters
Piecewise Piecewise Piecewise