Standard inputs and outputs

Descriptions of the basic functions are given below.

Function descriptions:

standardIO.timer(func)

Wrapper around a function to track the time taken by the function.

Parameters:

func – Function

Note

Usage as a decorator before a function -> @timer

standardIO.writeOptimizationOutputToExcel(esM, outputFileName='scenarioOutput', optSumOutputLevel=2, optValOutputLevel=1)

Write optimization output to an Excel file.

Parameters:

• esM (EnergySystemModel instance) – EnergySystemModel instance in which the optimized model is hold

• outputFileName (string) – name of the Excel output file (without .xlsx ending)
  * the default value is ‘scenarioOutput’

• optSumOutputLevel (int (0,1,2) or dict) – output level of the optimization summary (see EnergySystemModel). Either an integer (0,1,2) which holds for all model classes or a dictionary with model class names as keys and an integer (0,1,2) for each key (e.g. {‘StorageModel’:1,’SourceSinkModel’:1,…}
  * the default value is 2

• optValOutputLevel (int (0,1) or dict) –

  output level of the optimal values. Either an integer (0,1) which holds for all model classes or a dictionary with model class names as keys and an integer (0,1) for each key (e.g. {‘StorageModel’:1,’SourceSinkModel’:1,…}

  • 0: all values are kept.

  • 1: Lines containing only zeroes are dropped.

  
  * the default value is 1

standardIO.readEnergySystemModelFromExcel(fileName='scenarioInput.xlsx', engine='openpyxl')

Read energy system model from excel file.

Default arguments:

Parameters:

• fileName (string) – excel file name or path (including .xlsx ending)
  * the default value is ‘scenarioInput.xlsx’

• engine (string) –

  Used engine for reading the excel file. Please consider that the corresponding python package has to be installed. openpyxl and xlrd are already part of the requirements of FINE. For further information see the documentation of pandas.read_excel().

  • ’openpyxl’ supports newer Excel file formats

  • ’xlrd’ supports old-style Excel files (.xls)

  • ’odf’ supports OpenDocument file formats (.odf, .ods, .odt)

  
  * the default value is ‘openpyxl’.

Returns:

esM, esMData - an EnergySystemModel class instance and general esMData as a Series

standardIO.energySystemModelRunFromExcel(fileName='scenarioInput.xlsx', engine='openpyxl')

Run an energy system model from excel file.

Default arguments:

Parameters:

• fileName (string) – excel file name or path (including .xlsx ending)
  * the default value is ‘scenarioInput.xlsx’

• engine (string) –

  Used engine for reading the excel file. Please consider that the corresponding python package has to be installed. openpyxl and xlrd are already part of the requirements of FINE. For further information see the documentation of pandas.read_excel().

  • ’openpyxl’ supports newer Excel file formats

  • ’xlrd’ supports old-style Excel files (.xls)

  • ’odf’ supports OpenDocument file formats (.odf, .ods, .odt)

  
  * the default value is ‘openpyxl’.

Returns:

esM - an EnergySystemModel class instance and general esMData as a Series

standardIO.readOptimizationOutputFromExcel(esM, fileName='scenarioOutput.xlsx', engine='openpyxl')

Read optimization output from an excel file.

Parameters:

esM (EnergySystemModel instance) – EnergySystemModel instance which includes the setting of the optimized model

Default arguments:

Parameters:

• fileName (string) – excel file name oder path (including .xlsx ending) to an execl file written by writeOptimizationOutputToExcel()
  * the default value is ‘scenarioOutput.xlsx’

• engine (string) –

  Used engine for reading the excel file. Please consider that the corresponding python package has to be installed. openpyxl and xlrd are already part of the requirements of FINE. For further information see the documentation of pandas.read_excel().

  • ’openpyxl’ supports newer Excel file formats

  • ’xlrd’ supports old-style Excel files (.xls)

  • ’odf’ supports OpenDocument file formats (.odf, .ods, .odt)

  
  * the default value is ‘openpyxl’.

Returns:

esM - an EnergySystemModel class instance

standardIO.getDualValues(pyM)

Get dual values of an optimized pyomo instance.

Parameters:

pyM (pyomo Concrete Model) – optimized pyomo instance

Returns:

Pandas Series with dual values

standardIO.getShadowPrices(esM, constraint, ip=0, dualValues=None, hasTimeSeries=False, periodOccurrences=None, periodsOrder=None)

Get dual values of constraint (“shadow prices”).

Parameters:

• esM (EnergySystemModel class instance) – considered energy system model

• constraint (pyomo.core.base.constraint.SimpleConstraint) – constraint from which the dual values should be obtained (e.g. pyM.commodityBalanceConstraint)

• ip (int) – investment period of transformation path analysis.

• dualValues (None or Series) – dual values of the optimized model instance. If it is not specified, it is set by using the function getDualValues().
  * the default value is None

• hasTimeSeries (bool) – If the constaint is time dependent, this parameter concatenates the dual values to a full time series (particularly usefull if time series aggregation was considered).
  * the default value is False

• periodOccurrences (list or None) – Only required if hasTimeSeries is set to True.
  * the default value is None

• periodsOrder (list or None) – Only required if hasTimeSeries is set to True.
  * the default value is None

Returns:

Pandas Series with the dual values of the specified constraint

standardIO.plotOperation(esM, compName, loc, ip=0, locTrans=None, tMin=0, tMax=-1, variableName='operationVariablesOptimum', xlabel='time step', ylabel='operation time series', figsize=(12, 4), color='k', fontsize=12, save=False, fileName='operation.png', dpi=200, **kwargs)

Plot operation time series of a component at a location.

Required arguments:

Parameters:

• esM (EnergySystemModel class instance) – considered energy system model

• compName (string) – component name

• loc (string) – location

Default arguments:

Parameters:

• ip (int) – investment period
  * the default value is 0

• locTrans (string) – second location, required when Transmission components are plotted
  * the default value is None

• tMin (integer) – first time step to be plotted (starting from 0)
  * the default value is 0

• tMax (integer) – last time step to be plotted
  * the default value is -1 (i.e. the last available index)

• variableName (string) – name of the operation time series. Checkout the component model class to see which options are available.
  * the default value is ‘_operationVariablesOptimum’

• xlabel (string) – x-label of the plot
  * the default value is ‘time step’

• ylabel (string) – y-label of the plot
  * the default value is ‘operation time series’

• figsize (tuple of positive floats) – figure size in inches
  * the default value is (12,4)

• color (string) – color of the operation line
  * the default value is ‘k’

• fontsize (positive float) – font size of the axis
  * the default value is 12

• save (boolean) – indicates if figure should be saved
  * the default value is False

• fileName (string) – output file name
  * the default value is ‘operation.png’

• dpi (scalar > 0) – resolution in dots per inch
  * the default value is 200

standardIO.plotOperationColorMap(esM, compName, loc, ip=0, locTrans=None, nbPeriods=365, nbTimeStepsPerPeriod=24, variableName='operationVariablesOptimum', cmap='viridis', vmin=0, vmax=-1, xlabel='period', ylabel='timestep per period', zlabel='', figsize=(12, 4), fontsize=12, save=False, fileName='', xticks=None, yticks=None, xticklabels=None, yticklabels=None, monthlabels=False, dpi=200, pad=0.12, aspect=15, fraction=0.2, orientation='horizontal', **kwargs)

Plot operation time series of a component at a location.

Required arguments:

Parameters:

• esM (EnergySystemModel class instance) – considered energy system model

• compName (string) – component name

• loc (string) – location

Default arguments:

Parameters:

• ip (int) – investment period of transformation path analysis.

• locTrans (string) – second location, required when Transmission components are plotted
  * the default value is None

• nbPeriods (integer) – number of periods to be plotted
  * the default value is 365

• nbTimeStepsPerPeriod (integer) – time steps per period to be plotted (nbPeriods*nbTimeStepsPerPeriod=length of time series)
  * the default value is 24

• variableName (string) – name of the operation time series. Checkout the component model class to see which options are available.
  * the default value is ‘_operationVariablesOptimum’

• cmap (string) – heat map (color map) (see matplotlib options)
  * the default value is ‘viridis’

• vmin (integer) – minimum value in heat map
  * the default value is 0

• vmax (integer) – maximum value in heat map. If -1, vmax is set to the maximum value of the operation time series.
  * the default value is -1

• xlabel (string) – x-label of the plot
  * the default value is ‘day’

• ylabel (string) – y-label of the plot
  * the default value is ‘hour’

• zlabel (string) – z-label of the plot
  * the default value is ‘operation’

• figsize (tuple of positive floats) – figure size in inches
  * the default value is (12,4)

• fontsize (positive float) – font size of the axis
  * the default value is 12

• save (boolean) – indicates if figure should be saved
  * the default value is False

• fileName (string) – output file name
  * the default value is ‘operation.png’

• xticks (list) – user specified ticks of the x axis
  * the default value is None

• yticks (list) – user specified ticks of the ý axis
  * the default value is None

• xticklabels (list) – user specified tick labels of the x axis
  * the default value is None

• yticklabels (list) – user specified tick labels of the ý axis
  * the default value is None

• monthlabels (boolean) – specifies if month labels are to be plotted (only works correctly if 365 days are specified as the number of periods)
  * the default value is False

• dpi (scalar > 0) – resolution in dots per inch
  * the default value is 200

• pad (float) – pad parameter of colorbar
  * the default value is 0.12

• aspect (float) – aspect parameter of colorbar
  * the default value is 15

• fraction (float) – fraction parameter of colorbar
  * the default value is 0.2

• orientation (float) – orientation parameter of colorbar
  * the default value is ‘horizontal’

standardIO.plotLocations(locationsShapeFileName, indexColumn, plotLocNames=False, crs='EPSG:3035', faceColor='none', edgeColor='black', fig=None, ax=None, linewidth=0.5, figsize=(6, 6), fontsize=12, save=False, fileName='', dpi=200, **kwargs)

Plot locations from a shape file.

Required arguments:

Parameters:

• locationsShapeFileName (string) – file name or path to a shape file

• indexColumn (string) – name of the column in which the location indices are stored

Default arguments:

Parameters:

• plotLocNames (boolean) – indicates if the names of the locations should be plotted
  * the default value is False

• crs (string) – coordinate reference system
  * the default value is ‘EPSG:3035’

• faceColor (string) – face color of the plot
  * the default value is ‘none’

• edgeColor (string) – edge color of the plot
  * the default value is ‘black’

• fig (matplotlib Figure) – None or figure to which the plot should be added
  * the default value is None

• ax (matplotlib Axis) – None or ax to which the plot should be added
  * the default value is None

• linewidth (positive float) – linewidth of the plot
  * the default value is 0.5

• figsize (tuple of positive floats) – figure size in inches
  * the default value is (6,6)

• fontsize (positive float) – font size of the axis
  * the default value is 12

• save (boolean) – indicates if figure should be saved
  * the default value is False

• fileName (string) – output file name
  * the default value is ‘operation.png’

• dpi (scalar > 0) – resolution in dots per inch
  * the default value is 200

standardIO.plotTransmission(esM, compName, transmissionShapeFileName, loc0, loc1, ip=0, crs='EPSG:3035', variableName='capacityVariablesOptimum', color='k', loc=7, alpha=0.5, ax=None, fig=None, linewidth=10, figsize=(6, 6), fontsize=12, save=False, fileName='', dpi=200, **kwargs)

Plot build transmission lines from a shape file.

Required arguments:

Parameters:

• esM (EnergySystemModel class instance) – considered energy system model

• compName (string) – component name

• transmissionShapeFileName (string) – file name or path to a shape file

• loc0 (string) – name of the column in which the location indices are stored (e.g. start/end of line)

• loc1 (string) – name of the column in which the location indices are stored (e.g. end/start of line)

Default arguments:

Parameters:

• ip (int) – investment periods
  * the default value is 0

• crs (string) – coordinate reference system
  * the default value is ‘EPSG:3035’

• variableName (string) – parameter for plotting installed capacity (‘_capacityVariablesOptimum’) or operation (‘_operationVariablesOptimum’).
  * the default value is ‘_capacityVariablesOptimum’

• color (string) – color of the transmission line
  * the default value is ‘k’

• loc (0 <= integer <= 10) – location of the legend in the plot
  * the default value is 7

• alpha (0 <= scalar <= 1) – transparency of the legend
  * the default value is 0.5

• fig (matplotlib Figure) – None or figure to which the plot should be added
  * the default value is None

• ax (matplotlib Axis) – None or ax to which the plot should be added
  * the default value is None

• linewidth (positive float) – line width of the plot
  * the default value is 0.5

• figsize (tuple of positive floats) – figure size in inches
  * the default value is (6,6)

• fontsize (positive float) – font size of the axis
  * the default value is 12

• save (boolean) – indicates if figure should be saved
  * the default value is False

• fileName (string) – output file name
  * the default value is ‘operation.png’

• dpi (scalar > 0) – resolution in dots per inch
  * the default value is 200

standardIO.plotLocationalColorMap(esM, compName, locationsShapeFileName, indexColumn, ip=0, perArea=True, areaFactor=1000.0, crs='EPSG:3035', variableName='capacityVariablesOptimum', doSum=False, cmap='viridis', vmin=0, vmax=-1, zlabel=None, figsize=(6, 6), fontsize=12, save=False, fileName='capacity.png', dpi=200, **kwargs)

Plot the data of a component for each location.

Required arguments:

Parameters:

• esM (EnergySystemModel class instance) – considered energy system model

• compName (string) – component name

• locationsShapeFileName (string) – file name or path to a shape file

• indexColumn (string) – name of the column in which the location indices are stored

Default arguments:

Parameters:

• ip (int) – investment period
  * the default value is 0

• perArea (boolean) – indicates if the capacity should be given per area
  * the default value is False

• areaFactor (scalar > 0) – meter * areaFactor = km –> areaFactor = 1e3 (–> capacity/km)
  * the default value is 1e3

• crs (string) – coordinate reference system
  * the default value is ‘EPSG:3035’

• variableName (string) – parameter for plotting installed capacity (‘_capacityVariablesOptimum’) or operation (‘_operationVariablesOptimum’). In case of plotting the operation, set the parameter doSum to True.
  * the default value is ‘_capacityVariablesOptimum’

• doSum (boolean) – indicates if the variable has to be summarized for the location (e.g. for operation variables)
  * the default value is False

• cmap (string) – heat map (color map) (see matplotlib options)
  * the default value is ‘viridis’

• vmin (integer) – minimum value in heat map
  * the default value is 0

• vmax (integer) – maximum value in heat map. If -1, vmax is set to the maximum value of the operation time series.
  * the default value is -1

• zlabel (string) – z-label of the plot
  * the default value is ‘operation’

• figsize (tuple of positive floats) – figure size in inches
  * the default value is (12,4)

• fontsize (positive float) – font size of the axis
  * the default value is 12

• save (boolean) – indicates if figure should be saved
  * the default value is False

• fileName (string) – output file name
  * the default value is ‘capacity.png’

• dpi (scalar > 0) – resolution in dots per inch
  * the default value is 200