Expansion Modules¶
FINE expansion modules provide additional functionalities to the user. These functionalities either run energy system models multiple times or can be applied in the pre- and post-processing of an energy system model run.
Optimize TSA Multi Stage¶
Functions:
-
fixBinaryVariables–Search for the optimized binary variables and set them as fixed.
-
optimizeTSAmultiStage–Call the optimize function for a temporally aggregated MILP (so the model has to include
Search for the optimized binary variables and set them as fixed.
:param esM: energy system model to which the component should be added. Used for unit checks. :type esM: EnergySystemModel instance from the FINE package
optimizeTSAmultiStage(
esM,
declaresOptimizationProblem=True,
relaxIsBuiltBinary=False,
numberOfTypicalPeriods=30,
numberOfTimeStepsPerPeriod=24,
clusterMethod="hierarchical",
logFileName="",
threads=3,
solver="gurobi",
timeLimit=None,
optimizationSpecs="",
warmstart=False,
)
Call the optimize function for a temporally aggregated MILP (so the model has to include hasIsBuiltBinaryVariables in all or some components). Fix the binary variables and run it again without temporal aggregation. Furthermore, a LP with relaxed binary variables can be solved to obtain both, an upper and lower bound for the fully resolved MILP.
Required arguments:
:param esM: energy system model to which the component should be added. Used for unit checks. :type esM: EnergySystemModel instance from the FINE package
Default arguments:
:param declaresOptimizationProblem: states if the optimization problem should be declared (True) or not (False).
(a) If true, the declareOptimizationProblem function is called and a pyomo ConcreteModel instance is built.
(b) If false a previously declared pyomo ConcreteModel instance is used.
|br| * the default value is True
:type declaresOptimizationProblem: boolean
:param relaxIsBuiltBinary: states if the optimization problem should be solved as a relaxed LP to get the lower bound of the problem. |br| * the default value is False :type declaresOptimizationProblem: boolean
:param numberOfTypicalPeriods: states the number of typical periods into which the time series data should be clustered. The number of time steps per period must be an integer multiple of the total number of considered time steps in the energy system.
.. note::
Please refer to the tsam package documentation of the parameter noTypicalPeriods for more
information.
|br| * the default value is 30
:type numberOfTypicalPeriods: strictly positive integer
:param numberOfTimeStepsPerPeriod: states the number of time steps per period |br| * the default value is 24 :type numberOfTimeStepsPerPeriod: strictly positive integer
:param clusterMethod: states the method which is used in the tsam package for clustering the time series data. Options are for example 'averaging','k_means','exact k_medoid' or 'hierarchical'.
.. note::
Please refer to the tsam package documentation of the parameter clusterMethod for more information.
|br| * the default value is 'hierarchical'
:type clusterMethod: string
:param logFileName: logFileName is used for naming the log file of the optimization solver output if gurobi is used as the optimization solver. If the logFileName is given as an absolute path (e.g. logFileName = os.path.join(os.getcwd(), 'Results', 'logFileName.txt')) the log file will be stored in the specified directory. Otherwise, it will be stored by default in the directory where the executing python script is called. |br| * the default value is 'job' :type logFileName: string
:param threads: number of computational threads used for solving the optimization (solver dependent input) if gurobi is used as the solver. A value of 0 results in using all available threads. If a value larger than the available number of threads are chosen, the value will reset to the maximum number of threads. |br| * the default value is 3 :type threads: positive integer
:param solver: specifies which solver should solve the optimization problem (which of course has to be installed on the machine on which the model is run). |br| * the default value is 'gurobi' :type solver: string
:param timeLimit: if not specified as None, indicates the maximum solve time of the optimization problem in seconds (solver dependent input). The use of this parameter is suggested when running models in runtime restricted environments (such as clusters with job submission systems). If the runtime limitation is triggered before an optimal solution is available, the best solution obtained up until then (if available) is processed. |br| * the default value is None :type timeLimit: strictly positive integer or None
:param optimizationSpecs: specifies parameters for the optimization solver (see the respective solver documentation for more information). Example: 'LogToConsole=1 OptimalityTol=1e-6' |br| * the default value is an empty string ('') :type timeLimit: string
:param warmstart: specifies if a warm start of the optimization should be considered (not always supported by the solvers). |br| * the default value is False :type warmstart: boolean
Transformation Path¶
Functions:
-
getStock–Determine the stock of all considered technologies for the next optimization period.
-
optimizeSimpleMyopic–Optimization function for myopic approach. For each optimization run, the newly installed capacities
Determine the stock of all considered technologies for the next optimization period. If the technical lifetime has expired, set the fixed capacities of the affected components to 0.
:param mileStoneYear: Last year of the optimization period :type mileStoneYear: int
:param nbOfRepresentativeYears: Number of years within one optimization period. :type nbOfRepresentativeYears: int
:return: EnergySystemModel instance including the installed capacities of the previous optimization runs. :rtype: EnergySystemModel instance
optimizeSimpleMyopic(
esM,
startYear,
endYear=None,
nbOfSteps=None,
nbOfRepresentedYears=None,
timeSeriesAggregation=True,
numberOfTypicalPeriods=7,
numberOfTimeStepsPerPeriod=24,
clusterMethod="hierarchical",
logFileName="",
threads=3,
solver="gurobi",
timeLimit=None,
optimizationSpecs="",
warmstart=False,
CO2Reference=366,
CO2ReductionTargets=None,
saveResults=True,
trackESMs=True,
)
Optimization function for myopic approach. For each optimization run, the newly installed capacities will be given as a stock (with capacityFix) to the next optimization run.
:param esM: EnergySystemModel instance representing the energy system which should be optimized by considering the transformation pathway (myopic foresight). :type esM: esM - EnergySystemModel instance
:param startYear: year of the first optimization :type startYear: int
Default arguments:
:param endYear: year of the last optimization :type endYear: int
:param nbOfSteps: number of optimization runs excluding the start year (minimum number of optimization runs is 2: one optimization for the start year and one for the end year). |br| * the default value is None :type nbOfSteps: int or None
:param noOfRepresentedYears: number of years represented by one optimization run |br| * the default value is None :type nbOfRepresentedYears: int or None
:param timeSeriesAggregation: states if the optimization of the energy system model should be done with
(a) the full time series (False) or
(b) clustered time series data (True).
|br| * the default value is False
:type timeSeriesAggregation: boolean
:param numberOfTypicalPeriods: states the number of typical periods into which the time series data should be clustered. The number of time steps per period must be an integer multiple of the total number of considered time steps in the energy system. This argument is used if timeSeriesAggregation is set to True. Note: Please refer to the tsam package documentation of the parameter noTypicalPeriods for more information. |br| * the default value is 7 :type numberOfTypicalPeriods: strictly positive integer
:param numberOfTimeStepsPerPeriod: states the number of time steps per period |br| * the default value is 24 :type numberOfTimeStepsPerPeriod: strictly positive integer
:param clusterMethod: states the method which is used in the tsam package for clustering the time series data. Options are for example 'averaging','k_means','exact k_medoid' or 'hierarchical'.
.. note::
Please refer to the tsam package documentation of the parameter clusterMethod for more information.
|br| * the default value is 'hierarchical'
:type clusterMethod: string
:param CO2Reference: gives the reference value of the CO2 emission to which the reduction should be applied to. The default value refers to the emissions of 1990 within the electricity sector (366kt CO2_eq) |br| * the default value is 366 :type CO2Reference: float
:param CO2ReductionTargets: specifies the CO2 reduction targets for all optimization periods. If specified, the length of the list must equal the number of optimization steps, and an object of the sink class which counts the CO2 emission is required. |br| * the default value is None :type CO2ReductionTargets: list of strictly positive integer or None
:param saveResults: specifies if the results are saves in excelfiles or not. |br| * the default value is True :type saveResults: boolean
:param trackESMs: specifies if the energy system model instances of each model run should be stored in a dictionary or not. It´s not recommended to track the ESMs if the model is quite big. |br| * the default value is True :type trackESMs: boolean
:returns: myopicResults: Store all optimization outputs in a dictionary for further analyses. If trackESMs is set to false, nothing is returned. :rtype: dict of all optimized instances of the EnergySystemModel class or None.
Piecewise Linear Cost Function¶
Classes:
-
PiecewiseLinearCostFunctionModel–Model to handle piecewise linear cost functions within the energy system optimization.
-
PiecewiseLinearCostFunctionModule–Handle the initialization and preprocessing of piecewise linear cost functions.
Model to handle piecewise linear cost functions within the energy system optimization.
This class defines the necessary sets, variables, and constraints to represent piecewise linear cost functions in a Pyomo-based formulation. After declaring all structural model elements, the class extracts the economic contributions of PWL cost function components for a given commissioning year and stores their optimal values in the optimization summary.
Methods:
-
declareBinaryPwlcfConstr–Add the binary constraints.
-
declareBinaryPwlcfVar–Add binary variables.
-
declareBinarySpeedUpConstr–Add binary speed up constraints.
-
declareCapacityCommissioningPwlcfConstr–Enforce that the capacity segment variable equals the total commissioning.
-
declareComponentConstraints–Declare constraints of the pwlcf model.
-
declarePwlcfDesignSegmentSet–Declare the necessary sets for the variables of the pwlcf model.
-
declarePwlcfDesignSet–Declare the necessary sets for the variables of the pwlcf model.
-
declarePwlfPyomo–https://pyomo.readthedocs.io/en/latest/pyomo_modeling_components/Expressions.html#piecewise-linear-expressions.
-
declareSegmentCapacityPwlcfConstr–Add the segment capacity constraints.
-
declareSegmentCapacityPwlcfVar–Add segment capacity variables.
-
declareSets–Declare the necessary sets for the variables of the pwlcf model.
-
declareSos2PwlcfConstr–Declare SOS2 constraints for pwlcf model.
-
declareVariables–Declare the variables of the pwlcf model.
-
getCostContributionsPwlcf–Extract the cost contribution from a specified component and for a specified commissioning year.
-
getEconomicsPwlcf–Get the economic contribution to the cost function of pwlcf components.
-
setOptimalValues–Set the optimal values into the optimization summary.
Add the binary constraints. For each component, exactly one binary has to be 1 and the others 0. The binary indicates which segment is active.
.. math:: \begin{eqnarray} \underset{segment}{ \sum } binVar^{comp}_{ip,segment} = 1 \end{eqnarray}
:param pyM: pyomo ConcreteModel which stores the mathematical formulation of the model. :type pyM: pyomo ConcreteModel
Add binary variables.
:param pyM: pyomo ConcreteModel which stores the mathematical formulation of the model. :type pyM: pyomo ConcreteModel
Enforce that the capacity segment variable equals the total commissioning.
Constraint ist applied across all locations and investment periods, including also the initial capacity.
.. math:: \begin{eqnarray} \underset{segment}{ \sum } segmentCapacityPwlcfVar^{comp}{ip,segment} = underset{ip,comp}{ \sum } commVar^{comp} \end{eqnarray} + initCapacity^{comp}
:param esM: energy system model to which the component should be added. Used for unit checks. :type esM: EnergySystemModel instance from the FINE package
:param pyM: pyomo ConcreteModel which stores the mathematical formulation of the model. :type pyM: pyomo ConcreteModel
Declare constraints of the pwlcf model.
:param esM: energy system model to which the component should be added. Used for unit checks. :type esM: EnergySystemModel instance from the FINE package
:param pyM: pyomo ConcreteModel which stores the mathematical formulation of the model. :type pyM: pyomo ConcreteModel
Declare the necessary sets for the variables of the pwlcf model.
Define a set for each module, investment period, and segment.
:param esM: energy system model to which the component should be added. Used for unit checks. :type esM: EnergySystemModel instance from the FINE package
:param pyM: pyomo ConcreteModel which stores the mathematical formulation of the model. :type pyM: pyomo ConcreteModel
Declare the necessary sets for the variables of the pwlcf model.
When using the pwlcf approach from Pyomo via SOS2 constraints: define a set for each module and investment period.
:param esM: energy system model to which the component should be added. Used for unit checks. :type esM: EnergySystemModel instance from the FINE package
:param pyM: pyomo ConcreteModel which stores the mathematical formulation of the model. :type pyM: pyomo ConcreteModel
https://pyomo.readthedocs.io/en/latest/pyomo_modeling_components/Expressions.html#piecewise-linear-expressions.
Add the segment capacity constraints.
Each segment capacity variable has to be within the lower and upper bounds of the corresponding segment, if the segment is active (indicated by the binary segment variable). If the segment is not active, the capacity segment variable is zero.
.. math:: \begin{eqnarray} lowerCapacityBound^{comp}{ip,segment} \cdot binVar^{comp}} \leq capSegmentVar^{comp{ip,segment} \leq upperCapacityBound^{comp} \end{eqnarray} \cdot binVar^{comp}_{ip,segment}
:param pyM: pyomo ConcreteModel which stores the mathematical formulation of the model. :type pyM: pyomo ConcreteModel
Add segment capacity variables.
:param pyM: pyomo ConcreteModel which stores the mathematical formulation of the model. :type pyM: pyomo ConcreteModel
Declare the necessary sets for the variables of the pwlcf model.
:param esM: energy system model to which the component should be added. Used for unit checks. :type esM: EnergySystemModel instance from the FINE package
:param pyM: pyomo ConcreteModel which stores the mathematical formulation of the model. :type pyM: pyomo ConcreteModel
Declare the variables of the pwlcf model.
Define binary variables for each segment to indicate which segment is active, and segment capacity variables to specify the exact capacity for each segment (0 if the corresponding binary variable is 0).
:param esM: energy system model to which the component should be added. Used for unit checks. :type esM: EnergySystemModel instance from the FINE package
:param pyM: pyomo ConcreteModel which stores the mathematical formulation of the model. :type pyM: pyomo ConcreteModel
getCostContributionsPwlcf(
pyM,
moduleName,
pwlcf_type,
costType,
commisYear=None,
getOptValue=False,
)
Extract the cost contribution from a specified component and for a specified commissioning year.
:param pyM: pyomo ConcreteModel which stores the mathematical formulation of the model. :type pyM: pyomo ConcreteModel
:param moduleName: name of the module/component :type moduleName: string
:param pwlcf_type: type of the pwlcf, i.e. "etl" or "eos" :type pwlcf_type: string
:param costType: indicator which cost should be extracted, i.e. "opex" or "annuity" :type costType: string
:param commisYear: for which comissioning year the data should be extracted. defaults to None (if only single IP) :type commisYear: float
:param getOptValue: indicator, if value after optimization is wanted. defaults to False :type getOptValue: boolean
Get the economic contribution to the cost function of pwlcf components.
:param esM: energy system model to which the component should be added. Used for unit checks. :type esM: EnergySystemModel instance from the FINE package
:param pyM: pyomo ConcreteModel which stores the mathematical formulation of the model. :type pyM: pyomo ConcreteModel
:param getOptValue: indicator if optimal value extracted from optimization output should be used :type getOptValue: binary
:param getOptValueCostType: indicator which cost type is used, i.e. "TAC" or "NPV" :type getOptValueCostType: string
Set the optimal values into the optimization summary.
:param esM: energy system model to which the component should be added. Used for unit checks. :type esM: EnergySystemModel instance from the FINE package
:param pyM: pyomo ConcreteModel which stores the mathematical formulation of the model. :type pyM: pyomo ConcreteModel
Handle the initialization and preprocessing of piecewise linear cost functions.
Initialize the piecewise linear cost function module. At this stage, either endogenous technology learning or economies of scale (plant/location specific) can be used.
:param comp: component for which the pwlcf should be added. :type comp: Component instance from the FINE package
:param esM: energy system model to which the component should be added. Used for unit checks. :type esM: EnergySystemModel instance from the FINE package
:param etlParameters: parameters used for the endogenous technology learning approach. Required entries: "initCost": float, initial Cost at initial capacity, i.e. 500 €/kW "learningRate": float, learning rate for cost reductions "initCapacity": float, initial capacity "maxCapacity": float, maximum capacity until where learning effects are valid "noSegments": float, number of segments used for approximation of nonlinear cost function. defaults to 4. :type etlParameters: dict
"eosParameters": pd.DataFrame( data=np.array([[0,1,2,3],[0,1000, 1800, 2400],[0, 10, 18, 24]]).T, columns=["capacity", "totalInvest", "totalOpex"] ) :param eosParameters: parameters used for economies of scale approach. Required columns: "capacity": float, capacity at which the totalInvest/totalOpex are valid "totalInvest": float, total Invest at specified capacity "totalOpex": float, total opex at specified capacity -At each index rising capacities are defined and corresponding invest/opex are defined. Between the defined supporting points the cost is linearily interpolated. :type eosParameters: pandas DataFrame
Methods:
-
getTotalCostEtl–Calculate the total cost of a component with ETL.
-
linearizeLearningCurveEtl–Linearize the learning curve.
Calculate the total cost of a component with ETL.
:param capacity: The capacity of the component for which the total cost (Invest) is calculated :type capacity: float
:return: total cost at capacity :rtype: float
Linearize the learning curve.
Linearization is based on the given initial capacity, cost, and maximum capacity, as well as the learning rate.
:return: linearized etl parameters: cumulative experience, totalCost, slope and interception for each segments linear approximation :rtype: pd.DataFrame