urbs: A linear optimisation model for distributed energy systems¶

Maintainer:	Johannes Dorfner, <johannes.dorfner@tum.de>
Organization:	Chair of Renewable and Sustainable Energy Systems, Technical University of Munich
Version:	0.7
Date:	Oct 29, 2019
Copyright:	The model code is licensed under the GNU General Public License 3.0. This documentation is licensed under a Creative Commons Attribution 4.0 International license.

Contents¶

User’s manual¶

These documents give a general overview and help you getting started from after the installation (which is covered in the README.md file on GitHub) to you first running model.

Overview¶

urbs consists of several model entities. These are commodities, processes, transmission and storage. Demand and intermittent commodity supply through are modelled through time series datasets.

Commodity¶

Commodities are goods that can be generated, stored, transmitted and consumed. By convention, they are represented by their energy content (in MWh), but can be changed (to J, kW, t, kg) by simply using different (consistent) units for all input data. Each commodity must be exactly one of the following four types:

Stock: Buyable at any time for a given price. Supply can be limited per timestep or for a whole year. Examples are coal, gas, uranium or biomass.

SupIm: Supply intermittent stands for fluctuating resources like solar radiation and wind energy, which are available according to a timeseries of values, which could be derived from weather data.

Demand: These commodities have a timeseries for the requirement associated and must be provided by output from other process or from storage. Usually, there is only one demand commodity called electricity (abbreviated to Elec), but multiple (e.g. electricity, space heating, process heat, space cooling) demands can be specified.

Env: The special commodity CO2 is of this type and represents the amount (in tons) of greenhouse gas emissions from processes. Its total amount can be limited, to investigate the effect of policies on the model.

Stock commodities have three numeric attributes that represent their price, total annual and per timestep supply. Environmental commodities (i.e. CO2) have a maximum allowed quantity that may be created.

Commodities are defined over the tuple (site, commodity, type), for example (Norway, wind, SupIm) for wind in Norway with a time series or (Iceland, electricity, Demand) for an electricity demand time series in Iceland.

Process¶

Processes describe conversion technologies from one commodity to another. They can be visualised like a black box with input(s) (commodity) and output(s) (commodity). Process input and output ratios are the main technical parameters for processes. Fixed costs for investment and maintenance (per capacity) and variable costs for operation (per output) are the economical parameters.

Processes are defined over two tuples. The first tuple (site, process) specifies the location of a given process e.g. (Iceland, turbine) would locate a process turbine at site Iceland. The second tuple (process, commodity, direction) then specifies the inputs and outputs for that process. For example, (turbine, geothermal, In) and (turbine, electricity, Out) describes that the process named turbine has a single input geothermal and the single output electricity.

Transmission¶

Transmission allows instantaneous transportation of commodities between sites. It is characterised by an efficiency and costs, just like processes. Transmission is defined over the tuple (site in, site out, transmission, commodity). For example, (Iceland, Norway, undersea cable, electricity) would represent an undersea cable for electricity between Iceland and Norway.

Storage¶

Storage describes the possibility to deposit a deliberate amount of energy in the form of one commodity at one time step; with the purpose of retrieving it later. Efficiencies for charging/discharging depict losses during input/output. A self-discharge term is not included at the moment, but could be added trivially (one column, one modification of the storage state equation). Storage is characterised by capacities both for energy content (in MWh) and charge/discharge power (in MW). Both capacities have independent sets of investment, fixed and variable cost parameters to allow for a very flexible parametrization of various storage technologies; ranging from batteries to hot water tanks.

Storage is defined over the tuple (site, storage, stored commodity). For example, (Norway, pump storage, electricity) represents a pump storage power plant in Norway that can store and retrieve energy in form of electricity.

Timeseries¶

Demand¶

Each combination (site, demand commidty) may have one timeseries, describing the (average) power demand (MWh/h) per timestep. They are a crucial input parameter, as the whole optimisation aims to satisfy these demands with minimal costs by the given technologies (process, storage, transmission).

Intermittent Supply¶

Each combination (site, supim commodity) must be supplied with one timeseries, normalised to a maximum value of 1 relative to the installed capacity of a process using this commodity as input. For example, a wind power timeseries should reach value 1, when the wind speed exceeds the modelled wind turbine’s design wind speed is exceeded. This implies that any non-linear behaviour of intermittent processes can already be incorporated while preparing this timeseries.

Tutorial¶

The README file contains installation notes. This tutorial expands on the steps that follow this installation.

This tutorial is a commented walk-through through the script runme.py, which is a demonstration user script that can serve as a good basis for one’s own script.

Initialisation¶

Imports¶

try:
    import pyomo.environ
    from pyomo.opt.base import SolverFactory
    PYOMO3 = False
except ImportError:
    import coopr.environ
    from coopr.opt.base import SolverFactory
    PYOMO3 = True
import os
import shutil
import urbs
from datetime import datetime

Several packages are included.

the try-except block checks for the version of Coopr/Pyomo installed and imports

the necessary packages for the model creation and solution.

os is a builtin Python module, included here for its os.path submodule that offers operating system independent path manipulation routines. The following code creates the path string 'result/foo' or 'result\\foo' (depending on the operating system), checks whether it exists and creates the folder(s) if needed. This is used to prepare a new directory for generated result file:
```
result_dir = os.path.join('result', 'foo')
if not os.path.exists(result_dir):
    os.makedirs(result_dir)
```
urbs is the module whose functions are used mainly in this script. These are read_excel(), create_model(), report() and plot(). More functions can be found in the document API reference.
`pyomo.opt.base`_ is a utility package by pyomo and provides the function SolverFactory that allows creating a solver object. This objects hides the differences in input/output formats among solvers from the user. More on that in section Solving below.
datetime is used to append the current date and time to the result directory name (used in prepare_result_directory())

Settings¶

From here on, the script is best read from the back.:

if __name__ == '__main__':
    input_file = 'mimo-example.xlsx'
    result_name = os.path.splitext(input_file)[0]  # cut away file extension
    result_dir = prepare_result_directory(result_name)  # name + time stamp

    (offset, length) = (4000, 5*24)  # time step selection
    timesteps = range(offset, offset+length+1)

Variable input_file defines the input spreadsheet, from which the optimization problem will draw all its set/parameter data.

Variable timesteps is the list of timesteps to be simulated. Its members must be a subset of the labels used in input_file’s sheets “Demand” and “SupIm”. It is one of the two function arguments to create_model() and accessible directly, because one can quickly reduce the problem size by reducing the simulation length, i.e. the number of timesteps to be optimised.

range() is used to create a list of consecutive integers. The argument +1 is needed, because range(a,b) only includes integers from a to b-1:

>>> range(1,11)
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

The following section deals with the definition of different scenarios. Starting from the same base scenarios, defined by the data in input_file, they serve as a short way of defining the difference in input data. If needed, completely separate input data files could be loaded as well.

In addition to defining scenarios, the scenarios list allows to select a subset to be actually run.

Scenario functions¶

A scenario is simply a function that takes the input data and modifies it in a certain way. with the required argument data, the input data dict.:

# SCENARIOS
def scenario_base(data):
    # do nothing
    return data

The simplest scenario does not change anything in the original input file. It usually is called “base” scenario for that reason. All other scenarios are defined by 1 or 2 distinct changes in parameter values, relative to this common foundation.:

def scenario_stock_prices(data):
    # change stock commodity prices
    co = data['commodity']
    stock_commodities_only = (co.index.get_level_values('Type') == 'Stock')
    co.loc[stock_commodities_only, 'price'] *= 1.5
    return data

For example, scenario_stock_prices() selects all stock commodities from the DataFrame commodity, and increases their price value by 50%. See also pandas documentation Selection by label for more information about the .loc function to access fields. Also note the use of Augmented assignment statements (*=) to modify data in-place.:

def scenario_co2_limit(data):
    # change global CO2 limit
    hacks = data['hacks']
    hacks.loc['Global CO2 limit', 'Value'] *= 0.05
    return data

Scenario scenario_co2_limit() shows the simple case of changing a single input data value. In this case, a 95% CO2 reduction compared to the base scenario must be accomplished. This drastically limits the amount of coal and gas that may be used by all three sites.:

def scenario_north_process_caps(data):
    # change maximum installable capacity
    pro = data['process']
    pro.loc[('North', 'Hydro plant'), 'cap-up'] *= 0.5
    pro.loc[('North', 'Biomass plant'), 'cap-up'] *= 0.25
    return data

Scenario scenario_north_process_caps() demonstrates accessing single values in the process DataFrame. By reducing the amount of renewable energy conversion processes (hydropower and biomass), this scenario explores the “second best” option for this region to supply its demand.:

def scenario_all_together(data):
    # combine all other scenarios
    data = scenario_stock_prices(data)
    data = scenario_co2_limit(data)
    data = scenario_north_process_caps(data)
    return data

Scenario scenario_all_together() finally shows that scenarios can also be combined by chaining other scenario functions, making them dependent. This way, complex scenario trees can written with any single input change coded at a single place and then building complex composite scenarios from those.

Scenario selection¶

# select scenarios to be run
scenarios = [
    scenario_base,
    scenario_stock_prices,
    scenario_co2_limit,
    scenario_north_process_caps,
    scenario_all_together]
scenarios = scenarios[:1]  # select by slicing

In Python, functions are objects, so they can be put into data structures just like any variable could be. In the following, the list scenarios is used to control which scenarios are being actually computed.

Run scenarios¶

for scenario in scenarios:
    prob = run_scenario(input_file, timesteps, scenario, result_dir)

Having prepared settings, input data and scenarios, the actual computations happen in the function run_scenario() of the script. It is executed for each of the scenarios included in the scenario list. The following sections describe the content of function run_scenario(). In a nutshell, it reads the input data from its argument input_file, modifies it with the supplied scenario, runs the optimisation for the given timesteps and writes report and plots to result_dir.

Reading input¶

# scenario name, read and modify data for scenario
sce = scenario.__name__
data = urbs.read_excel(input_file)
data = scenario(data)

Function read_excel() returns a dict data of six pandas DataFrames with hard-coded column names that correspond to the parameters of the optimization problem (like eff for efficiency or inv-cost-c for capacity investment costs). The row labels on the other hand may be freely chosen (like site names, process identifiers or commodity names). By convention, it must contain the six keys commodity, process, storage, transmission, demand, and supim. Each value must be a pandas.DataFrame, whose index (row labels) and columns (column labels) conforms to the specification given by the example dataset in the spreadsheet mimo-example.xlsx.

data is then modified by applying the scenario() function to it.

Solving¶

# create model
prob = urbs.create_model(data, timesteps)
if PYOMO3:
    prob = prob.create()

# refresh time stamp string and create filename for logfile
now = prob.created
log_filename = os.path.join(result_dir, '{}.log').format(sce)

# solve model and read results
optim = SolverFactory('glpk')  # cplex, glpk, gurobi, ...
optim = setup_solver(optim, logfile=log_filename)
result = optim.solve(prob, tee=True)
if PYOMO3:
    prob.load(result)
else:
    prob.solutions.load_from(result)

This section is the “work horse”, where most computation and time is spent. The optimization problem is first defined (create_model()), then filled with values (create). The SolverFactory object is an abstract representation of the solver used. The returned object optim has a method set_options() to set solver options (not used in this tutorial).

The remaining two lines call the solver and read the result object back into the prob object, which is queried to for variable values in the remaining script file. Argument tee=True enables the realtime console output for the solver. If you want less verbose output, simply set it to False or remove it.

Reporting¶

# write report to spreadsheet
urbs.report(
    prob,
    os.path.join(result_dir, '{}-{}.xlsx').format(sce, now),
    ['Elec'], ['South', 'Mid', 'North'])

The urbs.report() function creates a spreadsheet from the main results. Summaries of costs, emissions, capacities (process, transmissions, storage) are saved to one sheet each. For timeseries, each combination of the given sites and commodities are summarised both in sum (in sheet “Energy sums”) and as individual timeseries (in sheet “… timeseries”). See also Reporting function explained for a detailed explanation of this function’s implementation.

Plotting¶

# add or change plot colors
my_colors = {
    'South': (230, 200, 200),
    'Mid': (200, 230, 200),
    'North': (200, 200, 230)}
for country, color in my_colors.items():
    urbs.COLORS[country] = color

First, the use of the module constant COLORS for customising plot colors is demonstrated. All plot colors are user-defineable by adding color tuple() (r, g, b) or modifying existing tuples for commodities and plot decoration elements. Here, new colors for displaying import/export are added. Without these, pseudo-random colors are generated in to_color().:

# create timeseries plot for each demand (site, commodity) timeseries
for sit, com in prob.demand.columns:
    # create figure
    fig = urbs.plot(prob, com, sit)

    # change the figure title
    ax0 = fig.get_axes()[0]
    nice_sce_name = sce.replace('_', ' ').title()
    new_figure_title = ax0.get_title().replace(
        'Energy balance of ', '{}: '.format(nice_sce_name))
    ax0.set_title(new_figure_title)

    # save plot to files
    for ext in ['png', 'pdf']:
        fig_filename = os.path.join(
            result_dir, '{}-{}-{}-{}.{}').format(sce, com, sit, now, ext)
        fig.savefig(fig_filename, bbox_inches='tight')

Finally, for each demand commodity (only Elec in this case), a plot over the whole optimisation period is created. If timesteps were longer, a shorter plotting period could be defined and given as an optional argument to plot().

The paragraph “change figure title” shows exemplarily how to use matplotlib manually to modify some aspects of a plot without having to recreate the plotting function from scratch. For more ideas for adaptations, look into plot()’s code or the matplotlib documentation.

The last paragraph uses the savefig() method to save the figure as a pixel png (raster) and pdf (vector) image. The bbox_inches='tight' argument eliminates whitespace around the plot.

Note

savefig() has some more interesting arguments. For example dpi=600 can be used to create higher resolution raster output for use with printing, in case the preferable vector images cannot be used. The filename extension or the optional format argument can be used to set the output format. Available formats depend on the used plotting backend. Most backends support png, pdf, ps, eps and svg.

Workflow¶

This page is a step-by-step explanation on how to get one’s own model running. For the sake of an example, assume you want to investigate whether the (imaginary) state New Sealand with its four islands Vled Haven, Qlyph Archipelago, Stryworf Key, and Jepid Island would benefit by linking their islands’ power systems by costly underground cables to better integrate fluctuating wind power generation.

Prerequisites¶

You have followed the sections installation instructions and get started in the README, i.e. you can successfully execute an optimisation run with the example dataset mimo-example.xlsx with the example run script runme.py. These two files will serve as a scaffold for your own investigation.

Create a private development branch¶

Using git, create and directly checkout a new branch with a topical name. Good names should tell you the goal of a branch, so something along the lines of test1234 is no good name. For this project, newsealand looks like a good name:

$ git checkout -b newsealand

The private branch can be used to commit your own changes, while benefitting from new features/bug fixes that are pushed to the master branch on GitHub. Whenever you want to retreive those new changes, execute the following commands:

$ git fetch origin
$ git rebase origin/master

A full explanation of how to use git is beyond the scope of this documentation, so please refer to the Git book, especially chapter 1, 2, 3.

Create an input data file¶

Create a copy of the file mimo-example.xlsx and give it short, descriptive name newsealand.xlsx. Open it.

Go through the sheets, either adding, deleting or modifying rows. Keep the column titles as they are, because they are required by the model. Each title has a tooltip that explains the use of the parameter.

If you have created a development branch, this is a good time to add this file to version control:

$ git add newsealand.xlsx
$ git commit -m "added newsealand.xlsx"

Site, DSM and Buy-Sell-price¶

Note at the outset, that you do not have to worry about the three mentioned worksheets, since they are not used for this tutorial. You need to keep them, however, and modify them in order to avoid problems. First, specify the four desired Sites in Site and set all values to either NV() or inf. In the sheet DSM enter the four islands of New Sealand as sites into the corresponding fields and set all values in the columns cap-max-do and cap-max-up to 0. You do not need to change anything in sheet Buy-Sell-Price.

Commodity¶

Remove the rows with unneeded commodities, here everything except Gas, Elec, Wind, CO2, and Slack. New Sealand only uses these for power generation. While Slack is not needed, it makes debugging unexpected model behaviour much easier. Better keep it. Rename the sites to match the island names. The file should now contain 20 rows, 5 for each island.

Let’s assume that Jepid Island does not have access to Gas, so change the parameter max and maxperstep to 0. Island Stryworf Key does have a gas connection, but the pipeline can only deliver 50 MW worth of Gas power.

These steps result in the following table. The bolded values result from the assumptions described in the previous paragraphs. The other values are left unchanged from the example dataset:

Sheet **Commodity**; empty cells correspond to `=NV()` (*no value*) fields¶
Site	Commodity	Type	price	max	maxperstep
Jepid Island	CO2	Env		inf	inf
Jepid Island	Elec	Demand
Jepid Island	Gas	Stock	27.0	0.0	0.0
Jepid Island	Slack	Stock	999.0	inf	inf
Jepid Island	Wind	SupIm
Qlyph Archipelago	CO2	Env		inf	inf
Qlyph Archipelago	Elec	Demand
Qlyph Archipelago	Gas	Stock	27.0	inf	inf
Qlyph Archipelago	Slack	Stock	999.0	inf	inf
Qlyph Archipelago	Wind	SupIm
Stryworf Key	CO2	Env		inf	inf
Stryworf Key	Elec	Demand
Stryworf Key	Gas	Stock	27.0	inf	50.0
Stryworf Key	Slack	Stock	999.0	inf	inf
Stryworf Key	Wind	SupIm
Vled Haven	CO2	Env		inf	inf
Vled Haven	Elec	Demand
Vled Haven	Gas	Stock	27.0	inf	inf
Vled Haven	Slack	Stock	999.0	inf	inf
Vled Haven	Wind	SupIm

You have done some work already. It’s time for another commit. Instead of adding every changed file manually, you can add option -a to the commit, which adds all unstaged changes from git status to the next commit. With that:

$ git commit -am "changed commodities to 4 islands in newsealand.xlsx"

Note

From now on, commit yourself whenever you reach a point you want to be able to go back to later.

Process¶

First, remove any process from sheet Process-Commodity that consumes or produces a commodity that is no longer mentioned in sheet Commodity. For New Sealand, this leaves us with three processes: Gas plant, Slack powerplant, Wind park. The output ratio 0.6 of the Gas plant is the electric efficiency.

Sheet **Process-Commodity**¶
Process	Commodity	Direction	ratio
Gas plant	CO2	Out	0.2
Gas plant	Elec	Out	0.6
Gas plant	Gas	In	1.0
Slack powerplant	CO2	Out	0.0
Slack powerplant	Elec	Out	1.0
Slack powerplant	Slack	In	1.0
Wind park	Elec	Out	1.0
Wind park	Wind	In	1.0

With only these processes remaining, the sheet Process, needs some work, too. create an entry for each process that can be built at a given site. The upper capacity limits cap-up for each process are the most important figure. Qlyph Archipelago is known for its large areas suitable for wind parks up to 200 MW, only surpased by the great offshore sites of Jepid Island with 250 MW potential capacity. The other islands only have space for up to 120 MW or 80 MW. Gas plants can be built up to 100 MW on every island, except for Vled Haven, which can house up to 80 MW only.

Slack powerplants are set to an installed capacity inst-cap higher than the peak demand in each site, so that any residual load could always be covered. To make its use unattractive, you set the variable costs var-cost to 9 M€/MWh. This yields the following table:

Sheet **Process**¶
Site	Process	inst-cap	cap-lo	cap-up	max-grad	inv-cost	fix-cost	var-cost	wacc	depr.
Jepid Island	Gas plant	25	0	100	5	450000	6000	1.62	0.07	30
Jepid Island	Slack powerplant	999	999	999	inf	0	0	9000000.0	0.07	1
Jepid Island	Wind park	0	0	250	inf	900000	30000	0.0	0.07	25
Qlyph Archipelago	Gas plant	0	0	100	5	450000	6000	1.62	0.07	30
Qlyph Archipelago	Slack powerplant	999	999	999	inf	0	0	9000000.0	0.07	1
Qlyph Archipelago	Wind park	0	0	200	inf	900000	30000	0.0	0.07	25
Stryworf Key	Gas plant	25	0	100	5	450000	6000	1.62	0.07	30
Stryworf Key	Slack powerplant	999	999	999	inf	0	0	9000000.0	0.07	1
Stryworf Key	Wind park	0	0	120	inf	900000	30000	0.0	0.07	25
Vled Haven	Gas plant	0	0	80	5	450000	6000	1.62	0.07	30
Vled Haven	Slack powerplant	999	999	999	inf	0	0	9000000.0	0.07	1
Vled Haven	Wind park	0	0	80	inf	900000	30000	0.0	0.07	25

Transmission¶

On transmission, map the network topology of New Sealand. Vled Haven is the central hub of the state, with the other islands connected like a star shape. The investment costs are scaled according to the air distance from the population centers of each island. So Jepid Island with 1.1 M€/MW investment costs is more than twice as far away from Vled Haven than Ylyph Archipelago with only 0.5 M€/MW. Stryworf Key is somewhere between with 0.8 M€/MW. All investment costs are per direction. So the bidirectional cable costs are actually the summed inv-cost for both directions.

Sheet **Transmission**¶
Site In	Site Out	Transmission	Commodity	eff	inv-cost	fix-cost	cap-up	wacc	depr.
Jepid Island	Vled Haven	undersea	Elec	0.85	1100000	30000	inf	0.07	30
Qlyph Archipelago	Vled Haven	undersea	Elec	0.95	500000	15000	inf	0.07	30
Stryworf Key	Vled Haven	undersea	Elec	0.9	800000	22500	inf	0.07	30
Vled Haven	Jepid Island	undersea	Elec	0.85	1100000	30000	inf	0.07	30
Vled Haven	Qlyph Archipelago	undersea	Elec	0.95	500000	15000	inf	0.07	30
Vled Haven	Stryworf Key	undersea	Elec	0.9	800000	22500	inf	0.07	30

Storage¶

Storing electricity is possible only on Qlyph Archipelago, using an unsepcified technology simply labeled gravity here. To allow for parameterising a host of technologies, costs for both storage power and capacity can be specified independently. For most technologies, one of the costs will be dominating, so the other value can be set simply (near) zero to reflect that. The last parameter init specifies a) how full the storage is at the first time step and b) at least how full it must be at the final time step. That way, a short simulation duration may not just exhaust the storage.

Sheet **Storage** (1/2)¶
Site	Storage	Commodity	inst-cap-c	cap-lo-c	cap-up-c	inst-cap-p	cap-lo-p	cap-up-p	eff-in	eff-out
Qlyph Archipelago	gravity	Elec	0	0	inf	0	0	inf	0.95	0.95

Sheet **Storage** (2/2)¶
Site	Storage	Commodity	inv-cost-p	inv-cost-c	fix-cost-p	fix-cost-c	var-cost-p	var-cost-c	depr.	wacc	init
Qlyph Archipelago	gravity	Elec	500000	5	0	0.25	0.02	0	50	0.07	0.05

Hacks¶

In the base scenario, no limit on CO2 emissions from Gas plants is needed. Therefore, you set the value to inf:

Sheet **Hacks**¶
Name	Value
Global CO2 limit	inf

Time series¶

The only commodity of type SupIm is Wind, which you defined in sheet Commodity on all four islands. Therefore, in total 4 time series must be provided here, even if they are all zeros. As your data provider has not kept his promise to send you the data on time, you (ab)use the mimo-example.xlsx data once more, and simply use its time series. To get qualitatively correct results, you assign the best (3600 full load hours) to Jepid island, the second best to Vled Haven (3000 full load hours) and two copies of the worst time series (2700 full load hours) to Qlyph Archipelago and Stryworf Key. With that, you get the following table of capacity factors:

Sheet **SupIm**¶
t	Jepid Island.Wind	Qlyph Archipelago.Wind	Stryworf Key.Wind	Vled Haven.Wind
0	0.0	0.0	0.0	0.0
1	0.603	0.935	0.935	0.458
2	0.585	0.942	0.942	0.453
3	0.571	0.956	0.956	0.453
4	0.561	0.956	0.956	0.461
…	…	…	…	…

You make sure that both the island names and the commodity name exactly match the identifiers used on the other sheets.

For the demand, you also have no real data for now. But with some scaling (divide by 1000), the example series make for a good temporary demand time series. Vled Haven has the highest peak load with 75 MW, followed by Stryworf Key with 19 MW and the other islands with 8.2 MW each:

Sheet **Demand**¶
t	Jepid Island.Elec	Qlyph Archipelago.Elec	Stryworf Key.Elec	Vled Haven.Elec
0	0	0	0	0
1	4	4	11	43
2	4	4	10	41
3	4	4	10	40
4	4	4	10	40
…	…	…	…	…

Note

For reference, this is how newsealand.xlsx looks for me having performed the above steps.

Test-drive the input¶

Now that newsealand.xlsx is ready to go, start ipython in the console. Execute the following lines, best by manually typing them in one by one. (Hint: use tab completion to avoid typing out function or file names!)

First, load the data:

>>> import urbs
>>> input_file = 'newsealand.xlsx'
>>> data = urbs.read_excel(input_file)

data now is a standard Python dict. So data.keys() yields the worksheet names, while data['commodity'] contains the Commodity worksheet as a DataFrame. Now create a range:

>>> offset, duration = (3500, 14*24)
>>> timesteps = range(offset, offset + duration + 1)

[3500, 3501, ..., 3836]

Now you can create the optimisation model, then convert it to an optimisation problem that can be handed to the solver:

>>> prob = urbs.create_model(data, timesteps)

Now the only thing missing is the solver. It can be used through another object that is generated by the SolverFactory function from the pyomo package:

>>> import pyomo.environ
>>> from pyomo.opt.base import SolverFactory
>>> optim = SolverFactory('glpk')

Ignore the deprecation warning [1] for now. The solver object has a solve method, which takes the problem as an argument and returns a solution. For bigger problems, the next step can take several hours or even days. Therefore, you enable visible progress output by setting the option tee [2]. Additionally, you can save the output to a logfile using the logfile option:

>>> result = optim.solve(prob, logfile='solver.log', tee=True)

This results in roughly the following output appearing on the console:

GLPSOL: GLPK LP/MIP Solver, v4.55
[...]
GLPK Simplex Optimizer, v4.55
26275 rows, 22558 columns, 63630 non-zeros
Preprocessing...
14793 rows, 13120 columns, 35970 non-zeros
Scaling...
 A: min|aij| = 2.305e-003  max|aij| = 1.053e+000  ratio = 4.567e+002
GM: min|aij| = 3.606e-001  max|aij| = 2.773e+000  ratio = 7.691e+000
EQ: min|aij| = 1.300e-001  max|aij| = 1.000e+000  ratio = 7.691e+000
Constructing initial basis...
Size of triangular part is 14790
      0: obj =  3.000000000e+005  infeas = 2.158e+004 (3)
    500: obj =  2.443067336e+007  infeas = 8.024e+003 (3)
   1000: obj =  3.635166806e+011  infeas = 5.311e+003 (3)
*  1379: obj =  1.688377193e+012  infeas = 0.000e+000 (3)
[...]
*  5500: obj =  3.438413434e+007  infeas = 6.221e-014 (3)
*  5822: obj =  3.419699391e+007  infeas = 7.889e-031 (3)
OPTIMAL LP SOLUTION FOUND
Time used:   3.5 secs
Memory used: 25.3 Mb (26496968 bytes)
Writing basic solution to '<temporary.glpk.raw>'...
48835 lines were written

Finally, you can load the result back into the optimisation problem oject prob:

>>> prob.solutions.load_from(result)
True

This object now contains all input data, the equations and result data. If you store this object as a file, you can later always create new analyses from it. That’s what save() is made for:

>>> urbs.save(prob, 'newsealand-base.pgz')

This becomes especially helpful for large problems that take hours to solve. Back to the prob. To get a quick numerical overview on the most important result numbers, use report():

>>> urbs.report(prob, 'report.xlsx',prob.com_demand,prob.sit)

By default, this report only includes total costs and capacities of process, transmission and storage. By adding the optional third and fourth parameter, you can retreive timeseries listings of energy production per site. For now, you are only interested in electricity in Vled Haven:

>>> urbs.report(prob, 'report-vled-haven.xlsx',
...             ['Elec'], ['Vled Haven'])

Then you finally want to see how the electricity production looks like. For that you use plot():

>>> %matplotlib
>>> fig = urbs.plot(prob, 'Elec', 'Vled Haven')

_images/newsealand_base-Elec-Vled-Haven.png

Depending on the plotting backend, you now either see a window with the plot (‘TkAgg’, ‘QtAgg’), or nothing. Either way, you can save the figure to a file using:

>>>  fig.savefig('newsealand-base-elec-vled-haven.png',
...              dpi=300, bbox_inches='tight')

The file extension determines how the output is written. Among the supported formats are jpg, pdf, png, svg and tif. Use png if raster images are needed and rely on pdf or svg for vector output. The dpi option is only used for raster images. bbox_inches='tight' removes unnecessary whitespace around the plot, making it suitable for inclusion in reports or presentations.

Create a run script¶

As it is quite tedious to perform the above actions by hand all the time, a script can automate these. This is where a runme.py script becomes handy.

Create a copy of the script file runme.py and give it a suitable name, e.g. runns.py.

Modify the scenario_co2_limit function. As the base scenario now has no limit, reducing it by 95 % does not make it finite. Therefore you set a fixed hard (annual) limit of 40 million tonnes of CO2 equivalent:

 def scenario_co2_limit(data):
     # change global CO2 limit
     hacks = data['hacks']
     hacks.loc['Global CO2 limit', 'Value'] = 40000
     return data

Next, set adjust the plot_tuples and report_tuples by replacing North, Mid and South by the four islands of Newsealand. Furthermore, you want to show imported/exported electricity in the plots in custom colors. So you modify the my_colors dict like this:

my_colors = {
    'Vled Haven': (230, 200, 200),
    'Stryworf Key': (200, 230, 200),
    'Qlyph Archipelago': (200, 200, 230),
    'Jepid Island': (215,215,215)}

Finally, you head down to the if __name__ == '__main__' section that is executed when the script is called. There, you change the input_file to your spreadsheet newsealand.xlsx and increase the optimisation duration to 14 days (14*24 time steps). For now, you don’t need the other scenarios, so you exclude them from the scenarios list:

 if __name__ == '__main__':
     input_file = 'newsealand.xlsx'
     result_name = os.path.splitext(input_file)[0]  # cut away file extension
     result_dir = prepare_result_directory(result_name)  # name + time stamp

     (offset, length) = (3500, 14*24)  # time step selection
     timesteps = range(offset, offset+length+1)

     # select scenarios to be run
     scenarios = [
         scenario_base,
         scenario_co2_limit]

     for scenario in scenarios:
         prob = run_scenario(input_file, timesteps, scenario, result_dir)

Note

For reference, here is how runns.py looks for me.

[1]	If you used Coopr 4.0, simply `import coopr.environ` before importing `SolverFactory`.

[2]	like the GNU tee output redirection tool.

Technical documentation¶

Continue here if you want to automate the scripting further, understand the model equations or extend the model yourself.

Reporting function explained¶

This page is a “code walkthrough” through the function report(). It shows more technical details than the Tutorial or Workflow pages, to facilitate writing one’s own analysis scripts that directly retrieve variables from the optimisation:

Report¶

So let’s start by first printing the function as a whole:

After the function header and the docstring briefly explaining its use, another function, get_constants(), is called. Before really diving into the report function, first one of the two Retrieve results functions is presented.

Get constants¶

Taking only one argument, this function retrieves all time-independent quantities from the given optimisation problem object and returns them as a tuple() of DataFrame. The low-level access functions get_entity() and get_entities() are beyond the scope of this walk through. They both yield “raw” DataFrame objects with only minor pre-processing of index names.

The second paragraph deals with the emission timeseries co2 by calculating its sum over time. The unstack() method allows to move the time dimension (index level 0 or the first) into the column direction. To sum over time, method sum() is called with its axis argument set to columns (1). This yields a DataFrame indexed over the tuple (site, process, input commodity, output commodity) and the summed emissions as value.

Get timeseries¶

With the arguments instance, com and sit the function :func: get_timeseries returns DataFrames of all timeseries that are referring to the given commodity and site. This includes the derivative for created and consumed, which is calculated and standardized by the power capacity at the end of the function.

Write to Excel¶

The ExcelWriter class creates a writer object, which is then used by the to_excel() method calls to aggregate all outputs into a single spreadsheet.

Note

to_excel() can also be called with a filename. However, this overwrites an existing file completely, thus deleting existing sheets. For quickly saving a DataFrame, to a spreadsheet, a simple df.to_excel('df.xlsx', 'df') is sufficient.

Constants¶

As written already, the individual DataFrame objects are written to individual sheets within the same spreadsheet file by using the writer object as a target. co2 is an exception, as it starts as a Series. It must be first converted to a DataFrame by calling to_frame().

Timeseries¶

Initialize an empty list() and an empty dict() for collecting the timeseries data. These are two builtin Python data structures. energies will become a list of DataFrame objects before getting stitched together, while timeseries becomes a dictionary of DataFrame objects, with a tuple (commodity, site) as key.

Module function get_timeseries() is similar to get_constants(), just for time-dependent quantities. For a given commodity and site, this function returns all DataFrames needed to create a balance plot.

Only overproduction is calculated in place. While it should not happen for scenarios close to today’s situation, future scenarios with much excess renewable infeed, overproduction could happen for significant duration and amount.

Using the function pandas.concat(), multiple DataFrames are glued together next to each other (axis=1), while creating a nested column index wih custom labels (keys=...) for each of the list argument ([...]). The resulting timeseries tableau is copied to the corresponding place in the timeseries dictionary.

For the Energy sums sheet, all timeseries DataFrames are summed along the time axis, resulting in a Series for each timeseries. These are then glued together on top of each other (axis=0) with a nested row index with custom labels (keys=...) for each series type. Finally the Series is converted back to a DataFrame, using Commodity.Site as the column title template.

Finally, the Energy sums table is assembled by stitching together the individual energy sums per commodity and site and filling missing values with fillna().

Finally, the timeseries tables are saved without change to individual sheets.

urbs.py module description¶

Overview¶

The following is a minimum “hello world” script that shows the life cycle of the optimization object prob, and how the various urbs module functions create it, modify it and process it.:

import urbs
from pyomo.opt.base import SolverFactory

# read input, create optimisation problem
data = urbs.read_excel('mimo-example.xlsx')
prob = urbs.create_model(data)

# solve problem, read results
optim = SolverFactory('glpk')
result = optim.solve(prob)
prob.solutions.load_from(result)

# save problem instance (incl. input and result) for later analyses
urbs.save(prob, 'mimo-example.pgz')

# write report and plot timeseries
urbs.report(prob, 'report.xlsx')
urbs.plot(prob, 'Elec', 'Mid')

The following lists and describes the use of all module-level functions. They are roughly ordered from high-level to low-level access, followed by helper functions.

Create model¶

urbs.read_excel(filename)¶

Parameters:	filename (str) – spreadsheet filename
Returns:	urbs input dict

The spreadsheet must contain 7 sheets labelled ‘Commodity’, ‘Process’, ‘Process-Commodity’, ‘Transmission’, ‘Storage’, ‘Demand’ and ‘SupIm’. It can contain 2 additional sheets called ‘Buy-Sell-Price’ and ‘Hacks’. If present, function add_hacks() is called by create_model() upon model creation.

Refer to the mimo-example.xlsx file for exemplary documentation of the table contents and definitions of all attributes by selecting the column titles.

urbs.create_model(data, timesteps)¶

Returns a Pyomo ConcreteModel object.

Parameters:	data (dict) – input like created by `read_excel()` timesteps (list) – consecutive list of modelled timesteps
Returns:	urbs model object

Timestep numbers must match those of the demand and supim timeseries.

If argument data has the key 'hacks', function add_hacks() is called with data['hacks'] as the second argument.

urbs.add_hacks(model, hacks)¶: Is called by create_model() to add special elements, e.g. constraints, to the model. Each hack, if present, can trigger the creation of additional sets, parameters, variables or constraints. Refer to the code of this function to see which hacks exists and what they do.

As of v0.3, only one hack exists: if a line “Global CO2 limit” exists in the hacks DataFrame, its value is used as a global upper limit for a constraint that limits the annual creation of the commodity “CO2”.

param model: urbs model object (not instance!)

param hacks: a DataFrame of hacks

return model: the modified urbs model object

Report & plotting¶

These two high-level functions cover the envisioned use of the unmodified urbs model and should cover most use cases.

urbs.plot(prob, com, sit[, timesteps=None])¶

Parameters:	prob – urbs model instance com (str) – commodity name to plot sit (str) – site name to plot timesteps (list) – timesteps to plot, default: all
Return fig:	matplotlib figure handle

urbs.report(prob, filename, commodities, sites)¶

Write optimisation result summary to spreadsheet.

Parameters:	prob – urbs model instance filename (str) – spreadsheet filename, will be overwritten if exists commodities (list) – list of commodities for which to output timeseries sites (list) – list sites for which to output timeseries

Retrieve results¶

While report() and plot() are quite flexible, custom result analysis scripts might be needed. These can be built on top of the following two medium-level functions. They retrieve all time-dependent and -independent quantities and return them as ready-to-use DataFrames.

urbs.get_constants(prob)¶

Return summary DataFrames for time-independent variables

Parameters:	prob – urbs model instance
Returns:	tuple of constants (costs, process, transmission, storage)

urbs.get_timeseries(prob, com, sit, timesteps=None)¶

Return DataFrames of all timeseries referring to a given commodity and site

Parameters:

prob – urbs model instance
com (str) – commodity name
sit (str) – site name
timesteps (list) – timesteps, default: all modelled timesteps

Returns:

tuple of timeseries (created, consumed, storage, imported, exported) tuple of DataFrames timeseries. These are:

created: timeseries of commodity creation, including stock source

consumed: timeseries of commodity consumption, including demand

storage: timeseries of commodity storage (level, stored, retrieved)

imported: timeseries of commodity import (by site)

exported: timeseries of commodity export (by site)

Persistence¶

To store valuable results for later analysis, or cross-scenario comparisons weeks after the original run, saving a problem instance with loaded results makes it possible to use one’s comparison scripts without having to solve the optimisation problem again. Simply load() the previously stored object using save():

urbs.save(prob, filename)¶

Save rivus model instance to a gzip’ed pickle file

Pickle is the standard Python way of serializing and de-serializing Python objects. By using it, saving any object, in case of this function a Pyomo ConcreteModel, becomes a twoliner.

GZip is a standard Python compression library that is used to transparently compress the pickle file further.

It is used over the possibly more compact bzip2 compression due to the lower runtime. Source: <http://stackoverflow.com/a/18475192/2375855>

Parameters:	prob – a rivus model instance filename (str) – pickle file to be written
Returns:	nothing

urbs.load(filename)¶

Load a rivus model instance from a gzip’ed pickle file

Parameters:	filename (str) – pickle file
Return prob:	the unpickled rivus model instance

Low-level access¶

If the previous functions still don’t cut it, there are three low-level functions.

urbs.list_entities(prob, entity_type)¶

Parameters:	prob – urbs model instance entity_type (str) – allowed values: set, par, var, con, obj
Returns:	a DataFrame with name, description and domain of entities

urbs.get_entity(prob, name)¶

Parameters:	prob – urbs model instance name (str) – name of a model entity
Returns:	Series with values of model entity

urbs.get_entities(prob, names)¶

Parameters:	prob – urbs model instance name (list) – list of model entity names
Returns:	DataFrame with values entities in columns

Only call get_entities for entities that share identical domains. This can be checked with list_entities(). For example, variable cap_pro naturally has the same domain as cap_pro_new.

Helper functions¶

urbs.annuity_factor(n, i)¶

Annuity factor formula.

Evaluates the annuity factor formula for depreciation duration and interest rate. Works also well for equally sized numpy arrays as input.

Parameters:	n (int) – number of depreciation periods (years) i (float) – interest rate (e.g. 0.06 means 6 %)
Returns:	value of the expression \(\frac{(1+i)^n i}{(1+i)^n - 1}\)

urbs.commodity_balance(m, tm, sit, com)¶

Calculate commodity balance at given timestep.

For a given commodity, site and timestep, calculate the balance of consumed (to process/storage/transmission, counts positive) and provided (from process/storage/transmission, counts negative) energy. Used as helper function in create_model() for defining constraints on demand and stock commodities.

Parameters:	m – the ConcreteModel object tm – the timestep number sit – the site co – the commodity
Returns:	amount of consumed (positive) or provided (negative) energy

urbs.split_columns(columns[, sep='.'])¶

Given a list of column labels containing a separator string (default: ‘.’), derive a MulitIndex that is split at the separator string.

Parameters:	columns (list) – column labels, each containing the separator string sep (str) – the separator string (default: ‘.’)
Returns:	a MultiIndex corresponding to input, with levels split at separator

urbs.to_color(obj=None)¶

Assign a deterministic pseudo-random color to argument.

If COLORS[obj] is set, return that. Otherwise, create a deterministically random color from the hash() of that object. For strings, this value depends only on the string content, so that identical strings always yield the same color.

Parameters:	obj – any hashable object
Returns:	a (r,g,b) tuple if COLORS[obj] exists, otherwise a hexstring

urbs.COLORS¶

dict of process and site colors. Colors are stored as (r,g,b) tuples in range 0-255 each. To retrieve a color in a form usable with matplotlib, used the helper function to_color().

This snippet from the example script runme.py shows how to add custom colors:

# add or change plot colours
my_colors = {
    'South': (230, 200, 200),
    'Mid': (200, 230, 200),
    'North': (200, 200, 230)}
for country, color in my_colors.items():
    urbs.COLORS[country] = color

Mathematical Documentation¶

In this Section, mathematical description of the model will be explained. This includes listing and describing all relevant sets, parameters, variables and constraints using mathematical notation together with corresponding code fragment.

Sets¶

Since urbs is a linear optimization model with many objects (e.g variables, parameters), it is reasonable to use sets to define the groups of objects. With the usage of sets, many facilities are provided, such as understanding the main concepts of the model. Many objects are represented by various sets, therefore sets can be easily used to check whether some object has a specific characteristic or not. Additionally sets are useful to define a hierarchy of objects. Mathematical notation of sets are expressed with uppercase letters, and their members are usually expressed with the same lowercase letters. Main sets, tuple sets and subsets will be introduced in this respective order.

Elementary sets¶

*Table: Model Sets*¶
Set	Description
\(t \in T\)	Timesteps
\(t \in T_\text{m}\)	Modelled Timesteps
\(v \in V\)	Sites
\(c \in C\)	Commodities
\(q \in Q\)	Commodity Types
\(p \in P\)	Processes
\(s \in S\)	Storages
\(f \in F\)	Transmissions
\(r \in R\)	Cost Types

Time Steps¶

The model urbs is considered to observe a energy system model and calculate the optimal solution within a limited span of time. This limited span of time is viewed as a discrete variable, which means values of variables are viewed as occurring only at distinct timesteps. The set of time steps \(T = \{t_0,\dots,t_N\}\) for \(N\) in \(\mathbb{N}\) represents Time. This set contains \(N+1\) sequential time steps with equal spaces. Each time step represents another point in time. At the initialisation of the model this set is fixed by the user by setting the variable timesteps in script runme.py. Duration of space between timesteps \(\Delta t = t_{x+1} - t_x\), length of simulation \(\Delta t \cdot N\) and time interval \([t_0,t_N]\) can be fixed to satisfy the needs of the user. In code this set is defined by the set t and initialized by the section:

m.t = pyomo.Set(
    initialize=m.timesteps,
    ordered=True,
    doc='Set of timesteps')

Where:

Initialize: A function that receives the set indices and model to return the value of that set element, initializes the set with data.
Ordered: A boolean value that indicates whether the set is ordered.
Doc: A string describing the set.

Modelled Timesteps¶

The Set, modelled timesteps, is a subset of the time steps set. The difference between modelled timesteps set and the timesteps set is that the initial timestep \(t_0\) is not included. All other features of the set time steps also apply to the set of modelled timesteps. This set is later required to facilitate the definition of the storage state equation. In script urbs.py this set is defined by the set tm and initialized by the code fragment:

m.tm = pyomo.Set(
    within=m.t,
    initialize=m.timesteps[1:],
    ordered=True,
    doc='Set of modelled timesteps')

Where:

Within: The option that supports the validation of a set array.
m.timesteps[1:] represents the timesteps set starting from the second element, excluding the first timestep \(t_0\)

Sites¶

Sites are represented by the set \(V\). A Site \(v\) can be any distinct location, a place of settlement or activity (e.g process, transmission, storage).A site is for example an individual building, region, country or even continent. Sites can be imagined as nodes(vertices) on a graph of locations, connected by edges. Index of this set are the descriptions of the Sites (e.g north, middle, south). In script urbs.py this set is defined by sit and initialized by the code fragment:

m.sit = pyomo.Set(
    initialize=m.commodity.index.get_level_values('Site').unique(),
    doc='Set of sites')

Commodities¶

As explained in the Overview section, commodities are goods that can be generated, stored, transmitted or consumed. The set of Commodities represents all goods that are relevant to the modelled energy system, such as all energy carriers, inputs, outputs, intermediate substances. (e.g Coal, CO2, Electric, Wind) By default, commodities are given by their energy content (MWh). Usage of some commodities are limited by a maximum value or maximum value per timestep due to their availability or restrictions, also some commodities have a price that needs to be compensated..(e.g coal, wind, solar).In script urbs.py this set is defined by com and initialized by the code fragment:

m.com = pyomo.Set(
    initialize=m.commodity.index.get_level_values('Commodity').unique(),
    doc='Set of commodities')

Commodity Types¶

Commodities differ in their usage purposes, consequently commodity types are introduced to subdivide commodities by their features. These Types are SupIm, Stock, Demand, Env, Buy, Sell. In script urbs.py this set is defined as com_type and initialized by the code fragment:

m.com_type = pyomo.Set(
    initialize=m.commodity.index.get_level_values('Type').unique(),
    doc='Set of commodity types')

Processes¶

One of the most important elements of an energy system is the process. A process \(p\) can be defined by the action of changing one or more forms of energy to others. In our modelled energy system, processes convert input commodities into output commodities. Process technologies are represented by the set processes \(P\). Different processes technologies have fixed input and output commodities. These input and output commodities can be either single or multiple regardless of each other. Some example members of this set can be: Wind Turbine,`Gas Plant`, Photovoltaics. In script urbs.py this set is defined as pro and initialized by the code fragment:

m.pro = pyomo.Set(
    initialize=m.process.index.get_level_values('Process').unique(),
    doc='Set of conversion processes')

Storages¶

Energy Storage is provided by technical facilities that store energy to generate a commodity at a later time for the purpose of meeting the demand. Occasionally, on-hand commodities may not be able to satisfy the required amount of energy to meet the demand, or the available amount of energy may be much more than required.Storage technologies play a major role in such circumstances. The Set \(S\) represents all storage technologies.(e.g Pump storage). In script urbs.py this set is defined as sto and initalized by the code fragment:

m.sto = pyomo.Set(
    initialize=m.storage.index.get_level_values('Storage').unique(),
    doc='Set of storage technologies')

Transmissions¶

Transmissions \(f \in F\) represent possible conveyances of commodities between sites. Transmission process technologies can vary between different commodities, due to distinct physical attributes and forms of commodities. Some examples for Transmission technologies are: hvac, hvdc, pipeline) In script urbs.py this set is defined as tra and initialized by the code fragment:

m.tra = pyomo.Set(
    initialize=m.transmission.index.get_level_values('Transmission').unique(),
    doc='Set of transmission technologies')

Cost Types¶

One of the major goals of the model is to calculate the costs of a simulated energy system. There are 6 different types of costs. Each one has different features and are defined for different instances. Set of cost types is hardcoded, which means they are not considered to be fixed or changed by the user. The Set \(R\) defines the Cost Types, each member \(r\) of this set \(R\) represents a unique cost type name. The cost types are : Investment, Fix, Variable, Fuel, Revenue, Purchase, Startup . In script urbs.py this set is defined as cost_type and initialized by the code fragment:

m.cost_type = pyomo.Set(
    initialize=['Inv', 'Fix', 'Var', 'Fuel','Revenue','Purchase','Startup'],
    doc='Set of cost types (hard-coded)')

Tuple Sets¶

A tuple is finite, ordered collection of elements.For example, the tuple (hat,red,large) consists of 3 ordered elements and defines another element itself. Tuples are needed in this model to define the combinations of elements from different sets. Defining a tuple lets us assemble related elements and use them as a single element. As a result a collection of by the same rule defined tuples, represents a tuple set.

Commodity Tuples¶

Commodity tuples represent combinations of defined commodities. These are represented by the set \(C_{vq}\). A member \(c_{vq}\) in set \(C_{vq}\) is a commodity \(c\) of commodity type \(q\) in site \(v\). For example, (Mid, Elec, Demand) is interpreted as commodity Elec of commodity type Demand in site Mid. This set is defined as com_tuples and given by the code fragment:

m.com_tuples = pyomo.Set(
    within=m.sit*m.com*m.com_type,
    initialize=m.commodity.index,
    doc='Combinations of defined commodities, e.g. (Mid,Elec,Demand)')

Process Tuples¶

Process tuples represent combinations of possible processes. These are represented by the set \(P_v\). A member \(p_v\) in set \(P_v\) is a process \(p\) in site \(v\). For example, (North, Coal Plant) is interpreted as process Coal Plant in site North. This set is defined as pro_tuples and given by the code fragment:

m.pro_tuples = pyomo.Set(
    within=m.sit*m.pro,
    initialize=m.process.index,
    doc='Combinations of possible processes, e.g. (North,Coal plant)')

A subset of these process tuples pro_partial_tuples \(P_v^\text{partial}\) is formed in order to identify processes that have partial & startup properties. Programmatically, they are identified by those processes, which have the parameter ratio-min set for one of their input commodities in table Process-Commodity. The tuple set is defined as:

m.pro_partial_tuples = pyomo.Set(
    within=m.sit*m.pro,
    initialize=[(site, process)
                for (site, process) in m.pro_tuples
                for (pro, _) in m.r_in_min_fraction.index
                if process == pro],
    doc='Processes with partial input')

A second subset is formed in order to caputure all processes that take up a certain area and are thus subject to the area constraint at the given site. These processes are identified by the parameter area-per-cap set in table Process, if at the same time a value for area is set in table Site. The tuple set is defined as:

m.pro_area_tuples = pyomo.Set(
    within=m.sit*m.pro,
    initialize=m.proc_area.index,
    doc='Processes and Sites with area Restriction')

Transmission Tuples¶

Transmission tuples represent combinations of possible transmissions. These are represented by the set \(F_{c{v_\text{out}}{v_\text{in}}}\). A member \(f_{c{v_\text{out}}{v_\text{in}}}\) in set \(F_{c{v_\text{out}}{v_\text{in}}}\) is a transmission \(f\),that is directed from an origin site \(v_\text{out}\) to a destination site \(v_{in}\) and carries a commodity \(c\). The term “directed from an origin site \(v_\text{out}\) to a destination site \(v_\text{in}\)” can also be defined as an Arc \(a\) . For example, (South, Mid, hvac, Elec) is interpreted as transmission hvac that is directed from origin site South to destination site Mid carrying commodity Elec. This set is defined as tra_tuples and given by the code fragment:

m.tra_tuples = pyomo.Set(
    within=m.sit*m.sit*m.tra*m.com,
    initialize=m.transmission.index,
    doc='Combinations of possible transmission, e.g. (South,Mid,hvac,Elec)')

Additionally, Subsets \(F_{vc}^\text{exp}\) and \(F_{vc}^\text{imp}\) represents all exporting and importing transmissions of a commodity \(c\) in a site \(v\). These subsets can be obtained by fixing either the origin site(for export) \(v_\text{out}\) or the destination site(for import) \(v_\text{in}\) to a desired site \(v\) in tuple set \(F_{c{v_\text{out}}{v_\text{in}}}\).

Storage Tuples¶

Storage tuples represent combinations of possible storages by site. These are represented by the set \(S_{vc}\). A member \(s_{vc}\) in set \(S_{vc}\) is a storage \(s\) of commodity \(c\) in site \(v\) For example, (Mid, Bat, Elec) is interpreted as storage Bat of commodity Elec in site Mid. This set is defined as sto_tuples and given by the code fragment:

m.sto_tuples = pyomo.Set(
    within=m.sit*m.sto*m.com,
    initialize=m.storage.index,
    doc='Combinations of possible storage by site, e.g. (Mid,Bat,Elec)')

Process Input Tuples¶

Process input tuples represent commodities consumed by processes. These are represented by the set \(C_{vp}^\text{in}\). A member \(c_{vp}^\text{in}\) in set \(C_{vp}^\text{in}\) is a commodity \(c\) consumed by the process \(p\) in site \(v\). For example, (Mid,PV,Solar) is interpreted as commodity Solar is consumed by the process PV in the site Mid. This set is defined as pro_input_tuples and given by the code fragment:

m.pro_input_tuples = pyomo.Set(
    within=m.sit*m.pro*m.com,
    initialize=[(site, process, commodity)
                for (site, process) in m.pro_tuples
                for (pro, commodity) in m.r_in.index
                if process == pro],
    doc='Commodities consumed by process by site, e.g. (Mid,PV,Solar)')

Where: r_in represents the process input ratio.

For processes in the tuple set pro_partial_tuples \(C_{vp}^\text{in,partial}\), the following tuple set pro_partial_input_tuples enumerates their input commodities. It is used to index the constraints that determine a process’ input commodity flow (i.e. def_process_input and def_partial_process_input). It is defined by the following code fragment:

m.pro_partial_input_tuples = pyomo.Set(
    within=m.sit*m.pro*m.com,
    initialize=[(site, process, commodity)
                for (site, process) in m.pro_partial_tuples
                for (pro, commodity) in m.r_in_min_fraction.index
                if process == pro],
    doc='Commodities with partial input ratio, e.g. (Mid,Coal PP,Coal)')

Process Output Tuples¶

Process output tuples represent commodities generated by processes. These are represented by the set \(C_{vp}^\text{out}\). A member \(c_{vp}^\text{out}\) in set \(C_{vp}^\text{out}\) is a commodity \(c\) generated by the process \(p\) in site \(v\). For example, (Mid,PV,Elec) is interpreted as the commodity Elec is generated by the process PV in the site Mid. This set is defined as pro_output_tuples and given by the code fragment:

m.pro_output_tuples = pyomo.Set(
    within=m.sit*m.pro*m.com,
    initialize=[(site, process, commodity)
                for (site, process) in m.pro_tuples
                for (pro, commodity) in m.r_out.index
                if process == pro],
    doc='Commodities produced by process by site, e.g. (Mid,PV,Elec)')

Where: r_out represents the process output ratio.

Demand Side Management Tuples¶

There are two kinds of demand side management (DSM) tuples in the model: DSM site tuples \(D_{vc}\) and DSM down tuples \(D_{vct,tt}^\text{down}\). The first kind \(D_{vc}\) represents all possible combinations of site \(v\) and commodity \(c\) of the DSM sheet. It is given by the code fragment:

m.dsm_site_tuples = pyomo.Set(
    within=m.sit*m.com,
    initialize=m.dsm.index,
    doc='Combinations of possible dsm by site, e.g. (Mid, Elec)')

The second kind \(D_{vct,tt}^\text{down}\) refers to all possible DSM downshift possibilities. It is defined to overcome the difficulty caused by the two time indices of the DSM downshift variable. Dependend on site \(v\) and commodity \(c\) the tuples contain two time indices. For example (5001, 5003, Mid, Elec) is intepreted as the downshift in timestep 5003, which was caused by the upshift of timestep 5001 in site Mid for commodity Elec. The tuples are given by the following code fragment:

m.dsm_down_tuples = pyomo.Set(
    within=m.tm*m.tm*m.sit*m.com,
    initialize=[(t, tt, site, commodity)
                for (t,tt, site, commodity) in dsm_down_time_tuples(m.timesteps[1:], m.dsm_site_tuples, m)],
    doc='Combinations of possible dsm_down combinations, e.g. (5001,5003,Mid,Elec)')

Commodity Type Subsets¶

Commodity Type Subsets represent the commodity tuples only from a given commodity type. Commodity Type Subsets are subsets of the sets commodity tuples These subsets can be obtained by fixing the commodity type \(q\) to a desired commodity type (e.g SupIm, Stock) in the set commodity tuples \(C_{vq}\). Since there are 6 types of commodity types, there are also 6 commodity type subsets. Commodity type subsets are;

Supply Intermittent Commodities (SupIm): The set \(C_\text{sup}\) represents all commodities \(c\) of commodity type SupIm. Commodities of this type have intermittent timeseries, in other words, availability of these commodities are not constant. These commodities might have various energy content for every timestep \(t\). For example solar radiation is contingent on many factors such as sun position, weather and varies permanently.

Stock Commodities (Stock): The set \(C_\text{st}\) represents all commodities \(c\) of commodity type Stock. Commodities of this type can be purchased at any time for a given price( \(k_{vc}^\text{fuel}\)).

Sell Commodities (Sell): The set \(C_\text{sell}\) represents all commodities \(c\) of commodity type Sell. Commodities that can be sold. These Commodities have a sell price ( \(k_{vct}^\text{bs}\) ) that may vary with the given timestep \(t\).

Buy Commodities (Buy): The set \(C_\text{buy}\) represents all commodities \(c\) of commodity type Buy. Commodities that can be purchased. These Commodities have a buy price ( \(k_{vc}^\text{bs}\) ) that may vary with the given timestep \(t\).

Demand Commodities (Demand): The set \(C_\text{dem}\) represents all commodities \(c\) of commodity type Demand. Commodities of this type are the requested commodities of the energy system. They are usually the end product of the model (e.g Electricity:Elec).

Environmental Commodities (Env): The set \(C_\text{env}\) represents all commodities \(c\) of commodity type Env. Commodities of this type are usually the undesired byproducts of processes that might be harmful for environment, optional maximum creation limits can be set to control the generation of these commodities (e.g Greenhouse Gas Emissions: \(\text{CO}_2\)).

Commodity Type Subsets are given by the code fragment:

m.com_supim = pyomo.Set(
    within=m.com,
    initialize=commodity_subset(m.com_tuples, 'SupIm'),
    doc='Commodities that have intermittent (timeseries) input')
m.com_stock = pyomo.Set(
    within=m.com,
    initialize=commodity_subset(m.com_tuples, 'Stock'),
    doc='Commodities that can be purchased at some site(s)')
m.com_sell = pyomo.Set(
   within=m.com,
   initialize=commodity_subset(m.com_tuples, 'Sell'),
   doc='Commodities that can be sold')
m.com_buy = pyomo.Set(
    within=m.com,
    initialize=commodity_subset(m.com_tuples, 'Buy'),
    doc='Commodities that can be purchased')
m.com_demand = pyomo.Set(
    within=m.com,
    initialize=commodity_subset(m.com_tuples, 'Demand'),
    doc='Commodities that have a demand (implies timeseries)')
m.com_env = pyomo.Set(
    within=m.com,
    initialize=commodity_subset(m.com_tuples, 'Env'),
    doc='Commodities that (might) have a maximum creation limit')

Where:

urbs.commodity_subset(com_tuples, type_name)¶

Returns the commodity names(\(c\)) of the given commodity type(\(q\)).

Parameters:	com_tuples – A list of tuples (site, commodity, commodity type) type_name – A commodity type or a list of commodity types
Returns:	The set (unique elements/list) of commodity names of the desired commodity type.

Variables¶

All the variables that the optimization model requires to calculate an optimal solution will be listed and defined in this section. A variable is a numerical value that is determined during optimization. Variables can denote a single, independent value, or an array of values. Variables define the search space for optimization. Variables of this optimization model can be seperated into sections by their area of use. These Sections are Cost, Commodity, Process, Transmission and Storage.

*Table: Model Variables*¶
Variable	Unit	Description
Cost Variables
\(\zeta\)	€/a	Total System Cost
\(\zeta_\text{inv}\)	€/a	Investment Costs
\(\zeta_\text{fix}\)	€/a	Fix Costs
\(\zeta_\text{var}\)	€/a	Variable Costs
\(\zeta_\text{fuel}\)	€/a	Fuel Costs
\(\zeta_\text{rev}\)	€/a	Revenue Costs
\(\zeta_\text{pur}\)	€/a	Purchase Costs
\(\zeta_\text{startup}\)	€/a	Startup Costs
Commodity Variables
\(\rho_{vct}\)	MW	Stock Commodity Source Term
\(\varrho_{vct}\)	MW	Sell Commodity Source Term
\(\psi_{vct}\)	MW	Buy Commodity Source Term
Process Variables
\(\kappa_{vp}\)	MW	Total Process Capacity
\(\hat{\kappa}_{vp}\)	MW	New Process Capacity
\(\tau_{vpt}\)	MW	Process Throughput
\(\epsilon_{vcpt}^\text{in}\)	MW	Process Input Commodity Flow
\(\epsilon_{vcpt}^\text{out}\)	MW	Process Output Commodity Flow
\(\omega_{vpt}\)	MW	Process Online Capacity
\(\phi_{vpt}\)	MW	Process Startup Capacity
Transmission Variables
\(\kappa_{af}\)	MW	Total transmission Capacity
\(\hat{\kappa}_{af}\)	MW	New Transmission Capacity
\(\pi_{aft}^\text{in}\)	MW	Transmission Power Flow (Input)
\(\pi_{aft}^\text{out}\)	MW	Transmission Power Flow (Output)
Storage Variables
\(\kappa_{vs}^\text{c}\)	MWh	Total Storage Size
\(\hat{\kappa}_{vs}^\text{c}\)	MWh	New Storage Size
\(\kappa_{vs}^\text{p}\)	MW	Total Storage Power
\(\hat{\kappa}_{vs}^\text{p}\)	MW	New Storage Power
\(\epsilon_{vst}^\text{in}\)	MW	Storage Power Flow (Input)
\(\epsilon_{vst}^\text{out}\)	MW	Storage Power Flow (Output)
\(\epsilon_{vst}^\text{con}\)	MWh	Storage Energy Content
Demand Side Management Variables
\(\delta_{vct}^\text{up}\)	MW	DSM Upshift
\(\delta_{vct,tt}^\text{down}\)	MW	DSM Downshift

Cost Variables¶

Total System Cost, \(\zeta\) : the variable \(\zeta\) represents the annual total expense incurred in reaching the satisfaction of the given energy demand. This is calculated by the sum total of all costs by type(\(\zeta_r\), \(\forall r \in R\)) and defined as costs by the following code fragment:

m.costs = pyomo.Var(
    m.cost_type,
    within=pyomo.Reals,
    doc='Costs by type (EUR/a)')

More information on calculation of this variable is available at the section Objective function.

Total System costs by type: System costs are divided into 6 cost types by their meaning and purpose. The separation of costs by type, facilitates business planning and provides calculation accuracy As mentioned before these cost types are hardcoded, which means they are not considered to be fixed or changed by the user. These cost types are as following;

Investment Costs \(\zeta_\text{inv}\): The variable \(\zeta_\text{inv}\) represents the annualised total investment costs. Costs for required new investments on storage, process and transmission technologies.

Fix Costs \(\zeta_\text{fix}\): The variable \(\zeta_\text{fix}\) represents the annualised total fix costs. Fix costs for all used storage, process, and transmission technologies. Such as maintenance costs.

Variable Costs \(\zeta_\text{var}\): The variable \(\zeta_\text{var}\) represents the annualised total variables costs. Variable costs that are reliant on the usage amount and period of the storage, process, transmission technologies.

Fuel Costs \(\zeta_\text{fuel}\): The variable \(\zeta_\text{fuel}\) represents the annualised total fuel costs. Fuel costs are dependent on the usage of stock commodities( \(\forall c \in C_\text{stock}\)).

Revenue Costs \(\zeta_\text{rev}\): The variable \(\zeta_\text{rev}\) represents the annualised total revenue costs. Revenue costs is defined for the costs that occures by selling the sell commodities( \(\forall c \in C_\text{sell}\)). Since this variable is an income for the system, it is either zero or has a negative value.

Purchase Costs \(\zeta_\text{pur}\): The variable \(\zeta_\text{pur}\) represents the annualised total purchase costs. Purchase costs is defined for the costs that occures by buying the buy commodities ( \(\forall c \in C_\text{buy}\) ).

Startup Costs \(\zeta_\text{startup}\): The variable \(\zeta_\text{startup}\) represents the annualised total startup costs. Startup costs are reliant on the yearly startup occurences of the processes.

For more information on calculation of these variables see section Objective function.

Commodity Variables¶

Stock Commodity Source Term, \(\rho_{vct}\), e_co_stock, MW : The variable \(\rho_{vct}\) represents the energy amount in [MW] that is being used by the system of commodity \(c\) from type stock (\(\forall c \in C_\text{stock}\)) in a site \(v\) (\(\forall v \in V\)) at timestep \(t\) (\(\forall t \in T_\text{m}\)). In script urbs.py this variable is defined by the variable e_co_stock and initialized by the following code fragment:

m.e_co_stock = pyomo.Var(
    m.tm, m.com_tuples,
    within=pyomo.NonNegativeReals,
    doc='Use of stock commodity source (MW) per timestep')

Sell Commodity Source Term, \(\varrho_{vct}\), e_co_sell, MW : The variable \(\varrho_{vct}\) represents the energy amount in [MW] that is being used by the system of commodity \(c\) from type sell (\(\forall c \in C_\text{sell}\)) in a site \(v\) (\(\forall v \in V\)) at timestep \(t\) (\(\forall t \in T_\text{m}\)). In script urbs.py this variable is defined by the variable e_co_sell and initialized by the following code fragment:

m.e_co_sell = pyomo.Var(
    m.tm, m.com_tuples,
    within=pyomo.NonNegativeReals,
    doc='Use of sell commodity source (MW) per timestep')

Buy Commodity Source Term, \(\psi_{vct}\), e_co_buy, MW : The variable \(\psi_{vct}\) represents the energy amount in [MW] that is being used by the system of commodity \(c\) from type buy (\(\forall c \in C_\text{buy}\)) in a site \(v\) (\(\forall v \in V\)) at timestep \(t\) (\(\forall t \in T_\text{m}\)). In script urbs.py this variable is defined by the variable e_co_buy and initialized by the following code fragment:

m.e_co_buy = pyomo.Var(
   m.tm, m.com_tuples,
   within=pyomo.NonNegativeReals,
   doc='Use of buy commodity source (MW) per timestep')

Process Variables¶

Total Process Capacity, \(\kappa_{vp}\), cap_pro: The variable \(\kappa_{vp}\) represents the total potential throughput (capacity) of a process tuple \(p_v\) (\(\forall p \in P, \forall v \in V\)), that is required in the energy system. The total process capacity includes both the already installed process capacity and the additional new process capacity that needs to be installed. Since the costs of the process technologies are mostly directly proportional to the maximum possible output (and correspondingly to the capacity) of processes, this variable acts as a scale factor of process technologies and helps us to calculate a more accurate cost plan. For further information see Process Capacity Rule. This variable is expressed in the unit MW. In script urbs.py this variable is defined by the model variable cap_pro and initialized by the following code fragment:

m.cap_pro = pyomo.Var(
    m.pro_tuples,
    within=pyomo.NonNegativeReals,
    doc='Total process capacity (MW)')

New Process Capacity, \(\hat{\kappa}_{vp}\), cap_pro_new: The variable \(\hat{\kappa}_{vp}\) represents the capacity of a process tuple \(p_v\) (\(\forall p \in P, \forall v \in V\)) that needs to be installed additionally to the energy system in order to provide the optimal solution. This variable is expressed in the unit MW. In script urbs.py this variable is defined by the model variable cap_pro_new and initialized by the following code fragment:

m.cap_pro_new = pyomo.Var(
    m.pro_tuples,
    within=pyomo.NonNegativeReals,
    doc='New process capacity (MW)')

Process Throughput, \(\tau_{vpt}\), tau_pro : The variable \(\tau_{vpt}\) represents the measure of (energetic) activity of a process tuple \(p_v\) (\(\forall p \in P, \forall v \in V\)) at a timestep \(t\) (\(\forall t \in T_{m}\)). By default, process throughput is represented by the major input commodity flow of the process (e.g. ‘Gas’ for ‘Gas plant’, ‘Wind’ for ‘Wind park’). Based on the process throughput amount in a given timestep of a process, flow amounts of the process’ input and output commodities at that timestep can be calculated by scaling the process throughput with corresponding process input and output ratios. For further information see Process Input Ratio and Process Output Ratio. This variable is expressed in the unit MW. In script urbs.py this variable is defined by the model variable tau_pro and initialized by the following code fragment:

m.tau_pro = pyomo.Var(
    m.tm, m.pro_tuples,
    within=pyomo.NonNegativeReals,
    doc='Activity (MW) through process')

Process Input Commodity Flow, \(\epsilon_{vcpt}^\text{in}\), e_pro_in: The variable \(\epsilon_{vcpt}^\text{in}\) represents the flow input into a process tuple \(p_v\) (\(\forall p \in P, \forall v \in V\)) caused by an input commodity \(c\) (\(\forall c \in C\)) at a timestep \(t\) (\(\forall t \in T_{m}\)). This variable is generally expressed in the unit MW. In script urbs.py this variable is defined by the model variable e_pro_in and initialized by the following code fragment:

m.e_pro_in = pyomo.Var(
    m.tm, m.pro_tuples, m.com,
    within=pyomo.NonNegativeReals,
    doc='Flow of commodity into process per timestep')

Process Output Commodity Flow, \(\epsilon_{vcpt}^\text{out}\), e_pro_out: The variable \(\epsilon_{vcpt}^\text{out}\) represents the flow output out of a process tuple \(p_v\) (\(\forall p \in P, \forall v \in V\)) caused by an output commodity \(c\) (\(\forall c \in C\)) at a timestep \(t\) (\(\forall t \in T_{m}\)). This variable is generally expressed in the unit MW (or tonnes e.g. for the environmental commodity ‘CO2’). In script urbs.py this variable is defined by the model variable e_pro_out and initialized by the following code fragment:

m.e_pro_out = pyomo.Var(
    m.tm, m.pro_tuples, m.com,
    within=pyomo.NonNegativeReals,
    doc='Flow of commodity out of process per timestep')

Process Online Capacity, \(\omega_{vpt}\), cap_online: This variable is the time-dependent version of the usual process capacity \(\kappa_{vp}\). It is defined for partial process tuples, i.e. those processes that have the parameter input ratio ratio-min set. of a process tuple \(p_v\) (\(\forall p \in P, \forall v \in V\)) at a timestep \(t\) (\(\forall t \in T\)). In script urbs.py this variable is defined by the model variable onlinestatus and initialized by the following code fragment:

m.cap_online = pyomo.Var(
    m.t, m.pro_partial_tuples,
    within=pyomo.NonNegativeReals,
    doc='Online capacity (MW) of process per timestep')

Process Startup Capacity, \(\phi'_{vpt}\), startup_pro: This variable indicates every rise in the process online capacity. This indicator is then used to determine startup costs for all partial process tuples. The variable is defined by the following code fragment:

m.startup_pro = pyomo.Var(
    m.tm, m.pro_partial_tuples,
    within=pyomo.NonNegativeReals,
    doc='Started capacity (MW) of process per timestep')

Transmission Variables¶

Total Transmission Capacity, \(\kappa_{af}\), cap_tra: The variable \(\kappa_{af}\) represents the total potential transfer power of a transmission tuple \(f_{ca}\), where \(a\) represents the arc from an origin site \(v_\text{out}\) to a destination site \({v_\text{in}}\). The total transmission capacity includes both the already installed transmission capacity and the additional new transmission capacity that needs to be installed. This variable is expressed in the unit MW. In script urbs.py this variable is defined by the model variable cap_tra and initialized by the following code fragment:

m.cap_tra = pyomo.Var(
    m.tra_tuples,
    within=pyomo.NonNegativeReals,
    doc='Total transmission capacity (MW)')

New Transmission Capacity, \(\hat{\kappa}_{af}\), cap_tra_new: The variable \(\hat{\kappa}_{af}\) represents the additional capacity, that needs to be installed, of a transmission tuple \(f_{ca}\), where \(a\) represents the arc from an origin site \(v_\text{out}\) to a destination site \(v_\text{in}\). This variable is expressed in the unit MW. In script urbs.py this variable is defined by the model variable cap_tra_new and initialized by the following code fragment:

m.cap_tra_new = pyomo.Var(
    m.tra_tuples,
    within=pyomo.NonNegativeReals,
    doc='New transmission capacity (MW)')

Transmission Power Flow (Input), \(\pi_{aft}^\text{in}\), e_tra_in: The variable \(\pi_{aft}^\text{in}\) represents the power flow input into a transmission tuple \(f_{ca}\) at a timestep \(t\), where \(a\) represents the arc from an origin site \(v_\text{out}\) to a destination site \(v_\text{in}\). This variable is expressed in the unit MW. In script urbs.py this variable is defined by the model variable e_tra_in and initialized by the following code fragment:

m.e_tra_in = pyomo.Var(
    m.tm, m.tra_tuples,
    within=pyomo.NonNegativeReals,
    doc='Power flow into transmission line (MW) per timestep')

Transmission Power Flow (Output), \(\pi_{aft}^\text{out}\), e_tra_out: The variable \(\pi_{aft}^\text{out}\) represents the power flow output out of a transmission tuple \(f_{ca}\) at a timestep \(t\), where \(a\) represents the arc from an origin site \(v_\text{out}\) to a destination site \(v_\text{in}\). This variable is expressed in the unit MW. In script urbs.py this variable is defined by the model variable e_tra_out and initialized by the following code fragment:

m.e_tra_out = pyomo.Var(
    m.tm, m.tra_tuples,
    within=pyomo.NonNegativeReals,
    doc='Power flow out of transmission line (MW) per timestep')

Storage Variables¶

Total Storage Size, \(\kappa_{vs}^\text{c}\), cap_sto_c: The variable \(\kappa_{vs}^\text{c}\) represents the total load capacity of a storage tuple \(s_{vc}\). The total storage load capacity includes both the already installed storage load capacity and the additional new storage load capacity that needs to be installed. This variable is expressed in unit MWh. In script urbs.py this variable is defined by the model variable cap_sto_c and initialized by the following code fragment:

m.cap_sto_c = pyomo.Var(
    m.sto_tuples,
    within=pyomo.NonNegativeReals,
    doc='Total storage size (MWh)')

New Storage Size, \(\hat{\kappa}_{vs}^\text{c}\), cap_sto_c_new: The variable \(\hat{\kappa}_{vs}^\text{c}\) represents the additional storage load capacity of a storage tuple \(s_{vc}\) that needs to be installed to the energy system in order to provide the optimal solution. This variable is expressed in the unit MWh. In script urbs.py this variable is defined by the model variable cap_sto_c_new and initialized by the following code fragment:

m.cap_sto_c_new = pyomo.Var(
    m.sto_tuples,
    within=pyomo.NonNegativeReals,
    doc='New storage size (MWh)')

Total Storage Power, \(\kappa_{vs}^\text{p}\), cap_sto_p: The variable \(\kappa_{vs}^\text{p}\) represents the total potential discharge power of a storage tuple \(s_{vc}\). The total storage power includes both the already installed storage power and the additional new storage power that needs to be installed. This variable is expressed in the unit MW. In script urbs.py this variable is defined by the model variable cap_sto_p and initialized by the following code fragment:

m.cap_sto_p = pyomo.Var(
    m.sto_tuples,
    within=pyomo.NonNegativeReals,
    doc='Total storage power (MW)')

New Storage Power, \(\hat{\kappa}_{vs}^\text{p}\), cap_sto_p_new: The variable \(\hat{\kappa}_{vs}^\text{p}\) represents the additional potential discharge power of a storage tuple \(s_{vc}\) that needs to be installed to the energy system in order to provide the optimal solution. This variable is expressed in the unit MW. In script urbs.py this variable is defined by the model variable cap_sto_p_new and initialized by the following code fragment:

m.cap_sto_p_new = pyomo.Var(
    m.sto_tuples,
    within=pyomo.NonNegativeReals,
    doc='New  storage power (MW)')

Storage Power Flow (Input), \(\epsilon_{vst}^\text{in}\), e_sto_in: The variable \(\epsilon_{vst}^\text{in}\) represents the input power flow into a storage tuple \(s_{vc}\) at a timestep \(t\). Input power flow into a storage tuple can also be defined as the charge of a storage tuple. This variable is expressed in the unit MW. In script urbs.py this variable is defined by the model variable e_sto_in and initialized by the following code fragment:

m.e_sto_in = pyomo.Var(
    m.tm, m.sto_tuples,
    within=pyomo.NonNegativeReals,
    doc='Power flow into storage (MW) per timestep')

Storage Power Flow (Output), \(\epsilon_{vst}^\text{out}\), e_sto_out: The variable \(\epsilon_{vst}^\text{out}\) represents the output power flow out of a storage tuple \(s_{vc}\) at a timestep \(t\). Output power flow out of a storage tuple can also be defined as the discharge of a storage tuple. This variable is expressed in the unit MW. In script urbs.py this variable is defined by the model variable e_sto_out and initialized by the following code fragment:

m.e_sto_out = pyomo.Var(
    m.tm, m.sto_tuples,
    within=pyomo.NonNegativeReals,
    doc='Power flow out of storage (MW) per timestep')

Storage Energy Content, \(\epsilon_{vst}^\text{con}\), e_sto_con: The variable \(\epsilon_{vst}^\text{con}\) represents the energy amount that is loaded in a storage tuple \(s_{vc}\) at a timestep \(t\). This variable is expressed in the unit MWh. In script urbs.py this variable is defined by the model variable e_sto_out and initialized by the following code fragment:

m.e_sto_con = pyomo.Var(
    m.t, m.sto_tuples,
    within=pyomo.NonNegativeReals,
    doc='Energy content of storage (MWh) in timestep')

Demand Side Management Variables¶

DSM Upshift, \(\delta_{vct}^\text{up}\), dsm_up, MW: The variable \(\delta_{vct}^\text{up}\) represents the DSM upshift in time step \(t\) in site \(v\) for commodity \(c\). It is only defined for all dsm_site_tuples. The following code fragment shows the definition of the variable:

m.dsm_up = pyomo.Var(
    m.tm, m.dsm_site_tuples,
    within=pyomo.NonNegativeReals,
    doc='DSM upshift')

DSM Downshift, \(\delta_{vct,tt}^\text{down}\), dsm_down, MW: The variable \(\delta_{vct,tt}^\text{down}\) represents the DSM downshift in timestepp \(tt\) caused by the upshift in time \(t\) in site \(v\) for commodity \(c\). The special combinations of timesteps \(t\) and \(tt\) for each site and commodity combination is created by the dsm_down_tuples. The definition of the variable is shown in the code fragment:

m.dsm_down = pyomo.Var(
    m.dsm_down_tuples,
    within=pyomo.NonNegativeReals,
    doc='DSM downshift')

Parameters¶

All the parameters that the optimization model requires to calculate an optimal solution will be listed and defined in this section. A parameter is a data, that is provided by the user before the optimization simulation starts. These parameters are the values that define the specifications of the modelled energy system. Parameters of this optimization model can be seperated into two main parts, these are Technical and Economical Parameters.

Technical Parameters¶

*Table: Technical Model Parameters*¶
Parameter	Unit	Description
General Technical Parameters
\(w\)	_	Weight
\(\Delta t\)	h	Timestep Duration
Commodity Technical Parameters
\(d_{vct}\)	MW	Demand for Commodity
\(s_{vct}\)	_	Intermittent Supply Capacity Factor
\(\overline{l}_{vc}\)	MW	Maximum Stock Supply Limit Per Time Step
\(\overline{L}_{vc}\)	MW	Maximum Annual Stock Supply Limit Per Vertex
\(\overline{m}_{vc}\)	t	Maximum Environmental Output Per Time Step
\(\overline{M}_{vc}\)	t	Maximum Annual Environmental Output
\(\overline{g}_{vc}\)	MW	Maximum Sell Limit Per Time Step
\(\overline{G}_{vc}\)	MW	Maximum Annual Sell Limit
\(\overline{b}_{vc}\)	MW	Maximum Buy Limit Per Time Step
\(\overline{B}_{vc}\)	MW	Maximum Annual Buy Limit
\(\overline{L}_{CO_2}\)	t	Maximum Global Annual CO2 Emission Limit
Process Technical Parameters
\(\underline{K}_{vp}\)	MW	Process Capacity Lower Bound
\(K_{vp}\)	MW	Process Capacity Installed
\(\overline{K}_{vp}\)	MW	Process Capacity Upper Bound
\(\overline{PG}_{vp}\)	1/h	Process Maximal Power Gradient (relative)
\(\underline{P}_{vp}\)	_	Process Minimum Part Load Fraction
\(r_{pc}^\text{in}\)	_	Process Input Ratio
\(\underline{r}_{pc}^\text{in}\)	_	Process Partial Input Ratio
\(r_{pc}^\text{out}\)	_	Process Output Ratio
Storage Technical Parameters
\(I_{vs}\)	1	Initial and Final State of Charge
\(e_{vs}^\text{in}\)	_	Storage Efficiency During Charge
\(e_{vs}^\text{out}\)	_	Storage Efficiency During Discharge
\(\underline{K}_{vs}^\text{c}\)	MWh	Storage Content Lower Bound
\(K_{vs}^\text{c}\)	MWh	Storage Content Installed
\(\overline{K}_{vs}^\text{c}\)	MWh	Storage Content Upper Bound
\(\underline{K}_{vs}^\text{p}\)	MW	Storage Power Lower Bound
\(K_{vs}^\text{p}\)	MW	Storage Power Installed
\(\overline{K}_{vs}^\text{p}\)	MW	Storage Power Upper Bound
Transmission Technical Parameters
\(e_{af}\)	_	Transmission Efficiency
\(\underline{K}_{af}\)	MW	Tranmission Capacity Lower Bound
\(K_{af}\)	MW	Tranmission Capacity Installed
\(\overline{K}_{af}\)	MW	Tranmission Capacity Upper Bound
Demand Side Management Parameters
\(e_{vc}\)	_	DSM Efficiency
\(y_{vc}\)	_	DSM Delay Time
\(o_{vc}\)	_	DSM Recovery Time
\(\overline{K}_{vc}^\text{up}\)	MW	DSM Maximal Upshift Capacity
\(\overline{K}_{vc}^\text{down}\)	MW	DSM Maximal Downshift Capacity

General Technical Parameters¶

Weight, \(w\), weight: The variable \(w\) helps to scale variable costs and emissions from the length of simulation, that the energy system model is being observed, to an annual result. This variable represents the rate of a year (8760 hours) to the observed time span. The observed time span is calculated by the product of number of time steps of the set \(T\) and the time step duration. In script urbs.py this variable is defined by the model variable weight and initialized by the following code fragment:

m.weight = pyomo.Param(
    initialize=float(8760) / (len(m.tm) * dt),
    doc='Pre-factor for variable costs and emissions for an annual result')

Timestep Duration, \(\Delta t\), dt: The variable \(\Delta t\) represents the duration between two sequential timesteps \(t_x\) and \(t_{x+1}\). This is calculated by the subtraction of smaller one from the bigger of the two sequential timesteps \(\Delta t = t_{x+1} - t_x\). This variable is the unit of time for the optimization model This variable is expressed in the unit h and by default the value is set to 1. In script urbs.py this variable is defined by the model variable dt and initialized by the following code fragment:

m.dt = pyomo.Param(
    initialize=dt,
    doc='Time step duration (in hours), default: 1')

Commodity Technical Parameters¶

Demand for Commodity, \(d_{vct}\), m.demand.loc[tm][sit, com]: The parameter represents the energy amount of a demand commodity tuple \(c_{vq}\) required at a timestep \(t\) (\(\forall v \in V, q = "Demand", \forall t \in T_m\)). The unit of this parameter is MW. This data is to be provided by the user and to be entered in the spreadsheet. The related section for this parameter in the spreadsheet can be found under the “Demand” sheet. Here each row represents another timestep \(t\) and each column represent a commodity tuple \(c_{vq}\). Rows are named after the timestep number \(n\) of timesteps \(t_n\). Columns are named after the combination of site name \(v\) and commodity name \(c\) respecting the order and seperated by a period(.). For example (Mid, Elec) represents the commodity Elec in site Mid. Commodity Type \(q\) is omitted in column declarations, because every commodity of this parameter has to be from commodity type Demand in any case.

Intermittent Supply Capacity Factor, \(s_{vct}\), m.supim.loc[tm][sit, com]: The parameter \(s_{vct}\) represents the normalized availability of a supply intermittent commodity \(c\) \((\forall c \in C_\text{sup})\) in a site \(v\) at a timestep \(t\). In other words this parameter gives the ratio of current available energy amount to maximum potential energy amount of a supply intermittent commodity. This data is to be provided by the user and to be entered in the spreadsheet. The related section for this parameter in the spreadsheet can be found under the “SupIm” sheet. Here each row represents another timestep \(t\) and each column represent a commodity tuple \(c_{vq}\). Rows are named after the timestep number \(n\) of timesteps \(t_n\). Columns are named after the combination of site name \(v\) and commodity name \(c\), in this respective order and seperated by a period(.). For example (Mid.Elec) represents the commodity Elec in site Mid. Commodity Type \(q\) is omitted in column declarations, because every commodity of this parameter has to be from commodity type SupIm in any case.

Maximum Stock Supply Limit Per Time Step, \(\overline{l}_{vc}\), m.commodity.loc[sit, com, com_type]['maxperstep']: The parameter \(\overline{l}_{vc}\) represents the maximum energy amount of a stock commodity tuple \(c_{vq}\) (\(\forall v \in V , q = "Stock"\)) that energy model is allowed to use per time step. The unit of this parameter is MW. This parameter applies to every timestep and does not vary for each timestep \(t\). This parameter is to be provided by the user and to be entered in spreadsheet. The related section for this parameter in the spreadsheet can be found under the Commodity sheet. Here each row represents another commodity tuple \(c_{vq}\) and the sixth column of stock commodity tuples in this sheet with the header label “maxperstep” represents the parameter \(\overline{l}_{vc}\). If there is no desired restriction of a stock commodity tuple usage per timestep, the corresponding cell can be set to “inf” to ignore this parameter.

Maximum Annual Stock Supply Limit Per Vertex, \(\overline{L}_{vc}\), m.commodity.loc[sit, com, com_type]['max']: The parameter \(\overline{L}_{vc}\) represents the maximum energy amount of a stock commodity tuple \(c_{vq}\) (\(\forall v \in V , q = "Stock"\)) that energy model is allowed to use annually. The unit of this parameter is MW. This parameter is to be provided by the user and to be entered in spreadsheet. The related section for this parameter in the spreadsheet can be found under the Commodity sheet. Here each row represents another commodity tuple \(c_{vq}\) and the fifth column of stock commodity tuples in this sheet with the header label “max” represents the parameter \(\overline{L}_{vc}\). If there is no desired restriction of a stock commodity tuple usage per timestep, the corresponding cell can be set to “inf” to ignore this parameter.

Maximum Environmental Output Per Time Step, \(\overline{m}_{vc}\), m.commodity.loc[sit, com, com_type]['maxperstep']: The parameter \(\overline{m}_{vc}\) represents the maximum energy amount of an environmental commodity tuple \(c_{vq}\) (\(\forall v \in V , q = "Env"\)) that energy model is allowed to produce and release to environment per time step. This parameter applies to every timestep and does not vary for each timestep \(t\). This parameter is to be provided by the user and to be entered in spreadsheet. The related section for this parameter in the spreadsheet can be found under the Commodity sheet. Here each row represents another commodity tuple \(c_{vq}\) and the sixth column of enviromental commodity tuples in this sheet with the header label “maxperstep” represents the parameter \(\overline{m}_{vc}\). If there is no desired restriction of an enviromental commodity tuple usage per timestep, the corresponding cell can be set to “inf” to ignore this parameter.

Maximum Annual Environmental Output, \(\overline{M}_{vc}\), m.commodity.loc[sit, com, com_type]['max']: The parameter \(\overline{M}_{vc}\) represents the maximum energy amount of an environmental commodity tuple \(c_{vq}\) (\(\forall v \in V , q = "Env"\)) that energy model is allowed to produce and release to environment annually. This parameter is to be provided by the user and to be entered in spreadsheet. The related section for this parameter in the spreadsheet can be found under the Commodity sheet. Here each row represents another commodity tuple \(c_{vq}\) and the fifth column of an environmental commodity tuples in this sheet with the header label “max” represents the parameter \(\overline{M}_{vc}\). If there is no desired restriction of a stock commodity tuple usage per timestep, the corresponding cell can be set to “inf” to ignore this parameter.

Maximum Sell Limit Per Time Step, \(\overline{g}_{vc}\), m.commodity.loc[sit, com, com_type][`maxperstep`]: The parameter \(\overline{g}_{vc}\) represents the maximum energy amount of a sell commodity tuple \(c_{vq}\) (\(\forall v \in V , q = "Sell"\)) that energy model is allowed to sell per time step. The unit of this parameter is MW. This parameter applies to every timestep and does not vary for each timestep \(t\). This parameter is to be provided by the user and to be entered in spreadsheet. The related section for this parameter in the spreadsheet can be found under the Commodity sheet. Here each row represents another commodity tuple \(c_{vq}\) and the sixth column of sell commodity tuples in this sheet with the header label “maxperstep” represents the parameter \(\overline{g}_{vc}\). If there is no desired restriction of a sell commodity tuple usage per timestep, the corresponding cell can be set to “inf” to ignore this parameter.

Maximum Annual Sell Limit, \(\overline{G}_{vc}\), m.commodity.loc[sit, com, com_type][`max`]: The parameter \(\overline{G}_{vc}\) represents the maximum energy amount of a sell commodity tuple \(c_{vq}\) (\(\forall v \in V , q = "Sell"\)) that energy model is allowed to sell annually. The unit of this parameter is MW. This parameter is to be provided by the user and to be entered in spreadsheet. The related section for this parameter in the spreadsheet can be found under the Commodity sheet. Here each row represents another commodity tuple \(c_{vq}\) and the fifth column of sell commodity tuples in this sheet with the header label “max” represents the parameter \(\overline{G}_{vc}\). If there is no desired restriction of a sell commodity tuple usage per timestep, the corresponding cell can be set to “inf” to ignore this parameter.

Maximum Buy Limit Per Time Step, \(\overline{b}_{vc}\), m.commodity.loc[sit, com, com_type][`maxperstep`]: The parameter \(\overline{b}_{vc}\) represents the maximum energy amount of a buy commodity tuple \(c_{vq}\) (\(\forall v \in V , q = "Buy"\)) that energy model is allowed to buy per time step. The unit of this parameter is MW. This parameter applies to every timestep and does not vary for each timestep \(t\). This parameter is to be provided by the user and to be entered in spreadsheet. The related section for this parameter in the spreadsheet can be found under the Commodity sheet. Here each row represents another commodity tuple \(c_{vq}\) and the sixth column of buy commodity tuples in this sheet with the header label “maxperstep” represents the parameter \(\overline{b}_{vc}\). If there is no desired restriction of a sell commodity tuple usage per timestep, the corresponding cell can be set to “inf” to ignore this parameter.

Maximum Annual Buy Limit, \(\overline{B}_{vc}\), m.commodity.loc[sit, com, com_type][`max`]: The parameter \(\overline{B}_{vc}\) represents the maximum energy amount of a buy commodity tuple \(c_{vq}\) (\(\forall v \in V , q = "Buy"\)) that energy model is allowed to buy annually. The unit of this parameter is MW. This parameter is to be provided by the user and to be entered in spreadsheet. The related section for this parameter in the spreadsheet can be found under the Commodity sheet. Here each row represents another commodity tuple \(c_{vq}\) and the fifth column of buy commodity tuples in this sheet with the header label “max” represents the parameter \(\overline{B}_{vc}\). If there is no desired restriction of a buy commodity tuple usage per timestep, the corresponding cell can be set to “inf” to ignore this parameter.

Maximum Global Annual CO\(_\textbf{2}\) Emission Limit, \(\overline{L}_{CO_2}\), m.hack.loc['Global CO2 Limit','Value']: The parameter \(\overline{L}_{CO_2}\) represents the maximum total energy amount of all environmental commodities that energy model is allowed to produce and release to environment annually. This parameter is optional. If the user desires to set a maximum annual limit to total \(CO_2\) emission of the whole energy model, this can be done by entering the desired value to the related spreadsheet. The related section for this parameter can be found under the sheet “hacks”. Here the the cell where the “Global CO2 limit” row and “value” column intersects stands for the parameter \(\overline{L}_{CO_2}\). If the user wants to disable this parameter and restriction it provides, this cell can be set to “inf” or simply be deleted.

Process Technical Parameters¶

Process Capacity Lower Bound, \(\underline{K}_{vp}\), m.process.loc[sit, pro]['cap-lo']: The parameter \(\underline{K}_{vp}\) represents the minimum amount of power output capacity of a process \(p\) at a site \(v\), that energy model is allowed to have. The unit of this parameter is MW. The related section for this parameter in the spreadsheet can be found under the “Process” sheet. Here each row represents another process \(p\) in a site \(v\) and the fourth column with the header label “cap-lo” represents the parameters \(\underline{K}_{vp}\) belonging to the corresponding process \(p\) and site \(v\) combinations. If there is no desired minimum limit for the process capacities, this parameter can be simply set to “0”, to ignore this parameter.

Process Capacity Installed, \(K_{vp}\), m.process.loc[sit, pro]['inst-cap']: The parameter \(K_{vp}\) represents the amount of power output capacity of a process \(p\) in a site \(v\), that is already installed to the energy system at the beginning of the simulation. The unit of this parameter is MW. The related section for this parameter in the spreadsheet can be found under the “Process” sheet. Here each row represents another process \(p\) in a site \(v\) and the third column with the header label “inst-cap” represents the parameters \(K_{vp}\) belonging to the corresponding process \(p\) and site \(v\) combinations.

Process Capacity Upper Bound, \(\overline{K}_{vp}\), m.process.loc[sit, pro]['cap-up']: The parameter \(\overline{K}_{vp}\) represents the maximum amount of power output capacity of a process \(p\) at a site \(v\), that energy model is allowed to have. The unit of this parameter is MW. The related section for this parameter in the spreadsheet can be found under the “Process” sheet. Here each row represents another process \(p\) in a site \(v\) and the fifth column with the header label “cap-up” represents the parameters \(\overline{K}_{vp}\) of the corresponding process \(p\) and site \(v\) combinations. Alternatively, \(\overline{K}_{vp}\) is determined by the column with the label “area-per-cap”, whenever the value in “cap-up” times the value “area-per-cap” is larger than the value in column “area” in sheet “Site” for site \(v\). If there is no desired maximum limit for the process capacities, both input parameters can be simply set to an unrealistic high value, to ignore this parameter.

Process Maximal Gradient, \(\overline{PG}_{vp}\), m.process.loc[sit, pro]['max-grad']: The parameter \(\overline{PG}_{vp}\) represents the maximal power gradient of a process \(p\) at a site \(v\), that energy model is allowed to have. The unit of this parameter is 1/h. The related section for this parameter in the spreadsheet can be found under the “Process” sheet. Here each row represents another process \(p\) in a site \(v\) and the sixth column with the header label “max-grad” represents the parameters \(\overline{PG}_{vp}\) of the corresponding process \(p\) and site \(v\) combinations. If there is no desired maximum limit for the process power gradient, this parameter can be simply set to an unrealistic high value, to ignore this parameter.

Process Minimum Part Load Fraction, \(\underline{P}_{vp}\), m.process.loc[sit, pro]['partial']: The parameter \(\underline{P}_{vp}\) represents the minimum allowable part load of a process \(p\) at a site \(v\) as a fraction of the total process capacity. The related section for this parameter in the spreadsheet can be found under the “Process” sheet. Here each row represents another process \(p\) in a site \(v\) and the twelfth column with the header label “partial” represents the parameters \(\underline{P}_{vp}\) of the corresponding process \(p\) and site \(v\) combinations.

Process Input Ratio, \(r_{pc}^\text{in}\), m.r_in.loc[pro, co]: The parameter \(r_{pc}^\text{in}\) represents the ratio of the input amount of a commodity \(c\) in a process \(p\), relative to the process throughput at a given timestep. The related section for this parameter in the spreadsheet can be found under the “Process-Comodity” sheet. Here each row represents another commodity \(c\) that either goes in to or comes out of a process \(p\). The fourth column with the header label “ratio” represents the parameters of the corresponding process \(p\), commodity \(c\) and direction (In,Out) combinations.

Process Partial Input Ratio, \(\underline{r}_{pc}^\text{in}\), m.r_in_partial.loc[pro, co]: The parameter \(\underline{r}_{pc}^\text{in}\) represents the ratio of the amount of input commodity \(c\) a process \(p\) consumes if it is at its minimum allowable partial operation. More precisely, when its throughput \(\tau_{vpt}\) has the minimum value \(\omega_{vpt} \underline{P}_{vp}\).

Process Output Ratio, \(r_{pc}^\text{out}\), m.r_out.loc[pro, co]: The parameter \(r_{pc}^\text{out}\) represents the ratio of the output amount of a commodity \(c\) in a process \(p\), relative to the process throughput at a given timestep. The related section for this parameter in the spreadsheet can be found under the “Process-Comodity” sheet. Here each row represents another commodity \(c\) that either goes in to or comes out of a process \(p\). The fourth column with the header label “ratio” represents the parameters of the corresponding process \(p\), commodity \(c\) and direction (In,Out) combinations.

Process input and output ratios are, in general, dimensionless since the majority of output and input commodities are represented in MW. Exceptionally, some process input and output ratios can be assigned units e.g. the environmental commodity (Env) ‘\(\text{CO}_2\) could have a process output ratio with the unit of \(Mt/MWh\).

Since process input and output ratios take the process throughput \(\tau_{vpt}\) as the reference in order to calculate the input and output commodity flows, the process input (or output) ratio of “1” is assigned to the commodity which represents the throughput. By default, the major input commodity flow of the process (e.g. ‘Gas’ for ‘Gas plant’, ‘Wind’ for ‘Wind park’) represents the process throughput so those commodities have the process input (or output) ratio of “1”; but the “throughput” selection can be arbitrarily shifted to other commodities (e.g. power output of the process) by scaling all of the process input and output ratios by an appropriate factor.

Storage Technical Parameters¶

Initial and Final State of Charge (relative), \(I_{vs}\), m.storage.loc[sit, sto, com]['init']: The parameter \(I_{vs}\) represents the initial load factor of a storage \(s\) in a site \(v\). This parameter shows, as a percentage, how much of a storage is loaded at the beginning of the simulation. The same value should be preserved at the end of the simulation, to make sure that the optimization model doesn’t consume the whole storage content at once and leave it empty at the end, otherwise this would disrupt the continuity of the optimization. The value of this parameter is expressed as a normalized percentage, where “1” represents a fully loaded storage and “0” represents an empty storage. The related section for this parameter in the spreadsheet can be found under the “Storage” sheet. Here each row represents a storage technology \(s\) in a site \(v\) that stores a commodity \(c\). The twentieth column with the header label “init” represents the parameters for corresponding storage \(s\), site \(v\), commodity \(c\) combinations.

Storage Efficiency During Charge, \(e_{vs}^\text{in}\), m.storage.loc[sit, sto, com]['eff-in']: The parameter \(e_{vs}^\text{in}\) represents the charge efficiency of a storage \(s\) in a site \(v\) that stores a commodity \(c\). The charge efficiency shows, how much of a desired energy and accordingly power can be succesfully stored into a storage. The value of this parameter is expressed as a normalized percentage, where “1” represents a charge with no power or energy loss and “0” represents that storage technology consumes whole enery during charge. The related section for this parameter in the spreadsheet can be found under the “Storage” sheet. Here each row represents a storage technology \(s\) in a site \(v\) that stores a commodity \(c\). The tenth column with the header label “eff-in” represents the parameters for corresponding storage \(s\), site \(v\), commodity \(c\) combinations.

Storage Efficiency During Discharge, \(e_{vs}^\text{out}\), m.storage.loc[sit, sto, com]['eff-out']: The parameter \(e_{vs}^\text{out}\) represents the discharge efficiency of a storage \(s\) in a site \(v\) that stores a commodity \(c\). The discharge efficiency shows, how much of a desired energy and accordingly power can be succesfully retrieved out of a storage. The value of this parameter is expressed as a normalized efipercentage, where “1” represents a discharge with no power or energy loss and “0” represents that storage technology consumes whole enery during discharge. The related section for this parameter in the spreadsheet can be found under the “Storage” sheet. Here each row represents a storage technology \(s\) in a site \(v\) that stores a commodity \(c\). The eleventh column with the header label “eff-out” represents the parameters for corresponding storage \(s\), site \(v\), commodity \(c\) combinations.

Storage Content Lower Bound, \(\underline{K}_{vs}^\text{c}\), m.storage.loc[sit, sto, com]['cap-lo-c']: The parameter \(\underline{K}_{vs}^\text{c}\) represents the minimum amount of energy content capacity allowed of a storage \(s\) storing a commodity \(c\) in a site \(v\), that the energy system model is allowed to have. The unit of this parameter is MWh. The related section for this parameter in the spreadsheet can be found under the “Storage” sheet. Here each row represents a storage technology \(s\) in a site \(v\) that stores a commodity \(c\). The fifth column with the header label “cap-lo-c” represents the parameters for corresponding storage \(s\), site \(v\), commodity \(c\) combinations. If there is no desired minimum limit for the storage energy content capacities, this parameter can be simply set to “0”, to ignore this parameter.

Storage Content Installed, \(K_{vs}^\text{c}\), m.storage.loc[sit, sto, com]['inst-cap-c']: The parameter \(K_{vs}^\text{c}\) represents the amount of energy content capacity of a storage \(s\) storing commodity \(c\) in a site \(v\), that is already installed to the energy system at the beginning of the simulation. The unit of this parameter is MWh. The related section for this parameter in the spreadsheet can be found under the “Storage” sheet. Here each row represents a storage technology \(s\) in a site \(v\) that stores a commodity \(c\). The fourth column with the header label “inst-cap-c” represents the parameters for corresponding storage \(s\), site \(v\), commodity \(c\) combinations.

Storage Content Upper Bound, \(\overline{K}_{vs}^\text{c}\), m.storage.loc[sit, sto, com]['cap-up-c']: The parameter \(\overline{K}_{vs}^\text{c}\) represents the maximum amount of energy content capacity allowed of a storage \(s\) storing a commodity \(c\) in a site \(v\), that the energy system model is allowed to have. The unit of this parameter is MWh. The related section for this parameter in the spreadsheet can be found under the “Storage” sheet. Here each row represents a storage technology \(s\) in a site \(v\) that stores a commodity \(c\). The sixth column with the header label “cap-up-c” represents the parameters for corresponding storage \(s\), site \(v\), commodity \(c\) combinations. If there is no desired maximum limit for the storage energy content capacitites, this parameter can be simply set to “”inf”” or an unrealistic high value, to ignore this parameter.

Storage Power Lower Bound, \(\underline{K}_{vs}^\text{p}\), m.storage.loc[sit, sto, com]['cap-lo-p']: The parameter \(\underline{K}_{vs}^\text{p}\) represents the minimum amount of power output capacity of a storage \(s\) storing commodity \(c\) in a site \(v\), that energy system model is allowed to have. The unit of this parameter is MW. The related section for this parameter in the spreadsheet can be found under the “Storage” sheet. Here each row represents a storage technology \(s\) in a site \(v\) that stores a commodity \(c\). The eighth column with the header label “cap-lo-p” represents the parameters for corresponding storage \(s\), site \(v\), commodity \(c\) combinations. If there is no desired minimum limit for the storage energy content capacities, this parameter can be simply set to “0”, to ignore this parameter.

Storage Power Installed, \(K_{vs}^\text{p}\), m.storage.loc[sit, sto, com]['inst-cap-p']: The parameter \(K_{vs}^\text{c}\) represents the amount of power output capacity of a storage \(s\) storing commodity \(c\) in a site \(v\), that is already installed to the energy system at the beginning of the simulation. The unit of this parameter is MW. The related section for this parameter in the spreadsheet can be found under the “Storage” sheet. Here each row represents a storage technology \(s\) in a site \(v\) that stores a commodity \(c\). The seventh column with the header label “inst-cap-p” represents the parameters for corresponding storage \(s\), site \(v\), commodity \(c\) combinations.

Storage Power Upper Bound, \(\overline{K}_{vs}^\text{p}\), m.storage.loc[sit, sto, com]['cap-up-p']: The parameter \(\overline{K}_{vs}^\text{p}\) represents the maximum amount of power output capacity allowed of a storage \(s\) storing a commodity \(c\) in a site \(v\), that the energy system model is allowed to have. The unit of this parameter is MW. The related section for this parameter in the spreadsheet can be found under the “Storage” sheet. Here each row represents a storage technology \(s\) in a site \(v\) that stores a commodity \(c\). The sixth column with the header label “cap-up-p” represents the parameters for corresponding storage \(s\), site \(v\), commodity \(c\) combinations. If there is no desired maximum limit for the storage energy content capacitites, this parameter can be simply set to “”inf”” or an unrealistic high value, to ignore this parameter.

Transmission Technical Parameters¶

Transmission Efficiency, \(e_{af}\), m.transmission.loc[sin, sout, tra, com]['eff']: The parameter \(e_{af}\) represents the energy efficiency of a transmission \(f\) that transfers a commodity \(c\) through an arc \(a\). Here an arc \(a\) defines the connection line from an origin site \(v_\text{out}\) to a destination site \({v_\text{in}}\). The ratio of the output energy amount to input energy amount, gives the energy efficiency of a transmission process. The related section for this parameter in the spreadsheet can be found under the “Transmission” sheet. Here each row represents another transmission,site in, site out, commodity combination. The fifth column with the header label “eff” represents the parameters \(e_{af}\) of the corresponding combinations.

Transmission Capacity Lower Bound, \(\underline{K}_{af}\), m.transmission.loc[sin, sout, tra, com]['cap-lo']: The parameter \(\underline{K}_{af}\) represents the minimum power output capacity of a transmission \(f\) transferring a commodity \(c\) through an arc \(a\), that the energy system model is allowed to have. Here an arc \(a\) defines the connection line from an origin site \(v_\text{out}\) to a destination site \({v_\text{in}}\). The unit of this parameter is MW. The related section for this parameter in the spreadsheet can be found under the “Transmission” sheet. Here each row represents another transmission,site in, site out, commodity combination. The tenth column with the header label “cap-lo” represents the parameters \(\underline{K}_{af}\) of the corresponding combinations.

Transmission Capacity Installed, \(K_{af}\), m.transmission.loc[sin, sout, tra, com]['inst-cap']: The parameter \(K_{af}\) represents the amount of power output capacity of a transmission \(f\) transferring a commodity \(c\) through an arc \(a\), that is already installed to the energy system at the beginning of the simulation. The unit of this parameter is MW. The related section for this parameter in the spreadsheet can be found under the “Transmission” sheet. Here each row represents another transmission,site in, site out, commodity combination. The tenth column with the header label “inst-cap” represents the parameters \(K_{af}\) of the corresponding combinations.

Transmission Capacity Upper Bound, \(\overline{K}_{af}\), m.transmission.loc[sin, sout, tra, com]['cap-up']: The parameter \(\overline{K}_{af}\) represents the maximum power output capacity of a transmission \(f\) transferring a commodity \(c\) through an arc \(a\), that the energy system model is allowed to have. Here an arc \(a\) defines the connection line from an origin site \(v_\text{out}\) to a destination site \({v_\text{in}}\). The unit of this parameter is MW. The related section for this parameter in the spreadsheet can be found under the “Transmission” sheet. Here each row represents another transmission, site in, site out, commodity combination. The tenth column with the header label “cap-up” represents the parameters \(\overline{K}_{af}\) of the corresponding combinations.

Demand Side Management Technical Parameters¶

DSM Efficiency, \(e_{vc}\), m.dsm.loc[sit, com]['eff']: The parameter \(e_{vc}\) represents the efficiency of the DSM upshift process. Which means losses of the DSM up- or downshift have to be taken into account by this factor.

DSM Delay Time, \(y_{vc}\), m.dsm.loc[sit, com]['delay']: The delay time \(y_{vc}\) restricts how long the time delta between an upshift and its corresponding downshifts may be.

DSM Recovery Time, \(o_{vc}\), m.dsm.loc[sit, com]['recov']: The recovery time \(o_{vc}\) prevents the DSM system to continously shift demand. During the recovery time, all upshifts may not exceed a predfined value.

DSM Maximal Upshift Capacity, \(\overline{K}_{vc}^\text{up}\), MW, m.dsm.loc[sit, com]['cap-max-up']: The DSM upshift capacity \(\overline{K}_{vc}^\text{up}\) limits the total upshift in one time step.

DSM Maximal Downshift Capacity, \(\overline{K}_{vc}^\text{down}\), MW, m.dsm.loc[sit, com]['cap-max-down']: Correspondingly, the DSM downshift capacity \(\overline{K}_{vc}^\text{down}\) limits the total downshift in one time step.

Economical Parameters¶

*Table: Economical Model Parameters*¶
Parameter	Unit	Description
\(AF\)	_	Annuity factor
Commodity Economical Parameters
\(k_{vc}^\text{fuel}\)	€/MWh	Stock Commodity Fuel Costs
\(k_{vc}^\text{env}\)	€/MWh	Environmental Commodity Costs
\(k_{vct}^\text{bs}\)	€/MWh	Buy/Sell Commodity Buy/Sell Costs
Process Economical Parameters
\(i_{vp}\)	_	Weighted Average Cost of Capital for Process
\(z_{vp}\)	_	Process Depreciation Period
\(k_{vp}^\text{inv}\)	€/(MW a)	Annualised Process Capacity Investment Costs
\(k_{vp}^\text{fix}\)	€/(MW a)	Process Capacity Fixed Costs
\(k_{vp}^\text{var}\)	€/MWh	Process Variable Costs
\(k_{vp}^\text{st}\)	€	Process Startup Costs
Storage Economical Parameters
\(i_{vs}\)	_	Weighted Average Cost of Capital for Storage
\(z_{vs}\)	_	Storage Depreciation Period
\(k_{vs}^\text{p,inv}\)	€/(MWh a)	Annualised Storage Power Investment Costs
\(k_{vs}^\text{p,fix}\)	€/(MW a)	Annual Storage Power Fixed Costs
\(k_{vs}^\text{p,var}\)	€/MWh	Storage Power Variable Costs
\(k_{vs}^\text{c,inv}\)	€/(MWh a)	Annualised Storage Size Investment Costs
\(k_{vs}^\text{c,fix}\)	€/(MWh a)	Annual Storage Size Fixed Costs
\(k_{vs}^\text{c,var}\)	€/MWh	Storage Usage Variable Costs
Transmission Economical Parameters
\(i_{vf}\)	_	Weighted Average Cost of Capital for Transmission
\(z_{af}\)	_	Tranmission Depreciation Period
\(k_{af}^\text{inv}\)	€/(MW a)	Annualised Transmission Capacity Investment Costs
\(k_{af}^\text{fix}\)	€/(MWh a)	Annual Transmission Capacity Fixed Costs
\(k_{af}^\text{var}\)	€/MWh	Tranmission Usage Variable Costs

Annuity factor, \(AF(n,i)\),: Annuity factor \(AF\) is used to calculate the present value of future fixed annuities. The parameter annuity factor is the only parameter that is not given as an input by the user. This parameter is derived from the parameters WACC \(i\) (Weighted average cost of capital) and Depreciation \(z\) by the annuity factor formula. The value of this parameter is expressed with the following equation.

\[AF = \frac{(1+i)^n i}{(1+i)^n - 1}\]

where;

n represents the depreciation period \(z\).
i represents the weighted average cost of capital(wacc) \(i\).

This derived parameter is calculated by the helper function annuity factor() and defined by the following code fragment.

# derive annuity factor from WACC and depreciation periods
process['annuity-factor'] = annuity_factor(
    process['depreciation'], process['wacc'])
transmission['annuity-factor'] = annuity_factor(
    transmission['depreciation'], transmission['wacc'])
storage['annuity-factor'] = annuity_factor(
    storage['depreciation'], storage['wacc'])

urbs.annuity_factor()¶

Annuity factor formula.

Evaluates the annuity factor formula for depreciation duration and interest rate. Works also well for equally sized numpy arrays as input.

Parameters:	n (int) – number of depreciation periods (years) i (float) – interest rate (e.g. 0.06 means 6 %)
Returns:	value of the expression \(\frac{(1+i)^n i}{(1+i)^n - 1}\)

Commodity Economical Parameters¶

Stock Commodity Fuel Costs, \(k_{vc}^\text{fuel}\), m.commodity.loc[c]['price']: The parameter \(k_{vc}^\text{fuel}\) represents the purchase cost for purchasing one unit (1 MWh) of a stock commodity \(c\) (\(\forall c \in C_\text{stock}\)) in a site \(v\) (\(\forall v \in V\)). The unit of this parameter is €/MWh. The related section for this parameter in the spreadsheet can be found under the “Commodity” sheet. Here each row represents another commodity tuple \(c_{vq}\) and the fourth column of stock commodity tuples (\(\forall q = "Stock"\)) in this sheet with the header label “price” represents the corresponding parameter \(k_{vc}^\text{fuel}\).

Environmental Commodity Costs, \(k_{vc}^\text{env}\), m.commodity.loc[c]['price']: The parameter \(k_{vc}^\text{env}\) represents the cost for producing/emitting one unit (1 t, 1 kg, …) of an environmentcal commodity \(c\) (\(\forall c \in C_\text{env}\)) in a site \(v\) (\(\forall v \in V\)). The unit of this parameter is €/t (i.e. per unit of output). The related section for this parameter in the spreadsheet is the “Commodity” sheet. Here, each row represents a commodity tuple \(c_{vq}\) and the fourth column of environmental commodity tuples (\(\forall q = "Env"\)) in this sheet with the header label “price” represents the corresponding parameter \(k_{vc}^\text{env}\).

Buy/Sell Commodity Buy/Sell Costs, \(k_{vct}^\text{bs}\), com_prices[c].loc[tm]: The parameter \(k_{vct}^\text{bs}\) represents the purchase/buy cost for purchasing/selling one unit(1 MWh) of a buy/sell commodity \(c\) (\(\forall c \in C_\text{buy}\))/(\(\forall c \in C_\text{sell}\)) in a site \(v\) (\(\forall v \in V\)) at a timestep \(t\) (\(\forall t \in T_m\)). The unit of this parameter is €/MWh. The related section for this parameter in the spreadsheet can be found under the “Commodity” sheet. Here each row represents another commodity tuple \(c_{vq}\) and the fourth column of buy/sell commodity tuples (\(\forall q = "Buy"\))/(\(\forall q = "Sell"\)) in this sheet with the header label “price” represents how the parameter \(k_{vct}^\text{bs}\) will be defined. There are two options for this parameter. This parameter will either be a fix value for the whole simulation duration or will vary with the timesteps \(t\). For the first option, if the buy/sell price of a buy/sell commodity is a fix value for the whole simulation duration, this value can be entered directly into the corresponding cell with the unit €/MWh. For the second option, if the buy/sell price of a buy/sell commodity depends on time, accordingly on timesteps, a string (a linear sequence of characters, words, or other data) should be written in the corresponding cell. An example string looks like this: “1,25xBuy” where the first numbers (1,25) represent a coefficient for the price. This value is than multiplied by values from another list given with timeseries. Here the word “Buy” refers to a timeseries located in “”Buy-Sell-Price”” sheet with commodity names, types and timesteps. This timeseries should be filled with time dependent buy/sell price variables. The parameter \(k_{vct}^\text{bs}\) is then calculated by the product of the price coefficient and the related time variable for a given timestep \(t\). This calculation and the decision for one of the two options is executed by the helper function get_com_price().

urbs.get_com_price(instance, tuples)¶

Parameters:	instance (str) – a Pyomo ConcreteModel instance tuples (list) – a list of (site, commodity, commodity type) tuples
Returns:	a Pandas DataFrame with entities as columns and timesteps as index

Calculate commodity prices for each modelled timestep. Checks whether the input is a float. If it is a float it gets the input value as a fix value for commodity price. Otherwise if the input value is not a float, but a string, it extracts the price coefficient from the string and multiplies it with a timeseries of commodity price variables.

Process Economical Parameters¶

Weighted Average Cost of Capital for Process, \(i_{vp}\), : The parameter \(i_{vp}\) represents the weighted average cost of capital for a process technology \(p\) in a site \(v\). The weighted average cost of capital gives the interest rate (%) of costs for capital after taxes. The related section for this parameter in the spreadsheet can be found under the “Process” sheet. Here each row represents another process \(p\) in a site \(v\) and the tenth column with the header label “wacc” represents the parameters \(i_{vp}\) of the corresponding process \(p\) and site \(v\) combinations. The parameter is given as a percentage, where “0,07” means 7%

Process Depreciation Period, \(z_{vp}\), (a): The parameter \(z_{vp}\) represents the depreciation period of a process \(p\) in a site \(v\). The depreciation period gives the economic lifetime (more conservative than technical lifetime) of a process investment. The unit of this parameter is “a”, where “a” represents a year of 8760 hours. The related section for this parameter in the spreadsheet can be found under the “Process” sheet. Here each row represents another process \(p\) in a site \(v\) and the eleventh column with the header label “depreciation” represents the parameters \(z_{vp}\) of the corresponding process \(p\) and site \(v\) combinations.

Annualised Process Capacity Investment Costs, \(k_{vp}^\text{inv}\), m.process.loc[p]['inv-cost'] * m.process.loc[p]['annuity-factor']: The parameter \(k_{vp}^\text{inv}\) represents the annualised investment cost for adding one unit new capacity of a process technology \(p\) in a site \(v\). The unit of this parameter is €/(MW a). This parameter is derived by the product of annuity factor \(AF\) and the process capacity investment cost for a given process tuple. The process capacity investment cost is to be given as an input by the user. The related section for the process capacity investment cost in the spreadsheet can be found under the “Process” sheet. Here each row represents another process \(p\) in a site \(v\) and the seventh column with the header label “inv-cost” represents the process capacity investment costs of the corresponding process \(p\) and site \(v\) combinations.

Process Capacity Fixed Costs, \(k_{vp}^\text{fix}\), m.process.loc[p]['fix-cost']: The parameter \(k_{vp}^\text{fix}\) represents the fix cost per one unit capacity \(\kappa_{vp}\) of a process technology \(p\) in a site \(v\), that is charged annually. The unit of this parameter is €/(MW a). The related section for this parameter in the spreadsheet can be found under the “Process” sheet. Here each row represents another process \(p\) in a site \(v\) and the eighth column with the header label “fix-cost” represents the parameters \(k_{vp}^\text{fix}\) of the corresponding process \(p\) and site \(v\) combinations.

Process Variable Costs, \(k_{vp}^\text{var}\), m.process.loc[p]['var-cost']: The parameter \(k_{vp}^\text{var}\) represents the variable cost per one unit energy throughput \(\tau_{vpt}\) through a process technology \(p\) in a site \(v\). The unit of this parameter is €/MWh. The related section for this parameter in the spreadsheet can be found under the “Process” sheet. Here each row represents another process \(p\) in a site \(v\) and the ninth column with the header label “var-cost” represents the parameters \(k_{vp}^\text{var}\) of the corresponding process \(p\) and site \(v\) combinations.

Process Startup Costs, \(k_{vp}^\text{st}\), m.process.loc[p]['startup']: The parameter \(k_{vp}^\text{st}\) represents the startup cost per “startup occurence” of a process technology \(p\) in a site \(v\). The unit of this parameter is €. The related section for this parameter in the spreadsheet can be found under the “Process” sheet. Here each row represents another process \(p\) in a site \(v\) and the thirteenth column with the header label “startup” represents the parameters \(k_{vp}^\text{st}\) of the corresponding process \(p\) and site \(v\) combinations.

Storage Economical Parameters¶

Weighted Average Cost of Capital for Storage, \(i_{vs}\), : The parameter \(i_{vs}\) represents the weighted average cost of capital for a storage technology \(s\) in a site \(v\). The weighted average cost of capital gives the interest rate(%) of costs for capital after taxes. The related section for this parameter in the spreadsheet can be found under the “Storage” sheet. Here each row represents another storage \(s\) in a site \(v\) and the nineteenth column with the header label “wacc” represents the parameters \(i_{vs}\) of the corresponding storage \(s\) and site \(v\) combinations. The parameter is given as a percentage, where “0,07” means 7%.

Storage Depreciation Period, \(z_{vs}\), (a): The parameter \(z_{vs}\) represents the depreciation period of a storage \(s\) in a site \(v\). The depreciation period gives the economic lifetime (more conservative than technical lifetime) of a storage investment. The related section for this parameter in the spreadsheet can be found under the “Storage” sheet. Here each row represents another storage \(s\) in a site \(v\) and the eighteenth column with the header label “depreciation” represents the parameters \(z_{vs}\) of the corresponding storage \(s\) and site \(v\) combinations.

Annualised Storage Power Investment Costs, \(k_{vs}^\text{p,inv}\), m.storage.loc[s]['inv-cost-p'] * m.storage.loc[s]['annuity-factor']: The parameter \(k_{vs}^\text{p,inv}\) represents the annualised investment cost for adding one unit new power output capacity of a storage technology \(s\) in a site \(v\). The unit of this parameter is €/(MWh a). This parameter is derived by the product of annuity factor \(AF\) and the investment cost for one unit of new power output capacity of a storage \(s\) in a site \(v\), which is to be given as an input parameter by the user. The related section for the storage power output capacity investment cost in the spreadsheet can be found under the “Storage” sheet. Here each row represents another storage \(s\) in a site \(v\) and the twelfth column with the header label “inv-cost-p” represents the storage power output capacity investment cost of the corresponding storage \(s\) and site \(v\) combinations.

Annual Storage Power Fixed Costs, \(k_{vs}^\text{p,fix}\), m.storage.loc[s]['fix-cost-p']: The parameter \(k_{vs}^\text{p,fix}\) represents the fix cost per one unit power output capacity of a storage technology \(s\) in a site \(v\), that is charged annually. The unit of this parameter is €/(MW a). The related section for this parameter in the spreadsheet can be found under the “Storage” sheet. Here each row represents another storage \(s\) in a site \(v\) and the fourteenth column with the header label “fix-cost-p” represents the parameters \(k_{vs}^\text{p,fix}\) of the corresponding storage \(s\) and site \(v\) combinations.

Storage Power Variable Costs, \(k_{vs}^\text{p,var}\), m.storage.loc[s]['var-cost-p']: The parameter \(k_{vs}^\text{p,var}\) represents the variable cost per unit energy, that is stored in or retrieved from a storage technology \(s\) in a site \(v\). The unit of this parameter is €/MWh. The related section for this parameter in the spreadsheet can be found under the “Storage” sheet. Here each row represents another storage \(s\) in a site \(v\) and the sixteenth column with the header label “var-cost-p” represents the parameters \(k_{vs}^\text{p,var}\) of the corresponding storage \(s\) and site \(v\) combinations.

Annualised Storage Size Investment Costs, \(k_{vs}^\text{c,inv}\), m.storage.loc[s]['inv-cost-c'] * m.storage.loc[s]['annuity-factor']: The parameter \(k_{vs}^\text{c,inv}\) represents the annualised investment cost for adding one unit new storage capacity to a storage technology \(s\) in a site \(v\). The unit of this parameter is €/(MWh a). This parameter is derived by the product of annuity factor \(AF\) and the investment cost for one unit of new storage capacity of a storage \(s\) in a site \(v\), which is to be given as an input parameter by the user. The related section for the storage content capacity investment cost in the spreadsheet can be found under the “Storage” sheet. Here each row represents another storage \(s\) in a site \(v\) and the thirteenth column with the header label “inv-cost-c” represents the storage content capacity investment cost of the corresponding storage \(s\) and site \(v\) combinations.

Annual Storage Size Fixed Costs, \(k_{vs}^\text{c,fix}\), m.storage.loc[s]['fix-cost-c']: The parameter \(k_{vs}^\text{c,fix}\) represents the fix cost per one unit storage content capacity of a storage technology \(s\) in a site \(v\), that is charged annually. The unit of this parameter is €/(MWh a). The related section for this parameter in the spreadsheet can be found under the “Storage” sheet. Here each row represents another storage \(s\) in a site \(v\) and the fifteenth column with the header label “fix-cost-c” represents the parameters \(k_{vs}^\text{c,fix}\) of the corresponding storage \(s\) and site \(v\) combinations.

Storage Usage Variable Costs, \(k_{vs}^\text{c,var}\), m.storage.loc[s]['var-cost-c']: The parameter \(k_{vs}^\text{p,var}\) represents the variable cost per unit energy, that is conserved in a storage technology \(s\) in a site \(v\). The unit of this parameter is €/MWh. The related section for this parameter in the spreadsheet can be found under the “Storage” sheet. Here each row represents another storage \(s\) in a site \(v\) and the seventeenth column with the header label “var-cost-c” represents the parameters \(k_{vs}^\text{c,var}\) of the corresponding storage \(s\) and site \(v\) combinations. The value of this parameter is usually set to zero, but the parameter can be taken advantage of if the storage has a short term usage or has an increased devaluation due to usage, compared to amount of energy stored.

Transmission Economical Parameters¶

Weighted Average Cost of Capital for Transmission, \(i_{vf}\), : The parameter \(i_{vf}\) represents the weighted average cost of capital for a transmission \(f\) transferring commodities through an arc \(a\). The weighted average cost of capital gives the interest rate(%) of costs for capital after taxes. The related section for this parameter in the spreadsheet can be found under the “Transmission” sheet. Here each row represents another transmission \(f\) transferring commodities through an arc \(a\) and the twelfth column with the header label “wacc” represents the parameters \(i_{vf}\) of the corresponding transmission \(f\) and arc \(a\) combinations. The parameter is given as a percentage, where “0,07” means 7%.

Transmission Depreciation Period, \(z_{af}\), (a): The parameter \(z_{af}\) represents the depreciation period of a transmission \(f\) transferring commodities through an arc \(a\). The depreciation period of gives the economic lifetime (more conservative than technical lifetime) of a transmission investment. The unit of this parameter is €/ (MW a). The related section for this parameter in the spreadsheet can be found under the “Transmission” sheet. Here each row represents another transmission \(f\) transferring commodities through an arc \(a\) and the thirteenth column with the header label “depreciation” represents the parameters \(z_{af}\) of the corresponding transmission \(f\) and arc \(a\) combinations.

Annualised Transmission Capacity Investment Costs, \(k_{af}^\text{inv}\), m.transmission.loc[t]['inv-cost'] * m.transmission.loc[t]['annuity-factor']: The parameter \(k_{af}^\text{inv}\) represents the annualised investment cost for adding one unit new transmission capacity to a transmission \(f\) transferring commodities through an arc \(a\). This parameter is derived by the product of annuity factor \(AF\) and the investment cost for one unit of new transmission capacity of a transmission \(f\) running through an arc \(a\), which is to be given as an input parameter by the user. The unit of this parameter is €/(MW a). The related section for the transmission capacity investment cost in the spreadsheet can be found under the “Transmission” sheet. Here each row represents another transmission \(f\) transferring commodities through an arc \(a\) and the sixth column with the header label “inv-cost” represents the transmission capacity investment cost of the corresponding transmission \(f\) and arc \(a\) combinations.

Annual Transmission Capacity Fixed Costs, \(k_{af}^\text{fix}\), m.transmission.loc[t]['fix-cost']: The parameter \(k_{af}^\text{fix}\) represents the fix cost per one unit capacity of a transmission \(f\) transferring commodities through an arc \(a\), that is charged annually. The unit of this parameter is €/(MWh a). The related section for this parameter in the spreadsheet can be found under the “Transmission” sheet. Here each row represents another transmission \(f\) transferring commodities through an arc \(a\) and the seventh column with the header label “fix-cost” represents the parameters \(k_{af}^\text{fix}\) of the corresponding transmission \(f\) and arc \(a\) combinations.

Transmission Usage Variable Costs, \(k_{af}^\text{var}\), m.transmission.loc[t]['var-cost']: The parameter \(k_{af}^\text{var}\) represents the variable cost per unit energy, that is transferred with a transmissiom \(f\) through an arc \(a\). The unit of this parameter is €/ MWh. The related section for this parameter in the spreadsheet can be found under the “Transmission” sheet. Here each row represents another transmission \(f\) transferring commodities through an arc \(a\) and the eighth column with the header label “var-cost” represents the parameters \(k_{af}^\text{var}\) of the corresponding transmission \(f\) and arc \(a\) combinations.

Equations¶

Objective function¶

The variable total system cost \(\zeta\) is calculated by the cost function. The cost function is the objective function of the optimization model. Minimizing the value of the variable total system cost would give the most reasonable solution for the modelled energy system The formula of the cost function expressed in mathematical notation is as following:

\[\zeta = \zeta_\text{inv} + \zeta_\text{fix} + \zeta_\text{var} + \zeta_\text{fuel} + \zeta_\text{rev} + \zeta_\text{pur} + \zeta_\text{startup}\]

The calculation of the variable total system cost is given in urbs.py by the following code fragment.

The variable total system cost \(\zeta\) is basically calculated by the summation of every type of total costs. As previously mentioned in section Cost Types, these cost types are : Investment, Fix, Variable, Fuel, Revenue, Purchase. The calculation of each single cost types are listed below.

Investment Costs¶

The variable investment costs \(\zeta_\text{inv}\) represent the required annual expenses made, in the hope of future benefits. These expenses are made on every new investment. The possible investments of an energy system in this model are:

Additional throughput capacity for process technologies.
Additional power capacity for storage technologies and additional storage content capacity for storage technologies.
Additional power capacity for transmission technologies.

The calculation of total annual investment cost \(\zeta_\text{inv}\) is expressed by the formula:

\[\begin{split}\zeta_\text{inv} = \sum_{\substack{v \in V\\ p \in P}} \hat{\kappa}_{vp} k_p^\text{inv} + \sum_{\substack{v \in V\\ s \in S}} \left( \hat{\kappa}_{vs}^\text{c} k_{vs}^\text{c,inv} + \hat{\kappa}_{vs}^\text{p} k_{vs}^\text{p,inv}\right) + \sum_{\substack{a \in A\\ f \in F}} \hat{\kappa}_{af} k_{af}^\text{inv}\end{split}\]

Total annual investment cost is calculated by the sum of three main summands, these are the investment costs for processes, storages, and transmissions.

The first summand of the formula calculates the required annual investment expenses to install the additional process capacity for every member of the set process tuples \(\forall p_v \in P_v\). Total process investment cost for all process tuples is defined by the sum of all possible annual process investment costs, which are calculated seperately for each process tuple ( \(p_v\), m.pro_tuples) consisting of process \(p\) in site \(v\). Annual process investment cost for a given process tuple \(p_v\) is calculated by the product of the variable new process capacity ( \(\hat{\kappa}_{vp}\),``m.cap_pro_new``) and the parameter annualised process capacity investment cost ( \(k_{vp}^\text{inv}\), m.process.loc[p]['inv-cost'] * m.process.loc[p]['annuity-factor']). In mathematical notation this summand is expressed as:

\[\begin{split}\sum_{\substack{v \in V\\ p \in P}} \hat{\kappa}_{vp} k_p^\text{inv}\end{split}\]

The second summand of the formula calculates the required investment expenses to install additional power output capacity and storage content capacity to storage technologies for every member of the set storage tuples ( \(\forall s_{vc} \in S_{vc}\)). This summand consists of two products:

The first product calculates the required annual investment expenses to install an additional storage content capacity to a given storage tuple . This is calculated by the product of the variable new storage size ( \(\hat{\kappa}_{vs}^\text{c}\), cap_sto_c_new) and the parameter annualised storage size investment costs ( \(k_{vs}^\text{c,inv}\), m.storage.loc[s]['inv-cost-c'] * m.storage.loc[s]['annuity-factor']).

The second product calculates the required annual investment expenses to install an additional power output capacity to a given storage tuple. This is calculated by the product of the variable new storage power ( \(\hat{\kappa}_{vs}^\text{p}\), cap_sto_p_new) and the parameter annualised storage power investment costs ( \(k_{vs}^\text{p,inv}\), m.storage.loc[s]['inv-cost-p'] * m.storage.loc[s]['annuity-factor']).

These two products for a given storage tuple are than added up. The calculation of investment costs for a given storage tuple is than repeated for every single storage tuple and summed up to calculate the total investment costs for storage technologies. In mathematical notation this summand is expressed as:

\[\begin{split}\sum_{\substack{v \in V\\ s \in S}} ( \hat{\kappa}_{vs}^\text{c} k_{vs}^\text{c,inv} + \hat{\kappa}_{vs}^\text{p} k_{vs}^\text{p,inv})\end{split}\]

The third and the last summand of the formula calculates the required investment expenses to install additional power capacity to transmission technologies for every member of the set transmission tuples \(\forall f_{ca} \in F_{ca}\). Total transmission investment cost for all transmission tuples is defined by the sum of all possible annual transmission investment costs, which are calculated seperately for each transmission tuple ( \(f_{ca}\)). Annual transmission investment cost for a given transmission tuple is calculated by the product of the variable new transmission capacity ( \(\hat{\kappa}_{af}\), cap_tra_new) and the parameter annualised transmission capacity investment costs ( \(k_{af}^\text{inv}\), m.transmission.loc[t]['inv-cost'] * m.transmission.loc[t]['annuity-factor']) for the given transmission tuple. In mathematical notation this summand is expressed as:

\[\begin{split}\sum_{\substack{a \in A\\ f \in F}} \hat{\kappa}_{af} k_{af}^\text{inv}\end{split}\]

As mentioned above the variable investment costs \(\zeta_\text{inv}\) is calculated by the sum of these 3 summands.

In script urbs.py the value of the total investment cost is calculated by the following code fragment:

if cost_type == 'Invest':
    return m.costs[cost_type] == \
        sum(m.cap_pro_new[p] *
            m.process.loc[p]['inv-cost'] *
            m.process.loc[p]['annuity-factor']
            for p in m.pro_tuples) + \
        sum(m.cap_tra_new[t] *
            m.transmission.loc[t]['inv-cost'] *
            m.transmission.loc[t]['annuity-factor']
            for t in m.tra_tuples) + \
        sum(m.cap_sto_p_new[s] *
            m.storage.loc[s]['inv-cost-p'] *
            m.storage.loc[s]['annuity-factor'] +
            m.cap_sto_c_new[s] *
            m.storage.loc[s]['inv-cost-c'] *
            m.storage.loc[s]['annuity-factor']
            for s in m.sto_tuples)

Fix Costs¶

The variable fix costs \(\zeta_\text{fix}\) represents the total annual fixed costs for all used storage, process and transmission technologies. The possible fix costs of an energy system in this model can be divided into sections, these are:

Fix costs for process technologies
Fix costs for storage technologies
Fix costs for transmission technologies.

The calculation of total annual fix cost \(\zeta_\text{fix}\) is expressed by the formula:

\[\begin{split}\zeta_\text{fix} = \sum_{\substack{v \in V\\ p \in P}} \kappa_{vp} k_{vp}^\text{fix} + \sum_{\substack{v \in V\\ s \in S}} \left( \kappa_{vs}^\text{c} k_{vs}^\text{c,fix} + \kappa_{vs}^\text{p} k_{vs}^\text{p,fix} \right) + \sum_{\substack{a \in A\\ f \in F}} \kappa_{af} k_{af}^\text{fix}\end{split}\]

Total annual fix cost \(\zeta_\text{fix}\) is calculated by the sum of three main summands, these are the fix costs for process, storage and transmission technologies.

The first summand of the formula calculates the required annual fix cost to keep all the process technologies maintained. This is calculated for every member of the set process tuples \(\forall p_v \in P_v\). Total process fix cost for all process tuples is defined by the sum of all possible annual process fix costs, which are calculated seperately for each process tuple ( \(p_v\), m.pro_tuples) consisting of process \(p\) in site \(v\). Annual process fix cost for a given process tuple is calculated by the product of the variable total process capacity ( \(\kappa_{vp}\), cap_pro) and process capacity fixed cost ( \(k_{vp}^\text{fix}\), m.process.loc[p]['fix-cost']). In mathematical notation this summand is expressed as:

\[\begin{split}\sum_{\substack{v \in V\\ p \in P}} \kappa_{vp} k_{vp}^\text{fix}\end{split}\]

The second summand of the formula calculates the required fix expenses to keep the power capacity and storage content capacity of storage technologies maintained. The present storage technologies comprise the members of the set storage tuples \(\forall s_{vc} \in S_{vc}\). This summand consists of two products:

The first product calculates the required annual fix expenses to keep the storage content capacity of a given storage tuple maintained. This is calculated by the product of the variable total storage size ( \(\kappa_{vs}^\text{c}\), cap_sto_c) and the parameter annual storage size fixed costs ( \(k_{vs}^\text{c,fix}\), m.storage.loc[s]['fix-cost-c']).

The second product calculates the required annual fix expenses to keep the power capacity of a given storage tuple maintained. This is calculated by the product of the variable total storage power ( \(\kappa_{vs}^\text{p}\), cap_sto_p) and the parameter annual storage power fixed costs (\(k_{vs}^\text{p,fix}\), m.storage.loc[s]['fix-cost-p']).

These two products for a given storage tuple are than added up. The calculation of fix costs for a storage tuple is then repeated for every single storage tuple and summed up to calculate the total fix costs for storage technologies. In mathematical notation this summand is expressed as:

\[\begin{split}\sum_{\substack{v \in V\\ s \in S}} (\kappa_{vs}^\text{c} k_{vs}^\text{c,fix} + \kappa_{vs}^\text{p} k_{vs}^\text{p,fix})\end{split}\]

The third and the last summand of the formula calculates the required fix expenses to keep the power capacity of transmission technologies maintained. The transmission technologies comprise the members of the set transmission tuples \(\forall f_{ca} \in F_{ca}\). Total transmission fix cost for all transmission tuples is defined by the sum of all possible annual transmission fix costs, which are calculated seperately for each transmission tuple \(f_{ca}\). Annual transmission fix cost for a given transmission tuple is calculated by the product of the variable total transmission capacity ( \(\kappa_{af}\), cap_tra) and the parameter annual transmission capacity fixed costs ( \(k_{af}^\text{fix}\), m.transmission.loc[t]['fix-cost']) for the given transmission tuple \(f_{ca}\). In mathematical notation this summand is expressed as:

\[\begin{split}\sum_{\substack{a \in A\\ f \in F}} \kappa_{af} k_{af}^\text{fix}\end{split}\]

As mentioned above, the fix costs \(\zeta_\text{fix}\) are calculated by the sum of these 3 summands.

In script urbs.py the value of the total fix cost is calculated by the following code fragment:

elif cost_type == 'Fixed':
    return m.costs[cost_type] == \
        sum(m.cap_pro[p] * m.process.loc[p]['fix-cost']
            for p in m.pro_tuples) + \
        sum(m.cap_tra[t] * m.transmission.loc[t]['fix-cost']
            for t in m.tra_tuples) + \
        sum(m.cap_sto_p[s] * m.storage.loc[s]['fix-cost-p'] +
            m.cap_sto_c[s] * m.storage.loc[s]['fix-cost-c']
            for s in m.sto_tuples)

Variable Costs¶

\[\begin{split}\zeta_\text{var} = w \sum_{t \in T_\text{m}} &\left( \sum_{\substack{v \in V\\ p \in P}} \tau_{vpt} k_{vp}^\text{var} \Delta t + \sum_{\substack{a \in a\\ f \in F}} \pi_{af}^\text{in} k_{af}^\text{var} \Delta t + \right.\nonumber \\ &\left.\phantom{\Big(} % invisible left parenthesis for horizontal alignment \sum_{\substack{v \in V\\ s \in S}} \left[ \epsilon_{vst}^\text{con} k_{vs}^\text{c,var} + \left( \epsilon_{vst}^\text{in} + \epsilon_{vst}^\text{out} \right) k_{vs}^\text{p,var} \Delta t \right] \right)\end{split}\]

elif cost_type == 'Variable':
    return m.costs[cost_type] == \
        sum(m.tau_pro[(tm,) + p] * m.dt *
            m.process.loc[p]['var-cost'] *
            m.weight
            for tm in m.tm
            for p in m.pro_tuples) + \
        sum(m.e_tra_in[(tm,) + t] * m.dt *
            m.transmission.loc[t]['var-cost'] *
            m.weight
            for tm in m.tm
            for t in m.tra_tuples) + \
        sum(m.e_sto_con[(tm,) + s] *
            m.storage.loc[s]['var-cost-c'] * m.weight +
            (m.e_sto_in[(tm,) + s] + m.e_sto_out[(tm,) + s]) * m.dt *
            m.storage.loc[s]['var-cost-p'] * m.weight
            for tm in m.tm
            for s in m.sto_tuples)

Fuel Costs¶

The variable fuel costs \(\zeta_\text{fuel}\) represents the total annual expenses that are required to be made to buy stock commodities \(c \in C_\text{stock}\). The calculation of the variable total annual fuel cost \(\zeta_\text{fuel}\) is expressed by the following mathematical notation:

\[\zeta_\text{fuel} = w \sum_{t\in T_\text{m}} \sum_{v \in V} \sum_{c \in C_\text{stock}} \rho_{vct} k_{vc}^\text{fuel} \Delta t\]

The variable \(\zeta_\text{fuel}\) is calculated by the sum of all possible annual fuel costs, defined by the combinations of commodity tuples of commodity type ‘Stock’( \(\forall c_{vq} \in C_{vq} \land q = \text{'Stock'}\)) and timesteps( \(\forall t \in T_m\)). These annual fuel costs are calculated by the product of the following elements:

The parameter stock commodity fuel cost for a given stock commodity \(c\) in a site \(v\).( \(k_{vc}^\text{fuel}\), m.commodity.loc[c]['price'])

The variable stock commodity source term for a given stock commodity \(c\) in a site \(v\) at a timestep \(t\).( \(\rho_{vct}\), e_co_stock)

The variable timestep duration.( \(\Delta t\), dt)

The variable weight.( \(w\), weight)

In script urbs.py the value of the total fuel cost is calculated by the following code fragment:

elif cost_type == 'Fuel':
    return m.costs[cost_type] == sum(
        m.e_co_stock[(tm,) + c] * m.dt *
        m.commodity.loc[c]['price'] *
        m.weight
        for tm in m.tm for c in m.com_tuples
        if c[1] in m.com_stock)

Revenue Costs¶

The variable revenue costs \(\zeta_\text{rev}\) represents the total annual expenses that are required to be made to sell sell commodities \(c \in C_\text{sell}\). The calculation of the variable total annual revenue cost \(\zeta_\text{rev}\) is expressed by the following mathematical notation:

\[\zeta_\text{rev} = -w \sum_{t\in T_\text{m}} \sum_{v \in V} \sum_{c \in C_\text{sell}} \varrho_{vct} k_{vct}^\text{bs} \Delta t\]

The variable \(\zeta_\text{rev}\) is calculated by the sum of all possible annual revenue costs, defined by the combinations of commodity tuples of commodity type ‘Sell’( \(\forall c_{vq} \in C_{vq} \land q = \text{'Sell'}\)) and timesteps (\(\forall t \in T_m\)). These annual revenue costs are calculated by the product of the following elements:

The parameter sell commodity sell cost for given sell commodity \(c\) in a site \(v\).( \(k_{vct}^\text{bs}\), com_prices[c].loc[tm] )

The variable sell commodity source term for a given sell commodity \(c\) in a site \(v\) at a timestep \(t\).( \(\varrho_{vct}\), e_co_sell)

The variable timestep duration.( \(\Delta t\), dt)

The variable weight.( \(w\), weight)

Coefficient [-1].

Since this variable is an income for the energy system, it is multiplied by the value -1 to be able to express it in the cost function as a summand. In script urbs.py the value of the total revenue cost is calculated by the following code fragment:

elif cost_type == 'Revenue':
    sell_tuples = commodity_subset(m.com_tuples, m.com_sell)
    com_prices = get_com_price(m, sell_tuples)

    return m.costs[cost_type] == -sum(
        m.e_co_sell[(tm,) + c] *
        com_prices[c].loc[tm] *
        m.weight * m.dt
        for tm in m.tm
        for c in sell_tuples)

Purchase Costs¶

The variable purchase costs \(\zeta_\text{pur}\) represents the total annual expenses that are required to be made to purchase buy commodities \(c \in C_\text{buy}\). The calculation of the variable total annual purchase cost \(\zeta_\text{pur}\) is expressed by the following mathematical notation:

\[\zeta_\text{pur} = w \sum_{t\in T_\text{m}} \sum_{v \in V} \sum_{c \in C_\text{buy}} \psi_{vct} k_{vct}^\text{bs} \Delta t\]

The variable \(\zeta_\text{pur}\) is calculated by the sum of all possible annual purchase costs, defined by the combinations of commodity tuples of commodity type ‘Buy’( \(\forall c_{vq} \in C_{vq} \land q = \text{'Buy'}\)) and timesteps (\(\forall t \in T_m\)). These annual purchase costs are calculated by the product of the following elements:

The parameter buy commodity buy cost for a given buy commodity \(c\) in a site \(v\). ( \(k_{vct}^\text{bs}\), com_prices[c].loc[tm] )

The variable buy commodity source term for a given buy commodity \(c\) in a site \(v\) at a timestep \(t\).( \(\psi_{vct}\), e_co_buy)

The variable timestep duration.( \(\Delta t\), dt)

The variable weight.( \(w\), weight)

In script urbs.py the value of the total purchase cost is calculated by the following code fragment:

elif cost_type == 'Purchase':
    buy_tuples = commodity_subset(m.com_tuples, m.com_buy)
    com_prices = get_com_price(m, buy_tuples)

    return m.costs[cost_type] == sum(
        m.e_co_buy[(tm,) + c] *
        com_prices[c].loc[tm] *
        m.weight * m.dt
        for tm in m.tm
        for c in buy_tuples)

Startup Costs¶

The variable startup costs \(\zeta_\text{startup}\) represents the total annual expenses that are required for the startup occurences of processes with the partial & startup feature activated. The calculation of the total annual startup costs is expressed by the following mathematical notation:

\[\zeta_\text{startup} = w \sum_{t\in T_\text{m}} \sum_{v \in V} \sum_{p \in P} \phi_{vpt} k_{vp}^\text{st} \Delta t\]

In script urbs.py the value of the total startup cost is calculated by the following code fragment:

elif cost_type == 'Startup':
    return m.costs[cost_type] == sum(
        m.startup_pro[(tm,) + p] *
        m.process.loc[p]['startup-cost'] *
        m.weight * m.dt
        for tm in m.tm
        for p in m.pro_partial_tuples)

Environmental Costs¶

Environmental costs \(\zeta_\text{env}\) represent the total annual taxes for created emissions/pollutions in form of environmental commodities. The total annual costs are calculated by summing the negative commodity balance \(\textrm{CB}\) of all environmental commodities, multiplied by their respective price

\[\zeta_\text{env} = - w \sum_{t\in T_\text{m}} \sum_{v\in V} \sum_{c \in C_\text{env}} \textrm{CB}(v,c,t) \Delta t\]

In script urbs.py the value of the total environmental cost is calculated by the following code fragment:

elif cost_type == 'Environmental':
    return m.costs[cost_type] == sum(
        - commodity_balance(m, tm, sit, com) *
        m.weight * m.dt *
        m.commodity.loc[sit, com, com_type]['price']
        for tm in m.tm
        for sit, com, com_type in m.com_tuples
        if com in m.com_env)

Constraints¶

Commodity Constraints¶

Commodity Balance The function commodity balance calculates the balance of a commodity \(c\) in a site \(v\) at a timestep \(t\). Commodity balance function facilitates the formulation of commodity constraints. The formula for commodity balance is expressed in mathematical notation as:

\[\begin{split}\mathrm{CB}(v,c,t) = \sum_{p|c \in C_{vp}^\text{in}} \epsilon_{vcpt}^\text{in} - \sum_{p|c \in C_{vp}^\text{out}} \epsilon_{vcpt}^\text{out} + \sum_{{s\in S_{vc}}} \left( \epsilon_{vst}^\text{in} - \epsilon_{vst}^\text{out} \right) + \sum_{{\substack{a\in A_v^\text{s}\\ f \in F_{vc}^\text{exp}}}} \pi_{aft}^\text{in} - \sum_{{\substack{a\in A_v^\text{p}\\ f \in F_{vc}^\text{imp}}}} \pi_{aft}^\text{out}\end{split}\]

This function sums up for a given commodity \(c\), site \(v\) and timestep \(t\);

the consumption: Process input commodity flow \(\epsilon_{vcpt}^\text{in}\) of all process tuples using the commodity \(c\) in the site \(v\) at the timestep \(t\).
the export: Input transmission power flow \(\pi_{aft}^\text{in}\) of all transmission tuples exporting the commodity \(c\) from the origin site \(v\) at the timestep \(t\).
the storage input: Input power flow \(\epsilon_{vst}^\text{in}\) of all storage tuples storing the commodity \(c\) in the site \(v\) at the timestep \(t\).

and subtracts for the same given commodity \(c\), site \(v\) and timestep \(t\);

the creation: Process output commodity flow \(\epsilon_{vcpt}^\text{out}\) of all process tuples using the commodity \(c\) in the site \(v\) at the timestep \(t\).
the import: Output transmission power flow \(\pi_{aft}^\text{out}\) of all transmission tuples importing the commodity math:c to the destination site \(v\) at the timestep \(t\).
the storage output: Output power flow \(\epsilon_{vst}^\text{out}\) of all storage tuples storing the commodity \(c\) in the site \(v\) at the timestep \(t\).

The value of the function \(\mathrm{CB}\) being greater than zero \(\mathrm{CB} > 0\) means that the presence of the commodity \(c\) in the site \(v\) at the timestep \(t\) is getting less than before by the technologies given above. Correspondingly, the value of the function being less than zero means that the presence of the commodity in the site at the timestep is getting more than before by the technologies given above.

In script urbs.py the value of the commodity balance function \(\mathrm{CB}(v,c,t)\) is calculated by the following code fragment:

Vertex Rule: Vertex rule is the main constraint that has to be satisfied for every commodity. This constraint is defined differently for each commodity type. The inequality requires, that any imbalance (CB>0, CB<0) of a commodity \(c\) in a site \(v\) at a timestep \(t\) to be balanced by a corresponding source term or demand.

Environmental commodities \(C_\text{env}\): this constraint is not defined for environmental commodities.
Suppy intermittent commodities \(C_\text{sup}\): this constraint is not defined for supply intermittent commodities.
Stock commodities \(C_\text{st}\): For stock commodities, the possible imbalance of the commodity must be supplied by the stock commodity purchases. In other words, commodity balance \(\mathrm{CB}(v,c,t)\) subtracted from the variable stock commodity source term \(\rho_{vct}\) must be greater than or equal to 0 to satisfy this constraint. In mathematical notation this is expressed as:

\[\forall v\in V, c\in C_\text{st}, t\in T_m\colon\ - \mathrm{CB}(v,c,t) + \rho_{vct} \geq 0\]

Sell commodities \(C_\text{sell}\): For sell commodities, the possible imbalance of the commodity must be supplied by the sell commodity trades. In other words, commodity balance \(\mathrm{CB}(v,c,t)\) subtracted from minus the variable sell commodity source term \(\varrho_{vct}\) must be greater than or equal to 0 to satisfy this constraint. In mathematical notation this is expressed as:

\[\forall v\in V, c\in C_\text{sell}, t\in T_m\colon\ - \mathrm{CB}(v,c,t) - \varrho_{vct} \geq 0\]

Buy commodities \(C_\text{buy}\): For buy commodities, the possible imbalance of the commodity must be supplied by the buy commodity purchases. In other words, commodity balance \(\mathrm{CB}(v,c,t)\) subtracted from the variable buy commodity source term \(\psi_{vct}\) must be greater than or equal to 0 to satisfy this constraint. In mathematical notation this is expressed as:

\[\forall v\in V, c\in C_\text{buy}, t\in T_m\colon\ - \mathrm{CB}(v,c,t) + \psi_{vct} \geq 0\]

Demand commodities \(C_\text{dem}\): For demand commodities, the possible imbalance of the commodity must supply the demand \(d_{vct}\) of demand commodities \(c \in C_\text{dem}\). In other words, the parameter demand for commodity subtracted \(d_{vct}\) from the minus commodity balance \(-\mathrm{CB}(v,c,t)\) must be greater than or equal to 0 to satisfy this constraint. In mathematical notation this is expressed as:

\[\forall v\in V, c\in C_\text{dem}, t\in T_m\colon\ - \mathrm{CB}(v,c,t) - d_{vct} \geq 0\]

Demand Side Management commodities and sites: For any combination of commodity and site for which demand side management is defined, the upshift is substracted and the downshift added to the negative commodity balance \(-\mathrm{CB}(v,c,t)\).

\[\forall (v,c) in D_{vc}, t\in T_m\colon\ - \mathrm{CB}(v,c,t) - \delta_{vct}^\text{up}` + \sum_{tt \in D_{vct,tt}^\text{down}} \delta_{vct,tt}^\text{down}` \geq 0\]

In script urbs.py the constraint vertex rule is defined and calculated by the following code fragments:

m.res_vertex = pyomo.Constraint(
        m.tm, m.com_tuples,
        rule=res_vertex_rule,
        doc='storage + transmission + process + source + buy - sell == demand')

Stock Per Step Rule: The constraint stock per step rule applies only for commodities of type “Stock” ( \(c \in C_\text{st}\)). This constraint limits the amount of stock commodity \(c \in C_\text{st}\), that can be used by the energy system in the site \(v\) at the timestep \(t\). The limited amount is defined by the parameter maximum stock supply limit per time step \(\overline{l}_{vc}\). To satisfy this constraint, the value of the variable stock commodity source term \(\rho_{vct}\) must be less than or equal to the value of the parameter maximum stock supply limit per time step \(\overline{l}_{vc}\). In mathematical notation this is expressed as:

\[\forall v\in V, c\in C_\text{st}, t\in T_m\colon\ \rho_{vct} \leq \overline{l}_{vc}\]

In script urbs.py the constraint stock per step rule is defined and calculated by the following code fragment:

m.res_stock_step = pyomo.Constraint(
    m.tm, m.com_tuples,
    rule=res_stock_step_rule,
    doc='stock commodity input per step <= commodity.maxperstep')

Total Stock Rule: The constraint total stock rule applies only for commodities of type “Stock” (\(c \in C_\text{st}\)). This constraint limits the amount of stock commodity \(c \in C_\text{st}\), that can be used annually by the energy system in the site \(v\). The limited amount is defined by the parameter maximum annual stock supply limit per vertex \(\overline{L}_{vc}\). To satisfy this constraint, the annual usage of stock commodity must be less than or equal to the value of the parameter stock supply limit per vertex \(\overline{L}_{vc}\). The annual usage of stock commodity is calculated by the sum of the products of the parameter weight \(w\), the parameter timestep duration \(\Delta t\) and the parameter stock commodity source term \(\rho_{vct}\) for every timestep \(t \in T_m\). In mathematical notation this is expressed as:

\[\forall v\in V, c\in C_\text{st}\colon\ w \sum_{t\in T_m} \Delta t\, \rho_{vct} \leq \overline{L}_{vc}\]

In script urbs.py the constraint total stock rule is defined and calculated by the following code fragment:

m.res_stock_total = pyomo.Constraint(
    m.com_tuples,
    rule=res_stock_total_rule,
    doc='total stock commodity input <= commodity.max')

Sell Per Step Rule: The constraint sell per step rule applies only for commodities of type “Sell” ( \(c \in C_\text{sell}\)). This constraint limits the amount of sell commodity \(c \in C_\text{sell}\), that can be sold by the energy system in the site \(v\) at the timestep \(t\). The limited amount is defined by the parameter maximum sell supply limit per time step \(\overline{g}_{vc}\). To satisfy this constraint, the value of the variable sell commodity source term \(\varrho_{vct}\) must be less than or equal to the value of the parameter maximum sell supply limit per time step \(\overline{g}_{vc}\). In mathematical notation this is expressed as:

\[\forall v\in V, c\in C_\text{sell}, t\in T_m\colon\ \varrho_{vct} \leq \overline{g}_{vc}\]

In script urbs.py the constraint sell per step rule is defined and calculated by the following code fragment:

m.res_sell_step = pyomo.Constraint(
   m.tm, m.com_tuples,
   rule=res_sell_step_rule,
   doc='sell commodity output per step <= commodity.maxperstep')

Total Sell Rule: The constraint total sell rule applies only for commodities of type “Sell” ( \(c \in C_\text{sell}\)). This constraint limits the amount of sell commodity \(c \in C_\text{sell}\), that can be sold annually by the energy system in the site \(v\). The limited amount is defined by the parameter maximum annual sell supply limit per vertex \(\overline{G}_{vc}\). To satisfy this constraint, the annual usage of sell commodity must be less than or equal to the value of the parameter sell supply limit per vertex \(\overline{G}_{vc}\). The annual usage of sell commodity is calculated by the sum of the products of the parameter weight \(w\), the parameter timestep duration \(\Delta t\) and the parameter sell commodity source term \(\varrho_{vct}\) for every timestep \(t \in T_m\). In mathematical notation this is expressed as:

\[\forall v\in V, c\in C_\text{sell}\colon\ w \sum_{t\in T_m} \Delta t\, \varrho_{vct} \leq \overline{G}_{vc}\]

In script urbs.py the constraint total sell rule is defined and calculated by the following code fragment:

m.res_sell_total = pyomo.Constraint(
    m.com_tuples,
    rule=res_sell_total_rule,
    doc='total sell commodity output <= commodity.max')

Buy Per Step Rule: The constraint buy per step rule applies only for commodities of type “Buy” ( \(c \in C_\text{buy}\)). This constraint limits the amount of buy commodity \(c \in C_\text{buy}\), that can be bought by the energy system in the site \(v\) at the timestep \(t\). The limited amount is defined by the parameter maximum buy supply limit per time step \(\overline{b}_{vc}\). To satisfy this constraint, the value of the variable buy commodity source term \(\psi_{vct}\) must be less than or equal to the value of the parameter maximum buy supply limit per time step \(\overline{b}_{vc}\). In mathematical notation this is expressed as:

\[\forall v\in V, c\in C_\text{buy}, t\in T_m\colon\ \psi_{vct} \leq \overline{b}_{vc}\]

In script urbs.py the constraint buy per step rule is defined and calculated by the following code fragment:

m.res_buy_step = pyomo.Constraint(
    m.tm, m.com_tuples,
    rule=res_buy_step_rule,
    doc='buy commodity output per step <= commodity.maxperstep')

Total Buy Rule: The constraint total buy rule applies only for commodities of type “Buy” ( \(c \in C_\text{buy}\)). This constraint limits the amount of buy commodity \(c \in C_\text{buy}\), that can be bought annually by the energy system in the site \(v\). The limited amount is defined by the parameter maximum annual buy supply limit per vertex \(\overline{B}_{vc}\). To satisfy this constraint, the annual usage of buy commodity must be less than or equal to the value of the parameter buy supply limit per vertex \(\overline{B}_{vc}\). The annual usage of buy commodity is calculated by the sum of the products of the parameter weight \(w\), the parameter timestep duration \(\Delta t\) and the parameter buy commodity source term \(\psi_{vct}\) for every timestep \(t \in T_m\). In mathematical notation this is expressed as:

\[\forall v\in V, c\in C_\text{buy}\colon\ w \sum_{t\in T_m} \Delta t\, \psi_{vct} \leq \overline{B}_{vc}\]

In script urbs.py the constraint total buy rule is defined and calculated by the following code fragment:

m.res_buy_total = pyomo.Constraint(
   m.com_tuples,
   rule=res_buy_total_rule,
   doc='total buy commodity output <= commodity.max')

Environmental Output Per Step Rule: The constraint environmental output per step rule applies only for commodities of type “Env” ( \(c \in C_\text{env}\)). This constraint limits the amount of environmental commodity \(c \in C_\text{env}\), that can be released to environment by the energy system in the site \(v\) at the timestep \(t\). The limited amount is defined by the parameter maximum environmental output per time step \(\overline{m}_{vc}\). To satisfy this constraint, the negative value of the commodity balance for the given environmental commodity \(c \in C_\text{env}\) must be less than or equal to the value of the parameter maximum environmental output per time step \(\overline{m}_{vc}\). In mathematical notation this is expressed as:

\[\forall v\in V, c\in C_\text{env}, t\in T_m\colon\ -\mathrm{CB}(v,c,t) \leq \overline{m}_{vc}\]

In script urbs.py the constraint environmental output per step rule is defined and calculated by the following code fragment:

m.res_env_step = pyomo.Constraint(
    m.tm, m.com_tuples,
    rule=res_env_step_rule,
    doc='environmental output per step <= commodity.maxperstep')

Total Environmental Output Rule: The constraint total environmental output rule applies only for commodities of type “Env” ( \(c \in C_\text{env}\)). This constraint limits the amount of environmental commodity \(c \in C_\text{env}\), that can be released to environment annually by the energy system in the site \(v\). The limited amount is defined by the parameter maximum annual environmental output limit per vertex \(\overline{M}_{vc}\). To satisfy this constraint, the annual release of environmental commodity must be less than or equal to the value of the parameter maximum annual environmental output \(\overline{M}_{vc}\). The annual release of environmental commodity is calculated by the sum of the products of the parameter weight \(w\), the parameter timestep duration \(\Delta t\) and the negative value of commodity balance function, for every timestep \(t \in T_m\). In mathematical notation this is expressed as:

\[\forall v\in V, c\in C_\text{env}\colon\ - w \sum_{t\in T_m} \Delta t\, \mathrm{CB}(v,c,t) \leq \overline{M}_{vc}\]

In script urbs.py the constraint total environmental output rule is defined and calculated by the following code fragment:

m.res_env_total = pyomo.Constraint(
    m.com_tuples,
    rule=res_env_total_rule,
    doc='total environmental commodity output <= commodity.max')

In script urbs.py the constraint total environmental output rule is defined and calculated by the following code fragment:

Demand Side Management Constraints¶

The DSM equations are taken from the Paper of Zerrahn and Schill “On the representation of demand-side management in power system models”, DOI: 10.1016/j.energy.2015.03.037.

DSM Variables Rule: The DSM variables rule defines the relation between upshift and downshift. An upshift \(\delta_{vct}^\text{up}\) in site \(v\) of commodity \(c\) in time step \(t\) can be compensated during a certain time interval \([t-y_{vc}, t+y_{vc}]\) by multiple downshifts \(\delta_{vct,tt}^\text{down}\). Depending on the efficiency \(e_{vc}\), less downshifts have to be made. This is given by:

\[\forall (v,c) \in D_{vc}, t\in T\colon\ \delta_{vct}^\text{up} e_{vc} = \sum_{tt = t-y_{vc}}^{t+y_{vc}} \delta_{vct,tt}^\text{down}\]