Skip to content

Commit b1bc381

Browse files
emanuel-schmidemanuel-schmid
committed
installation guide update: spyder, pypi installation, separation of core and petals
1 parent 30cd7de commit b1bc381

File tree

1 file changed

+232
-101
lines changed

1 file changed

+232
-101
lines changed

‎doc/guide/Guide_Installation.ipynb‎

Lines changed: 232 additions & 101 deletions
Original file line numberDiff line numberDiff line change
@@ -2,120 +2,251 @@
22
"cells": [
33
{
44
"cell_type": "markdown",
5+
"id": "5c1e8ad3",
6+
"metadata": {
7+
"tags": []
8+
},
59
"source": [
6-
"# Installation\r\n",
7-
"\r\n",
8-
"Please execute the instructions of the following text boxes in a Terminal or Anaconda Prompt.\r\n",
9-
"\r\n",
10-
"## Download CLIMADA and CLIMADA_petals\r\n",
11-
"\r\n",
12-
"```bash\r\n",
13-
"cd $[installation directory]\r\n",
14-
"\r\n",
15-
"git clone https://github.com/CLIMADA-project/climada_python.git\r\n",
16-
"cd climada_python\r\n",
17-
"git checkout develop\r\n",
18-
"cd ..\r\n",
19-
"\r\n",
20-
"git clone https://github.com/CLIMADA-project/climada_petals.git\r\n",
21-
"cd climada_petals\r\n",
22-
"git checkout develop\r\n",
23-
"cd ..\r\n",
24-
"```\r\n",
25-
"\r\n",
26-
"## Install environment with Anaconda or Miniconda\r\n",
27-
"\r\n",
28-
"### Conda\r\n",
29-
"\r\n",
30-
"It's highly recommanded to use [Conda](https://docs.conda.io/projects/conda/en/latest/) for the installation. 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.\r\n",
31-
"\r\n",
32-
"### Install dependencies\r\n",
33-
"\r\n",
34-
"Open a command prompt (Windows) or shell (Mac, Linux)\r\n",
35-
"\r\n",
36-
"```bash\r\n",
37-
"cd $[installation directory]\r\n",
38-
"conda env create -n climada_env -f climada_petals/requirements/env_climada.yml\r\n",
39-
"conda activate climada_env\r\n",
40-
"```\r\n",
41-
"\r\n",
42-
"### Install climada core and petals\r\n",
43-
"\r\n",
44-
"```bash\r\n",
45-
"cd $[installation directory]\r\n",
46-
"pip install -e climada_python\r\n",
47-
"pip install -e climada_petals\r\n",
48-
"```\r\n",
49-
"\r\n",
50-
"### Test installation\r\n",
51-
"\r\n",
52-
"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).\r\n",
53-
"\r\n",
54-
"### Run tutorials\r\n",
55-
"\r\n",
56-
"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.\r\n",
57-
"\r\n",
58-
"### Workaround if **Spyder** installation in Anaconda fails for *climada_env*.\r\n",
59-
"\r\n",
60-
"In a terminal window, enter:\r\n",
61-
"\r\n",
62-
"```bash\r\n",
63-
"conda activate climada_env \r\n",
64-
"conda install spyder-kernels \r\n",
65-
"python -c \"import sys; print(sys.executable)\" \r\n",
66-
"--> returns a path, like /Users/XXX/opt/anaconda3/envs/climada_env/bin/python\r\n",
67-
"```\r\n",
68-
"\r\n",
69-
"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``.\r\n",
70-
"\r\n",
71-
"## FAQs\r\n",
72-
"\r\n",
73-
"* 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:\r\n",
74-
"\r\n",
75-
" ```bash\r\n",
76-
" import sys\r\n",
77-
" sys.path.append('path/to/climada_python-x.y.z')\r\n",
78-
" ```\r\n",
79-
"\r\n",
80-
"\r\n",
81-
"* 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:\r\n",
82-
"\r\n",
83-
" ```bash\r\n",
84-
" conda activate climada_env\r\n",
85-
" pip install library_name\r\n",
86-
" ```\r\n",
87-
"\r\n",
88-
" where ``library_name`` is the missing library.\r\n",
89-
"\r\n",
90-
" Another reason may be a recent update of the operating system (macOS). In this case removing and reinstalling Anaconda will be required.\r\n",
91-
"\r\n",
92-
"* 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)\r\n",
93-
"\r\n",
94-
"* 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\\_' ([climada v2.2.0](https://github.com/CLIMADA-project/climada_python/releases/tag/v2.2.0)).\r\n",
95-
" To solve it, run `python -c 'import climada; climada.setup_climada_data(reload=True)` in a terminal.\r\n",
96-
"\r\n",
97-
"* How to change the log level: By default the logging level is set to ``'INFO'``, which is quite verbose. This can be changed\r\n",
98-
"\r\n",
99-
" * programmatically, in a script or interactive python environment (Spyder, Jupyter, IPython) by executing e.g., ``from climada.util.config import LOGGER; from logging import WARNING; LOGGER.setLevel(WARNING)``, \r\n",
100-
" \r\n",
101-
" * through configuration, by editing the config file ``CLIMADA/conf/defaults.conf`` and setting the value of the ``global.log_level`` property.\r\n"
102-
],
103-
"metadata": {}
10+
"# Installation\n",
11+
"\n",
12+
"Please execute the instructions of the following text boxes in a Terminal or Anaconda Prompt. Chose an installation directory, e.g., the user's home directory. In the following it will be referred to as `$[installation directory]`.\n"
13+
]
14+
},
15+
{
16+
"cell_type": "markdown",
17+
"id": "fb641808-0a83-4b11-a2c6-2ea691d1efe9",
18+
"metadata": {
19+
"jp-MarkdownHeadingCollapsed": true,
20+
"tags": []
21+
},
22+
"source": [
23+
"## Install CLIMADA from sources\n",
24+
"\n",
25+
"### Download the latest version\n",
26+
"\n",
27+
"```bash\n",
28+
"cd $[installation directory]\n",
29+
"\n",
30+
"git clone https://github.com/CLIMADA-project/climada_python.git\n",
31+
"cd climada_python\n",
32+
"git checkout develop\n",
33+
"cd ..\n",
34+
"\n",
35+
"```\n",
36+
"\n",
37+
"### Set up the environment\n",
38+
"\n",
39+
"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",
40+
"\n",
41+
"Open a command prompt (Windows) or shell (Mac, Linux) and run:\n",
42+
"\n",
43+
"```bash\n",
44+
"conda env create -n climada_env -f climada_python/requirements/env_climada.yml\n",
45+
"conda activate climada_env\n",
46+
"```\n",
47+
"\n",
48+
"### Install the climada package\n",
49+
"\n",
50+
"Include the CLIMADA path into the Conda environment as follows:\n",
51+
"\n",
52+
"```bash\n",
53+
"pip install -e climada_python\n",
54+
"```\n",
55+
"\n",
56+
"With this setup, changes to CLIMADA's source code will immediately take effect. It removes the need to reinstall during development."
57+
]
58+
},
59+
{
60+
"cell_type": "markdown",
61+
"id": "7f94bbf8-5429-437c-8602-e11c79c92d40",
62+
"metadata": {
63+
"jp-MarkdownHeadingCollapsed": true,
64+
"tags": []
65+
},
66+
"source": [
67+
"## Install CLIMADA from PyPi (alternative)\n",
68+
"\n",
69+
"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",
70+
"\n",
71+
"### Set up the environment\n",
72+
"\n",
73+
"Download the environment specification file from the git repository and save it locally, then create the conda environment:\n",
74+
"\n",
75+
"```bash\n",
76+
"wget https://github.com/CLIMADA-project/climada_python/blob/main/requirements/env_climada.yml\n",
77+
"conda env create -n climada_env -f env_climada.yml\n",
78+
"conda activate climada_env\n",
79+
"```\n",
80+
"\n",
81+
"If this was successful, `env_climada.yml` can be safely deleted.\n",
82+
"\n",
83+
"### Install the climada package\n",
84+
"\n",
85+
"```bash\n",
86+
"pip install climada\n",
87+
"```"
88+
]
89+
},
90+
{
91+
"cell_type": "markdown",
92+
"id": "5136859e-8b25-4719-a540-0f42339ccee8",
93+
"metadata": {},
94+
"source": [
95+
"## Install CLIMADA-petals (optional)\n",
96+
"\n",
97+
"### Download the latest version\n",
98+
"\n",
99+
"```bash\n",
100+
"cd $[installation directory]\n",
101+
"\n",
102+
"git clone https://github.com/CLIMADA-project/climada_petals.git\n",
103+
"cd climada_petals\n",
104+
"git checkout develop\n",
105+
"cd ..\n",
106+
"\n",
107+
"```\n",
108+
"\n",
109+
"### Update the environment\n",
110+
"\n",
111+
"It is possible that CLIMADA-petals has slightly different dependencies than CLIMADA-core, hence the conda environment should be updated.\n",
112+
"\n",
113+
"```bash\n",
114+
"conda env update -n climada_env -f climada_python/requirements/env_climada.yml\n",
115+
"conda activate climada_env\n",
116+
"```\n",
117+
"\n",
118+
"### Install the climada_petals package\n",
119+
"\n",
120+
"Include the CLIMADA-petals path into the Conda environment as follows:\n",
121+
"\n",
122+
"```bash\n",
123+
"pip install -e climada_petals\n",
124+
"```\n",
125+
"\n",
126+
"In case of a separate environment for CLIMADA-petals, one needs to install the core package as well, either with the package from PyPi (`pip install climada`) or from local sources (`pip install -e climada_python`)"
127+
]
128+
},
129+
{
130+
"cell_type": "markdown",
131+
"id": "cf90fa87-cc4e-44be-ae1a-0c5d754316f1",
132+
"metadata": {},
133+
"source": [
134+
"## Test the installation\n",
135+
"\n",
136+
"Run the following commands:\n",
137+
"\n",
138+
"```bash\n",
139+
"python -m unittest climada.engine.test.test_impact\n",
140+
"python -m unittest climada.engine.test.test_cost_benfit\n",
141+
"```\n",
142+
"\n",
143+
"If the installation has been successful, an OK will appear at the end (the execution shouldn't last more than 2 min).\n",
144+
"\n",
145+
"\n",
146+
"### Run tutorials\n",
147+
"\n",
148+
"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."
149+
]
150+
},
151+
{
152+
"cell_type": "markdown",
153+
"id": "b943087a-ca5b-4da2-bc04-9f9d491fcd5d",
154+
"metadata": {},
155+
"source": [
156+
"## Working with _Spyder_\n",
157+
"\n",
158+
"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",
159+
"\n",
160+
"- 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",
161+
"\n",
162+
"```bash\n",
163+
"conda activate climada_env \n",
164+
"python -c \"import sys; print(sys.executable)\" \n",
165+
"# this returns a path, like /Users/XXX/opt/anaconda3/envs/climada_env/bin/python\n",
166+
"```\n",
167+
"\n",
168+
"\n",
169+
"- 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",
170+
"\n",
171+
"```bash\n",
172+
"conda activate climada_env \n",
173+
"conda install spyder-kernels=1.10.2\n",
174+
"```\n",
175+
"\n",
176+
"- Start a new IPython console in Spyder and run ``tests_install.py``."
177+
]
178+
},
179+
{
180+
"cell_type": "markdown",
181+
"id": "9d550564-ddac-4b9a-a780-05274aa4321d",
182+
"metadata": {},
183+
"source": [
184+
"## FAQs\n",
185+
"\n",
186+
"* **ModuleNotFoundError**\n",
187+
" * the CLIMADA packages are not found. \\\n",
188+
" 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",
189+
" * an external python library is not found. \\\n",
190+
" 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",
191+
" They can be installed manually one by one as follows:\n",
192+
" ```bash\n",
193+
" conda activate climada_env\n",
194+
" pip install library_name\n",
195+
" ```\n",
196+
" where ``library_name`` is the missing library.\\\n",
197+
" Another reason may be a recent update of the operating system (macOS). In this case removing and reinstalling Anaconda will be required.\n",
198+
"\n",
199+
"\n",
200+
"* **Conda permission error**\\\n",
201+
" (``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",
202+
"\n",
203+
"* **No 'impf\\_TC' column in GeoDataFrame**\\\n",
204+
" 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",
205+
" To solve it, run `python -c 'import climada; climada.setup_climada_data(reload=True)` in a terminal.\n",
206+
"\n",
207+
"* **How to change the log level**\\\n",
208+
" By default the logging level is set to ``'INFO'``, which is quite verbose. This can be changed\n",
209+
"\n",
210+
" * through configuration, by editing the config file `climada.conf` (see Guide_configuration.ipynb) and setting the value of the ``global.log_level`` property.\n",
211+
" \n",
212+
" * programmatically, globally, in a script or interactive python environment (Spyder, Jupyter, IPython) by executing e.g.,\n",
213+
" ```python\n",
214+
" from climada.util.config import LOGGER\n",
215+
" from logging import WARNING\n",
216+
" LOGGER.setLevel(WARNING)\n",
217+
" ```\n",
218+
" \n",
219+
" * programmatically, context based, using `climada.util.log_level`:\n",
220+
" ```python\n",
221+
" from climada.util import log_level\n",
222+
" with log_level(level='WARNING'):\n",
223+
" quietly_do_something()\n",
224+
" ```\n"
225+
]
104226
}
105227
],
106228
"metadata": {
107229
"interpreter": {
108230
"hash": "927c67ab198fcb661784b2c362c65b0d20aa8c2be2fb72d3ff0a6f4e04b047d1"
109231
},
110232
"kernelspec": {
111-
"display_name": "Python 3.8.8 64-bit",
233+
"display_name": "Python 3 (ipykernel)",
234+
"language": "python",
112235
"name": "python3"
113236
},
114237
"language_info": {
238+
"codemirror_mode": {
239+
"name": "ipython",
240+
"version": 3
241+
},
242+
"file_extension": ".py",
243+
"mimetype": "text/x-python",
115244
"name": "python",
116-
"version": ""
245+
"nbconvert_exporter": "python",
246+
"pygments_lexer": "ipython3",
247+
"version": "3.8.12"
117248
}
118249
},
119250
"nbformat": 4,
120251
"nbformat_minor": 5
121-
}
252+
}

0 commit comments

Comments
 (0)