EnergySystemModel class¶
A description of the class is given below.
Class description:
Last edited: July 27 2018
@author: Lara Welder
-
class
energySystemModel.
EnergySystemModel
(locations, commodities, commodityUnitsDict, numberOfTimeSteps=8760, hoursPerTimeStep=1, costUnit='1e9 Euro', lengthUnit='km', verboseLogLevel=0)[source]¶ EnergySystemModel class
The functionality provided by the EnergySystemModel class is fourfold:
- With it, the basic structure (spatial and temporal resolution, considered commodities) of the investigated energy system is defined.
- It serves as a container for all components investigated in the energy system model. These components, namely sources and sinks, conversion options, storage options, and transmission options (in the core module), can be added to an EnergySystemModel instance.
- It provides the core functionality of modeling and optimizing the energy system based on the specified structure and components on the one hand and of specified simulation parameters on the other hand,.
- It stores optimization results which can then be post-processed with other modules.
The parameter which are stored in an instance of the class refer to:
- the modeled spatial representation of the energy system (locations, lengthUnit)
- the modeled temporal representation of the energy system (totalTimeSteps, hoursPerTimeStep, years, periods, periodsOrder, periodsOccurrences, timeStepsPerPeriod, interPeriodTimeSteps, isTimeSeriesDataClustered, typicalPeriods, tsaInstance, timeUnit)
- the considered commodities in the energy system (commodities, commodityUnitsDict)
- the considered components in the energy system (componentNames, componentModelingDict, costUnit)
- optimization related parameters (pyM, solverSpecs) all parameters are marked as protected (thus they all begin with an underscore) and are set when an class instance is initiated, components are added or user accessible functions are called.
Instances of this class provide function for
- adding components and their respective modeling classes (add)
- clustering the time series data of all added components using the time series aggregation package tsam, cf. https://github.com/FZJ-IEK3-VSA/tsam (cluster)
- optimizing the specified energy system (optimize), for which a pyomo discrete model instance is build and filled with (0) basic time sets, (1) sets, variables and constraints contributed by the component modeling classes, (2) basic, component overreaching constraints, and (3) an objective function. The pyomo instance is then optimized by a specified solver and the optimization results processed once available.
- getting components and their attributes (getComponent, getCompAttr, getOptimizationSummary)
Last edited: July 27, 2018
@author: Lara Welder-
__init__
(locations, commodities, commodityUnitsDict, numberOfTimeSteps=8760, hoursPerTimeStep=1, costUnit='1e9 Euro', lengthUnit='km', verboseLogLevel=0)[source]¶ Constructor for creating an EnergySystemModel class instance
Required arguments:
Parameters: - locations (set of strings) – locations considered in the energy system
- commodities (set of strings) – commodities considered in the energy system
- commodityUnitsDict (dictionary of strings) – dictionary which assigns each commodity a quantitative unit per time (e.g. GW_el, GW_H2, Mio.t_CO2/h). The dictionary is used for results output. Note for advanced users: the scale of these units can influence the numerical stability of the optimization solver, cf. http://files.gurobi.com/Numerics.pdf where a reasonable range of model coefficients is suggested
Default arguments:
Parameters: - numberOfTimeSteps – number of time steps considered when modeling the energy system (for each
time step, or each representative time step, variables and constraints are constituted). Together
with the hours per time step, the total number of hours considered can be derived. The total
number of hours is again used for scaling the arising costs to the arising total annual costs (TAC),
which are minimized during optimization.
* the default value is 8760 - hoursPerTimeStep – hours per time step
* the default value is 1 - costUnit (string) – cost unit of all cost related values in the energy system. This value sets the unit of
all cost parameters which are given as an input to the EnergySystemModel instance (i.e. for the
invest per capacity or the cost per operation).
Note for advanced users: the scale of this unit can influence the numerical stability of the
optimization solver, cf. http://files.gurobi.com/Numerics.pdf where a reasonable range of model
coefficients is suggested
* the default value is ‘10^9 Euro’ (billion euros), which can be a suitable scale for national energy systems. - lengthUnit (string) – length unit for all length related values in the energy system
Note for advanced users: the scale of this unit can influence the numerical stability of the
optimization solver, cf. http://files.gurobi.com/Numerics.pdf where a reasonable range of model
coefficients is suggested.
* the default value is ‘km’ (kilometers) - verboseLogLevel (integer (0, 1 or 2)) – defines how verbose the console logging is
- 0: general model logging, warnings and optimization solver logging are displayed
- 1: warnings are displayed
- 2: no general model logging or warnings are displayed, the optimization solver logging is set to a minimum
Note: if required, the optimization solver logging can be separately enabled in the optimizationSpecs
of the optimize function.
* the default value is 0
-
add
(component)[source]¶ Function for adding a component and, if required, its respective modeling class to the EnergySystemModel instance
Parameters: component (An object which inherits from the FINE Component class) – the component to be added
-
getComponent
(componentName)[source]¶ Function which returns a component of the energy system
Parameters: componentName (string) – name of the component that should be returned Returns: the component which has the name componentName Return type: Component
-
getComponentAttribute
(componentName, attributeName)[source]¶ Function which returns an attribute of a component considered in the energy system
Parameters: Returns: the attribute specified by the attributeName of the component with the name componentName
Return type: depends on the specified attribute
-
getOptimizationSummary
(modelingClass, outputLevel=0)[source]¶ Function which returns the optimization summary (design variables, aggregated operation variables, objective contributions) of a modeling class
Parameters: - modelingClass (string) – name of the modeling class from which the optimization summary should be obtained
- outputLevel (integer (0, 1 or 2)) – states the level of detail of the output summary:
- 0: full optimization summary is returned
- 1: full optimization summary is returned but rows in which all values are NaN (not a number) are dropped
- 2: full optimization summary is returned but rows in which all values are NaN or 0 are dropped
* the default value is 0
Returns: the attribute specified by the attributeName of the component with the name componentName
Return type: depends on the specified attribute
-
cluster
(numberOfTypicalPeriods=7, numberOfTimeStepsPerPeriod=24, clusterMethod='hierarchical', sortValues=True, storeTSAinstance=False, **kwargs)[source]¶ Clusters the time series data of all components considered in the EnergySystemModel instance and then stores the clustered data in the respective components. For this, the time series data is broken down into an ordered sequence of periods (e.g. 365 days) and to each period a typical period (e.g. 7 typical days with 24 hours) is assigned. For the clustering itself, the tsam package is used (cf. https://github.com/FZJ-IEK3-VSA/tsam). Additional keyword arguments for the TimeSeriesAggregation instance can be added (facilitated by kwargs). As an example: it might be useful to add extreme periods to the clustered typical periods.
Default arguments:
Parameters: - numberOfTypicalPeriods (strictly positive integer) – 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.
* the default value is 7 - numberOfTimeStepsPerPeriod (strictly positive integer) – states the number of time steps per period
* the default value is 24 - clusterMethod (string) – 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.
* the default value is ‘hierarchical’ - sortValues (boolean) – states if the algorithm in the tsam package should use
(a) the sorted duration curves (-> True) or
(b) the original profiles (-> False)
of the time series data within a period for clustering.
Note: Please refer to the tsam package documentation of the parameter sortValues for more information.
* the default value is True - storeTSAinstance (boolean) – states if the TimeSeriesAggregation instance create during clustering should be
stored in the EnergySystemModel instance.
* the default value is False
Last edited: August 10, 2018
@author: Lara Welder- numberOfTypicalPeriods (strictly positive integer) – 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.
-
declareTimeSets
(pyM, timeSeriesAggregation)[source]¶ Set and initialize basic time parameters and sets
-
declareCommodityBalanceConstraints
(pyM)[source]¶ Declare commodity balance constraints (one balance constraint for each commodity, location and time step)
-
declareObjective
(pyM)[source]¶ Declare objective function by obtaining the contributions to the objective function from all modeling classes Currently, the only objective function which can be selected is the sum of the total annual cost of all components.
-
declareOptimizationProblem
(timeSeriesAggregation=False)[source]¶ Declares the optimization problem belonging to the specified energy system, for which a pyomo discrete model instance is build and filled with * basic time sets, * sets, variables and constraints contributed by the component modeling classes, * basic, component overreaching constraints, and * an objective function.
Default arguments:
Parameters: timeSeriesAggregation (boolean) – 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).
* the default value is FalseLast edited: November 10, 2018
@author: Lara Welder
-
optimize
(declaresOptimizationProblem=True, timeSeriesAggregation=False, logFileName='job', threads=3, solver='gurobi', timeLimit=None, optimizationSpecs='OptimalityTol=1e-6', warmstart=False)[source]¶ Optimizes the specified energy system, for which a pyomo discrete model instance is build or called upon. A pyomo instance is optimized with the specified inputs and the optimization results are further processed.
Default arguments:
Parameters: - declaresOptimizationProblem – states if the optimization problem should be declared (True) or not (False).
(a) If true, the declareOptimizationProblem function is called and concrete pyomo model instance is built.
(b) If false a previously declared concrete pyomo model instance is used.
* the default value is True - timeSeriesAggregation (boolean) – 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).
* the default value is False - logFileName (string) – logFileName is used for naming the log file of the optimization solver output.
If the logFileName is given as an absolute path (i.e. logFileName = os.path.join(os.getcwd(),
‘Results’, ‘logFileName.txt’)) the log file will be stored in the specified directory. Otherwise
it will be by default stored in the directory where the executing python script is called.
* the default value is ‘job’ - threads (positive integer) – number of computational threads used for solving the optimization (solver dependent
input). If gurobi is selected 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.
* the default value is 3 - solver (string) – specifies which solver should solve the optimization problem (which of course has to be
installed on the machine on which the model is run).
* the default value is ‘gurobi’ - timeLimit (string) – 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.
* the default value is None - optimizationSpecs – specifies parameters for the optimization solver (see the respective solver
documentation for more information)
* the default value is ‘LogToConsole=1 OptimalityTol=1e-6’ - warmstart (boolean) – specifies if a warm start of the optimization should be considered
(not supported by all solvers).
* the default value is False
Last edited: August 10, 2018
@author: Lara Welder- declaresOptimizationProblem – states if the optimization problem should be declared (True) or not (False).
(a) If true, the declareOptimizationProblem function is called and concrete pyomo model instance is built.
(b) If false a previously declared concrete pyomo model instance is used.