From 03abe9b7f13de39e2cc02338b2503cf774cbef9f Mon Sep 17 00:00:00 2001 From: Lisa Bock Date: Wed, 12 Aug 2026 09:20:07 +0200 Subject: [PATCH 01/17] first try --- doc/sphinx/source/tutorials/episode_0.rst | 180 ++++++++++++++++++++++ doc/sphinx/source/tutorials/index.rst | 5 +- 2 files changed, 182 insertions(+), 3 deletions(-) create mode 100644 doc/sphinx/source/tutorials/episode_0.rst diff --git a/doc/sphinx/source/tutorials/episode_0.rst b/doc/sphinx/source/tutorials/episode_0.rst new file mode 100644 index 0000000000..553d4fd502 --- /dev/null +++ b/doc/sphinx/source/tutorials/episode_0.rst @@ -0,0 +1,180 @@ +.. _title_of_the_tutorial: + +Introduction +===================== + +.. admonition:: Overview + :class: note + + .. grid:: 2 + :gutter: 1 + :margin: 3 3 0 5 + + .. grid-item-card:: Timings + :columns: 12 + + * Teaching: 5 min + * Exercises: 10 min + + .. grid-item-card:: Questions + + * What is ESMValTool? + * Who are the people behind ESMValTool? + + .. grid-item-card:: Learning outcomes + + * Familiarization with ESMValTool + * Synchronize expectations + + .. grid-item-card:: Compatibility + :columns: 12 + + ESMValTool v2.15.0 + + +What is ESMValTool? +------------------- + +This tutorial is a first introduction to ESMValTool. Before diving into the +technical steps, let’s talk about what ESMValTool is all about. + +.. admonition:: What is ESMValTool? + :class: note + :icon: pencil + + What do you already know about or expect from ESMValTool? + + .. dropdown:: ESMValTool is... + :color: secondary + :icon: eye + + ESMValTool is many things, but in this tutorial we will focus on the + following traits: + + :check: **A tool to analyse climate data** + :check: **A collection of diagnostics for reproducible climate science** + :check: **A community effort** + +A tool to analyse climate data +------------------------------ + +ESMValTool takes care of finding, opening, checking, fixing, concatenating, +and preprocessing CMIP data and several other supported datasets. + +The central component of ESMValTool that we will see in this tutorial is the +**recipe**. Any ESMValTool recipe is basically a set of instructions to +reproduce a certain result. The basic structure of a recipe is as follows: + + * Documentation with relevant (citation) information + * Datasets that should be analysed + * Preprocessor steps that must be applied + * Diagnostic scripts performing more specific evaluation steps + +An example recipe could look like this: + +.. code-block:: bash + + documentation: + title: This is an example recipe. + description: Example recipe + authors: + - lastname_firstname + + datasets: + - {dataset: UKESM1-0-LL, project: CMIP6, exp: historical, mip: Amon, + ensemble: r1i1p1f2, start_year: 1960, end_year: 2005} + + preprocessors: + global_mean: + area_statistics: + operator: mean + + diagnostics: + hockeystick_plot: + description: plot of global mean temperature change + variables: + temperature: + short_name: tas + preprocessor: global_mean + scripts: hockeystick.py + +.. admonition:: Understanding the different sections of the recipe + :class: note + :icon: pencil + + Try to figure out the meaning of the different dataset keys. Hint: they can + be found in the documentation of ESMValTool. + + .. dropdown:: Solution + :color: secondary + :icon: eye + + The keys are explained in the ESMValTool documentation, in the + **Recipe** section, under :ref:`recipe-section-datasets`. + +A collection of diagnostics for reproducible climate science +------------------------------------------------------------ + +More than a tool, ESMValTool is a collection of publicly available recipes and +diagnostic scripts. This makes it possible to easily reproduce important +results. + +.. admonition:: Explore the available recipes + :class: note + :icon: pencil + + Go to the :doc:'/' and explore the **Recipes** section in the sidebar. + Which recipe(s) would you like to try? + +A community effort +------------------ + +ESMValTool is built and maintained by an active community of scientists and +software engineers. It is an open source project to which anyone can +contribute. Many of the interactions take place on GitHub. Here, we briefly +introduce you to some of the most important pages. + +.. admonition:: Meet the ESMValGroup + :class: note + :icon: pencil + + Go to [github.com/ESMValGroup](https://github.com/ESMValGroup). This is the + GitHub page of our 'organization'. Have a look around. How many + collaborators are there? Do you know any of them? + + Near the top of the page there are 3 pinned repositories: ESMValTool, + ESMValCore and Community. Visit each of the repositories. How many people + have contributed to each of them? Can you also find out how many people + have contributed to this tutorial? + +.. admonition:: Issues and pull requests + :class: note + :icon: pencil + + Go back to the repository pages of [ESMValTool](https://github.com/ + ESMValGroup/ESMValTool) or [ESMValCore](https://github.com/ESMValGroup/ + ESMValCore). There are tabs for ‘issues’ and ‘pull requests’. You can use + the labels to navigate them a bit more. How many open issues are about + enhancements of ESMValTool? And how many bugs have been fixed in + ESMValCore? There is also an ‘insights’ tab, where you can see a summary + of recent activity. How many issues have been opened and closed in the + past month? + +Conclusion +---------- + +This concludes the introduction of the tutorial. You now have a basic +knowledge of ESMValTool and its community. The following episodes will walk +you through the installation, configuration and running your first recipes. + +.. admonition:: Key points + :class: important + + * ESMValTool provides a reliable interface to analyse and evaluate climate + data + * A large collection of recipes and diagnostic scripts is already available + * ESMValTool is built and maintained by an active community of scientists + and developers + +.. _`PyData Theme documentation: Admonitions`: https://pydata-sphinx-theme.readthedocs.io/en/stable/examples/kitchen-sink/admonitions.html +.. _`Font Awesome`: https://fontawesome.com/search?ic=free-collection diff --git a/doc/sphinx/source/tutorials/index.rst b/doc/sphinx/source/tutorials/index.rst index 4cfefa9d3b..4d020fde98 100644 --- a/doc/sphinx/source/tutorials/index.rst +++ b/doc/sphinx/source/tutorials/index.rst @@ -23,7 +23,6 @@ While these are tailored for ACCESS users, they are still very informative. .. toctree:: :maxdepth: 1 - :caption: + :caption: ESMValTool Tutorial - template -.. + epsiode_0 From 78b6b9960d6a223da9c78108cc1cfbd02c20944f Mon Sep 17 00:00:00 2001 From: Lisa Bock Date: Wed, 12 Aug 2026 10:58:43 +0200 Subject: [PATCH 02/17] first episode --- doc/sphinx/source/tutorials/episode_0.rst | 50 +++++++++++------------ doc/sphinx/source/tutorials/index.rst | 9 +++- doc/sphinx/source/tutorials/template.rst | 2 +- 3 files changed, 32 insertions(+), 29 deletions(-) diff --git a/doc/sphinx/source/tutorials/episode_0.rst b/doc/sphinx/source/tutorials/episode_0.rst index 553d4fd502..248f76feb8 100644 --- a/doc/sphinx/source/tutorials/episode_0.rst +++ b/doc/sphinx/source/tutorials/episode_0.rst @@ -1,4 +1,4 @@ -.. _title_of_the_tutorial: +.. _epsiode_0: Introduction ===================== @@ -39,8 +39,7 @@ This tutorial is a first introduction to ESMValTool. Before diving into the technical steps, let’s talk about what ESMValTool is all about. .. admonition:: What is ESMValTool? - :class: note - :icon: pencil + :class: admonition-todo What do you already know about or expect from ESMValTool? @@ -51,9 +50,9 @@ technical steps, let’s talk about what ESMValTool is all about. ESMValTool is many things, but in this tutorial we will focus on the following traits: - :check: **A tool to analyse climate data** - :check: **A collection of diagnostics for reproducible climate science** - :check: **A community effort** + * **A tool to analyse climate data** + * **A collection of diagnostics for reproducible climate science** + * **A community effort** A tool to analyse climate data ------------------------------ @@ -65,10 +64,10 @@ The central component of ESMValTool that we will see in this tutorial is the **recipe**. Any ESMValTool recipe is basically a set of instructions to reproduce a certain result. The basic structure of a recipe is as follows: - * Documentation with relevant (citation) information - * Datasets that should be analysed - * Preprocessor steps that must be applied - * Diagnostic scripts performing more specific evaluation steps +* **Documentation** with relevant (citation) information +* **Datasets** that should be analysed +* **Preprocessor** steps that must be applied +* **Diagnostic** scripts performing more specific evaluation steps An example recipe could look like this: @@ -99,8 +98,7 @@ An example recipe could look like this: scripts: hockeystick.py .. admonition:: Understanding the different sections of the recipe - :class: note - :icon: pencil + :class: admonition-todo Try to figure out the meaning of the different dataset keys. Hint: they can be found in the documentation of ESMValTool. @@ -109,8 +107,10 @@ An example recipe could look like this: :color: secondary :icon: eye - The keys are explained in the ESMValTool documentation, in the - **Recipe** section, under :ref:`recipe-section-datasets`. + The keys are explained in the ESMValCore documentation, in **The + recipe format** section under + `Overview `_. + A collection of diagnostics for reproducible climate science ------------------------------------------------------------ @@ -120,11 +120,11 @@ diagnostic scripts. This makes it possible to easily reproduce important results. .. admonition:: Explore the available recipes - :class: note - :icon: pencil + :class: admonition-todo - Go to the :doc:'/' and explore the **Recipes** section in the sidebar. - Which recipe(s) would you like to try? + Go to the `ESMValTool documentation `_ + and explore the **Recipes** section in the sidebar. Which recipe(s) would + you like to try? A community effort ------------------ @@ -135,10 +135,9 @@ contribute. Many of the interactions take place on GitHub. Here, we briefly introduce you to some of the most important pages. .. admonition:: Meet the ESMValGroup - :class: note - :icon: pencil + :class: admonition-todo - Go to [github.com/ESMValGroup](https://github.com/ESMValGroup). This is the + Go to https://github.com/ESMValGroup. This is the GitHub page of our 'organization'. Have a look around. How many collaborators are there? Do you know any of them? @@ -148,12 +147,11 @@ introduce you to some of the most important pages. have contributed to this tutorial? .. admonition:: Issues and pull requests - :class: note - :icon: pencil + :class: admonition-todo - Go back to the repository pages of [ESMValTool](https://github.com/ - ESMValGroup/ESMValTool) or [ESMValCore](https://github.com/ESMValGroup/ - ESMValCore). There are tabs for ‘issues’ and ‘pull requests’. You can use + Go back to the repository pages of `ESMValTool `_ or `ESMValCore `_. There are tabs for ‘issues’ and ‘pull requests’. You can use the labels to navigate them a bit more. How many open issues are about enhancements of ESMValTool? And how many bugs have been fixed in ESMValCore? There is also an ‘insights’ tab, where you can see a summary diff --git a/doc/sphinx/source/tutorials/index.rst b/doc/sphinx/source/tutorials/index.rst index 4d020fde98..46d0f0a38e 100644 --- a/doc/sphinx/source/tutorials/index.rst +++ b/doc/sphinx/source/tutorials/index.rst @@ -21,8 +21,13 @@ While these are tailored for ACCESS users, they are still very informative. .. and a filename is added .. (test by replacing '' with 'template'). + +ESMValTool Tutorial +------------------- + .. toctree:: :maxdepth: 1 - :caption: ESMValTool Tutorial + :caption: Basic episodes - epsiode_0 + episode_0 +.. diff --git a/doc/sphinx/source/tutorials/template.rst b/doc/sphinx/source/tutorials/template.rst index f9147deedd..d58fc58c43 100644 --- a/doc/sphinx/source/tutorials/template.rst +++ b/doc/sphinx/source/tutorials/template.rst @@ -1,4 +1,4 @@ -.. :orphan: # uncomment before merging! +:orphan: .. How to use this template .. From 8fb32a972fdc90e45a0852b008a1af0952d76b06 Mon Sep 17 00:00:00 2001 From: Lisa Bock Date: Thu, 13 Aug 2026 15:16:08 +0200 Subject: [PATCH 03/17] numbering --- doc/sphinx/source/tutorials/{episode_0.rst => episode_1.rst} | 0 doc/sphinx/source/tutorials/index.rst | 4 ++-- 2 files changed, 2 insertions(+), 2 deletions(-) rename doc/sphinx/source/tutorials/{episode_0.rst => episode_1.rst} (100%) diff --git a/doc/sphinx/source/tutorials/episode_0.rst b/doc/sphinx/source/tutorials/episode_1.rst similarity index 100% rename from doc/sphinx/source/tutorials/episode_0.rst rename to doc/sphinx/source/tutorials/episode_1.rst diff --git a/doc/sphinx/source/tutorials/index.rst b/doc/sphinx/source/tutorials/index.rst index 46d0f0a38e..800f3a65b3 100644 --- a/doc/sphinx/source/tutorials/index.rst +++ b/doc/sphinx/source/tutorials/index.rst @@ -27,7 +27,7 @@ ESMValTool Tutorial .. toctree:: :maxdepth: 1 + :numbered: :caption: Basic episodes - episode_0 -.. + episode_1 From 9869c2ed58f5291a54b2f14154d64ddb128a2638 Mon Sep 17 00:00:00 2001 From: Lisa Bock Date: Fri, 14 Aug 2026 07:57:12 +0200 Subject: [PATCH 04/17] Update doc/sphinx/source/tutorials/episode_1.rst Co-authored-by: Felicity Chun <32269066+flicj191@users.noreply.github.com> --- doc/sphinx/source/tutorials/episode_1.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/sphinx/source/tutorials/episode_1.rst b/doc/sphinx/source/tutorials/episode_1.rst index 248f76feb8..cce03af8ec 100644 --- a/doc/sphinx/source/tutorials/episode_1.rst +++ b/doc/sphinx/source/tutorials/episode_1.rst @@ -109,7 +109,7 @@ An example recipe could look like this: The keys are explained in the ESMValCore documentation, in **The recipe format** section under - `Overview `_. + :ref:`Overview `. A collection of diagnostics for reproducible climate science From ec56105e1a8805a288209cff8ae62d4fbdbd13c2 Mon Sep 17 00:00:00 2001 From: Lisa Bock Date: Fri, 14 Aug 2026 07:57:18 +0200 Subject: [PATCH 05/17] Update doc/sphinx/source/tutorials/episode_1.rst Co-authored-by: Felicity Chun <32269066+flicj191@users.noreply.github.com> --- doc/sphinx/source/tutorials/episode_1.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/sphinx/source/tutorials/episode_1.rst b/doc/sphinx/source/tutorials/episode_1.rst index cce03af8ec..9e77cab964 100644 --- a/doc/sphinx/source/tutorials/episode_1.rst +++ b/doc/sphinx/source/tutorials/episode_1.rst @@ -122,7 +122,7 @@ results. .. admonition:: Explore the available recipes :class: admonition-todo - Go to the `ESMValTool documentation `_ + Go to the :doc:`ESMValTool documentation ` and explore the **Recipes** section in the sidebar. Which recipe(s) would you like to try? From 6858395aff1a33745a1478b07bb305ba884f4536 Mon Sep 17 00:00:00 2001 From: Lisa Bock Date: Fri, 14 Aug 2026 17:32:00 +0200 Subject: [PATCH 06/17] add tutorial overview and setup --- doc/sphinx/source/tutorials/episode_1.rst | 2 +- doc/sphinx/source/tutorials/index.rst | 16 +- .../source/tutorials/tutorial_overview.rst | 104 ++++++ .../source/tutorials/tutorial_setup.rst | 303 ++++++++++++++++++ 4 files changed, 416 insertions(+), 9 deletions(-) create mode 100644 doc/sphinx/source/tutorials/tutorial_overview.rst create mode 100644 doc/sphinx/source/tutorials/tutorial_setup.rst diff --git a/doc/sphinx/source/tutorials/episode_1.rst b/doc/sphinx/source/tutorials/episode_1.rst index 9e77cab964..10474e0def 100644 --- a/doc/sphinx/source/tutorials/episode_1.rst +++ b/doc/sphinx/source/tutorials/episode_1.rst @@ -1,4 +1,4 @@ -.. _epsiode_0: +.. _epsiode_1: Introduction ===================== diff --git a/doc/sphinx/source/tutorials/index.rst b/doc/sphinx/source/tutorials/index.rst index 800f3a65b3..4bf53a81c2 100644 --- a/doc/sphinx/source/tutorials/index.rst +++ b/doc/sphinx/source/tutorials/index.rst @@ -5,6 +5,8 @@ Tutorials A tutorial is available on https://tutorial.esmvaltool.org. +A tutorial is available on :doc:`ESMValTool Tutorial `. + Learning resources ------------------ @@ -21,13 +23,11 @@ While these are tailored for ACCESS users, they are still very informative. .. and a filename is added .. (test by replacing '' with 'template'). - -ESMValTool Tutorial -------------------- - .. toctree:: - :maxdepth: 1 - :numbered: - :caption: Basic episodes + :hidden: + :maxdepth: 2 + :caption: ESMValTool Tutorial - episode_1 + Overview + Setup + Introduction diff --git a/doc/sphinx/source/tutorials/tutorial_overview.rst b/doc/sphinx/source/tutorials/tutorial_overview.rst new file mode 100644 index 0000000000..7efe35df08 --- /dev/null +++ b/doc/sphinx/source/tutorials/tutorial_overview.rst @@ -0,0 +1,104 @@ +.. _tutorial_overview: + +ESMValTool Tutorial +=================== + +This tutorial helps you to use ESMValTool. + +The Earth System Model Evaluation Tool (ESMValTool) is a community developed +software toolkit that aims to facilitate the diagnosis and evaluation of the +causes and effects of model biases and inter-model spread within the CMIP model +ensemble. + +This tutorial is structured into ``basic`` and ``advanced`` topics such that +episodes starting from the **Introduction** up to the episode on **Conclusion +of the basic tutorial** all cover basic topics and can be done in one sitting. + +The remaining episodes cover the ``advanced`` topics and each episode is a +mini-tutorial covering an advanced aspect of working with ESMValTool. These +mini-tutorials can be appended to the main tutorial or worked through +independently. + +.. admonition:: What will you learn in this course + :class: note + + * What is ESMValTool + * How to install ESMValTool + * How to configure ESMValTool for your local system + * How to run ESMValTool + * How to work with ESMValTool's suite of preprocessors + * How to debug your recipes + * How to access and deploy recipes from the ESMValTools gallery (Advanced) + * How to develop your own diagnostics and recipes (Advanced) + * How to contribute your recipes and diagnostics back into ESMValTool + (Advanced) + * How to include new observational datasets (Advanced) + * How to handle errors and warnings (Advanced) + * How to use ESMValCore API with Jupyter notebooks (Advanced) + +.. admonition:: Prerequisites + :class: important + + The prerequisites for the tutorial are listed on the :doc:`tutorial setup + page `. + +Main things you need to know before starting this course +-------------------------------------------------------- + +1. This tutorial can be taken online independently or taught by one of our + instructors. +2. Don't be alarmed if you can't work through the entire tutorial in one + sitting. It may take some time to get used to working with ESMValTool. +3. If you get stuck, help is always available from the tutors, from ESMValTool + developers via the `github issues page + `_ + or via the `ESMValTool discussion page + `_. +4. This tutorial includes several advanced lessons after the conclusion. These + advanced lessons should be treated like “mini-tutorials”, and include aspects + like **Developing your own diagnostic** or **How to include observations**. + +.. admonition:: Additional resources + :class: note + + * :doc:`Documentation <\index>` + * `ESMValTool home page `_ + * `ESMValTool discussion page + `_ + * `Publications `_ + * `ESMValTool Source code `_ + * `ESMValCore Source code `_ + * **?** `ESMValTool Citation info + `_ + +How to site the tutorial +------------------------ + +**?** Please use citation information available at +https://doi.org/10.5281/zenodo.3974591. + +Schedule +-------- + +.. tabularcolumns:: |p{3cm}|p{5cm}|p{3cm}| + ++--------+----------------------------------+----------------------------------------+ +| | :doc:`Setup ` | Download files required for the lesson | ++--------+----------------------------------+----------------------------------------+ +|| 00:00 || :doc:`episode_1` || What is ESMValTool? | +|| || || Who are the people behind ESMValTool? | ++--------+----------------------------------+----------------------------------------+ +| | Quickstart guide | | ++--------+----------------------------------+----------------------------------------+ +| | Installation | | ++--------+----------------------------------+----------------------------------------+ +| | Configuration | | ++--------+----------------------------------+----------------------------------------+ +| | Running your first recipe | | ++--------+----------------------------------+----------------------------------------+ +| | Conclusion of the basic tutorial | | ++--------+----------------------------------+----------------------------------------+ + + +The actual schedule may vary slightly depending on the topics and exercises +chosen by the instructor. diff --git a/doc/sphinx/source/tutorials/tutorial_setup.rst b/doc/sphinx/source/tutorials/tutorial_setup.rst new file mode 100644 index 0000000000..1410e47f1a --- /dev/null +++ b/doc/sphinx/source/tutorials/tutorial_setup.rst @@ -0,0 +1,303 @@ +.. _tutorial_setup: + +ESMValTool Tutorial: Preparations for participating in the tutorial +=================================================================== + +This page includes some information on how to prepare for participating in this +tutorial. + +.. admonition:: Prerequisites + :class: important + + *Minimal requirements:* + + * Basic understanding of your preferred command line interface (for example + a bash terminal) + * Access to CMIP data + + *Optional, but useful:* + + * Basic understanding of git + * Access to a suitable computing system (for example CEDA-Jasmin or + DKRZ-Mistral) + * GitHub account + + +Command line & git tutorials +----------------------------- + +We typically use the command line to interact with ESMValTool. While most of us +are likely to have experience with the command line, novices may want to work +through the Software Carpentry Unix Shell course. + +* Command line: `Software Carpentry Shell Novice + `_ + +Git is a distributed version-control system for tracking changes in source code +during software development. It is how we distribute, share, and manage the +ESMValTool code. + +* git: `Software Carpentry Git Novice + `_ + + +Access to CMIP and observational data and a suitable compute cluster +--------------------------------------------------------------------- + +To complete this tutorial and use ESMValTool, you will need access to data in a +reasonable format. Some data will be provided, but there is simply too much +data available for your tutors to make it all available directly. + +ESMValTool may be run on multiple platforms, from your local machine to large +computing clusters. The best option is to use a computing cluster with an +`Earth System Grid Federation (ESGF) node `_. +The benefit of using a compute cluster with an ESGF node is that the +`Coupled Model Intercomparison Project (CMIP) +`_ is +locally stored on disk and accessible directly by the tool. Similarly, +observational data would also be available at these sites. + +The ESGF also hosts observations for Model Intercomparison Projects (obs4MIPs) +and reanalyses data (ana4MIPs). + +Here are a few options for compute clusters with ESGF nodes: + +* :ref:`ceda-jasmin` +* :ref:`dkrz` + +For more information see: + +* `CMIP5 `_ and + `CMIP6 `_ data obey the + `CF conventions `_. Available variables can be + found under the `CMIP5 data request + `_ and the + `CMIP6 Data Request `_. +* List of all `CMIP named variables + `_. +* List of all `ESGF nodes `_. +* A good `tutorial + `_ + on how to search and download CMIP data from ESGF nodes. +* `Exploring climate model data + `_ on + infrastructure for the European network for Earth system modelling. + + +.. _ceda-jasmin: + +CEDA-Jasmin (UK) +~~~~~~~~~~~~~~~~ + +Please skip this section if you are not going to use JASMIN and continue to the +:ref:`github-account-advanced` section. + +If you do not already have an account on JASMIN, then request an account as +soon as possible. Please follow the steps below (also documented in detail +here: `Essential steps to gain login access to JASMIN +`_). + +* Generate an `SSH key + `_ +* Get a `JASMIN portal account + `_ +* Get a `jasmin-login account + `_ + +Note that the JASMIN portal is only an account for the web interface. A +jasmin-login account is also required. + +Also note that if you are working from home, JASMIN may not be directly +accessible from your home. You may need to use SSH to connect to a machine in +your institute and then on to JASMIN. Please test your connection before the +tutorial. + +Here are some further, general resources for `getting started with JASMIN +`_. + +Access to data on JASMIN +^^^^^^^^^^^^^^^^^^^^^^^^ + +Please request access to the working groups: + +* `esmeval working group + `_ +* `CMIP5 data + `_ + +Once you have access to the data archive on CEDA, make sure to link your CEDA +and JASMIN accounts. This can be done by checking the link to CEDA box on `your +JASMIN profile page `_. + +The linking may take a few hours to take effect and is necessary for you to +access the BADC archives via JASMIN. Some CMIP5 data sets such as MIROC are not +accessible by default and special permission has to be requested to access them +via `the CEDA catalogue page `_. + +Test your setup +^^^^^^^^^^^^^^^ + +Log into jasmin-login: + +.. code-block:: bash + + ssh -X JASMIN-USERNAME@login1.jasmin.ac.uk + +Then log into the sci1 machine: + +.. code-block:: bash + + ssh -X jasmin-sci1 + +Can you see the following locations: + +.. code-block:: bash + + ls /gws/ssde/j25a/esmeval/obsdata-v2/ + ls /badc/cmip5/data/cmip5/output1/MOHC/HadGEM2-ES + ls /badc/cmip6/data/CMIP6/CMIP/*/*/historical/r1i1p1f?/Omon/[ts]os/gn/latest/*.nc + +Note that JASMIN is only open to certain locations (mostly universities and +research centres). You may need a VPN if you wish to connect from your home +network. + +Congratulations! Please continue to the :ref:`github-account-advanced` section +next. + + +.. _dkrz: + +DKRZ (Germany) +~~~~~~~~~~~~~~ + +Please skip this section if you are not going to use DKRZ and continue to the +:ref:`github-account-advanced` section. + +If you do not already have an account at the DKRZ, then `register +`_ as soon as possible. You could find a +short introduction on how to get started at DKRZ `here +`_. + +There is also a `user manual `_ +for Levante, which is DKRZ's current supercomputer. + +Join a project +^^^^^^^^^^^^^^ + +To use the resources on DKRZ you have to join a project. One option is to join +an existing project by logging into `https://luv.dkrz.de/ +`_ with your account and selecting ``Join existing +project``. Once you are accepted by the manager of your chosen project, your +web account will be turned into a full LDAP account which will allow you to log +into and use the DKRZ resources. If you do not have access to an existing +project, another option for you would be to apply for resources at DKRZ. Here +are some instructions on `how to apply for resources +`_. + +Access to data on DKRZ +^^^^^^^^^^^^^^^^^^^^^^ + +CMIP5 and CMIP6 data are available in these directories: + +* CMIP5: ``/work/kd0956/CMIP5/data/cmip5/output1/`` +* CMIP6: ``/work/ik1017/CMIP6/data/CMIP6/CMIP/`` + +Test your setup +^^^^^^^^^^^^^^^ + +Log into Levante (DKRZ): + +.. code-block:: bash + + ssh -X user-account@levante.dkrz.de + +Additional information +^^^^^^^^^^^^^^^^^^^^^^ + +Login nodes are for compiling and job submission only. For all other tasks, you +can use the `interactive partition +`_ +or start an `interactive session +`_. + +Data storage: + +* Personal data: home directory (30 GiB) +* Project data: ``/work/project_id/username`` +* Temporary data: scratch directory on ``/scratch/*/username`` is automatically + deleted after 14 days (15 TiB). Please use this directory for all your + testing; do not use the work directory for tests. See also `this page + `_. + +Running batch jobs: information and examples on the SLURM job scheduling system +at DKRZ can be found `here +`_. + +Congratulations! Please continue to the :ref:`github-account-advanced` section +next. + + +Using your own machine +---------------------- + +Please skip this section if you are not going to use ESMValTool on your local +machine and continue to the :ref:`github-account-advanced` section. + +If you are planning on running ESMValTool on your own machine, please make sure +that you are able to download CMIP data and that you have a few GB of space +available to install conda and ESMValTool, but also enough to make a copy of +some data (about 125 MB) needed for this tutorial. + +You can use ESMValTool to automatically download data needed for test recipes. +Please see the Configuration episode or the configuration file documentation +for more information. This is the recommended option as it has the advantage +that data is stored in subdirectories, and features such as wildcards and +recording the version of the data will work automatically. + +Alternatively, you can run the following command using `wget +`_: + +.. code-block:: shell + + wget --no-clobber --input-file \ + https://github.com/ESMValGroup/ESMValTool_Tutorial/raw/main/data/dataset.urls \ + --directory-prefix $HOME/esmvaltool_tutorial/data/ + + +.. _github-account-advanced: + +GitHub account (Advanced) +------------------------- + +You do not need a GitHub account to participate in the tutorial. However, if +you want to raise an issue, contribute to the discussions, or share your code, +please `create a GitHub account `_. + +To learn how to use GitHub, please have a look at this `introduction to GitHub +`_. + +You may hear a few of the following phrases during the tutorial. Do not be +alarmed; they will make sense eventually. + +GitHub issues +~~~~~~~~~~~~~ + +Issues are GitHub's ticketing system. They allow users and developers to +discuss problems, identify bugs, or make suggestions. Each issue is assigned a +number and will have its own page on GitHub. + +Here is an explanation of the `GitHub issues +`_. + +Raising an issue is the act of creating a new issue. If you are asked to raise +an issue, please follow any instructions that you are given, and also make sure +that you read the default issue text. + +GitHub pull requests +~~~~~~~~~~~~~~~~~~~~ + +A GitHub pull request is the act of requesting that a branch is merged with +another branch. + +This is an advanced feature of GitHub, and will generally be performed by the +ESMValTool development team. From f2de48ed6d9d3637e706e84771c7c81442b2a6a6 Mon Sep 17 00:00:00 2001 From: Lisa Bock Date: Thu, 20 Aug 2026 13:14:25 +0200 Subject: [PATCH 07/17] small fixes --- doc/sphinx/source/tutorials/tutorial_setup.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/sphinx/source/tutorials/tutorial_setup.rst b/doc/sphinx/source/tutorials/tutorial_setup.rst index 1410e47f1a..9e2e53ae45 100644 --- a/doc/sphinx/source/tutorials/tutorial_setup.rst +++ b/doc/sphinx/source/tutorials/tutorial_setup.rst @@ -1,7 +1,7 @@ .. _tutorial_setup: -ESMValTool Tutorial: Preparations for participating in the tutorial -=================================================================== +Setup: Preparations for participating in the tutorial +===================================================== This page includes some information on how to prepare for participating in this tutorial. @@ -70,7 +70,7 @@ For more information see: * `CMIP5 `_ and `CMIP6 `_ data obey the `CF conventions `_. Available variables can be - found under the `CMIP5 data request + found under the `CMIP5 Data Request `_ and the `CMIP6 Data Request `_. * List of all `CMIP named variables From d957a25c7fa3f90d74cd554dc450cb9d2328858d Mon Sep 17 00:00:00 2001 From: Lisa Bock Date: Thu, 20 Aug 2026 13:20:41 +0200 Subject: [PATCH 08/17] small fix --- doc/sphinx/source/tutorials/tutorial_setup.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/sphinx/source/tutorials/tutorial_setup.rst b/doc/sphinx/source/tutorials/tutorial_setup.rst index 9e2e53ae45..d85963ae8f 100644 --- a/doc/sphinx/source/tutorials/tutorial_setup.rst +++ b/doc/sphinx/source/tutorials/tutorial_setup.rst @@ -175,7 +175,7 @@ Please skip this section if you are not going to use DKRZ and continue to the If you do not already have an account at the DKRZ, then `register `_ as soon as possible. You could find a -short introduction on how to get started at DKRZ `here +short introduction on how to get started at DKRZ `in the documentation `_. There is also a `user manual `_ From 380a1019121d755c2d9bf9c7d57a6680d9205d57 Mon Sep 17 00:00:00 2001 From: Lisa Bock Date: Thu, 20 Aug 2026 13:36:37 +0200 Subject: [PATCH 09/17] citation info --- doc/sphinx/source/tutorials/tutorial_overview.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/doc/sphinx/source/tutorials/tutorial_overview.rst b/doc/sphinx/source/tutorials/tutorial_overview.rst index 7efe35df08..e2f7ada4cd 100644 --- a/doc/sphinx/source/tutorials/tutorial_overview.rst +++ b/doc/sphinx/source/tutorials/tutorial_overview.rst @@ -68,13 +68,12 @@ Main things you need to know before starting this course * `Publications `_ * `ESMValTool Source code `_ * `ESMValCore Source code `_ - * **?** `ESMValTool Citation info - `_ + * `ESMValTool Citation info `_ How to site the tutorial ------------------------ -**?** Please use citation information available at +Please use citation information available at https://doi.org/10.5281/zenodo.3974591. Schedule From 99165ba6d92aedb6c3ec6c4da9edeca21c14f258 Mon Sep 17 00:00:00 2001 From: Lisa Bock Date: Fri, 18 Sep 2026 11:19:48 +0200 Subject: [PATCH 10/17] automated fixes --- doc/sphinx/source/tutorials/index.rst | 2 -- doc/sphinx/source/tutorials/tutorial_overview.rst | 5 +++-- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/doc/sphinx/source/tutorials/index.rst b/doc/sphinx/source/tutorials/index.rst index 4bf53a81c2..d0ebdbc6e2 100644 --- a/doc/sphinx/source/tutorials/index.rst +++ b/doc/sphinx/source/tutorials/index.rst @@ -3,8 +3,6 @@ Tutorials ========= -A tutorial is available on https://tutorial.esmvaltool.org. - A tutorial is available on :doc:`ESMValTool Tutorial `. Learning resources diff --git a/doc/sphinx/source/tutorials/tutorial_overview.rst b/doc/sphinx/source/tutorials/tutorial_overview.rst index e2f7ada4cd..706fa0b71d 100644 --- a/doc/sphinx/source/tutorials/tutorial_overview.rst +++ b/doc/sphinx/source/tutorials/tutorial_overview.rst @@ -70,7 +70,7 @@ Main things you need to know before starting this course * `ESMValCore Source code `_ * `ESMValTool Citation info `_ -How to site the tutorial +How to cite the tutorial ------------------------ Please use citation information available at @@ -100,4 +100,5 @@ Schedule The actual schedule may vary slightly depending on the topics and exercises -chosen by the instructor. +chosen by the instructor and how fast you work your way through the different +episodes. From a89ab550792c370eda6b78cad1e6557a71abd234 Mon Sep 17 00:00:00 2001 From: Lisa Bock Date: Fri, 18 Sep 2026 15:25:56 +0200 Subject: [PATCH 11/17] rename file episode 1 --- .../tutorials/{episode_1.rst => episode_1_introduction.rst} | 0 doc/sphinx/source/tutorials/tutorial_overview.rst | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename doc/sphinx/source/tutorials/{episode_1.rst => episode_1_introduction.rst} (100%) diff --git a/doc/sphinx/source/tutorials/episode_1.rst b/doc/sphinx/source/tutorials/episode_1_introduction.rst similarity index 100% rename from doc/sphinx/source/tutorials/episode_1.rst rename to doc/sphinx/source/tutorials/episode_1_introduction.rst diff --git a/doc/sphinx/source/tutorials/tutorial_overview.rst b/doc/sphinx/source/tutorials/tutorial_overview.rst index 706fa0b71d..0eb9713719 100644 --- a/doc/sphinx/source/tutorials/tutorial_overview.rst +++ b/doc/sphinx/source/tutorials/tutorial_overview.rst @@ -84,7 +84,7 @@ Schedule +--------+----------------------------------+----------------------------------------+ | | :doc:`Setup ` | Download files required for the lesson | +--------+----------------------------------+----------------------------------------+ -|| 00:00 || :doc:`episode_1` || What is ESMValTool? | +|| 00:00 || :doc:`episode_1_introduction` || What is ESMValTool? | || || || Who are the people behind ESMValTool? | +--------+----------------------------------+----------------------------------------+ | | Quickstart guide | | From 80f887db68a2e3037443f3f486a0476b15190c02 Mon Sep 17 00:00:00 2001 From: Lisa Bock Date: Fri, 18 Sep 2026 15:41:46 +0200 Subject: [PATCH 12/17] initial version of episode 2 --- .../source/tutorials/episode_2_quickstart.rst | 154 ++++++++++++++++++ doc/sphinx/source/tutorials/index.rst | 3 +- .../source/tutorials/tutorial_overview.rst | 2 +- 3 files changed, 157 insertions(+), 2 deletions(-) create mode 100644 doc/sphinx/source/tutorials/episode_2_quickstart.rst diff --git a/doc/sphinx/source/tutorials/episode_2_quickstart.rst b/doc/sphinx/source/tutorials/episode_2_quickstart.rst new file mode 100644 index 0000000000..c6ada39023 --- /dev/null +++ b/doc/sphinx/source/tutorials/episode_2_quickstart.rst @@ -0,0 +1,154 @@ +.. _episode_2_quickstart: + +Quickstart guide +================ + +.. admonition:: Overview + :class: note + + .. grid:: 2 + :gutter: 1 + :margin: 3 3 0 5 + + .. grid-item-card:: Timings + :columns: 12 + + * Teaching: 2 min + * Exercises: 8 min + + .. grid-item-card:: 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? + + .. grid-item-card:: Learning outcomes + + * Understand the purpose of the quickstart guide + * Load and check the ESMValTool environment + * Configure ESMValTool + * Run a recipe + + .. grid-item-card:: Compatibility + :columns: 12 + + ESMValTool v2.15.0 + + +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 minimum number of changes. + +.. admonition:: Purpose of the quickstart guide + :class: discussion + + The purpose of this quickstart guide is to get you running with ESMValTool + as quickly as possible without requiring a full tutorial walkthrough. + + +How do I load and check the ESMValTool environment? +--------------------------------------------------- + +For this quickstart guide, it is assumed that ESMValTool has already been +installed at the site where it will be run. If this is not the case, see the +:doc:`Installation ` episode in this tutorial. + +Load the ESMValTool environment by following the instructions in the +`ESMValTool installation and environment activation guide +`_. This usually involves loading a module such as: + +.. code-block:: bash + + module load esmvaltool + +Check the ESMValTool environment by accessing the help for ESMValTool: + +.. code-block:: bash + + esmvaltool --help + +.. admonition:: Check the ESMValTool environment + :class: admonition-todo + + Run the command above to confirm that your ESMValTool environment is loaded + correctly and that the command-line interface is available. + + +How do I configure ESMValTool? +------------------------------ + +Create the ESMValTool user configuration file. By default, this file is written +to ``~/.config/esmvaltool/config-user.yml``: + +.. code-block:: bash + + esmvaltool config copy defaults/config-user.yml + +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 +:doc:`Configuration ` episode in this tutorial. + +.. admonition:: Configure the tool + :class: admonition-todo + + Create the user configuration file and adjust the settings for the machine on + which you are running ESMValTool. + + +How do I run a recipe? +--------------------- + +Run the example Python recipe: + +.. code-block:: bash + + esmvaltool run examples/recipe_python.yml + +Wait for the recipe to complete. If the recipe completes successfully, the last +line printed to the screen at the end of the log will look something like: + +.. code-block:: 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 the screen near the end of the log: + +.. code-block:: bash + + YYYY-MM-DD HH:mm:SS, NNN UTC [NNNNN] INFO Wrote recipe output to: + file:///$HOME/esmvaltool_output/recipe_python__