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
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):
- InvestParameters - Investment decision modeling
- OnOffParameters - Binary on/off operation
- Piecewise - Piecewise linear approximations
User API: When you pass invest_parameters
or on_off_parameters
to a Flow
or component, these formulations are applied.
System-Level
- Effects, Penalty & Objective - Cost allocation and objective function
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:
- Bounds and States - Variable bounding patterns
- Duration Tracking - Consecutive time period tracking
- State Transitions - State change modeling
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 |