2_installation_pypsaafrica.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Installation\n",
    "\n",
    "In this script we detail the main dependencies needed to install the software.\n",
    "In particular, the main software dependencies covered in this document are:\n",
    "\n",
    "1. [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/download.html): package management system to install, run and updates packages and their dependencies\n",
    "2. [Git](https://git-scm.com/): software to track changes in the code development and interact with github\n",
    "3. IDE Python: software to easily run and debug python code\n",
    "4. Solver [optional]: mathematical solver that solves the problem drawn by the workflow\n",
    "5. Clone the repository: clone the repository from github\n",
    "6. Environment setup: how to setup the environment to execute the PyPSA Africa software\n",
    "7. Download tutorial data: procedure to setup the initial data needed for the execution of the tutorial"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 1. conda\n",
    "\n",
    "PyPSA Africa can be easily installed by using the [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/download.html) management system.\n",
    "Conda enables to manage software package needed for the execution of the model.\n",
    "\n",
    "We recommend the installation of [miniconda](https://docs.conda.io/en/latest/miniconda.html) that is a minimal installer for conda: it provides conda, a base Python distribution needed to run conda and a small number of packages. Alternatively, [Anaconda](https://www.anaconda.com/products/individual) can also be used but it requires more resources.\n",
    "\n",
    "With conda it is possible to manage packages and easily reproduce the same package: this prevents problems due to package versions and incompatibilities"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 2. Git\n",
    "\n",
    "Git enables to easily interact with Github, please download and install the packages as follows.\n",
    "This description has been adapted from the [official link](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git).\n",
    "\n",
    "### 2.1. Linux users\n",
    "\n",
    "To install software on linux, a bash command can enable you to install the software.\n",
    "\n",
    "On Fedora-like distributions, please run the following code on bash:\n",
    "``` bash\n",
    "sudo dnf install git-all\n",
    "```\n",
    "\n",
    "On debian-based distribution, please use the following code:\n",
    "``` bash\n",
    "sudo apt install git-all\n",
    "```\n",
    "\n",
    "### 2.2. macOS users\n",
    "\n",
    "Mac users may have git already installed; please verify using the following command in bash:\n",
    "\n",
    "``` bash\n",
    "git --version\n",
    "```\n",
    "\n",
    "If fit is not installed, then a prompt will appear and follow the instructions to install the software.\n",
    "\n",
    "### 2.3. Windows users\n",
    "\n",
    "For windows users, you can download and install the software from the official website: [link](https://git-scm.com/download/win)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 3. IDE Python\n",
    "\n",
    "### 3.1. Install the IDE\n",
    "\n",
    "To ease the debugging and use of Python code, we suggest using an Integrated Development Environment (IDE), such as PyCharm, VSCode or alike.\n",
    "\n",
    "The PyPSA Africa team recommends [Visual Studio Code](https://code.visualstudio.com/); please visit the official website and dowload the software for your platform.\n",
    "\n",
    "Link: https://code.visualstudio.com/\n",
    "\n",
    "### 3.2. [VSCode specific] Install Python extension\n",
    "\n",
    "To successfully use Python in VSCode, please, add the Python extension as follows:\n",
    "\n",
    "1. Open VSCode\n",
    "2. Open the Extension folder on the left of the screen, as shown in the picture\n",
    "\n",
    "![Extension VSCode](./images/vscode_extension.png)\n",
    "\n",
    "3. Search for the python extension and make sure to have it installed.\n",
    "\n",
    "![Python extension](./images/python_extension.png)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 4. Solver [optional]\n",
    "\n",
    "To solve the mathematical model, a mathematical solver is needed.\n",
    "\n",
    "Well known solvers such as [Gurobi](https://www.gurobi.com/) or [CPLEX](https://www.ibm.com/it-it/analytics/cplex-optimizer) can be used, however they need a commercial license.\n",
    "The distribution that will be installed with conda includes an open-source distribution, thus there is no need to install additional solvers."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 5. Clone the Github repository\n",
    "\n",
    "Once all the software needs are installed, it is possible to proceed with cloning the repository from github.\n",
    "\n",
    "**Note**: in the following, a new folder named `pypsa-africa` will be added in the folder `path_without_spaces` desired by the user. Please, if you have already downloaded a copy of the repository pypsa-africa, make sure to rename the already installed folder, otherwise data will be overwritten.\n",
    "\n",
    "To do so, from bash, digit the following:\n",
    "\n",
    "``` bash\n",
    "cd path_without_spaces\n",
    "git clone https://github.com/pypsa-meets-africa/pypsa-africa-hackathon pypsa-africa\n",
    "```\n",
    "\n",
    "With the above call, the package for the hackaton will be downloaded in the directory `path_without_spaces`, chosen by the user.\n",
    "After this operation, the online github repository will be downloaded; please refer to the `architecture notebook` for details about the organization of the repository."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 6. Environment setup\n",
    "\n",
    "Before using the software, please install python, snakemake and all the python packages needed for the execution.\n",
    "This can be easily done through the conda manager tool by following the procedure described below:\n",
    "\n",
    "``` bash\n",
    "cd path_without_spaces/pypsa-africa\n",
    "conda env create -f envs/environment.yaml\n",
    "```\n",
    "\n",
    "With the first line, we make sure to be in the folder where the package downloaded before has been installed. The second line related to the conda command creates a new environment, named `pypsa-africa` where snakemake, python and all the python packages are installed.\n",
    "\n",
    "After this operation, the `pypsa-africa` environment shall be enabled before executing any PyPSA Africa model so that the correct dependencies are executed.\n",
    "The following code can be executed to activate the `pypsa-africa` environment:\n",
    "``` bash\n",
    "conda activate pypsa-africa\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## 7. Download data\n",
    "\n",
    "In order to successfully run the code, please follow the following procedure to execute preliminary operation with snakemake to properly prepare the data:\n",
    "\n",
    "1. Go into the main folder where the package is located: \n",
    "   ``` bash \n",
    "   cd some_path/pypsa-africa\n",
    "   ```\n",
    "2. Copy and paste the file `config.tutorial.yaml` and rename the new copy as `config.yaml`:\n",
    "   ``` bash \n",
    "   cp config.tutorial.yaml config.yaml\n",
    "   ```\n",
    "3. Open file `config.yaml` and make sure that the option `enable.retrieve_databundle` is set to true:\n",
    "\n",
    "   ![Verify retrieve_databundle set to true](./images/retrieve_true_verify.png)\n",
    "   <br>\n",
    "4. Activate pypsa-africa environment:\n",
    "   ``` bash \n",
    "   conda activate pypsa-africa\n",
    "   ```\n",
    "5. Execute the snakemake rule `retrieve_databundle_light` to download the initial data:\n",
    "   ``` bash \n",
    "   snakemake -j1 retrieve_databundle_light\n",
    "   ```\n",
    "6. [optional] Open file `config.yaml` and set the option `enable.retrieve_databundle` to false:\n",
    "\n",
    "   ![Set option retrieve_databundle to false](./images/retrieve_false_set.png)\n",
    "   <br>"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}