Quickstart guide

Last updated on 2024-11-26 | Edit this page

Estimated time: 10 minutes

Overview

Questions

  • What is the purpose of the quickstart guide?
  • How do I load and check the ESMValTool environment?
  • How do I configure ESMValTool?
  • How do I run a recipe?

Objectives

  • Understand the purpose of the quickstart guide
  • Load and check the ESMValTool environment
  • Configure ESMValTool
  • Run a recipe

What is the purpose of the quickstart guide?

  • The purpose of the quickstart guide is to enable a user of ESMValTool to run ESMValTool as quickly as possible by making the bare minimum number of changes.

How do I load and check the ESMValTool environment?

  • For this quickstart guide, an assumption is made that ESMValTool has already been installed at the site where ESMValTool will be run. If this is not the case, see the [Installation][lesson-installation] episode in this tutorial.

  • Load the ESMValTool environment by following the instructions at [ESMValTool: Pre-installed versions on HPC clusters / other servers][activate-environment].

  • Check the ESMValTool environment by accessing the help for ESMValTool:

    BASH 

    esmvaltool --help

How do I configure ESMValTool?

  • Create the ESMValTool user configuration file (the file is written by default to ~/.esmvaltool/config-user.yml):

    BASH 

    esmvaltool config get_config_user

  • Edit the ESMValTool user configuration file using your favourite text editor to uncomment the lines relating to the site where ESMValTool will be run.

  • For more details about the ESMValTool user configuration file see the [Configuration][lesson-configuration] episode in this tutorial.

How do I run a recipe?

  • Run the example Python recipe:

    BASH 

    esmvaltool run examples/recipe_python.yml

  • Wait for the recipe to complete. If the recipe completes successfully, the last line printed to screen at the end of the log will look something like:

    BASH 

    YYYY-MM-DD HH:mm:SS, NNN UTC [NNNNN] INFO    Run was successful

  • View the output of the recipe by opening the HTML file produced by ESMValTool (the location of this file is printed to screen near the end of the log):

    BASH 

    YYYY-MM-DD HH:mm:SS, NNN UTC [NNNNN] INFO    Wrote recipe output to:
file:///$HOME/esmvaltool_output/recipe_python_<date>_<time>/index.html

  • For more details about running recipes see the [Running your first recipe][lesson-recipe] episode in this tutorial.

Key Points

  • The purpose of the quickstart guide is to enable a user of ESMValTool to run ESMValTool as quickly as possible without having to go through the whole tutorial
  • Use the module load command to load the ESMValTool environment, see the \[Installation\]\[lesson-installation\] episode for more details and use esmvaltool --help to check the ESMValTool environment
  • Use esmvaltool config get_config_user to create the ESMValTool user configuration file
  • Use esmvaltool run <recipe>.yml to run a recipe