Merge pull request #918 from yerbol-akhmetov/improve_docs

Improvements of the documentation

doc/installation.rst

@@ -8,36 +8,93 @@
 Installation
 ##########################################
 
-The subsequently described installation steps are demonstrated as shell commands, where the path before the ``%`` sign denotes the directory in which the commands following the ``%`` should be entered.
+Before installing PyPSA-Earth on your computer, it's crucial to ensure that your system meets the necessary hardware and software requirements. The following sections outline the prerequisites in terms of hardware and software. Additionally, detailed installation guidelines for required software tools will be provided, followed by step-by-step instructions for installing PyPSA-Earth.
 
+Hardware Requirements
+=====================
+Ensure that your system meets the minimum hardware specifications to run PyPSA-Earth effectively. Recommended hardware specifications may include:
+
+* 8-16 GB RAM and adequate CPU (at-least 2-cores)
+
+* Storage (HDD/SSD) capacity depends on the region of interest. Africa model requires 40 GB, the world `--`` 250 GB, a single country `--` between 1-10 GB. Tutorial requires just below 2 GB. Thus, considering all required software tools, at least 40 GB of storage space is recommended.
+
+.. note::
+
+    The subsequently described installation steps are demonstrated as shell commands, where the path before the ``%`` sign denotes the directory in which the commands following the ``%`` should be entered.
+
+Software Prerequisites
+======================
+Prior to installing PyPSA-Earth, you'll need to ensure the following software tools are installed and configured on your system:
+
+* `Miniconda <https://docs.conda.io/projects/miniconda/en/latest/miniconda-install.html>`_
+* `Git <https://git-scm.com/downloads>`_
+* `VSCode <https://code.visualstudio.com/>`_ (or any other IDE)
+* `Java <https://www.oracle.com/java/technologies/downloads/>`_
+
+Miniconda
+---------
+To use packages in python, it is highly recommended to use a ``conda`` package manager, such as `miniconda <https://docs.conda.io/projects/miniconda/en/latest/>`__. You may check if ``conda`` is already installed on your system with
+
+.. code:: bash
+
+    conda --version
+
+If ``conda`` is not installed, follow `miniconda installation guide <https://docs.conda.io/projects/conda/en/latest/user-guide/install/>`_.
+For more on information on how to install conda and work with it you can look into :ref:`software_hints`.
+
+Git
+---
+`Git <https://git-scm.com/>`__ is a free open-source tool that facilitates tracking changes in the code development and enable to coordinate the parallel software development between many developers.
+Download and install ``git`` to your system using the following `link <https://git-scm.com/downloads>`__.
+It is highly recommended to `learn the git basics <https://git-scm.com/doc>`__.
+
+VSCode
+------
+In order to write and debug python code, you need an Integrated Development Environment (IDE) that is a software used to write code. We recommend `Visual Studio Code <https://code.visualstudio.com/>`_, which is freely available online and provides an easy-to-use interface with Git. Obviously, any alternatives like `PyCharm <https://www.jetbrains.com/pycharm/>`_ or `Sublime <https://www.sublimetext.com/>`_ will work as well.
+
+Java
+----
+PyPSA-Earth currently needs Java redistribution to work properly. To check if Java is still installed you can request it's version from a terminal:
+
+.. code:: bash
+
+    java --version
+
+The expected output should resemble the following:
+
+.. code:: bash
+
+    java version "1.8.0_341"
+    Java(TM) SE Runtime Environment (build 1.8.0_341-b10)
+    Java HotSpot(TM) 64-Bit Server VM (build 25.341-b10, mixed mode)
+
+In case you don't have Java, you have to install it from the `official website <https://www.oracle.com/java/technologies/downloads/>`_ or equivalent. Depending on the version of OS, download and install ``JDK 21`` or ``JDK 17`` from the link.
+
+
+PyPSA-Earth Installation
+========================
 
 Clone the Repository
-====================
+--------------------
 .. note::
 
-  In order to work with the provided Jupyter notebooks in the `documentation repository <https://github.com/pypsa-meets-earth/documentation>`_, it is recommended to follow the folder structure suggested in :ref:`notebooks`.
+  In order to work with the provided Jupyter notebooks in the `documentation repository <https://github.com/pypsa-meets-earth/documentation>`__, it is recommended to follow the folder structure suggested in :ref:`notebooks`.
 
-First of all, clone the `PyPSA-Earth repository <https://github.com/pypsa-meets-earth/pypsa-earth/>`_ using the version control system ``git``.
+First of all, clone the `PyPSA-Earth repository <https://github.com/pypsa-meets-earth/pypsa-earth/>`__ using the version control system ``git``.
 The path to the directory into which the ``git repository`` is cloned, must **not** have any spaces.
-If you do not have ``git`` installed, follow installation instructions `here <https://git-scm.com/book/en/v2/Getting-Started-Installing-Git>`_.
+The following commands can be executed in command prompt of ``miniconda``, terminal of ``VSCode``, or in ``Git Bash``.
 
 .. code:: bash
 
     /some/other/path % cd /some/path/without/spaces
 
     /some/path/without/spaces % git clone https://github.com/pypsa-meets-earth/pypsa-earth.git
 
-.. _deps:
-
 Install Dependencies
-===============================
-
-Python Dependencies
---------------------------------
-
+-------------------------
 PyPSA-Earth relies on a set of other Python packages to function.
 
-The python package requirements are curated in the `envs/environment.yaml <https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/envs/environment.yaml>`_ file. We install only `mamba` in the conda base environment to accelerate the installation.
+The python package requirements are located in the `envs/environment.yaml <https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/envs/environment.yaml>`_ file. We install only `mamba` in the conda base environment to accelerate the installation.
 **Please keep the base environment always clean, meaning don't install anything there!** It will allow to ensure compatibility of all the packages needed to work with PyPSA-Earth model.
 
 The environment can be installed and activated like this:
@@ -64,33 +121,15 @@ In case mamba did not work for you, you might want to try conda instead:
 
 For more on information on how to install conda and work with it you can look into :ref:`software_hints`.
 
-Java Installation
----------------------------------
-
-PyPSA-Earth currently needs Java redistribution to work properly. To check if Java is still installed you can request it's version from a terminal:
-
-  .. code:: bash
-
-    .../pypsa-earth % java --version
-
-The expected output should resemble the following:
-
-   .. code:: bash
-
-      java version "1.8.0_341"
-      Java(TM) SE Runtime Environment (build 1.8.0_341-b10)
-      Java HotSpot(TM) 64-Bit Server VM (build 25.341-b10, mixed mode)
-
-In case you don't have Java, you have to install it from the `official website <https://www.oracle.com/java/technologies/downloads/>`_ or equivalent. In Linux and Mac OS that is possible through the following command:
+To confirm the installation, run the following command in the activated environment:
 
 .. code:: bash
 
-    .../pypsa-earth (pypsa-earth) % conda install -c conda-forge openjdk
+    .../pypsa-earth (pypsa-earth) % snakemake --version
 
 
 Solver Installation
----------------------------------
-
+------------------
 An optimization solver is needed to solve the mathematical problem that is build with the automated workflow of PyPSA-Earth.
 With the goal of supporting completely open source initiative, we focus on relying on Open-Source solvers, such as
 
@@ -108,25 +147,19 @@ To further improve performances, commercial solvers like
 
 (both commercial licenses with free academic options) can also be used.
 
-A recommended instruction to install the HiGHS solver is given `here <https://github.com/PyPSA/PyPSA/blob/633669d3f940ea256fb0a2313c7a499cbe0122a5/pypsa/linopt.py#L608-L632>`_.
-
-Set Configuration File
-================================
-
-PyPSA-Earth has several configuration options that must be specified in a ``config.yaml`` file located in the project directory. An example configuration ``config.default.yaml`` is maintained in the repository. More details on the configuration options are in :ref:`config` section.
-
-Before first use, create a ``config.yaml`` by copying the example.
+.. note::
 
-.. code:: bash
+    No need to install ``glpk`` separately, as they are included in ``envs/environment.yaml`` and installed during ``conda`` environment creation.
+    However, solving capabilities of ``glpk`` are limited.
+    To run the model with high temporal and spatial resolution, it is recommended to use ``cplex``, ``gurobi``, or ``highs``.
 
-    .../pypsa-earth % cp config.default.yaml config.yaml
+A recommended instruction to install the HiGHS solver is given `here <https://github.com/PyPSA/PyPSA/blob/633669d3f940ea256fb0a2313c7a499cbe0122a5/pypsa/linopt.py#L608-L632>`_.
 
-It makes sense to regularly check their own ``config.yaml`` against changes in the ``config.default.yaml`` when pulling a new version from the remote repository.
 
 Install Jupyter Lab
 ================================
 
-We use Jupyter notebooks to share examples on how to use the model and analyse the results. VSCode supports working with Jupyter Notebooks natively. In case you are using different IDE and don't have Jupyter notebooks pre-installed you can install jupyter lab (new jupyter notebooks) with the `ipython kernel installation <http://echrislynch.com/2019/02/01/adding-an-environment-to-jupyter-notebooks/>`_ and test if your jupyter lab works:
+We use Jupyter notebooks to share examples on how to use the model and analyse the results. ``VSCode`` supports working with Jupyter Notebooks natively. In case you are using different IDE and don't have Jupyter notebooks pre-installed you can install jupyter lab (new jupyter notebooks) with the `ipython kernel installation <http://echrislynch.com/2019/02/01/adding-an-environment-to-jupyter-notebooks/>`_ and test if your jupyter lab works:
 
 .. code:: bash
 

doc/release_notes.rst

@@ -28,6 +28,8 @@ E.g. if a new rule becomes available describe how to use it `snakemake -j1 run_t
 
 * Revise databundles and improve logging in retrieve_databundle `PR #928 <https://github.com/pypsa-meets-earth/pypsa-earth/pull/928>`__
 
+* Improve documentation on installation and short tutorial `PR #918 <https://github.com/pypsa-meets-earth/pypsa-earth/pull/918>`__
+
 PyPSA-Earth 0.2.3
 =================
 

doc/short_tutorial.rst

@@ -6,24 +6,27 @@
 
 
 ##########################################
-Getting started
+Short tutorial
 ##########################################
 
 The installation procedure installs PyPSA-Earth model with all the software dependencies needed to build and run it.
-To properly model any region of the Earth, PyPSA-Earth needs to download and fetch different datasets.
-This section explains how to perform this data management.
+To properly model any region of the Earth, it is first crucial to get familiar with a tutorial where a simpler model is considered.
+This section explains how to run and analyze the tutorial model.
 
-How to build the tutorial model?
---------------------------------
+Build the tutorial model
+---------------------------
 
 The user can explore the majority of the model's functions on a local machine by running the tutorial, which uses fewer computational resources than the entire model does. A tutorial data kit was developed to facilitate exploring the model.
 You can build it using the tutorial configuration file `config.tutorial.yaml` (placed in the project folder `pypsa-earth`).
-To do that, you may want to do a reserve copy of your current configuration file and then overwrite it by a tutorial configuration:
+By default, PyPSA-Earth reads configuration parameters of simulation from `config.yaml` file located in `pypsa-earth` folder.
+Thus, to run the tutorial model, `config.tutorial.yaml` needs to be stored as `config.yaml`:
 
 .. code:: bash
 
     .../pypsa-earth (pypsa-earth) % cp config.tutorial.yaml config.yaml
 
+.. note::
+    You may want to do a reserve copy of your current configuration file (`config.yaml`) as it will be overwritten by a tutorial configuration.
 
 In the configuration file `config.yaml` there is a flag `retrieve_databundle` which triggers data loading and a `tutorial` flag which determines that the loaded data belong to the tutorial kit. Currently the tutorial can be run only for Nigeria ("NG"), Benin ("BJ"), Botswana ("BW") and Morocco ("MA").
 
@@ -37,7 +40,7 @@ In the configuration file `config.yaml` there is a flag `retrieve_databundle` wh
 It's recommended to set `retrieve_databundle: true` when building the model for the first time to download all needed common data files.
 When the first run is completed and all the necessary data are extracted, it may be a good idea to set `retrieve_databundle: false` to avoid data loss.
 
-How to run the model?
+Run the model
 ---------------------
 
 After configuration set-up, the model is ready to be built and run.
@@ -60,7 +63,7 @@ both `tutorial` and `retrieve_databundle` flags are on. The tutorial model will
 Note that data load will need about 1.6Gb and model building will take a while (about 20..50 minutes).
 
 
-How to analyse the solved networks?
+Analyse the solved networks
 ------------------------------------
 
 The solved networks can be analysed just like any other PyPSA network (e.g. in Jupyter Notebooks).
@@ -100,3 +103,5 @@ It is also possible to make manual clean-up removing folders "resources", "netwo
   This tutorial only covers Nigeria. To make the workflow run on other regions you need to use the ``config.default.yaml`` as ``config.yaml``.
   To use the model in and outside Africa, you should also read
   `How to create a model for you region of interest with PyPSA-Earth? <https://github.com/pypsa-meets-earth/pypsa-earth/discussions/505>`_
+
+:ref:`tutorial` section elaborates on building and running a full PyPSA-Earth model.

doc/tutorial.rst

@@ -6,7 +6,7 @@
 
 
 ##########################################
-Tutorial
+Full model
 ##########################################
 
 How to customise PyPSA-Earth?