Tutorial

So, you are planning to use the Earth Diagnostics? You don’t know how to use them? This is the place to go. From now on this tutorial will guide you through all the process from installation to running.

Hint

If you have any problem with this tutorial, please report it to <javier.vegas@bsc.es> so it can be corrected. A lof of people will benefit from it.

Installation

If you have access to the BSC-ES machines, you don’t need to install it. Just use the available module:

In case that you need a custom installation for development or can not use the BSC-ES machines, install it from BSC-ES GitLab repository:

pip install git+https://earth.bsc.es/gitlab/es/ocean_diagnostics.git

You will also need

  • CDO version 1.7.2 (other versions could work, but this is the one we use)
  • NCO version 4.5.4 or newer
  • Python 2.7 or newer (but no 3.x) with bscearth.utils, CDO and NCO packages, among others.
  • Access to CDFTOOLS_3.0 executables for BSC-ES. The source code is available on Github (https://github.com/jvegasbsc/CDFTOOLS) and it can be compiled with CMake

Creating a config file

Go to the folder where you installed the EarthDiagnostics. You will see a folder called earthdiagnostics, and, inside it, the model_diags.conf file that can be used as a template for your config file. Create a copy of it wherever it suites you.

Now open your brand new copy with your preferred text editor. The file contains commentaries explaining each one of its options, so read it carefully and edit whatever you need. Don’t worry about DIAGS option, we will talk about it next.

After this, you need to choose the diagnostics you want to run. For a simple test, it’s recommended to use the monmean diagnostic to compute monthly means from daily data. We recommend it because it can be used with any variable, the user has to provide parameters but they are quite intuitive and it’s relatively fast to compute. If your experiment does not have daily data, you can use any other diagnostic. Check next section for a list of available diagnostics and choose whichever suits you better. From now on, we will assume that you are going to run the monmean diagnostic.

Hint

For old Ocean Diagnostics users: you can use most of the old names as aliases to launch one or multiple diagnostics. Check the ALIAS section on the model_diags.conf to see which ones are available.

First, choose a variable that has daily data. Then replace the DIAGS option with the next one where $VARIABLE represents the variable’s name and $DOMAIN its domain (atmos, ocean, seaice, landice…)

DIAGS = monmean,$DOMAIN,$VARIABLE

Prepare the run script

Once you have configured your experiment you can execute any diagnostic with the provided model_launch_diags.sh script. Create a copy and change the variable PATH_TO_CONF_FILE so it points to your conf file .

Now, execute the script (or submit it to bsceslogin01, it has the correct header) and… that’s it! You will find your results directly on the storage and a folder for the temp files in the scratch named after the EXPID.