conda environments
==================

In the course we will work with a *conda environment*. An environment contains a
specific collection of conda packages that you have installed.

**You should always work within a dedicated environment**, rather than the default (base)
environment. This allows to separate the packages used for analyses and for handling
packages etc. (e.g. conda itself is installed in the base environment).

You should have added the two additional packages (:ref:`instructions <base_environment>`)
before continuing. We will again work on a command-line terminal:

- *Windows* users should open the `Miniforge prompt` (search in the start menu)
- *macOS* and *linux* users open a `shell` (`Konsole` or `terminal`)

At this point you should have a window showing the following:

.. code:: console

   (base) username@computer:~$


Analysis environment
--------------------

For the *Integrated Practical - Python in Geosciences* course we will work in a environment
with the name `ipp_analysis`. We create this environment from a file that lists all required packages.


#. In the section `Preparation <01_preparation.html>`__ we created a folder for the course
   named `ip_python`.

#. From the terminal we now need to navigate to this folder. This can be done using the ``cd`` command:

   .. code:: bash

      cd ip_python

   Depending on where you created the folder you need to adapt the path, e.g.:

   .. code:: bash

      cd Documents/ETH/ip_python

#. Next we need to download the :download:`environment.yml <../../../environment.yml>`
   file.

   - Download the file and save it to the `ip_python` folder.

     .. warning::
        Sometimes the file can be renamed to `environment.yml.txt` by the download
        (especially on macOS). Rename it back to `environment.yml`.


#. Open the `environment.yml` file in a text editor and take a look. Which packages will be installed?

Setup the analysis environment
------------------------------

Next we create the environment that we will use for the course. This is also done from
the terminal:

.. code:: bash

   conda env create --file environment.yml

.. tip::
   You need to be in the same folder as the `environment.yml` file else it does not work.

This will download and install the packages listed in the environment file. It contains
all packages used for the introduction and the projects (except the climada project).
This is still part of the preparation for the python exercises. If you are having trouble
please come ask us for support.

Test environment
----------------

It might still be unclear why we are using environments to install python and python
packages. In this section we will try to motivate this and also get a bit more familiar
with conda environments. For this we set up a small test environment. It's not
really needed for the course so we will delete it again at the end.

All commands have to be entered in the `Terminal` opened in the last section.

#. Above we created a environment from a file that listed all packages we wanted. Here,
   we specify the packages manually. We do this using the following command to install
   python and numpy:

   .. code:: bash

      conda create --name test_env python=3.11 numpy=1.24

   This creates a new environment with the name  `test_env`. We specify two packages
   that should be installed, namely `python`, and `numpy`. It will install
   more than these two packages, because they have dependencies that will also be added.
   By using ``python=3.11`` and ``numpy=1.24`` we tell conda to install a specific version of python.
   If no version constraint is given the newest compatible version is installed.

#. Now that the environment was created we can activate it:

   .. code:: bash

      conda activate test_env

   Now your command prompt should show that your `test_env` environment is active:

   .. code:: bash

      (test_env) username@computer:~$

#. Once it is active we can install additional packages into the environment. For
   example we can add the python plotting library `matplotlib`:

   .. code:: bash

      conda install matplotlib

   Again, this should install `matplotlib` as well as additional dependencies.

#. To see all the packages that are currently installed, their version and source channel
   you can execute

   .. code:: bash

      conda list

   from the command prompt.

#. We can also list a specific package:

   .. code:: bash

      conda list numpy

   This should indicate that numpy version 1.24 is installed. If we compare this with
   the numpy version installed in the `ipp_analysis` environment:

   .. code:: bash

      conda list -n ipp_analysis numpy

   we should see that it contains a different version. Being able to have different versions
   of python and packages installed, and to be able to switch effortlessly between is one
   of the main motivations to work with environments.

#. We leave the `test_env` environment again by calling:

   .. code:: bash

      conda deactivate

#. You show all environments that you installed using:

   .. code:: bash

      conda env list

#. Environments can be removed by calling

   .. code:: bash

      conda env remove --name test_env

   You can remove the test environment - it's no longer needed.