Update environment and README to latest Python version (#322)

* Update environment and README to latest Python version

* Adjust default timesteps

* Add information on activating environments in README

* Fix format in README

Author: bereba

README.md

@@ -5,6 +5,24 @@ urbs is a [linear programming](https://en.wikipedia.org/wiki/Linear_programming)
 [![Documentation Status](https://readthedocs.org/projects/urbs/badge/?version=latest)](http://urbs.readthedocs.io/en/latest/?badge=latest)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.594200.svg)](https://doi.org/10.5281/zenodo.594200)
 
+## Table of Contents
+
+- [Features](#features)
+- [Screenshots](#screenshots)
+- [Installation](#installation)
+  - [Installing Python](#installing-python)
+  - [Installing a Python IDE (optional)](#installing-a-python-ide-optional)
+  - [Installing Git](#installing-git)
+  - [Cloning the urbs repository](#cloning-the-urbs-repository)
+  - [Installing your environment](#installing-your-environment)
+  - [Solver](#solver)
+- [Get started](#get-started)
+- [Next steps and tips](#next-steps-and-tips)
+- [Further reading](#further-reading)
+- [Example uses](#example-uses)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## Features
 
   * urbs is a linear programming model for multi-commodity energy systems with a focus on optimal storage sizing and use.
@@ -22,40 +40,65 @@ urbs is a [linear programming](https://en.wikipedia.org/wiki/Linear_programming)
 
 ## Installation
 
-There are 2 ways to get all required packages under Windows. We recommend using the Python distribution Anaconda. If you don't want to use it or already have an existing Python (version 3.6 **recommended**, 2.7 is supported as well) installation, you can also download the required packages by yourself..
+### Installing Python
 
-### Anaconda/Miniconda (recommended)
+1) Download and install [Python 3.12](https://www.python.org/downloads/). ***Note: Make sure to check the box "Add Python to PATH" during installation.***
+2) 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.
+   <br /> (***Note: If your standard python version is Python 2.X, you might need to call `python3` instead of `python`.***)
 
-  1. **[Anaconda (Python 3)](http://continuum.io/downloads)/[Miniconda](https://docs.conda.io/en/latest/miniconda.html)**. Choose the 64-bit installer if possible.
-     During the installation procedure, keep both checkboxes "modify PATH" and "register Python" selected! If only higher Python versions are available, you can switch to a specific Python Version by typing `conda install python=<version>`
-  2. **Packages and Solver**: [GLPK](http://winglpk.sourceforge.net/).
-     1. Download the [environment file](https://github.com/tum-ens/urbs/blob/master/urbs-env.yml).
-     2. Launch a new command prompt (Windows: Win+R, type "cmd", Enter)
-     3. Install it via conda by `conda env create -f urbs-env.yml`.
-     4. Each time you open a new terminal for running urbs, you can activate the environment by `conda activate urbs`.
+### Installing an IDE (optional)
 
-Continue at [Get Started](#get-started).
+If you want to use an IDE for Python, you can install [PyCharm](https://www.jetbrains.com/pycharm/download/#section=windows) or [Visual Studio Code](https://code.visualstudio.com/). Both are free to use.
 
-### Manually (the hard way)
+### Installing Git
 
-For all packages, best take the latest release or release candidate version. Both 32 bit and 64 bit versions work, though 64 bit is recommended. The list of packages can be found in the [environment file](https://github.com/tum-ens/urbs/blob/master/urbs-env.yml).
-  
-## Get started
+1) Download and install [Git](http://git-scm.com/). Make sure to check the box "Run Git from the Windows Command Prompt" during installation.
+You can also use the [GitHub Desktop](https://desktop.github.com/) application if you prefer a graphical user interface.
+2) Check that Git is installed by running the command `git --version` in your terminal. 
+
+### Cloning the urbs repository
+
+1) Open your terminal and navigate to your preferred directory.
+2) 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`
+3) Navigate to the cloned repository by running `cd urbs` in your terminal.
+
+### Installing your environment
 
-### Developers
-Once installation is complete, finally [install git (for version control)](http://git-scm.com/). **Remark:** at step "Adjusting your PATH environment", select "Run Git from the Windows Command Prompt".
+1) 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.
+2) If you want to install the environment manually, enter the commands below in your terminal:
+- Windows: <br />
+    `py -3.12 -m venv urbs-env` <br />
+    `urbs-env\Scripts\activate` <br />
+    `python -m pip install -r urbs-env.txt`
 
-Then, in a directory of your choice, clone this repository by:
+- Linux/MacOS: <br />
+    `python3.12 -m venv urbs-env` <br />
+    `source urbs-env/bin/activate` <br />
+    `python -m pip install -r urbs-env.txt`
 
-    git clone https://github.com/tum-ens/urbs.git
-    
-Continue like the users after they downloaded the zip file. 
+### 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](https://highs.dev/) (open-source)
+- [Gurobi](https://www.gurobi.com/) (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](https://www.gurobi.com/features/academic-named-user-license/)).
 
-### Users
+However, also other solvers such as [glpk](https://www.gnu.org/software/glpk/) (open-source) or [CPLEX](https://www.ibm.com/analytics/cplex-optimizer) (commercial) are compatible with the Pyomo interface in urbs.
 
-If you are not planning on developing urbs, pick the [latest release](https://github.com/tum-ens/urbs/releases) and download the zip file.
+### (optional) Installing Jupyter Notebook
+If you want to use the Jupyter Notebook, install it by running `python -m pip install jupyter` in your terminal.
 
-In the downloaded directory, open a execute the runme script by using the following on the command prompt (Windows) or Terminal (Linux). (Depending on what your standard python version is, you might need to call `python3` instead of `python`.):
+## 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. 
+<br /> (***Note: Depending on what your standard python version is, you might need to call `python3.12` instead of `python`.***):
 
     python runme.py
 
@@ -67,7 +110,7 @@ and look at the new files `result/mimo-example-.../comparison.xlsx` and `result/
 
 ## Next steps and tips
 
-  1. Head over to the tutorial at http://urbs.readthedocs.io, which goes through runme.py step by step. 
+  1. 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. 
   2. Read the source code of `runme.py` and `comp.py`. 
   3. Try adding/modifying scenarios in `scenarios.py` and see their effect on results.
   4. If you need a nice python editor, think about using [PyCharm](https://www.jetbrains.com/pycharm/download). It has many features including easy Git integration, package management, etc.
@@ -90,15 +133,7 @@ and look at the new files `result/mimo-example-.../comparison.xlsx` and `result/
 <a href="https://raw.githubusercontent.com/ojdo/urbs/1house/img/comparison.png"><img src="https://raw.githubusercontent.com/ojdo/urbs/1house/img/comparison.png" alt="Comparison plot in example study 1house."></a>
 
   - Branch [haag15](https://github.com/ojdo/urbs/tree/haag15) in the forked repository [ojdo/urbs](https://github.com/ojdo/urbs) shows a larger example of a real-world use. Its input file contains a town divided into 12 regions, 12 process types, and 2 demand commodities (electricity and heat) . Patience and RAM (64 GB or more) is needed to run these scenarios with 8760 timesteps. The branch also contains three IPython notebooks that are used for result analysis and coupling to model [rivus](https://github.com/tum-ens/rivus).
-  
-## List of branches
-  - ASEAN
-  - CoTraDis
-  - decensys
-  - extremos
-  - MIQCP
-  - near_optimal
-  - urbs_gui
+
 
 ## Copyright
 

prepare-virtual-environment-WINDOWS.bat

@@ -0,0 +1,48 @@
+@echo off
+REM =======================================
+REM Batch script to set up Python environment for urbs
+REM =======================================
+
+REM Check if the virtual environment exists
+if exist "urbs-env\Scripts\activate" (
+    echo Virtual environment already exists.
+) else (
+    REM Create the virtual environment
+    echo Creating virtual environment...
+    py -3.12 -m venv urbs-env
+
+    REM Check if creation was successful
+    if not exist "urbs-env\Scripts\activate" (
+        echo Error: Failed to create virtual environment.
+        exit /b 1
+    )
+)
+
+REM Activate the virtual environment (Windows)
+call urbs-env\Scripts\activate
+echo Virtual environment has been activated.
+
+REM Check if packages are already installed
+REM Using a dummy file to detect if packages are installed, you can also use pip freeze or similar checks
+if exist "urbs-env\installed.flag" (
+    echo Required packages already installed.
+) else (
+    echo Installing required packages from urbs-env.txt...
+    python -m pip install -r urbs-env.txt
+
+    REM Check if the installation succeeded
+    if %errorlevel% neq 0 (
+        echo Error: Failed to install packages.
+        exit /b 1
+    )
+
+    REM Create a flag to indicate that packages have been installed
+    echo Packages installed successfully > urbs-env\installed.flag
+    echo Packages installed successfully.
+)
+
+REM Notify the user that the process is complete
+echo Your urbs environment is ready to use.
+
+REM Prevent the script from closing immediately
+pause

run_intertemporal.py

@@ -28,7 +28,7 @@
 solver = 'gurobi'
 
 # simulation timesteps
-(offset, length) = (0, 24)  # time step selection
+(offset, length) = (0, 8760)  # time step selection
 timesteps = range(offset, offset+length+1)
 dt = 1  # length of each time step (unit: hours)
 

run_single_year.py

@@ -28,7 +28,7 @@
 solver = 'gurobi'
 
 # simulation timesteps
-(offset, length) = (0, 20)  # time step selection
+(offset, length) = (0, 8760)  # time step selection
 timesteps = range(offset, offset+length+1)
 dt = 1  # length of each time step (unit: hours)
 

runme.py

@@ -24,7 +24,7 @@
 solver = 'gurobi'
 
 # simulation timesteps
-(offset, length) = (3500, 24)  # time step selection
+(offset, length) = (0, 8760)  # time step selection
 timesteps = range(offset, offset+length+1)
 dt = 1  # length of each time step (unit: hours)
 

urbs-env.txt

@@ -0,0 +1,13 @@
+# Python venv
+numpy==1.26.4
+matplotlib==3.8.3
+pandas==2.2.1
+pandas-datareader==0.10.0
+tables==3.9.2 #pytables in conda
+openpyxl==3.1.2
+xlrd==2.0.1
+pyomo==6.7.1
+psutil==5.9.8
+pyutilib==6.0.0
+gurobipy
+highspy