{ "cells": [ { "cell_type": "markdown", "id": "north-following", "metadata": {}, "source": [ "# Installation\n", "\n", "Please execute the instructions of the following text boxes in a Terminal or Anaconda Prompt.\n", "\n", "## Download\n", "\n", "Download the last CLIMADA release available in [CLIMADA releases](https://github.com/climada-project/climada_python/releases) as a zip or tar.gz file. Uncompress it to your local computer. Hereinafter ``climada_python-x.y.z`` refers to the downloaded folder of CLIMADA version x.y.z.\n", "\n", "## Unix, Mac and Windows Operating Systems\n", "\n", "\n", "### Install environment with Anaconda\n", "1. **Anaconda**: Download or update to the latest version of [Anaconda](https://www.anaconda.com/). Execute it.\n", "\n", "2. **Install dependencies**: In the *Environments* section, use the *Import* box to create a new virtual environment from a yml file. A dialogue box will ask you for the location of the file. Provide first the path of CLIMADA's ``climada_python-x.y.z/requirements/env_climada.yml``. The default name of the environment, *climada_env*, appears. Click the *Import* button to start the installation. \n", "\n", " The installation of the packages will take some minutes. No dialogue box should appear in the meantime. If an error happens, try to solve it looking into the details description. \n", "\n", " Finally, set the ``climada_python-x.y.z`` folder path into the environment using the following command:\n", "\n", " ```\n", " conda activate climada_env\n", " conda develop /your/path/to/climada_python-x.y.z/\n", " conda deactivate\n", " ```\n", "\n", "\n", " You can also do so by clicking on the green right arrow in the Anaconda GUI in the *Environments* section right to the 'climada_env' environment, select 'Open Terminal' and execute the following line:\n", "\n", " ```\n", " conda develop /your/path/to/climada_python-x.y.z/\n", " ```\n", "\n", "3. **Test installation**: Before leaving the *Environments* section of Anaconda, make sure that the CLIMADA environment, *climada_env* is selected. Go to the *Home* section of Anaconda and install and launch Spyder (or your preferred editor). Open the file containing all the installation tests, ``tests_install.py`` in ``climada_python-x.y.z`` folder and execute it. If the installation has been successful, an OK will appear at the end (the execution should last less than 2 min).\n", " \n", "4. **Run tutorials**: 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-x.y.z`` 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.\n", "\n", "### Workaround if **Spyder** installation in Anaconda fails for *climada_env*.\n", "\n", "In a terminal window, enter:\n", "\n", "```\n", "conda activate climada_env \n", "conda install spyder-kernels \n", "python -c \"import sys; print(sys.executable)\" \n", "--> returns a path, like /Users/XXX/opt/anaconda3/envs/climada_env/bin/python\n", "```\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.1.5), start this Spyder, then, after Spyder has started, navigate to Preferences > Python Interpreter > Use the following interpreter and paste the path from above (e.g. /Users/XXX/opt/anaconda3/envs/CLIMADA_env/bin/python) into the text box. Start a new IPython console and run ``tests_install.py``.\n", "\n", "\n", "## Unix and Mac Operating Systems\n", "\n", "### Install environment with Miniconda\n", "\n", "1. **Miniconda**: Download or update to the latest version of [Miniconda](https://conda.io/miniconda.html) \n", "\n", "2. **Install dependencies**: Create the virtual environment *climada_env* with CLIMADA's dependencies:\n", "\n", " ```\n", " cd climada_python-x.y.z\n", " conda env create -f requirements/env_climada.yml --name climada_env\n", " ```\n", "\n", " Finally, set the ``climada_python-x.y.z`` folder path into the environment using the following command:\n", "\n", " ```\n", " conda activate climada_env\n", " conda develop /your/path/to/climada_python-x.y.z/\n", " conda deactivate\n", " ```\n", "\n", "3. **Test installation**: Activate the environment, execute the installation tests and deactivate the environment when finished using CLIMADA:\n", "\n", " ```\n", " conda activate climada_env\n", " python3 tests_install.py\n", " source deactivate\n", " ```\n", "\n", " If the installation has been successful, an OK will appear at the end (the execution should last less than 2min).\n", " \n", "4. **Run tutorials**: Install and launch *jupyter notebook* in the same environment:\n", "\n", " ```\n", " conda activate climada_env\n", " conda install jupyter\n", " jupyter notebook --notebook-dir /path/to/climada_python-x.y.z\n", " ```\n", "\n", " A browser window will show up. Open ``climada_python-x.y.z/doc/tutorial/1_main_CLIMADA.ipynb``. This is the tutorial which will guide you\n", " through all CLIMADA's functionalities. Execute each code cell to see the results, you might also edit the code cells before executing. \n", " See [tutorials](https://github.com/CLIMADA-project/climada_python/tree/main/doc/tutorial) for more information.\n", "\n", "## FAQs\n", "* ModuleNotFoundError; CLIMADA libraries are not found. Try to include *climada_python-x.y.z* path in the environment *climada_env* path as suggested in Section 2 of [Install environment with Anaconda]. If it does not work you can always include the path manually before executing your code:\n", "\n", " ```\n", " import sys\n", " sys.path.append('path/to/climada_python-x.y.z')\n", " ```\n", "\n", "* ModuleNotFoundError; some python library is not found. 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*. You can then install them manually one by one as follows:\n", "\n", " ```\n", " conda activate climada_env\n", " pip install library_name\n", " ```\n", "\n", " where ``library_name`` is the missing library.\n", "\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 (``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", "\n", "* How to change the log level: By default the logging level is set to ``'INFO'``. This can be changed\n", "\n", " * programmatically, in a script or interactive python environment (Spyder, Jupyter, IPython) by executing e.g., ``CLIMADA.util.config.setup_logging('DEBUG')``, \n", " \n", " * through configuration, by editing the config file ``CLIMADA/conf/defaults.conf`` and setting the value of the ``global.log_level`` property." ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "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.8" } }, "nbformat": 4, "nbformat_minor": 5 }