flixOpt.math_modeling

This module contains the mathematical core of the flixOpt framework. THe module is designed to be used by other modules than flixOpt itself. It holds all necessary classes and functions to create a mathematical model, consisting of Varaibles and constraints, and translate it into a ModelingLanguage like Pyomo, and the solve it through a solver. Multiple solvers are supported.

Classes

Variable

Variable(label: str, length: int, label_short: Optional[str] = None, is_binary: bool = False, fixed_value: Optional[Numeric] = None, lower_bound: Optional[Numeric] = None, upper_bound: Optional[Numeric] = None)

Variable class

label: full label of the variable label_short: short label of the variable

TODO: Allow for None values in fixed_value. If None, the index gets not fixed!

Functions

VariableTS

VariableTS(label: str, length: int, label_short: Optional[str] = None, is_binary: bool = False, fixed_value: Optional[Numeric] = None, lower_bound: Optional[Numeric] = None, upper_bound: Optional[Numeric] = None, previous_values: Optional[Numeric] = None)

Bases: Variable

Timeseries-Variable, optionally with previous_values. class for Variables that are related by time

Equation

Equation(label, label_short=None, is_objective=False)

Bases: _Constraint

Equation of the form: ∑() = Can be the Objective of a MathModel.

Parameters:

Name	Type	Description	Default
`label`	`str`	Full label of the variable.	required
`label_short`	`str`	Short label of the variable. If None, the full label is used.	`None`
`is_objective`	`bool`	Indicates if this equation is the objective of the model (default is False).	`False`

Functions

add_summand

add_summand(variable: Variable, factor: Numeric, indices_of_variable: Optional[Union[int, ndarray, range, List[int]]] = None, as_sum: bool = False) -> None

Adds a summand to the left side of the equation.

This method creates a summand from the given variable and factor, optionally summing over all given indices. The summand is then added to the summands of the equation, which represent the left side.

Parameters:

variable : Variable The variable to be used in the summand. factor : Numeric The factor by which the variable is multiplied. indices_of_variable : Optional[Numeric], optional Specific indices of the variable to be used. If not provided, all indices are used. as_sum : bool, optional If True, the summand is treated as a sum over all indices of the variable.

Raises:

TypeError If the provided variable is not an instance of the Variable class. ValueError If the variable is None and as_sum is True. ValueError If the length doesnt match the Equation's length.

add_constant

add_constant(value: Numeric) -> None

Adds a constant value to the rigth side of the equation

Parameters:

Name	Type	Description	Default
`value`	`float or array`	constant-value of equation [Ax = constant] or [Ax <= constant]	required

Returns:

Type	Description
`None.`

Raises:

ValueError If the length doesnt match the Equation's length.

Inequation

Inequation(label, label_short=None)

Bases: _Constraint

Equation of the form: >= ∑()

Functions

add_summand

add_summand(variable: Variable, factor: Numeric, indices_of_variable: Optional[Union[int, ndarray, range, List[int]]] = None, as_sum: bool = False) -> None

Adds a summand to the left side of the equation.

This method creates a summand from the given variable and factor, optionally summing over all given indices. The summand is then added to the summands of the equation, which represent the left side.

Parameters:

variable : Variable The variable to be used in the summand. factor : Numeric The factor by which the variable is multiplied. indices_of_variable : Optional[Numeric], optional Specific indices of the variable to be used. If not provided, all indices are used. as_sum : bool, optional If True, the summand is treated as a sum over all indices of the variable.

Raises:

TypeError If the provided variable is not an instance of the Variable class. ValueError If the variable is None and as_sum is True. ValueError If the length doesnt match the Equation's length.

add_constant

add_constant(value: Numeric) -> None

Adds a constant value to the rigth side of the equation

Parameters:

Name	Type	Description	Default
`value`	`float or array`	constant-value of equation [Ax = constant] or [Ax <= constant]	required

Returns:

Type	Description
`None.`

Raises:

ValueError If the length doesnt match the Equation's length.

Summand

Summand(variable: Variable, factor: Numeric, indices: Optional[Union[int, ndarray, range, List[int]]] = None)

Represents a part of a Constraint , consisting of a variable (or a time-series variable) and a factor.

Parameters:

Name	Type	Description	Default
`variable`	`Variable`	The variable associated with this summand.	required
`factor`	`Numeric`	The factor by which the variable is multiplied in the equation.	required
`indices`	`(int, ndarray, range, List[int])`	Specifies which indices of the variable to use. If None, all indices of the variable are used.	`None`

SumOfSummand

SumOfSummand(variable: Variable, factor: Numeric, indices: Optional[Union[int, ndarray, range, List[int]]] = None)

Bases: Summand

Represents a part of an Equation that sums all components of a regular Summand over specified indices.

Parameters:

Name	Type	Description	Default
`variable`	`Variable`	The variable associated with this summand.	required
`factor`	`Numeric`	The factor by which the variable is multiplied.	required
`indices`	`(int, ndarray, range, List[int])`	Specifies which indices of the variable to use for the sum. If None, all indices are summed.	`None`

MathModel

MathModel(label: str, modeling_language: Literal['pyomo', 'cvxpy'] = 'pyomo')

A mathematical model for defining equations and constraints of the form:

a1 * x1 + a2 + x2  = y
and
a1 * x1 + a2 + x2 <= y

where 'a1', 'a2' and y can be vectors or scalars, while 'x1' and 'x2' are variables with an appropriate length.

This class provides methods to add variables, equations, and inequality constraints to the model and supports translation to a specified modeling language like pyomo.

The expression 'a1 * x1' is referred to as a 'Summand'. Supported summand formats are: - 'Variable[j] * Factor[i]' : Multiplication of vector variables and vector factors. - 'Variable[j] * Factor' : Vector variable with scalar factor. - 'Variable * Factor' : Scalar variable with scalar factor. - 'Factor' : Scalar constant.

Parameters:

Name	Type	Description	Default
`label`	`str`	A descriptive label for the model.	required
`modeling_language`	`(pyomo, cvxpy)`	Specifies the modeling language used for translation (default is 'pyomo').	`'pyomo'`

Attributes:

Name	Type	Description
`label`	`str`	The label assigned to the model.
`modeling_language`	`str`	The modeling language to which the model will be translated.
`epsilon`	`float`	Small tolerance value used in model calculations, defaulting to `1e-5`.
`solver`	`Optional[Solver]`	The solver instance assigned to solve the model.
`model`	`Optional[ModelingLanguage]`	The model instance in the specified modeling language.
`_variables`	`List[Variable]`	List of variables added to the model.
`_constraints`	`List[Union[Equation, Inequation]]`	List of equations and inequality constraints in the model.
`_objective`	`Optional[Equation]`	The objective function, if defined as an equation.
`duration`	`dict`	Dictionary tracking the time taken for translation and solving steps.

Methods:

Name	Description
`add`	Adds variables, equations, or inequations to the model.
`describe_size`	Provides a summary of the number of equations, inequations, and variables.
`translate_to_modeling_language`	Translates the model to the specified modeling language.
`solve`	Solves the model using the specified solver instance.
`results`	Returns a dictionary of variable results after solving.

SolverLog

SolverLog(solver_name: str, filename: str)

Parses and holds solver log information for specific solvers.

Attributes: solver_name (str): Name of the solver (e.g., 'gurobi', 'cbc'). log (str): Content of the log file. presolved_rows (Optional[int]): Number of rows after presolving. presolved_cols (Optional[int]): Number of columns after presolving. presolved_nonzeros (Optional[int]): Number of nonzeros after presolving. presolved_continuous (Optional[int]): Number of continuous variables after presolving. presolved_integer (Optional[int]): Number of integer variables after presolving. presolved_binary (Optional[int]): Number of binary variables after presolving.

Solver

Solver(mip_gap: float, solver_output_to_console: bool, logfile_name: str)

Bases: ABC

Abstract base class for solvers.

Attributes: mip_gap (float): Solver's mip gap setting. The MIP gap describes the accepted (MILP) objective, and the lower bound, which is the theoretically optimal solution (LP) solver_output_to_console (bool): Whether to display solver output. logfile_name (str): Filename for saving the solver log. objective (Optional[float]): Objective value from the solution. best_bound (Optional[float]): Best bound from the solver. termination_message (Optional[str]): Solver's termination message.

GurobiSolver

GurobiSolver(mip_gap: float = 0.01, time_limit_seconds: int = 300, logfile_name: str = 'gurobi.log', solver_output_to_console: bool = True)

Bases: Solver

Solver implementation for Gurobi. Also Look in class Solver for more details

Attributes: time_limit_seconds (int): Time limit for the solver. After this time, the solver takes the currently best solution, ignoring the mip_gap.

CplexSolver

CplexSolver(mip_gap: float = 0.01, time_limit_seconds: int = 300, logfile_name: str = 'cplex.log', solver_output_to_console: bool = True)

Bases: Solver

Solver implementation for CPLEX. Also Look in class Solver for more details

Attributes: time_limit_seconds (int): Time limit for the solver. After this time, the solver takes the currently best solution, ignoring the mip_gap.

HighsSolver

HighsSolver(mip_gap: float = 0.01, time_limit_seconds: int = 300, logfile_name: str = 'highs.log', solver_output_to_console: bool = True, threads: int = 4)

Bases: Solver

Solver implementation for HIGHS. Also Look in class Solver for more details

Attributes: time_limit_seconds (int): Time limit for the solver. After this time, the solver takes the currently best solution, ignoring the mip_gap. threads (int): Number of threads to use for the solver.

CbcSolver

CbcSolver(mip_gap: float = 0.01, time_limit_seconds: int = 300, logfile_name: str = 'cbc.log', solver_output_to_console: bool = True)

Bases: Solver

Solver implementation for CBC. Also Look in class Solver for more details

Attributes: time_limit_seconds (int): Time limit for the solver. After this time, the solver takes the currently best solution, ignoring the mip_gap.

GlpkSolver

GlpkSolver(mip_gap: float = 0.01, logfile_name: str = 'glpk.log', solver_output_to_console: bool = True)

Bases: Solver

Solver implementation for Glpk. Also Look in class Solver for more details

ModelingLanguage

Bases: ABC

Abstract base class for modeling languages.

Methods: translate_model(model): Translates a math model into a solveable form.

PyomoModel

PyomoModel()

Bases: ModelingLanguage

Pyomo-based modeling language for constructing and solving optimization models. Translates a MathModel into a PyomoModel.

Attributes: model: Pyomo model instance. mapping (dict): Maps variables and equations to Pyomo components. _counter (int): Counter for naming Pyomo components.