From 259df9eb7b61753a718f1c3c0c373f70632c2d4f Mon Sep 17 00:00:00 2001 From: Lukas Riedel <34276446+peanutfun@users.noreply.github.com> Date: Mon, 6 Feb 2023 14:33:26 +0100 Subject: [PATCH 1/9] Add new installation guide --- doc/guide/install.rst | 443 ++++++++++++++++++++++++++++++++++++++++++ doc/index.rst | 3 +- 2 files changed, 444 insertions(+), 2 deletions(-) create mode 100644 doc/guide/install.rst diff --git a/doc/guide/install.rst b/doc/guide/install.rst new file mode 100644 index 000000000..4b7d80cd6 --- /dev/null +++ b/doc/guide/install.rst @@ -0,0 +1,443 @@ +============ +Installation +============ + +The following sections will guide you through the installation of CLIMADA and its dependencies. + +.. attention:: + + CLIMADA has a complicated set of dependencies that cannot be installed with ``pip`` alone. + Please make sure you follow the installation instructions carefully! + We recommend to use `Anaconda`_ for creating a suitable software environment to execute CLIMADA. + +All following instructions should work on any operating system (OS) that is supported by `Anaconda`_, including in particular: **Windows**, **macOS**, and **Linux**. + +.. note:: When mentioning the terms "terminal" or "command line" in the following, we are referring to the "Terminal" apps on macOS or Linux and the "Anaconda Prompt" on Windows. + +------------- +Prerequisites +------------- + +* Make sure you are using the **latest version** of your OS. Install any outstanding **updates**. +* Free up at least 10 GB of **free storage space** on your machine. + Anaconda and the CLIMADA dependencies will require around 5 GB of free space, and you will need at least that much additional space for storing the input and output data of CLIMADA. +* Ensure a **stable internet connection** for the installation procedure. + All dependencies will be downloaded from the internet. + Do **not** use a metered, mobile connection! +* Install `Anaconda`_, following the `installation instructions `_ for your OS. +* Create a workspace directory, ideally in subdirectory of your user/home directory. + Do **not** use a directory that is synchronized by cloud storage systems like OneDrive, iCloud or Polybox! + +.. hint:: If you need help with the vocabulary used on this page, refer to the :ref:`Glossary `. + +.. _install-choice: + +Decide on Your Entry Level! +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Depening on your level of expertise, we provide two different approaches: + +* If you have never worked with a command line, or if you just want to give CLIMADA a try, follow the :ref:`simple instructions `. +* If you want to use the very latest development version of CLIMADA or even develop new CLIMADA code, follow the :ref:`advanced instructions `. + If you want to install `CLIMADA Petals`_, also follow these. + +Both approaches are not mutually exclusive. +After successful installation, you may switch your setup at any time. + +.. _install-simple: + +------------------- +Simple Instructions +------------------- + +These instructions will install the most recent stable version of CLIMADA without cloning its repository. + +#. Download the Anaconda environment specifications for CLIMADA: :download:`env_climada.yml `. + You can also find it online in the `CLIMADA GitHub repository `_. + Move or copy the file into your workspace directory. +#. Open the command line and navigate to the workspace directory you created. + The command for entering a directory is ``cd``. + Use the following command, where you replace ```` with the actual path of the workspace folder: + + .. code-block:: shell + + cd + +#. Instruct Anaconda to create a new environment called ``climada_env`` from the specification file: + + .. code-block:: shell + + conda env create -n climada_env -f env_climada.yml + + This might take around 5 minutes, depending on your internet connection speed and computer hardware. + +#. Activate the environment: + + .. code-block:: shell + + conda activate climada_env + + You should now see ``(climada_env)`` appear in the beginning of your command prompt. + This means the environment is activated. + +#. Download and install the stable CLIMADA version using ``pip``: + + .. code-block:: shell + + python -m pip install climada + +#. Verify that everything is installed correctly by executing a single test: + + .. code-block:: shell + + python -m unittest climada.engine.test.test_impact + + Executing CLIMADA for the first time will take some time because it will generate a directory tree in your home/user directory. + After a while, some text should appear in your terminal. + In the end, you should see an "Ok". + If so, great! You are good to go. + +.. _install-advanced: + +--------------------- +Advanced Instructions +--------------------- + +For advanced Python users or developers of CLIMADA, we recommed cloning the CLIMADA repository and installing the package from source. + +#. Open the command line and navigate to the workspace directory you created using ``cd``. + Replace ```` with the path of the directory that contains the workspace folder: + + .. code-block:: shell + + cd + +#. Clone CLIMADA from its `GitHub repository `_. + Enter the directory and check out the branch of your choice. + The latest development version will be available under the branch ``develop``. + + .. code-block:: shell + + git clone https://github.com/CLIMADA-project/climada_python.git + cd climada_python + git checkout develop + +#. Create a Anaconda environment called ``climada_env`` for installing CLIMADA. + Use the default environment specs in ``env_climada.yml`` to create it, and update it with the ``env_developer.yml`` specs. + Then activate the environment: + + .. code-block:: shell + + conda env create -n climada_env -f requirements/env_climada.yml + conda env update -n climada_env -f requirements/env_developer.yml + conda activate climada_env + +#. Install the local CLIMADA source files as Python package using ``pip``: + + .. code-block:: shell + + python -m pip install -e ./ + + .. hint:: + + Using a path ``./`` (referring to the path you are currently located at) will instruct ``pip`` to install the local files instead of downloading the module from the internet. + The ``-e`` (for "editable") option further instructs ``pip`` to link to the source files instead of copying them during installation. + This means that any changes to the source files will have immediate effects in your environment, and re-installing the module is never required. + +#. Verify that everything is installed correctly by executing a single test: + + .. code-block:: shell + + python -m unittest climada.engine.test.test_impact + + Executing CLIMADA for the first time will take some time because it will generate a directory tree in your home/user directory. + If this test passes, great! + You are good to go. + +Install CLIMADA Petals (Optional) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +CLIMADA is divided into two repositories, CLIMADA Core (`climada_python `_) and CLIMADA Petals (`climada_petals `_). +The Core contains all the modules necessary for probabilistic impact, averted damage, uncertainty and forecast calculations. +Data for hazard, exposures and impact functions can be obtained from the `Data API `_. +Hazard and Exposures subclasses are included as demonstrators only. + +.. attention:: CLIMADA Petals is **not** a standalone module and requires CLIMADA Core to be installed! + +CLIMADA Petals contains all the modules for generating data (e.g., ``TC_Surge``, ``WildFire``, ``OpenStreeMap``, ...). +New modules are developed and tested here. +Some data created with modules from Petals is available to download from the :doc:`CLIMADA Data API `. +This works with just CLIMADA Core installed. +CLIMADA Petals can be used to generate additional data of this type, or to have a look at the tutorials for all data types available from the API. + +To install CLIMADA Petals, we assume you already have installed CLIMADA Core with the advanced instructions above. + +#. Open the command line and navigate to the workspace directory. +#. Clone CLIMADA Petals from its `GitHub repository `_. + Enter the directory and check out the branch of your choice. + The latest development version will be available under the branch ``develop``. + + .. code-block:: shell + + git clone https://github.com/CLIMADA-project/climada_petals.git + cd climada_petals + git checkout develop + +#. Update the Anaconda environment with the specifications from Petals and activate it: + + .. code-block:: shell + + conda env update -n climada_env -f requirements/env_climada.yml + conda env update -n climada_env -f requirements/env_developer.yml + conda activate climada_env + +#. Install the CLIMADA Petals package: + + .. code-block:: shell + + python -m pip install -e ./ + +------------------------------ +Apps for Programming in Python +------------------------------ + +To work with CLIMADA, you will need an application that supports Jupyter Notebooks. +There are plugins available for nearly every code editor or IDE, but if you are unsure about which to choose, we recommend `JupyterLab `_ or `Spyder `_. + +JupyterLab +^^^^^^^^^^ + +#. Install JupyterLab into the Anaconda environment: + + .. code-block:: shell + + conda install -n climada_env -c conda-forge jupyterlab + +#. Make sure that the ``climada_env`` is activated (see above) and then start JupyterLab: + + .. code-block:: shell + + conda env activate climada_env + jupyter-lab + + JupyterLab will open in a new window of your default browser. + +Spyder +^^^^^^ + +Installing Spyder into the existing Anaconda environment for CLIMADA might fail depending on the exact versions of dependencies installed. +Therefore, we recommend installing Spyder in a *separate* environment, and then connecting it to a kernel in the original ``climada_env``. + +#. Follow the `installation instructions `_ to install Spyder with ``conda``. + +#. Check the version of the Spyder kernel in the new environment: + + .. code-block:: shell + + conda env export -n spyder-env | grep spyder-kernels + + This will return a line like this: + + .. code-block:: shell + + - spyder-kernels=X.Y.Z= + + Copy the part ``spyder-kernels=X.Y.Z`` (until the second ``=``) and paste it into the following command to install the same kernel version into the ``climada_env``: + + .. code-block:: shell + + conda install -n climada_env spyder-kernels=X.Y.Z + +#. Obtain the path to the Python interpreter of your ``climada_env``. + Execute the following commands: + + .. code-block:: shell + + conda activate climada_env + python -c "import sys; print(sys.executable)" + + Copy the resulting path. + +#. Open Spyder. + You can do so from the Anaconda Navigator, or by activating the new environment and launching it through the command line: + + .. code-block:: shell + + conda activate spyder-env + spyder + +#. Set the Python interpreter used by Spyder to the one of ``climada_env``. + Select *Preferences* > *Python Interpreter* > *Use the following interpreter* and paste the iterpreter path you copied from the ``climada_env``. + +---- +FAQs +---- + +Answers to frequently asked questions. + +.. _install-more-packages: + +Installing More Packages +^^^^^^^^^^^^^^^^^^^^^^^^ + +You might use CLIMADA in code that requires more packages than the ones readily available in the CLIMADA Anaconda environment. +If so, **prefer installing these packages via Anaconda**, and only rely on ``pip`` if that fails. +The default channels of Anaconda sometimes contain outdated versions. +Therefore, use the ``conda-forge`` channel: + +.. code-block:: shell + + conda install -n climada_env -c conda-forge + +Only if the desired package (version) is not available, go for ``pip``: + +.. code-block:: shell + + conda activate climada_env + python -m pip install + +Verifying Your Installation +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you followed the installation instructions, you already executed a single unit test. +This test, however, will not cover all issues that could occur within your installation setup. +If you are unsure if everything works as intended, try running all unit tests. +This is only available for :ref:`advanced setups `! +Move into the CLIMADA repository, activate the environment and then execute the tests: + +.. code-block:: shell + + cd /climada_python + conda activate climada_env + python -m unittest -s climada/ -p "test*.py" + +Error: ``ModuleNotFoundError`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Something is wrong with the environment you are using. +After **each** of the following steps, check if the problem is solved, and only continue if it is **not**: + +#. Make sure you are working in the CLIMADA environment: + + .. code-block:: shell + + conda activate climada_env + +#. Update the environment using the specifications. + Replace ```` with the path to the specification file(s), depending on the :ref:`installation type ` you chose (see above). + + .. code-block:: shell + + conda update -n climada_env -f + +#. Anaconda will notify you if it is not up-to-date. + In this case, follow its instructions to update it. + +#. Install the missing package manually. + Follow the instructions for :ref:`installing more packages `. + +#. If you reached this point, something is severely broken. + Delete your CLIMADA environment and reinstall everything following one :ref:`instruction set `: + + .. code-block:: shell + + conda deactivate + conda env remove -n climada_env + +#. Still no good? + Please raise an `issue on GitHub `_ to get help. + +Changing the Logging Level +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +By default the logging level is set to ``INFO``, which is quite verbose. +You can change this setting in multiple ways: + +* Adjust the :doc:`configuration file ` ``climada.conf`` by setting a the value of the ``global.log_level`` property. + +* Set a global logging level in your Python script: + + .. code-block:: python + + from climada.util.config import LOGGER + from logging import WARNING + LOGGER.setLevel(WARNING) + +* Set a local logging level in a context manager: + + .. code-block:: python + + from climada.util import log_level + with log_level(level="WARNING"): + # Silenced code goes here + foo() + + # Default logging level again + bar() + +All of these approaches can also be combined. + +`Mamba `_ Instead of Anaconda +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you prefer using Mamba, you should be able to simply replace all ``conda`` commands with ``mamba``, **except** ``conda activate`` and ``conda deactivate``. +Note that we can only provide **limited support** for Mamba installations! + +Error: ``operation not permitted`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Conda might report a permission error on macOS Mojave. +Carefully follow these instructions: https://github.com/conda/conda/issues/8440#issuecomment-481167572 + +No ``impf_TC`` Column in ``GeoDataFrame`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This may happen when a demo file from CLIMADA was not updated after the change in the impact function naming pattern from ``if_`` to ``impf_`` when `CLIMADA v2.2.0 `_ was released. +Execute + +.. code-block:: shell + + conda activate climada_env + python -c "import climada; climada.setup_climada_data(reload=True)" + +.. _install-glossary: + +------------------------ +The What Now? (Glossary) +------------------------ + +You might have become confused about all the names thrown at you. +Let's clear that up: + +Terminal, Command Line + A text-only program for interacting with your computer (the old fashioned way). + +`Anaconda`_, conda + The program that installs all requirements and creates a suitable environment for CLIMADA. + +Environment (Programming) + A setup where only a specific set of modules and programs can interact. + This is especially useful if you want to install programs with incompatible requirements. + +`pip `_ + The Python package installer. + +`git `_ + A program for version controlling your software (or any text-based set of files). + +`GitHub `_ + A website that publicly hosts git repositories. + +git Repository + A collection of files and their entire revision/version history, managed by git. + +Cloning + The process and command (``git clone``) for downloading a git repository. + +IDE + Integrated Development Environment. + A fancy source code editor tailored for software development and engineering. + + +.. _Anaconda: https://www.anaconda.com/ +.. _CLIMADA Petals: https://climada-petals.readthedocs.io/en/latest/ diff --git a/doc/index.rst b/doc/index.rst index 6e090b03d..f36b74cf0 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -60,8 +60,7 @@ Jump right in: guide/Guide_Introduction Getting Started - guide/Guide_Installation - Very Easy Installation + Running CLIMADA on Euler From 7258aec96f93667b31b609e77b972ad6bb700ac1 Mon Sep 17 00:00:00 2001 From: Lukas Riedel <34276446+peanutfun@users.noreply.github.com> Date: Mon, 6 Feb 2023 14:34:02 +0100 Subject: [PATCH 2/9] Remove old installation guides --- doc/guide/Guide_Installation.ipynb | 336 ------------------ .../climada_installation_step_by_step.ipynb | 247 ------------- 2 files changed, 583 deletions(-) delete mode 100644 doc/guide/Guide_Installation.ipynb delete mode 100644 doc/tutorial/climada_installation_step_by_step.ipynb diff --git a/doc/guide/Guide_Installation.ipynb b/doc/guide/Guide_Installation.ipynb deleted file mode 100644 index e9619b370..000000000 --- a/doc/guide/Guide_Installation.ipynb +++ /dev/null @@ -1,336 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "8b2c1f7f", - "metadata": { - "tags": [] - }, - "source": [ - "# Installation\n", - "\n", - "This guide provides general installation instructions for users who are comfortable with the command line and knowledgeble about _git_, _pip_ and _conda_. For more detailed instructions see the [CLIMADA Installation Step by Step](../tutorial/climada_installation_step_by_step.ipynb) tutorial.\n", - "\n", - "Please execute the instructions of the following text boxes in a Terminal or Anaconda Prompt. Choose an installation directory, e.g., the user's home directory. In the following it will be referred to as `$[installation directory]`.\n", - "\n", - "It's highly recommanded to install CLIMADA into a [Conda](https://docs.conda.io/projects/conda/en/latest/) environment. Without Conda, the installation of the dependencies can be cumbersome. If it is not already installed, download the latest version of [Anaconda](https://www.anaconda.com/) or [Miniconda](https://conda.io/miniconda.html) and execute it.\n" - ] - }, - { - "cell_type": "markdown", - "id": "fe70ac23", - "metadata": { - "jp-MarkdownHeadingCollapsed": true, - "tags": [] - }, - "source": [ - "## Install CLIMADA from sources (for developers)\n", - "\n", - "### What does \"from sources\" mean?\n", - "\n", - "This method is usually used by developers, since it gives you the opportunity to modify the source code and install CLIMADA from any branch of climada_python, including the _develop_ branch where the latest changes are incorporated. If you are not sure whether this is the right option for you or if you are happy with the official CLIMADA releases, you're suggested to pick the method introduced in the section below: Install CLIMADA from PyPI (users). But if you need a particular branch or if you intend to change the code yourself, this is your choice.\n", - "\n", - "### What is Git/Github?\n", - "\n", - "Git is software for tracking changes in any set of files, usually used for coordinating work among programmers collaboratively developing source code during software development. GitHub is a provider of Internet hosting for software development and version control using Git. We will use Git commands here to download the project CLIMADA from GitHub.\n", - "\n", - "### Download the latest version\n", - "\n", - "```bash\n", - "cd $[installation directory]\n", - "\n", - "git clone https://github.com/CLIMADA-project/climada_python.git\n", - "cd climada_python\n", - "git checkout develop\n", - "cd ..\n", - "\n", - "```\n", - "\n", - "### Set up the environment\n", - "\n", - "Reminder: [Conda](https://docs.conda.io/projects/conda/en/latest/) must be installed.\n", - "\n", - "Open a command prompt (Windows) or shell (Mac, Linux) and run:\n", - "\n", - "```bash\n", - "conda env create -n climada_env -f climada_python/requirements/env_climada.yml\n", - "conda activate climada_env\n", - "```\n", - "\n", - "### Install the climada package\n", - "\n", - "Include the CLIMADA path into the Conda environment as follows:\n", - "\n", - "```bash\n", - "pip install -e climada_python\n", - "```\n", - "\n", - "With this setup, changes to CLIMADA's source code will immediately take effect. It removes the need to reinstall during development.\n", - "\n", - "\n", - "### Optional: Add developer packages\n", - "\n", - "If you want to develop new CLIMADA code, we recommend you also install the environment requirements for developers.\n", - "\n", - "```bash\n", - "conda env update -n climada_env -f climada_python/requirements/env_developer.yml\n", - "```" - ] - }, - { - "cell_type": "markdown", - "id": "e92c2983", - "metadata": { - "jp-MarkdownHeadingCollapsed": true, - "tags": [] - }, - "source": [ - "## Install CLIMADA from PyPI (for users)\n", - "\n", - "Published releases of CLIMADA (not CLIMADA-petals) can also be installed from the PyPI repository https://PyPI.org/project/climada/, since version 3.0.\n", - "\n", - "### What is PyPI/pip?\n", - "\n", - "The Python Package Index, abbreviated as PyPI is the official third-party software repository for Python. _pip_ is a package manager that is used to download and install packages directly from PyPI. \n", - "\n", - "### Download the environment specification file\n", - "\n", - "Download the environment specification file from the git repository and save it locally.\n", - "If you are using Linux, run:\n", - "\n", - "```bash\n", - "curl -o env_climada.yml https://raw.githubusercontent.com/CLIMADA-project/climada_python/main/requirements/env_climada.yml\n", - "```\n", - "\n", - "### Set up the environment\n", - "\n", - "Reminder: [Conda](https://docs.conda.io/projects/conda/en/latest/) must be installed.\n", - "\n", - "Create the conda environment:\n", - "\n", - "```bash\n", - "conda env create -n climada_env -f env_climada.yml\n", - "conda activate climada_env\n", - "```\n", - "\n", - "If this was successful, `env_climada.yml` can be safely deleted.\n", - "\n", - "### Install the climada package\n", - "\n", - "```bash\n", - "pip install climada\n", - "```" - ] - }, - { - "cell_type": "markdown", - "id": "15340754", - "metadata": {}, - "source": [ - "## Install CLIMADA-petals (optional)\n", - "\n", - "### Why is CLIMADA-petals optional? \n", - "CLIMADA is divided into two parts (two repositories):
\n", - "1. the core [climada_python](https://github.com/CLIMADA-project/climada_python) contains all the modules necessary for the probabilistic impact, the averted damage, uncertainty and forecast calculations.\n", - "Data for hazard, exposures and impact functions can be obtained from the [data API](https://github.com/CLIMADA-project/climada_python/blob/main/doc/tutorial/climada_util_api_client.ipynb).\n", - "[Litpop](https://github.com/CLIMADA-project/climada_python/blob/main/doc/tutorial/climada_entity_LitPop.ipynb) is included as _demo_ Exposures module, and\n", - "[Tropical cyclones](https://github.com/CLIMADA-project/climada_python/blob/main/doc/tutorial/climada_hazard_TropCyclone.ipynb) is included as a _demo_ Hazard module.
\n", - "2. CLIMADA-petals [climada_petals](https://github.com/CLIMADA-project/climada_petals) contains all the modules for generating data (e.g., TC_Surge, WildFire, OpenStreeMap, ...). Most development is done here.\n", - "CLIMDA-petals builds upon the core and does not work as stand-alone.
\n", - "You need the core to use CLIMDA-petals, but not the other way around. However, there is data created with CLIMADA-petals (e.g. RiverFlood or CropYield) available from the CLIMADA Data API. This data can be downloaded and\n", - "used directly with just the core installed. CLIMADA-petals is only required to generate additional data of this type. Nevertheless, users who want to calculate, e.g., RiverFlood impacts by core and API may still want to look into the\n", - "tutorial RiverFlood to understand how RiverFlood is calculated.\n", - "\n", - "### Download the latest version\n", - "\n", - "```bash\n", - "cd $[installation directory]\n", - "\n", - "git clone https://github.com/CLIMADA-project/climada_petals.git\n", - "cd climada_petals\n", - "git checkout develop\n", - "cd ..\n", - "\n", - "```\n", - "\n", - "### Update the environment\n", - "\n", - "It is possible that CLIMADA-petals has slightly different dependencies than CLIMADA-core, hence the conda environment should be updated.\n", - "\n", - "```bash\n", - "conda env update -n climada_env -f climada_petals/requirements/env_climada.yml\n", - "conda activate climada_env\n", - "```\n", - "\n", - "### Install the climada_petals package\n", - "\n", - "Include the CLIMADA-petals path into the Conda environment as follows:\n", - "\n", - "```bash\n", - "pip install -e climada_petals\n", - "```" - ] - }, - { - "cell_type": "markdown", - "id": "7bb61df2", - "metadata": {}, - "source": [ - "## Test the installation\n", - "\n", - "Run the following command:\n", - "\n", - "```bash\n", - "python -m unittest climada.engine.test.test_impact climada.engine.test.test_cost_benefit\n", - "```\n", - "\n", - "If the installation has been successful, an OK will appear at the end (the execution shouldn't last more than 2 min).\n", - "\n", - "\n", - "### Run tutorials\n", - "\n", - "In the *Home* section of Anaconda, with `climada_env` selected, install and launch `jupyter notebook`. A browser window will show up. Navigate to your ``climada_python`` repository and open ``doc/tutorial/1_main_CLIMADA.ipynb``. This is the tutorial which will guide you through all CLIMADA's functionalities. Execute each code cell to see the results, you might also edit the code cells before executing. See [tutorials](https://github.com/CLIMADA-project/climada_python/tree/main/doc/tutorial) for more information." - ] - }, - { - "cell_type": "markdown", - "id": "912a2d68", - "metadata": {}, - "source": [ - "## Working with _Spyder_\n", - "\n", - "It is possible to use climada in combination with the [Spyder-IDE](https://www.spyder-ide.org/). However, depending on OS, CLIMADA version, Spyder version and installation tool, installing `spyder` into the `climada_env` environment may fail. In particular, MacOS and `conda install spyder` don't work well together. Although there are cases where `pip install spyder` bears satisfactory results, it is suggested to install `spyder` in a separate Conda environment and run it with the python interpreter from the `climada_env` environment instead. To do so, follow these instructions:\n", - "\n", - "- Start Anaconda, create a new python_env environment (just click create and enter the name, then press Create) and install latest Spyder in there (currently 4.2.5). Start this version of Spyder. After Spyder has started, navigate to *Preferences > Python Interpreter > Use the following interpreter* and paste the output of the following terminal command into the text box:\n", - "\n", - "```bash\n", - "conda activate climada_env \n", - "python -c \"import sys; print(sys.executable)\" \n", - "# this returns a path, like /Users/XXX/opt/anaconda3/envs/climada_env/bin/python\n", - "```\n", - "\n", - "\n", - "- Obtain the version of the package `spyder-kernels` (currently 1.10.2) that has automatically been installed along with Spyder in the Anaconda environment and install the same version of `spyder-kernels` in the `climada_env` environment:\n", - "\n", - "```bash\n", - "conda activate climada_env \n", - "conda install spyder-kernels=1.10.2\n", - "```\n", - "\n", - "- Start a new IPython console in Spyder and run ``tests_install.py``." - ] - }, - { - "cell_type": "markdown", - "id": "064bac80", - "metadata": {}, - "source": [ - "## FAQs\n", - "\n", - "* **ModuleNotFoundError**\n", - " * the CLIMADA packages are not found. \\\n", - " Check whether the climada environment is activated. If not, activate it (`conda activate climada_env`). Otherwise, the installation has failed. Try and follow the installation instructions above.\n", - " * an external python library is not found. \\\n", - " It might happen that the pip dependencies of `env_climada.yml` (the ones specified after ``pip:``) have not been installed in the environment `climada_env`.\n", - " They can be installed manually one by one as follows:\n", - " ```bash\n", - " conda activate climada_env\n", - " pip install library_name\n", - " ```\n", - " where ``library_name`` is the missing library.\\\n", - " Another reason may be a recent update of the operating system (macOS). In this case removing and reinstalling Anaconda will be required.\n", - "\n", - "\n", - "* **Conda permission error**\\\n", - " (``operation not permitted``) in macOS Mojave: try the solutions suggested here [https://github.com/conda/conda/issues/8440](https://github.com/conda/conda/issues/8440)\n", - "\n", - "* **No 'impf\\_TC' column in GeoDataFrame**\\\n", - " This may happen when a demo file from CLIMADA was not updated after the change in the impact function naming pattern from 'if\\_' to 'impf\\_' ([climada v2.2.0](https://github.com/CLIMADA-project/climada_python/releases/tag/v2.2.0)).\\\n", - " To solve it, run `python -c 'import climada; climada.setup_climada_data(reload=True)` in a terminal.\n", - "\n", - "* **How to change the log level**\\\n", - " By default the logging level is set to ``'INFO'``, which is quite verbose. This can be changed\n", - "\n", - " * through configuration, by editing the config file `climada.conf` (see Guide_configuration.ipynb) and setting the value of the ``global.log_level`` property.\n", - " \n", - " * programmatically, globally, in a script or interactive python environment (Spyder, Jupyter, IPython) by executing e.g.,\n", - " ```python\n", - " from climada.util.config import LOGGER\n", - " from logging import WARNING\n", - " LOGGER.setLevel(WARNING)\n", - " ```\n", - " \n", - " * programmatically, context based, using `climada.util.log_level`:\n", - " ```python\n", - " from climada.util import log_level\n", - " with log_level(level='WARNING'):\n", - " quietly_do_something()\n", - " ```\n", - "\n", - "* **How to install climada_petals in a separate environment**\\\n", - " If you want to have a separate environment for CLIMADA-petals, proceed as described above but create a new environment instead of updating:\n", - " ```bash\n", - " conda env create -n petals_env -f climada_petals/requirements/env_climada.yml\n", - " conda activate petals_env\n", - " ```\n", - " and before running `pip install -e climada_petals` install the core package, either with the package from PyPi (`pip install climada`) or from local sources (`pip install -e climada_python`)" - ] - } - ], - "metadata": { - "hide_input": false, - "interpreter": { - "hash": "927c67ab198fcb661784b2c362c65b0d20aa8c2be2fb72d3ff0a6f4e04b047d1" - }, - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.8.12" - }, - "latex_envs": { - "LaTeX_envs_menu_present": true, - "autoclose": false, - "autocomplete": true, - "bibliofile": "biblio.bib", - "cite_by": "apalike", - "current_citInitial": 1, - "eqLabelWithNumbers": true, - "eqNumInitial": 1, - "hotkeys": { - "equation": "Ctrl-E", - "itemize": "Ctrl-I" - }, - "labels_anchors": false, - "latex_user_defs": false, - "report_style_numbering": false, - "user_envs_cfg": false - }, - "toc": { - "base_numbering": 1, - "nav_menu": {}, - "number_sections": true, - "sideBar": true, - "skip_h1_title": false, - "title_cell": "Table of Contents", - "title_sidebar": "Contents", - "toc_cell": false, - "toc_position": {}, - "toc_section_display": true, - "toc_window_display": false - } - }, - "nbformat": 4, - "nbformat_minor": 5 -} diff --git a/doc/tutorial/climada_installation_step_by_step.ipynb b/doc/tutorial/climada_installation_step_by_step.ipynb deleted file mode 100644 index d057f1583..000000000 --- a/doc/tutorial/climada_installation_step_by_step.ipynb +++ /dev/null @@ -1,247 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "id": "cc8580cc-24a4-474f-9aca-727c7d0f07e6", - "metadata": {}, - "source": [ - "# CLIMADA Installation Step by Step" - ] - }, - { - "cell_type": "markdown", - "id": "e24eb4c0-6846-4227-b18e-dab38a072002", - "metadata": {}, - "source": [ - "## System Requirements\n", - "\n", - "- __OS__: Linux, macOS, Windows" - ] - }, - { - "cell_type": "markdown", - "id": "2afee592-c5ee-4750-a5e9-487790a40c86", - "metadata": {}, - "source": [ - "## Prerequisites\n", - "\n", - "- [Conda](https://docs.conda.io/en/latest/)\\\n", - " For the installation you will need the _Conda_ package manager. If it is not yet installed, please download the latest version of Anaconda and execute it.\\\n", - " On Windows you will have to restart your computer after installing Anaconda." - ] - }, - { - "cell_type": "markdown", - "id": "7240943d-6e5f-42d4-9817-7a16c16e8682", - "metadata": {}, - "source": [ - "## Instructions\n", - "\n", - "- Make a folder `climada_workspace` where you will save all your results.\\\n", - "The folder shouldn't be on a Cloud drive, like OneDrive, ICloud or PolyBox, as this may cause synchronization problems." - ] - }, - { - "cell_type": "markdown", - "id": "641548e8-a1ea-4b12-9c0c-aae33d13753b", - "metadata": {}, - "source": [ - "- Open a ‘command line’ or ‘terminal’ or ‘anaconda prompt’ and navigate to the folder climada_workspace.\\\n", - "Please get familiar with the ’anaconda prompt (all), the ‘command line’ (windows) or ‘terminal’ (linux, MacOs). Several resources are available online.\\\n", - "Below ‘terminal’ and ‘command line’ and ‘anaconda prompt’ will be used interchangeably.\\\n", - "To navigate use `cd` (replace `path/to` with the actual path to the directory you have created):" - ] - }, - { - "cell_type": "code", - "execution_count": 1, - "id": "74d80546-3e1a-4a59-8630-183d830b9c01", - "metadata": {}, - "outputs": [], - "source": [ - "cd path/to/climada_workspace" - ] - }, - { - "cell_type": "markdown", - "id": "129b2b0c-380b-4888-867b-ab4ccbda28cc", - "metadata": {}, - "source": [ - "- Download the [_Conda_ environment specifications for CLIMADA](https://github.com/CLIMADA-project/climada_python/blob/main/requirements/env_climada.yml) from the GitHub repository. This can be done using the command below. In case this fails, you can alternatively do it manually, by clicking on the link above, then on [Raw] and then saving the page that opens as env_climada.yml into the `climada_workspace` folder." - ] - }, - { - "cell_type": "code", - "execution_count": 2, - "id": "bfd21d97-0033-4ea1-b15b-e569a719b521", - "metadata": {}, - "outputs": [], - "source": [ - "curl -o env_climada.yml https://raw.githubusercontent.com/CLIMADA-project/climada_python/main/requirements/env_climada.yml" - ] - }, - { - "cell_type": "markdown", - "id": "c6defb2d-5bba-47d3-8941-9596d8b951f3", - "metadata": {}, - "source": [ - "- Create the _Conda_ environment" - ] - }, - { - "cell_type": "code", - "execution_count": 3, - "id": "40eaaa81-df04-4d12-9dd1-04e1cdf76358", - "metadata": {}, - "outputs": [], - "source": [ - "conda env create -n climada_env -f env_climada.yml" - ] - }, - { - "cell_type": "markdown", - "id": "1f6e4171-a5b5-47a2-8ebf-5616e7e90751", - "metadata": {}, - "source": [ - "> Executing this command will take a while, expect 4 minutes or so." - ] - }, - { - "cell_type": "markdown", - "id": "37f6d11f-1ecf-473d-953a-81299b30ed6b", - "metadata": {}, - "source": [ - "- Activate the environment" - ] - }, - { - "cell_type": "code", - "execution_count": 4, - "id": "e781315f-55f4-4c7d-84c1-45b55cb4d070", - "metadata": {}, - "outputs": [], - "source": [ - "conda activate climada_env" - ] - }, - { - "cell_type": "markdown", - "id": "f72749ed-338e-4c4b-abdd-253a2645f203", - "metadata": {}, - "source": [ - "- Install CLIMADA within the environment" - ] - }, - { - "cell_type": "code", - "execution_count": 5, - "id": "892745a9-a0ca-448a-9522-48b9b6204cc5", - "metadata": {}, - "outputs": [], - "source": [ - "pip install climada" - ] - }, - { - "cell_type": "markdown", - "id": "4dc0da96-a4cf-4c12-b115-a790e5eac4b1", - "metadata": {}, - "source": [ - "- Test the installation" - ] - }, - { - "cell_type": "code", - "execution_count": 6, - "id": "f9098259-b041-4f5b-9d37-b110b325d987", - "metadata": {}, - "outputs": [], - "source": [ - "python -m unittest climada.engine.test.test_impact" - ] - }, - { - "cell_type": "markdown", - "id": "c7c97771-c628-41fc-9e3a-890376b1774f", - "metadata": {}, - "source": [ - "> Note that at first it seems like nothing happens. At the beginning of the test some files are moved around in your local filesystem, which can take some time.\\\n", - "You will notice a `climada` folder in your home directory once the test has run - or after any python program executing `import climada` somewhere.\\\n", - "This directory contains data files that are used by climada and cached on the local file system for performance reasons. (See the [Configuration Guide](https://climada-python.readthedocs.io/en/latest/guide/Guide_Configuration.html) for further options.)\\\n", - "Later on, some text will appear. If all goes well, you should see an “Ok” at the end. \n", - "\n", - "Great, now you are ready for some climate risk modelling!" - ] - }, - { - "cell_type": "markdown", - "id": "3e37700c-ed32-44b8-9fc7-4ab6a3c90e0b", - "metadata": {}, - "source": [ - "## Jupyter\n", - "To work with CLIMADA, we recommend that you work in a Jupyter Notebook in Jupyter Lab.\\\n", - "Please install jupyter lab executing the following command line:" - ] - }, - { - "cell_type": "code", - "execution_count": 7, - "id": "bb29d294-2774-4fcb-9b44-878c5076c89c", - "metadata": {}, - "outputs": [], - "source": [ - "conda activate climada_env\n", - "pip install jupyterlab" - ] - }, - { - "cell_type": "markdown", - "id": "5f70a3a8-5b93-4abc-ae8e-483c02f377e5", - "metadata": {}, - "source": [ - "Before starting a notebook, make sure to be in the conda environment climada_env. Here are the commands you should execute in your terminal.\\\n", - "The first line activates the environment and the second will open a Jupyer Lab console in your default web browser." - ] - }, - { - "cell_type": "code", - "execution_count": 8, - "id": "dd09a287-87b0-411f-a32b-2ced4c858b12", - "metadata": {}, - "outputs": [], - "source": [ - "conda activate climada_env\n", - "jupyter-lab" - ] - }, - { - "cell_type": "markdown", - "id": "07741ad9-6551-403c-a651-0e9b414e82eb", - "metadata": {}, - "source": [ - "Once launched, you can create a new jupyter notebook or continue working with one you have already created." - ] - } - ], - "metadata": { - "kernelspec": { - "display_name": "Python 3 (ipykernel)", - "language": "python", - "name": "python3" - }, - "language_info": { - "codemirror_mode": { - "name": "ipython", - "version": 3 - }, - "file_extension": ".py", - "mimetype": "text/x-python", - "name": "python", - "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", - "version": "3.8.12" - } - }, - "nbformat": 4, - "nbformat_minor": 5 -} From e1fccf3093eba78420d42c4883af3853e6767b6a Mon Sep 17 00:00:00 2001 From: Lukas Riedel <34276446+peanutfun@users.noreply.github.com> Date: Mon, 6 Feb 2023 14:56:58 +0100 Subject: [PATCH 3/9] Fix links to install instructions and update FAQs --- CONTRIBUTING.md | 23 +++++++--------- README.md | 2 +- doc/README.md | 2 +- doc/guide/Guide_Git_Development.ipynb | 3 ++- doc/guide/Guide_get_started.ipynb | 14 +++++++--- doc/guide/install.rst | 38 ++++++++++++++++++++++++++- doc/index.rst | 4 +-- doc/tutorial/1_main_climada.ipynb | 9 ++++--- 8 files changed, 67 insertions(+), 28 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b5dff9ba6..2f3b1722f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -8,27 +8,22 @@ Before you start, please have a look at our [Developer Guide][devguide]. To contribute follow these steps: -1. Install CLIMADA following the [installation instructions for developers](https://climada-python.readthedocs.io/en/stable/guide/Guide_Installation.html#Install-CLIMADA-from-sources-(for-developers)). -2. Additionally, install the packages for developers: - - ``` - $ conda update -n climada_env -f climada_python/requirements/env_developer.yml - ``` -3. In the CLIMADA repository, create a new feature branch from the latest `develop` branch: +1. Install CLIMADA following the [installation instructions for developers](https://climada-python.readthedocs.io/en/latest/guide/install.html#advanced-instructions). +2. In the CLIMADA repository, create a new feature branch from the latest `develop` branch: ``` $ git checkout develop && git pull $ git checkout -b feature/my-fancy-branch ``` -4. Implement your changes and commit them with [meaningful and well formatted](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) commit messages. -5. Add [unit and integration tests][testing] to your code, if applicable. -6. Use [Pylint](https://pypi.org/project/pylint/) for a static code analysis of your code with CLIMADA's configuration `.pylintrc`: +3. Implement your changes and commit them with [meaningful and well formatted](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) commit messages. +4. Add [unit and integration tests][testing] to your code, if applicable. +5. Use [Pylint](https://pypi.org/project/pylint/) for a static code analysis of your code with CLIMADA's configuration `.pylintrc`: ``` $ pylint ``` -7. Add your name to the [AUTHORS](/AUTHORS) file. -8. Push your updates to the remote repository: +6. Add your name to the [AUTHORS](/AUTHORS) file. +7. Push your updates to the remote repository: ``` $ git push --set-upstream origin feature/my-fancy-branch @@ -44,11 +39,11 @@ To contribute follow these steps: $ git push --set-upstream fork feature/my-fancy-branch ``` -9. On the [CLIMADA-project/climada_python](https://github.com/CLIMADA-project/climada_python) GitHub repository, create a new pull request with target branch `develop`. +8. On the [CLIMADA-project/climada_python](https://github.com/CLIMADA-project/climada_python) GitHub repository, create a new pull request with target branch `develop`. This also works if you pushed to a fork instead of the main repository. Add a description and explanation of your changes and work through the pull request author checklist provided. Feel free to request reviews from specific team members. -10. After approval of the pull request, the branch is merged into `develop` and your changes will become part of the next CLIMADA release. +9. After approval of the pull request, the branch is merged into `develop` and your changes will become part of the next CLIMADA release. ## Resources diff --git a/README.md b/README.md index cdf06ccd5..46d6f1984 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ This is the Python (3.8+) version of CLIMADA - please see https://github.com/dav ## Getting started -CLIMADA runs on Windows, macOS and Linux. It can be installed from sources or - in case of climada_python - directly with pip. See the [installation guide](https://climada-python.readthedocs.io/en/latest/guide/Guide_Installation.html) for instructions. +CLIMADA runs on Windows, macOS and Linux. It can be installed from sources or - in case of climada_python - directly with pip. See the [installation guide](https://climada-python.readthedocs.io/en/latest/guide/install.html) for instructions. Follow the [tutorial](https://climada-python.readthedocs.io/en/latest/tutorial/1_main_climada.html) `climada_python-x.y.z/doc/tutorial/1_main_climada.ipynb` in a Jupyter Notebook to see what can be done with CLIMADA and how. diff --git a/doc/README.md b/doc/README.md index f502a1b8c..0cddae25f 100644 --- a/doc/README.md +++ b/doc/README.md @@ -15,7 +15,7 @@ You can switch to `latest`, which refers to the latest version of the `develop` You can also build and browse the documentation on your machine. This can be useful if you want to access the documentation of a particular feature branch or to check your updates to the documentation. -For building the documentation, you need to follow the [installation instructions for developers](https://climada-python.readthedocs.io/en/latest/guide/Guide_Installation.html#Install-CLIMADA-from-sources-(for-developers)). +For building the documentation, you need to follow the [advanced installation instructions](https://climada-python.readthedocs.io/en/latest/guide/install.html#advanced-instructions). Make sure to install the developer requirements as well. Then, activate the `climada_env` and navigate to the `doc` directory: diff --git a/doc/guide/Guide_Git_Development.ipynb b/doc/guide/Guide_Git_Development.ipynb index f0657321d..92b3bb237 100644 --- a/doc/guide/Guide_Git_Development.ipynb +++ b/doc/guide/Guide_Git_Development.ipynb @@ -271,6 +271,7 @@ ] }, { + "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ @@ -290,7 +291,7 @@ " git clone https://github.com/CLIMADA-project/climada_python.git\n", "```\n", "2. **Install the packages** in ``climada_python/requirements/env_climada.yml`` and\n", - " ``climada_python/requirements/env_developer.yml`` (see [install](../guide/Guide_Installation.ipynb)). You\n", + " ``climada_python/requirements/env_developer.yml`` (see [Installation](install.rst)). You\n", " might need to install additional environments contained in ``climada_python/requirements``\n", " when using specific functionalities.\n" ] diff --git a/doc/guide/Guide_get_started.ipynb b/doc/guide/Guide_get_started.ipynb index 6274014b4..0d03250b5 100644 --- a/doc/guide/Guide_get_started.ipynb +++ b/doc/guide/Guide_get_started.ipynb @@ -18,6 +18,7 @@ ] }, { + "attachments": {}, "cell_type": "markdown", "id": "israeli-street", "metadata": {}, @@ -27,9 +28,9 @@ "1. To get the lastest release from the git repository [CLIMADA releases](https://github.com/climada-project/climada_python/releases) or clone the project with git if you are interested in contributing to the development.\n", "2. To build a conda environment with the dependencies needed by CLIMADA. \n", "\n", - "For details see the [Installation Guide](../guide/Guide_Installation.ipynb).\n", + "For details see the [Installation Instructions](install.rst).\n", "\n", - "If you need to run a model on a computational cluster, have a look at [this guide](../guide/Guide_Euler.ipynb) to install CLIMADA and run your jobs." + "If you need to run a model on a computational cluster, have a look at [this guide](Guide_Euler.ipynb) to install CLIMADA and run your jobs." ] }, { @@ -82,7 +83,7 @@ ], "metadata": { "kernelspec": { - "display_name": "Python 3 (ipykernel)", + "display_name": "climada_env", "language": "python", "name": "python3" }, @@ -96,7 +97,12 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.8.12" + "version": "3.8.15 | packaged by conda-forge | (default, Nov 22 2022, 08:49:06) \n[Clang 14.0.6 ]" + }, + "vscode": { + "interpreter": { + "hash": "fe76ddefd4ac3b756bca82b2809865e7c67c346a46477cb9eec4ead581742ab6" + } } }, "nbformat": 4, diff --git a/doc/guide/install.rst b/doc/guide/install.rst index 4b7d80cd6..f59da9810 100644 --- a/doc/guide/install.rst +++ b/doc/guide/install.rst @@ -170,7 +170,7 @@ Some data created with modules from Petals is available to download from the :do This works with just CLIMADA Core installed. CLIMADA Petals can be used to generate additional data of this type, or to have a look at the tutorials for all data types available from the API. -To install CLIMADA Petals, we assume you already have installed CLIMADA Core with the advanced instructions above. +To install CLIMADA Petals, we assume you have already installed CLIMADA Core with the :ref:`advanced instructions ` above. #. Open the command line and navigate to the workspace directory. #. Clone CLIMADA Petals from its `GitHub repository `_. @@ -275,6 +275,42 @@ FAQs Answers to frequently asked questions. +Updating CLIMADA +^^^^^^^^^^^^^^^^ + +We recommend keeping CLIMADA up-to-date. +To update, follow the instructions based on your :ref:`installation type `: + +* **Simple Instructions:** Activate the environment and update CLIMADA using ``pip``: + + .. code-block:: shell + + conda activate climada_env + python -m pip install -U climada + + Then, download the latest environment specifications: :download:`env_climada.yml `. + Use them to update the existing environment: + + .. code-block:: shell + + conda env update -n climada_env -f env_climada.yml + +* **Advanced Instructions:** Move into your local CLIMADA repository and pull the latest version of your respective branch: + + .. code-block:: shell + + cd /climada_python + git pull + + Then, update the environment: + + .. code-block:: shell + + conda env update -n climada_env -f requirements/env_climada.yml + conda env update -n climada_env -f requirements/env_developer.yml + + The same instructions apply for CLIMADA Petals. + .. _install-more-packages: Installing More Packages diff --git a/doc/index.rst b/doc/index.rst index f36b74cf0..1e3252104 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -16,7 +16,7 @@ Jump right in: * :doc:`README ` * :doc:`Getting Started ` -* :doc:`Installation ` +* :doc:`Installation ` * :doc:`Overview ` * `GitHub Repository `_ * :doc:`Module Reference ` @@ -60,7 +60,7 @@ Jump right in: guide/Guide_Introduction Getting Started - + guide/install Running CLIMADA on Euler diff --git a/doc/tutorial/1_main_climada.ipynb b/doc/tutorial/1_main_climada.ipynb index b9555a425..6a0948241 100644 --- a/doc/tutorial/1_main_climada.ipynb +++ b/doc/tutorial/1_main_climada.ipynb @@ -31,6 +31,7 @@ ] }, { + "attachments": {}, "cell_type": "markdown", "metadata": {}, "source": [ @@ -53,7 +54,7 @@ "\n", "### Resources beyond this tutorial\n", "\n", - "- [Installation guide](../guide/Guide_Installation.ipynb) - go here if you've not installed the model yet\n", + "- [Installation guide](/guide/install.rst) - go here if you've not installed the model yet\n", "- [CLIMADA Read the Docs home page](https://climada-python.readthedocs.io) - for all other documentation\n", "- [List of CLIMADA's features and associated tutorials](#CLIMADA-features)\n", "- [CLIMADA GitHub develop branch documentation](https://github.com/CLIMADA-project/climada_python/tree/develop/doc) for the very latest versions of code and documentation\n", @@ -1260,7 +1261,7 @@ "metadata": { "hide_input": false, "kernelspec": { - "display_name": "Python 3.8.13 ('climada_env')", + "display_name": "climada_env", "language": "python", "name": "python3" }, @@ -1274,11 +1275,11 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.8.13" + "version": "3.8.15 | packaged by conda-forge | (default, Nov 22 2022, 08:49:06) \n[Clang 14.0.6 ]" }, "vscode": { "interpreter": { - "hash": "0d8f20e4ce91d520e7feec912e0986dcdc154072031c954af0101af347b335d9" + "hash": "fe76ddefd4ac3b756bca82b2809865e7c67c346a46477cb9eec4ead581742ab6" } } }, From 10aa39a1f044c7eb1eb2f0c809bfe6bebcd838d2 Mon Sep 17 00:00:00 2001 From: Lukas Riedel <34276446+peanutfun@users.noreply.github.com> Date: Mon, 6 Feb 2023 15:45:52 +0100 Subject: [PATCH 4/9] Update CHANGELOG.md --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index c665ae3cd..d7101fc9e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -58,6 +58,7 @@ updated: [#620](https://github.com/CLIMADA-project/climada_python/pull/620) [#615](https://github.com/CLIMADA-project/climada_python/pull/615) [#617](https://github.com/CLIMADA-project/climada_python/pull/617) +- Updated installation instructions [#644](https://github.com/CLIMADA-project/climada_python/pull/644) ### Fixed From 11c734f996c1d1e902bfe8acbe48ec43d0a31d92 Mon Sep 17 00:00:00 2001 From: Lukas Riedel <34276446+peanutfun@users.noreply.github.com> Date: Mon, 6 Feb 2023 18:00:15 +0100 Subject: [PATCH 5/9] Tweak install instructions --- doc/guide/install.rst | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/doc/guide/install.rst b/doc/guide/install.rst index f59da9810..ed7b74e8f 100644 --- a/doc/guide/install.rst +++ b/doc/guide/install.rst @@ -7,7 +7,7 @@ The following sections will guide you through the installation of CLIMADA and it .. attention:: CLIMADA has a complicated set of dependencies that cannot be installed with ``pip`` alone. - Please make sure you follow the installation instructions carefully! + Please follow the installation instructions carefully! We recommend to use `Anaconda`_ for creating a suitable software environment to execute CLIMADA. All following instructions should work on any operating system (OS) that is supported by `Anaconda`_, including in particular: **Windows**, **macOS**, and **Linux**. @@ -25,7 +25,7 @@ Prerequisites All dependencies will be downloaded from the internet. Do **not** use a metered, mobile connection! * Install `Anaconda`_, following the `installation instructions `_ for your OS. -* Create a workspace directory, ideally in subdirectory of your user/home directory. +* Create a **workspace directory**, ideally in subdirectory of your user/home directory. Do **not** use a directory that is synchronized by cloud storage systems like OneDrive, iCloud or Polybox! .. hint:: If you need help with the vocabulary used on this page, refer to the :ref:`Glossary `. @@ -159,14 +159,14 @@ Install CLIMADA Petals (Optional) CLIMADA is divided into two repositories, CLIMADA Core (`climada_python `_) and CLIMADA Petals (`climada_petals `_). The Core contains all the modules necessary for probabilistic impact, averted damage, uncertainty and forecast calculations. -Data for hazard, exposures and impact functions can be obtained from the `Data API `_. +Data for hazard, exposures and impact functions can be obtained from the :doc:`CLIMADA Data API `. Hazard and Exposures subclasses are included as demonstrators only. .. attention:: CLIMADA Petals is **not** a standalone module and requires CLIMADA Core to be installed! CLIMADA Petals contains all the modules for generating data (e.g., ``TC_Surge``, ``WildFire``, ``OpenStreeMap``, ...). New modules are developed and tested here. -Some data created with modules from Petals is available to download from the :doc:`CLIMADA Data API `. +Some data created with modules from Petals is available to download from the :doc:`Data API `. This works with just CLIMADA Core installed. CLIMADA Petals can be used to generate additional data of this type, or to have a look at the tutorials for all data types available from the API. @@ -373,13 +373,15 @@ After **each** of the following steps, check if the problem is solved, and only Follow the instructions for :ref:`installing more packages `. #. If you reached this point, something is severely broken. - Delete your CLIMADA environment and reinstall everything following one :ref:`instruction set `: + The last course of action is to delete your CLIMADA environment: .. code-block:: shell conda deactivate conda env remove -n climada_env + Now repeat the :ref:`installation process `. + #. Still no good? Please raise an `issue on GitHub `_ to get help. From cd8e3a0c87d41e4579ad808f07d8f5387ba7cd96 Mon Sep 17 00:00:00 2001 From: Lukas Riedel <34276446+peanutfun@users.noreply.github.com> Date: Wed, 15 Feb 2023 17:59:13 +0100 Subject: [PATCH 6/9] Apply suggestions from code review Co-authored-by: Emanuel Schmid <51439563+emanuel-schmid@users.noreply.github.com> --- doc/guide/install.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/guide/install.rst b/doc/guide/install.rst index ed7b74e8f..9240dcdbc 100644 --- a/doc/guide/install.rst +++ b/doc/guide/install.rst @@ -122,7 +122,7 @@ For advanced Python users or developers of CLIMADA, we recommed cloning the CLIM cd climada_python git checkout develop -#. Create a Anaconda environment called ``climada_env`` for installing CLIMADA. +#. Create an Anaconda environment called ``climada_env`` for installing CLIMADA. Use the default environment specs in ``env_climada.yml`` to create it, and update it with the ``env_developer.yml`` specs. Then activate the environment: @@ -455,13 +455,13 @@ Terminal, Command Line Environment (Programming) A setup where only a specific set of modules and programs can interact. - This is especially useful if you want to install programs with incompatible requirements. + This is especially useful if you want to install programs with mutually incompatible requirements. `pip `_ The Python package installer. `git `_ - A program for version controlling your software (or any text-based set of files). + A popular version control software for programming code (or any text-based set of files). `GitHub `_ A website that publicly hosts git repositories. From 4f3824e5ed612df4317aa3e46fd4675b576a4219 Mon Sep 17 00:00:00 2001 From: Lukas Riedel <34276446+peanutfun@users.noreply.github.com> Date: Wed, 15 Feb 2023 18:11:57 +0100 Subject: [PATCH 7/9] Use curl to download conda environment specs --- doc/guide/install.rst | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/doc/guide/install.rst b/doc/guide/install.rst index 9240dcdbc..b5daf2ab6 100644 --- a/doc/guide/install.rst +++ b/doc/guide/install.rst @@ -27,6 +27,15 @@ Prerequisites * Install `Anaconda`_, following the `installation instructions `_ for your OS. * Create a **workspace directory**, ideally in subdirectory of your user/home directory. Do **not** use a directory that is synchronized by cloud storage systems like OneDrive, iCloud or Polybox! +* **Linux** users need to make sure they have ``git`` and ``curl`` installed. + Ubuntu and Debian users may use APT: + + .. code-block:: shell + + apt update + apt install curl git + + Both commands will probably require administrator rights, which can be enabled by prepending ``sudo``. .. hint:: If you need help with the vocabulary used on this page, refer to the :ref:`Glossary `. @@ -52,9 +61,6 @@ Simple Instructions These instructions will install the most recent stable version of CLIMADA without cloning its repository. -#. Download the Anaconda environment specifications for CLIMADA: :download:`env_climada.yml `. - You can also find it online in the `CLIMADA GitHub repository `_. - Move or copy the file into your workspace directory. #. Open the command line and navigate to the workspace directory you created. The command for entering a directory is ``cd``. Use the following command, where you replace ```` with the actual path of the workspace folder: @@ -63,6 +69,14 @@ These instructions will install the most recent stable version of CLIMADA withou cd +#. Download the Anaconda environment specifications for CLIMADA using ``curl``: + + .. code-block:: shell + + curl -o env_climada.yml https://raw.githubusercontent.com/CLIMADA-project/climada_python/main/requirements/env_climada.yml + + Alternatively, download the file through your browser and place it in the workspace directory: :download:`env_climada.yml ` + #. Instruct Anaconda to create a new environment called ``climada_env`` from the specification file: .. code-block:: shell From 616746de069568d597bf798662b13fa4ba28bc6d Mon Sep 17 00:00:00 2001 From: Lukas Riedel <34276446+peanutfun@users.noreply.github.com> Date: Wed, 15 Feb 2023 18:15:14 +0100 Subject: [PATCH 8/9] Fix indentation in install.rst --- doc/guide/install.rst | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/doc/guide/install.rst b/doc/guide/install.rst index b5daf2ab6..c9ee6f416 100644 --- a/doc/guide/install.rst +++ b/doc/guide/install.rst @@ -132,9 +132,9 @@ For advanced Python users or developers of CLIMADA, we recommed cloning the CLIM .. code-block:: shell - git clone https://github.com/CLIMADA-project/climada_python.git - cd climada_python - git checkout develop + git clone https://github.com/CLIMADA-project/climada_python.git + cd climada_python + git checkout develop #. Create an Anaconda environment called ``climada_env`` for installing CLIMADA. Use the default environment specs in ``env_climada.yml`` to create it, and update it with the ``env_developer.yml`` specs. @@ -142,21 +142,21 @@ For advanced Python users or developers of CLIMADA, we recommed cloning the CLIM .. code-block:: shell - conda env create -n climada_env -f requirements/env_climada.yml - conda env update -n climada_env -f requirements/env_developer.yml - conda activate climada_env + conda env create -n climada_env -f requirements/env_climada.yml + conda env update -n climada_env -f requirements/env_developer.yml + conda activate climada_env #. Install the local CLIMADA source files as Python package using ``pip``: .. code-block:: shell - python -m pip install -e ./ + python -m pip install -e ./ .. hint:: - Using a path ``./`` (referring to the path you are currently located at) will instruct ``pip`` to install the local files instead of downloading the module from the internet. - The ``-e`` (for "editable") option further instructs ``pip`` to link to the source files instead of copying them during installation. - This means that any changes to the source files will have immediate effects in your environment, and re-installing the module is never required. + Using a path ``./`` (referring to the path you are currently located at) will instruct ``pip`` to install the local files instead of downloading the module from the internet. + The ``-e`` (for "editable") option further instructs ``pip`` to link to the source files instead of copying them during installation. + This means that any changes to the source files will have immediate effects in your environment, and re-installing the module is never required. #. Verify that everything is installed correctly by executing a single test: @@ -193,23 +193,23 @@ To install CLIMADA Petals, we assume you have already installed CLIMADA Core wit .. code-block:: shell - git clone https://github.com/CLIMADA-project/climada_petals.git - cd climada_petals - git checkout develop + git clone https://github.com/CLIMADA-project/climada_petals.git + cd climada_petals + git checkout develop #. Update the Anaconda environment with the specifications from Petals and activate it: .. code-block:: shell - conda env update -n climada_env -f requirements/env_climada.yml - conda env update -n climada_env -f requirements/env_developer.yml - conda activate climada_env + conda env update -n climada_env -f requirements/env_climada.yml + conda env update -n climada_env -f requirements/env_developer.yml + conda activate climada_env #. Install the CLIMADA Petals package: .. code-block:: shell - python -m pip install -e ./ + python -m pip install -e ./ ------------------------------ Apps for Programming in Python From 842a95874df1a30360c8af3afd6872bbb3e1f786 Mon Sep 17 00:00:00 2001 From: Lukas Riedel <34276446+peanutfun@users.noreply.github.com> Date: Wed, 15 Feb 2023 18:35:06 +0100 Subject: [PATCH 9/9] Fix Sphinx warnings and minor issues with installation instructions --- doc/guide/install.rst | 22 +++++++++++----------- doc/tutorial/1_main_climada.ipynb | 4 ++-- 2 files changed, 13 insertions(+), 13 deletions(-) diff --git a/doc/guide/install.rst b/doc/guide/install.rst index c9ee6f416..90ebad452 100644 --- a/doc/guide/install.rst +++ b/doc/guide/install.rst @@ -25,7 +25,8 @@ Prerequisites All dependencies will be downloaded from the internet. Do **not** use a metered, mobile connection! * Install `Anaconda`_, following the `installation instructions `_ for your OS. -* Create a **workspace directory**, ideally in subdirectory of your user/home directory. +* Create a **workspace directory**. + To make sure that your user can manipulate it without special privileges, use a subdirectory of your user/home directory. Do **not** use a directory that is synchronized by cloud storage systems like OneDrive, iCloud or Polybox! * **Linux** users need to make sure they have ``git`` and ``curl`` installed. Ubuntu and Debian users may use APT: @@ -75,7 +76,7 @@ These instructions will install the most recent stable version of CLIMADA withou curl -o env_climada.yml https://raw.githubusercontent.com/CLIMADA-project/climada_python/main/requirements/env_climada.yml - Alternatively, download the file through your browser and place it in the workspace directory: :download:`env_climada.yml ` + Alternatively, download the file through your browser and place it into the workspace directory: :download:`env_climada.yml ` #. Instruct Anaconda to create a new environment called ``climada_env`` from the specification file: @@ -187,7 +188,7 @@ CLIMADA Petals can be used to generate additional data of this type, or to have To install CLIMADA Petals, we assume you have already installed CLIMADA Core with the :ref:`advanced instructions ` above. #. Open the command line and navigate to the workspace directory. -#. Clone CLIMADA Petals from its `GitHub repository `_. +#. Clone CLIMADA Petals from its `repository `_. Enter the directory and check out the branch of your choice. The latest development version will be available under the branch ``develop``. @@ -242,7 +243,8 @@ Spyder Installing Spyder into the existing Anaconda environment for CLIMADA might fail depending on the exact versions of dependencies installed. Therefore, we recommend installing Spyder in a *separate* environment, and then connecting it to a kernel in the original ``climada_env``. -#. Follow the `installation instructions `_ to install Spyder with ``conda``. +#. Follow the `Spyder installation instructions `_. + Make sure you install it with ``conda``! #. Check the version of the Spyder kernel in the new environment: @@ -289,6 +291,8 @@ FAQs Answers to frequently asked questions. +.. _update-climada: + Updating CLIMADA ^^^^^^^^^^^^^^^^ @@ -373,15 +377,11 @@ After **each** of the following steps, check if the problem is solved, and only conda activate climada_env -#. Update the environment using the specifications. - Replace ```` with the path to the specification file(s), depending on the :ref:`installation type ` you chose (see above). - - .. code-block:: shell - - conda update -n climada_env -f +#. :ref:`Update the conda environment and CLIMADA `. #. Anaconda will notify you if it is not up-to-date. In this case, follow its instructions to update it. + Then, repeat the last step and update the environment and CLIMADA (again). #. Install the missing package manually. Follow the instructions for :ref:`installing more packages `. @@ -421,7 +421,7 @@ You can change this setting in multiple ways: from climada.util import log_level with log_level(level="WARNING"): - # Silenced code goes here + # This code only emits log levels 'WARNING' or higher foo() # Default logging level again diff --git a/doc/tutorial/1_main_climada.ipynb b/doc/tutorial/1_main_climada.ipynb index 6a0948241..8e6ca9d6a 100644 --- a/doc/tutorial/1_main_climada.ipynb +++ b/doc/tutorial/1_main_climada.ipynb @@ -54,7 +54,7 @@ "\n", "### Resources beyond this tutorial\n", "\n", - "- [Installation guide](/guide/install.rst) - go here if you've not installed the model yet\n", + "- [Installation guide](../guide/install.rst) - go here if you've not installed the model yet\n", "- [CLIMADA Read the Docs home page](https://climada-python.readthedocs.io) - for all other documentation\n", "- [List of CLIMADA's features and associated tutorials](#CLIMADA-features)\n", "- [CLIMADA GitHub develop branch documentation](https://github.com/CLIMADA-project/climada_python/tree/develop/doc) for the very latest versions of code and documentation\n", @@ -1275,7 +1275,7 @@ "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", - "version": "3.8.15 | packaged by conda-forge | (default, Nov 22 2022, 08:49:06) \n[Clang 14.0.6 ]" + "version": "3.8.15" }, "vscode": { "interpreter": {