urbs

urbs is a linear programming optimisation model for capacity expansion planning and unit commitment for distributed energy systems. Its name, latin for city, stems from its origin as a model for optimisation for urban energy systems. Since then, it has been adapted to multiple scales from neighbourhoods to continents.

Features
Screenshots
Installation
Get started
Next steps and tips
Further reading
Example uses
Contributing
License

Features

urbs is a linear programming model for multi-commodity energy systems with a focus on optimal storage sizing and use.
It finds the minimum cost energy system to satisfy given demand time series for possibly multiple commodities (e.g. electricity).
By default, operates on hourly-spaced time steps (configurable).
Thanks to Pandas, complex data analysis is easy.
The model itself is quite small thanks to relying on package Pyomo.
The small codebase includes reporting and plotting functionality.

Screenshots

Installation

Installing Python

Download and install Python 3.12. Note: Make sure to check the box "Add Python to PATH" during installation.
Using your terminal you can check which Python versions are installed on your system with py -0 and check your standard version with python --version. The output should be Python 3.12.x or similar. (Note: If your standard python version is Python 2.X, you might need to call python3 instead of python.)

Installing an IDE (optional)

If you want to use an IDE for Python, you can install PyCharm or Visual Studio Code. Both are free to use.

Installing Git

Download and install Git. Make sure to check the box "Run Git from the Windows Command Prompt" during installation. You can also use the GitHub Desktop application if you prefer a graphical user interface.
Check that Git is installed by running the command git --version in your terminal.

Cloning the urbs repository

Open your terminal and navigate to your preferred directory.
Clone the repository by running the following commands in your terminal.:
- For GitLab: git clone git@gitlab.lrz.de:tum-ens/urbs.git
- For GitHub: git clone git@github.com:tum-ens/urbs.git
Navigate to the cloned repository by running cd urbs in your terminal.

Installing your environment

In windows you can install the environment by running the batch script prepare-virtual-environment in the root directory of the repository. You can do so from a terminal or by double-clicking the file in the file explorer. This will create a virtual environment and install all necessary packages.
If you want to install the environment manually, enter the commands below in your terminal:

Windows: py -3.12 -m venv urbs-env urbs-env\Scripts\activate python -m pip install -r urbs-env.txt
Linux/MacOS: python3.12 -m venv urbs-env source urbs-env/bin/activate python -m pip install -r urbs-env.txt

Solver

There are several solvers that can be used to solve the optimization problems. Our recommendations are the following two python libraries that have been installed in the environment.

Highs (open-source)
Gurobi (commercial): To run this powerful solver you first need to create an account, apply for an academic license in the license center and download it (descriptions).

However, also other solvers such as glpk (open-source) or CPLEX (commercial) are compatible with the Pyomo interface in urbs.

(optional) Installing Jupyter Notebook

If you want to use the Jupyter Notebook, install it by running python -m pip install jupyter in your terminal.

Get started

Before running a script, ensure your environment is activated:

Either set up your interpreter in your IDE with your created environment.
Or, if running from your terminal, use the following command to activate it:
- Windows: urbs-env\Scripts\activate
- Linux/MacOS: source urbs-env/bin/activate

In the downloaded directory, open a execute the runme script by using the following on the command prompt or Terminal. (Note: Depending on what your standard python version is, you might need to call python3.12 instead of python.):

python runme.py

Some minutes later, the subfolder result should contain plots and summary spreadsheets for multiple optimised energy supply scenarios, whose definitions are contained in the run script (watch out for def scenario lines). Not working at the moment: To get a graphical and tabular summary over all scenarios, execute

python comp.py

and look at the new files result/mimo-example-.../comparison.xlsx and result/mimo-example-.../comparison.png for a quick comparison. This script parses the summary spreadsheets for all scenarios.

Next steps and tips

Head over to the tutorial at http://urbs.readthedocs.io, which goes through runme.py step by step or try out the Jupyter Notebook tutorial inside the teaching folder.
Read the source code of runme.py and comp.py.
Try adding/modifying scenarios in scenarios.py and see their effect on results.
If you need a nice python editor, think about using PyCharm. It has many features including easy Git integration, package management, etc.
Fire up IPython (ipython3) and run the scripts from there using the run command: run runme and run comp. Then use whos and inspect the workspace afterwards (whos). See what you can do (analyses, plotting) with the DataFrames. Take the urbs.get_constants, urbs.get_timeseries and urbs.plot functions as inspriation and the Pandas docs as reference.

Example uses

Branch 1node in the forked repository ojdo/urbs shows a small example of a real-world usage of the model. It includes a scenario_generator function in its run script, which is useful for extensive parameter sweeps.
Branch 1house in the forked repository ojdo/urbs shows another (newer) example of a small-scale application of the model. It demonstrates the use for two demand commodities (electricity and heat) for a single consumer (a single site named 'house'). It also shows how to create a very customized comparison script:

Branch [haag15](https://github.com/ojd

Urbs

Install / Use

README