Skip to content

02-installation.md

Latest commit

 

History

History
196 lines (156 loc) · 6.21 KB

02-installation.md

File metadata and controls

196 lines (156 loc) · 6.21 KB
title Installation
teaching 10
exercises 10
compatibility ESMValTool v2.12.0
questions
What are the prerequisites for installing ESMValTool?
How do I confirm that the installation was successful?
objectives
Install ESMValTool
Demonstrate that the installation was successful
keypoints
All the required packages can be installed using mamba.
You can find more information about installation in the [documentation](https://docs.esmvaltool.org/en/latest/quickstart/installation.html).

Overview

The instructions help with the installation of ESMValTool on operating systems like Linux/MacOSX/Windows. We use the Mamba package manager to install the ESMValTool. Other installation methods are also available; they can be found in the documentation. We will first install Mamba, and then ESMValTool. We end this chapter by testing that the installation was successful.

Before we begin, here are all the possible ways in which you can use ESMValTool depending on your level of expertise or involvement with ESMValTool and associated software such as GitHub and Mamba.

  1. If you have access to a server where ESMValTool is already installed as a module, for e.g., the [CEDA JASMIN](https://help.jasmin.ac.uk/article /4955-community-software-esmvaltool) server, you can simply load the module with the following command:
module load esmvaltool

After loading esmvaltool, we can start using ESMValTool right away. Please see the [next lesson]({{ page.root }}{% link _episodes/03-configuration.md %}). 2. If you would like to install ESMValTool as a mamba package, then this lesson will tell you how! 3. If you would like to start experimenting with existing diagnostics or contributing to ESMvalTool, please see the instructions for source installation in the lesson [Development and contribution]({{ page.root }}{% link _episodes/07-development-setup.md %}) and in the documentation.

Install ESMValTool on Windows

ESMValTool does not directly support Windows, but successful usage has been reported through the Windows Subsystem for Linux(WSL), available in Windows 10. To install the WSL please follow the instructions on the Windows Documentation page. After installing the WSL, installation can be done using the same instructions for Linux/MacOSX. {: .callout}

Install ESMValTool on Linux/MacOSX

Install Mamba

ESMValTool is distributed using Mamba. To install mamba on Linux or MacOSX, follow the instructions below:

  1. Please download the installation file for the latest Mamba version here.

  2. Next, run the installer from the place where you downloaded it:

    On Linux:

    bash Mambaforge-Linux-x86_64.sh

    On MacOSX:

    bash Mambaforge-MacOSX-x86_64.sh

  3. Follow the instructions in the installer. The defaults should normally suffice.

  4. You will need to restart your terminal for the changes to have effect.

  5. We recommend updating mamba before the esmvaltool installation. To do so, run:

    mamba update --name base mamba

  6. Verify you have a working mamba installation by:

    which mamba

    This should show the path to your mamba executable, e.g. ~/mambaforge/bin/mamba.

For more information about installing mamba, see [the mamba installation documentation](https://docs.esmvaltool.org/en /latest/quickstart/installation.html#mamba-installation).

Install the ESMValTool package

The ESMValTool package contains diagnostics scripts in four languages: R, Python, Julia and NCL. This introduces a lot of dependencies, and therefore the installation can take quite long. It is, however, possible to install 'subpackages' for each of the languages. The following (sub)packages are available:

  • esmvaltool-python
  • esmvaltool-ncl
  • esmvaltool-r
  • esmvaltool --> the complete package, i.e. the combination of the above.

For the tutorial, we will install the complete package. Thus, to install the ESMValTool package, run

mamba create --name esmvaltool esmvaltool

On MacOSX ESMValTool functionalities in Julia, NCL, and R are not supported. To install a Mamba environment on MacOSX, please refer to specific [information](https:// docs.esmvaltool.org/en/latest/quickstart/installation.html#installation-on- macosx).

This will create a new [Mamba environment](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks /manage-environments.html) called esmvaltool, with the ESMValTool package and all of its dependencies installed in it.

Common issues

You find a list of common installation problems and their solutions in the [documentation](https://docs.esmvaltool.org/en/latest/quickstart/installation .html#common-installation-problems-and-their-solutions).

{: .callout}

Test that the installation was successful

To test that the installation was successful, run

conda activate esmvaltool

to activate the conda environment called esmvaltool. In the shell prompt the active conda environment should have been changed from (base) to (esmvaltool).

Next, run

esmvaltool --help

to display the command line help.

Version of ESMValTool

Can you figure out which version of ESMValTool has been installed?

Solution

The esmvaltool --help command lists version as a command to get the version

When you run

esmvaltool version

{: .bash} The version of ESMValTool installed should be displayed on the screen as:

ESMValCore: 2.12.0
ESMValTool: 2.12.0

{: .output} Note that on HPC servers such as JASMIN, sometimes a more recent development version may be displayed for ESMValTool, for e.g. ESMValTool: 2.12.0.dev71+g2c60b4d97 {: .solution} {: .challenge}

{% include links.md %}