diff --git a/docs/model_evaluation/model_evaluation_on_gadi/model_evaluation_on_gadi_ilamb.md b/docs/model_evaluation/model_evaluation_on_gadi/model_evaluation_on_gadi_ilamb.md index 41e34eeac..b3497e70a 100644 --- a/docs/model_evaluation/model_evaluation_on_gadi/model_evaluation_on_gadi_ilamb.md +++ b/docs/model_evaluation/model_evaluation_on_gadi/model_evaluation_on_gadi_ilamb.md @@ -1,117 +1,86 @@ -# Tutorial for using `ilamb` on Gadi@NCI +# `ilamb` on Gadi at NCI -This tutorial explains how you can setup and run International Land Model Benchmarking (ILAMB) and International Ocean Model Benchmarking (IOMB) tests on `NCI` infrastracture. Both projects are maintained as `python` code under the package name `ilamb`. +ACCESS-NRI is maintaining a version of the `python` package `ilamb` for International Land Model Benchmarking (ILAMB) and International Ocean Model Benchmark (IOMB) on Gadi at the National Compuational Infrastructure (NCI). -The Tutorial contains: - -1. [Background](#1-background-international-land-model-benchmarking-ilamb-and-international-ocean-model-benchmarking-iomb) -2. [Installation guide](#2-installing-ilamb) -3. [Setup details](#3-configuring-ilamb) -4. [Run `ilamb`](#4-run-ilamb) -5. [Run `liamb` on `NCI`](#5-run-ilamb-on-nci) -6. [Fix your setup with `ilamb-doctor`](#6-fix-your-interactive-setup-with-ilamb_doctor) - -## 1. Background: International Land Model Benchmarking (ILAMB) and International Ocean Model Benchmarking (IOMB) - -As earth system models (ESMs) become increasingly complex, there is a growing need for comprehensive and multi-faceted evaluation of model projections. The International Land Model Benchmarking (ILAMB) project is a model-data intercomparison and integration project designed to improve the performance of land models and, in parallel, improve the design of new measurement campaigns to reduce uncertainties associated with key land surface processes. - -If you have used (and installed) `ilamb` on NCI and know the basic principle of `ilamb`, you can start from [Section 5) Guide for using ilamb on NCI](#5-guide-for-use-on-nci). - -## 2. Installing `ilamb` - -For NCI users, ACCESS-NRI is providing a `conda` environment called `ilamb_dev` through the `xp65` project, with ilamb installed. You can load and activate it via: +Here, we provide a quick tutorial on how use `ilamb` on Gadi. We assume that you already have access to Gadi, logged onto Gadi via secure shell (ssh) and loaded our `access-med` `conda` environment (if not, follow [these instructions](../model_evaluation_getting_started/index.md)). +All you need are configuration files and paths for models and data (we show you how to set up all necessary steps and options below). You should then be able to execute `ilamb` with the following command: ``` ->>> module use /g/data/xp65/public/modules ->>> module load conda/ilamb_dev ->>> conda activate ilamb_dev +ilamb-run --config config.cfg --model_root $ILAMB_ROOT/MODELS --regions global ``` +This will create output files that you can load as a html website via the prompt +``` +python -m http.server +``` +This command will show you which port the browser is sending output to (for example http://0.0.0.0:8000/). Opening this link in your browser will show a summary table of the `ilamb` runs in the center, which will look similar to this minimum example: -We will soon add `ilamb` also to the ACCESS-NRI MED `conda` environment, `access-med` under project`xp65`. - -If you want to install `ilamb` yourself, please follow the official installation instructions at [https://www.ilamb.org/doc/install.html](https://www.ilamb.org/doc/install.html). - -## 3. Configuring `ilamb` +

Starting side of ilamb output

-Before you can run `ilamb`, you need to configure a few things: +Clicking on a row of the table will expand it to reveal the underlying datasets used. Clicking on CERES, for example, will take you to another page which presents detailed scores and plots: -3.1. [Organise the ILAMB_ROOT path](#31-organise-the-ilamb_root-path) -3.2. [Set up a `config` file](#32-set-up-a-config-file) -3.3. [Set up a `modelroute` and `regions` files](#33-set-up-modelroute-and-regions-files) (Optional, if you want to run only a subset of models and/or specific regions of the world) -3.4. [Download a `shapefiles` files locally](#33-download-a-shapefiles-files-locally) (Optional online, necessary offline e.g. on NCI compute nodes) +

Detailed output of Surface Upward SW Radiation Benchmarking

-### 3.1 Organise the ILAMB_ROOT path +## 1 Prerequisites -`ilamb` demands files to be organised in a specific directory structure of `DATA` and `MODELS`. +In this tutorial, we are specifically explaining how to use `ilamb` on NCI's Gadi. If you want to install and adjust `ilamb` locally, please follow the official installation instructions at [https://www.ilamb.org/doc/install.html](https://www.ilamb.org/doc/install.html). +### 1.1 $ILAMB_ROOT - -If you do not have your own files yet, you can download and use [example files](https://www.ilamb.org/Downloads/minimal_ILAMB_data.tgz) provided as part of the of `ilamb`'s [*First Steps* Tutorial](https://www.ilamb.org/doc/first_steps.html) +In our default setup, we will place ILAMB_ROOT and the shapefiles for cartopy directly in the home directory. After logging onto Gadi, you have to create the ILAMB_ROOT directory +``` +mkdir $PWD/ILAMB_ROOT +mkdir $ILAMB_ROOT/DATA +mkdir $ILAMB_ROOT/MODELS +``` -The following tree represents the organization of the contents of this extracted sample data (Note: We renamed the main directory name): +You can then simply export their paths after login as: ``` -$ILAMB_ROOT (renamed from "ILAMB_sample") -├── sample.cfg (see [Section 3.2](#32-set-up-a-config-file)) -├── modelroute.txt (optional, see [Section 3.3](#33-set-up-modelroute-and-regions-files)) -├── regions.txt (optional, see [Section 3.3](#33-set-up-modelroute-and-regions-files)) -├── DATA -│ ├── albedo -│ │ └── CERES -│ │ └── albedo_0.5x0.5.nc -│ └── rsus -│ └── CERES -│ └── rsus_0.5x0.5.nc -└── MODELS - └── CLM40cn - ├── rsds - │ └── rsds_Amon_CLM40cn_historical_r1i1p1_185001-201012.nc - └── rsus - └── rsus_Amon_CLM40cn_historical_r1i1p1_185001-201012.nc +export ILAMB_ROOT=$PWD/ILAMB_ROOT +export CARTOPY_DATA_DIR=/g/data/xp65/public/apps/cartopy-data ``` -There are two main branches in this directory. The first is the `DATA` directory–this is where we keep the observational datasets each in a subdirectory bearing the name of the variable. While not strictly necesary to follow this form, it is a convenient convention. The second branch is the `MODEL` directory in which we see a single model result from CLM. +You can of course change the path of the directory, but will need to take this into account for the PBS job by adding a command to change into the $ILAMB_ROOT directory (see [PBS setup comments](https://github.com/svenbuder/ILAMB-workflow/edit/main/ilamb_note.md#52-portable-batch-system-pbs-jobs-on-nci)). -#### 3.1.1 Add files to DATA +### 1.2 ILAMB_ROOT/DATA -There is a lot of DATA available to add. Take a look at https://www.ilamb.org/ILAMB-Data/ and https://www.ilamb.org/IOMB-Data/ for extensive lists for ILAMB-Data (land modelling) and IOMB-Data (ocean modelling). +An extensive colletion of DATA is provided in the `kj13` project. You need to have [joined the project on NCI](https://my.nci.org.au/mancini/project-search) to get access to this data. -`ilamb` has a commandline prompt to add new DATA in a substructure. To fetch all available DATA from the website, you can simply go to your $ILAMB_ROOT and type -``` ->>> ilamb-fetch +To create a symbolic link to this data, use the bash command ``` - -The command will compare the above website with your current DATA and make suggestions for downloads: +ln -s /g/data/kj13/datasets/ilamb/DATA/* $ILAMB_ROOT/DATA/ +ln -s /g/data/kj13/datasets/iomb/DATA/* $ILAMB_ROOT/DATA/ ``` -Comparing remote location: - - https://www.ilamb.org/ILAMB-Data/ - -To local location: +Note that the directory `WOA2018` is an overlapping catalog (you can ignore the warning that a link already exists). +For more information on the data sets, please visit the the `ilamb` [dataset website](https://www.ilamb.org/datasets.html). - ./ +### 1.3 ILMAB_ROOT/MODEL -I found the following files which are missing, out of date, or corrupt: +Similar to the observational data, we recommend to create symbolic link to model data within the $ILAMB_ROOT/MODEL directory. You can find models by searching our currated `intake` catalog [here](../model_evaluation_model_catalogs/index.md). To add model data (in our example models of the ACCESS-ESM1.5) for the analysis with `ilamb`, you need to do the following: +``` +ln -s /g/data/fs38/publications/CMIP6/CMIP/CSIRO/ACCESS-ESM1-5/historical/r* $ILAMB_ROOT/MODELS +``` - .//DATA/twsa/GRACE/twsa_0.5x0.5.nc - .//DATA/rlus/CERES/rlus_0.5x0.5.nc - ... (we have abbreviated the extensive list here) +This will allow you, to simply use the `--model_root $ILAMB_ROOT/MODELS` keyword when using `ilamb`. -Download replacements? [y/n] +Note that these different models have a lot of subdirectories, which are important to keep in mind when defining the `source` parameter in your `ilamb` `.cfg` file. Note that the `ilamb` files will end with `*.nc*. For example, one of the *rsus* files for run `r10i1p1f1` can be found (and used for `.cfg` under ``` - -You can use `ilamb-fetch -h` to see how you can adjust the remote and local locations. If you want to download IOMB-Data, you can for example use +source = /g/data/fs38/publications/CMIP6/CMIP/CSIRO/ACCESS-ESM1-5/historical/r1i1p1f1/Amon/rsus/gn/files/d20191115/rsus_Amon_ACCESS-ESM1-5_historical_r1i1p1f1_gn_185001-201412.nc ``` -ilamb-fetch --remote_root https://www.ilamb.org/IOMB-Data/ +or shorter +``` +source = $ILAMB_ROOT/MODELS/r1i1p1f1/Amon/rsus/gn/files/d20191115/rsus_Amon_ACCESS-ESM1-5_historical_r1i1p1f1_gn_185001-201412.nc ``` +## 2 Setup Files + +At the beginning, we showed you the default call of `ilamb` via +``` +ilamb-run --config config.cfg --model_setup modelroute.txt --regions regions.txt +``` -#### 3.1.2 Add files to MODEL - -If you want to add your own `MODEL` to `ilamb`, you can do so by following [this description](https://www.ilamb.org/doc/add_model.html). - -For `NCI` users, our `ilamb_dev` `conda` enrivonment already provides all observational datasets from the `ilamb` official web and the [ACCESS-ESM1_5](https://access-hive.org.au/configurations/access-esm/) model result for user at `ILAMB_ROOT`. Stay tune for more observational and model data or tell us which ones we should definitely add. +Here, we explain how you can setup all these files that are called via `--config`, `--model_setup`, and `--regions`. -### 3.2 Set up a `config` file +### 2.1 `config` files Now that we have the data, we need to setup a `config` file which the `ilamb` package will use to initiate a benchmark study. @@ -119,7 +88,7 @@ Now that we have the data, we need to setup a `config` file which the `ilamb` pa Below we explain both which variables you can define, but start by showing you the minimum setup from the [tutorial's](https://www.ilamb.org/doc/first_steps.html). `sample.cfg` [file](https://github.com/rubisco-sfa/ILAMB/blob/master/src/ILAMB/data/sample.cfg): -#### Minimum configure file with a direct and a derived variable +**Minimum configure file with a direct and a derived variable** ``` # This configure file specifies the variables @@ -142,7 +111,7 @@ source = "DATA/albedo/CERES/albedo_0.5x0.5.nc" In brief: This file allows you to create different header descriptions of the experiments (`h1`: top level for grouping of variables, `h2`: sub-level for each variable), but most importantly the `variable`s that we will look into and their `source`. In the eaxmple, `rsus` (*Surface Upward Shortwave Radiation*) and `albedo` are the used variables. The latter is actually derived from two variables by dividing the *Surface Upward Shortwave Radiation* by the *Surface Downward Shortwave Radiation*, `derived = rsus/rsds`. Finally, sources are defined as `source` with a text-font header without `h1` or `h2`. -#### Changing configure file variables +**Changing configure file variables** This is the list of all the variables you can modify in config file: ``` @@ -199,44 +168,78 @@ weight = 1 ``` -### 3.3 Set up `modelroute` and `regions` files +### 2.2 `model_setup` file instead of `model_root` -If you plan to run only a specific subset of models, you can already define them in a `modelroute.txt` file. It could look like our specific example for running different versions (1, 2, and 3) of the ACCESS-ESM 1.5 suite: +If you plan to run only a specific subset of models, you can already define them in a `modelroute.txt` file that is then called via the +``` +--model_setup modelroute.txt +``` +instead of using `--model_root` + +It could look like our specific example for running different versions (1, 2, and 3) of the ACCESS-ESM 1.5 suite: ``` -# Model Name , PATH/TO/MODELS , EXTRA COMMANDS -ACCESS_ESM1-5-r1i1p1f1 , MODELS/r1i1p1f1 , CMIP6 -ACCESS_ESM1-5-r2i1p1f1 , MODELS/r2i1p1f1 , CMIP6 -ACCESS_ESM1-5-r3i1p1f1 , MODELS/r3i1p1f1 , CMIP6 +# Model Name , ABOSLUTE/PATH/TO/MODELS , EXTRA COMMANDS +ACCESS_ESM1-5-r1i1p1f1 , MODELS/r1i1p1f1 , CMIP6 +ACCESS_ESM1-5-r2i1p1f1 , MODELS/r2i1p1f1 , CMIP6 +ACCESS_ESM1-5-r3i1p1f1 , MODELS/r3i1p1f1 , CMIP6 ... (abbreviated) ``` -### 3.4 Download/link `shapefiles` files locally - -You can download the `shapefiles` that are needed to run `ilamb` and `cartopy` offline here: +### 2.3 Other setup options -- For Land: https://www.naturalearthdata.com/http//www.naturalearthdata.com/download/110m/physical/ne_110m_land.zip -- For Ocean: https://www.naturalearthdata.com/http//www.naturalearthdata.com/download/110m/physical/ne_110m_ocean.zip +There are many options to adjust the `ilamb` setup. You can find them on this [`ilamb` website](https://www.ilamb.org/doc/ilamb_run.html), including the `--build_dir` option to change the output directory. -Finally, you need to define that path as `CARTOPY_DATA_DIR` via +We want to specifically point towards the option to limit the analysis region. You can either define a region yourself or use predefined regions the following for Australia: ``` -export CARTOPY_DATA_DIR=/absolute/path/to/shapefiles/directory +--regions aust ``` -Note: For NCI, we already provide shapefiles in a directory as part of project `xp65`. After joining the project, you can thus easily use +## 3 Portable Batch System (PBS) jobs on NCI + +The following default PBS file, let's call it `ilamb_test.sh` can help you to setup your own, while making sure to use the correct project (#PBS -P) to charge your computing cost to: ``` +#!/bin/bash + +#PBS -N default_ilamb +#PBS -P tm70 +#PBS -q normalbw +#PBS -l ncpus=1 +#PBS -l mem=32GB +#PBS -l jobfs=10GB +#PBS -l walltime=00:10:00 +#PBS -l storage=gdata/xp65+gdata/kj13+gdata/fs38 +#PBS -l wd + +module use /g/data/xp65/public/modules +module load conda/access-med-0.1 + +export ILAMB_ROOT=$PWD/ILAMB_ROOT export CARTOPY_DATA_DIR=/g/data/xp65/public/apps/cartopy-data + +ilamb-run --config cmip.cfg --model_setup $PWD/modelroute.txt --regions global ``` -## 4. Run `ilamb` +If you are not familiar with PBS jobs on NCI, you could find the guide [here](https://opus.nci.org.au/display/Help/4.+PBS+Jobs). In brief: this PBS script (which you can submit via the bash command `qsub ilamb_test.sh`), will submit a job to Gadi with the job name (`#PBS -N`) *default_ilamb* under project (`#PBS -P`) `tm70` with a normal queue (`#PBS -q normalbw`), for 1 CPU (`#PBS -l ncpus=1`) with 32 GB RAM (`#PBS -l mem=32GB`), with an walltime of 10 hours (`#PBS -l walltime=00:10:00`) and access to 10 GB local disk space (`#PBS -l jobfs=10GB`) as well as data storage access to projects `xp65`, `kj13`, and `fs38` (again, note that you have to be [member of both projects on NCI](https://my.nci.org.au/mancini/project-search). Upon starting the job, it will change into to the working directory that you started the job from (`#PBS -l wd`) and load the access-med conda environment. Finally, it will export the $ILAMB_ROOT as well as $ARTOPY_DATA_DIR paths and start an `ilamb-run`. -### 4.1 ilamb-run +In our example, we actually run the `cmip.cfg` file from the `ilamb` [config file github repository](https://github.com/rubisco-sfa/ILAMB/blob/master/src/ILAMB/data/) for files spec -Now that we have the configuration file set up, you can run the study using the `ilamb-run` script. Executing the following command at the $ILAMB_ROOT directory will run `ilamb` as specified in your `sample.cfg` for all models of the `model_root` and all regions (`global`) of the world: +Note: If your ILAMB_ROOT and CARTOPY_DATA_DIR are not in your directory from where you submitted the job from, then you need to adjust the export commands to their path +``` +export ILAMB_ROOT=/absolute/path/where/ILAMB_ROOT/actually/is +export CARTOPY_DATA_DIR=/absolute/path/where/shapefiles/actually/are +``` + +Once the jobs are finished, you can again inspect the outcome via an http server as described at the top of this tutorial + + +## 5 An example `ilamb` run + +When running, `ilamb` will the example configuration file that we provided above via ``` ilamb-run --config sample.cfg --model_root $ILAMB_ROOT/MODELS/ --regions global ``` -If you are on some institutional resource, you may need to launch the above command using a submission script, or request an interactive node. As the script runs, it will yield output which resembles the following: +`ilamb` should print the following messages while computing: ``` Searching for model results in /Users/ncf/sandbox/ILAMB_sample/MODELS/ @@ -265,134 +268,6 @@ Next we ran all model-confrontation pairs. In our parlance, a confrontation is a The next stage is the post-processing. This is done as a separate loop to exploit some parallelism. All the work in a model-confrontation pair is purely local to the pair. Yet plotting results on the same scale implies that we know the maxmimum and minimum values from all models and thus requires the communcation of this information. Here, as we are plotting only over the globe and not extra regions, the plotting occurs quickly. -### 4.2 Run specific models and regions - -As mentioned in [Section 3.3](#33-set-up-modelroute-and-regions-files), you can adjust the models and regions that `ilamb` will run on. You can find more information in the `ilamb` [tutorial](https://www.ilamb.org/doc/ilamb_run.html). Calling `ilamb-run` with both specifications, would look like: -``` -ilamb-run --config cmip.cfg --model_setup modelroute.txt --regions regions.txt -``` -where you call a specific config file (see [Section 3.2](#32-set-up-a-config-file)) as well as specific model routes and regions with files (see [Section 3.3](#33-set-up-modelroute-and-regions-files)). - -### 4.3 Viewing the benchmarking output in your browser - -The whole process generates a directory of results within ILAMB_ROOT which by default is called `_build`. To view the results locally on your computer, navigate into this directory and start a local `http` server: -``` -python -m http.server -``` -You should see a message similar to this (or use http://0.0.0.0:8000/): -``` -Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ... -``` -Open this link in your browser and you will see a webpage with a summary table in the center. As we have so few variables and a single model at this point, the table will very simple: - -

Starting side of ilamb output

- -As we add more variables and models, this summary table helps you understand relative differences in scores among models. For now, clicking on a row of the table will expand it to reveal the underlying datasets used. Clicking on CERES will take you to another page which presents detailed scores and plots. - -

Detailed output of Surface Upward SW Radiation Benchmarking

- -## 5. Run `ilamb` on NCI - -If you followed the guides above, you should be familiar with how you can setup `ilamb`. - -To run `ilamb` on NCI, you can either start an interactive setup [Section 5.1](#51-interactive-setup-on-nci) or use a non-interactive Portable Batch System (PBS) job [Section 5.2](#52-portable-batch-system-pbs-jobs-on-NCI). - -In both cases, you need to again define the variable `$ILAMB_ROOT` - -### 5.1 ILAMB_ROOT and DATA/MODEL on NCI - -In our default setup, we will place ILAMB_ROOT and the shapefiles for cartopy directly in the home directory. First, you have to create the ILAMB_ROOT directory -``` -mkdir $PWD/ILAMB_ROOT -``` -You can then simply export their paths after login as: -``` -export ILAMB_ROOT=$PWD/ILAMB_ROOT -export CARTOPY_DATA_DIR=/g/data/xp65/public/apps/cartopy-data -``` - -You can of course change the path of the directory, but will need to take this into account for the PBS job by adding a command to change into the $ILAMB_ROOT directory (see [PBS setup comments](https://github.com/svenbuder/ILAMB-workflow/edit/main/ilamb_note.md#52-portable-batch-system-pbs-jobs-on-nci)). - -#### ILAMB_ROOT/DATA on NCI - -An extensive colletion of DATA is provided in the `kj13` project. You need to have [joined the project on NCI](https://my.nci.org.au/mancini/project-search) to get access to this data. - -To create a symbolic link to this data, use the bash command -``` -ln -s /g/data/kj13/datasets/ilamb/DATA $ILAMB_ROOT/DATA -``` - -#### ILMAB_ROOT/MODEL on NCI - -In the future, we will provide a symbolic link to a MODEL catalog for you as well. - -For now, you will need to create the directory $ILAMB_ROOT/MODEL and populate it with symbolic links to specific models yourself. - -In our example, we will use ACCESS-ESM1.5, which is provided on NCI as part of project `fs38`. You need to have [joined the project on NCI](https://my.nci.org.au/mancini/project-search) to get access to this data. - -To link the ACCESS-ESM1.5 suite files to your $ILAMB_ROOT/MODEL, simply execute the following bash command -``` -mkdir $ILAMB_ROOT/MODELS -ln -s /g/data/fs38/publications/CMIP6/CMIP/CSIRO/ACCESS-ESM1-5/historical/r* $ILAMB_ROOT/MODELS -``` - -By the end of Section 5.1.1 and 5.1.2, your $ILAMB_ROOT Directory should look similar to -``` -$ILAMB_ROOT -├── ... -├── DATA -> /g/data/kj13/datasets/ilamb/DATA -└── MODELS - ├── r10i1p1f1 -> /g/data/fs38/publications/CMIP6/CMIP/CSIRO/ACCESS-ESM1-5/historical/r10i1p1f1 - ├── ... (abbreviated) - └── r9i1p1f1 -> /g/data/fs38/publications/CMIP6/CMIP/CSIRO/ACCESS-ESM1-5/historical/r9i1p1f1 -``` - -These different models have a lot of subdirectories, which are important to keep in mind when defining the `source` parameter in your `ilamb` `.cfg` file. Note that the `ilamb` files will end with `*.nc*. For example, one of the *rsus* files for run `r10i1p1f1` can be found (and used for `.cfg` under -``` -source = /g/data/fs38/publications/CMIP6/CMIP/CSIRO/ACCESS-ESM1-5/historical/r1i1p1f1/Amon/rsus/gn/files/d20191115/rsus_Amon_ACCESS-ESM1-5_historical_r1i1p1f1_gn_185001-201412.nc -``` -or shorter -``` -source = $ILAMB_ROOT/MODELS/r1i1p1f1/Amon/rsus/gn/files/d20191115/rsus_Amon_ACCESS-ESM1-5_historical_r1i1p1f1_gn_185001-201412.nc -``` - -### 5.2 Portable Batch System (PBS) jobs on NCI - -The following default PBS file, let's call it `ilamb_test.sh` can help you to setup your own, while making sure to use the correct project (#PBS -P) to charge your computing cost to: -``` -#!/bin/bash - -#PBS -N default_ilamb -#PBS -P tm70 -#PBS -q normalbw -#PBS -l ncpus=1 -#PBS -l mem=32GB -#PBS -l jobfs=10GB -#PBS -l walltime=00:10:00 -#PBS -l storage=gdata/xp65+gdata/kj13+gdata/fs38 -#PBS -l wd - -module use /g/data/xp65/public/modules -module load conda/access-med-0.1 - -export ILAMB_ROOT=$PWD/ILAMB_ROOT -export CARTOPY_DATA_DIR=/g/data/xp65/public/apps/cartopy-data - -ilamb-run --config cmip.cfg --model_setup $PWD/modelroute.txt --regions global -``` - -If you are not familiar with PBS jobs on NCI, you could find the guide [here](https://opus.nci.org.au/display/Help/4.+PBS+Jobs). In brief: this PBS script (which you can submit via the bash command `qsub ilamb_test.sh`), will submit a job to Gadi with the job name (#PBS -N) *default_ilamb* under project (#PBS -P) `tm70` with a normal queue (#PBS -q normalbw), for 1 CPU (#PBS -l ncpus=1) with 32 GB RAM (#PBS -l mem=32GB), with an walltime of 10 hours and access to 10 GB local disk space (#PBS -l jobfs=10GB) as well as data storage access to projects `xp65`, `kj13`, and `fs38` (again, note that you have to be [member of both projects on NCI](https://my.nci.org.au/mancini/project-search). Upon starting the job, it will change into to the working directory that you started the job from (#PBS -l wd) and load the access-med conda environment. Finally, it will export the $ILAMB_ROOT as well as $ARTOPY_DATA_DIR paths and start an `ilamb-run`. - -In our example, we actually run the `cmip.cfg` file from the `ilamb` [config file github repository](https://github.com/rubisco-sfa/ILAMB/blob/master/src/ILAMB/data/) for files spec - -Note: If your ILAMB_ROOT and CARTOPY_DATA_DIR are not in your directory from where you submitted the job from, then you need to adjust the export commands to their path -``` -export ILAMB_ROOT=/absolute/path/where/ILAMB_ROOT/actually/is -export CARTOPY_DATA_DIR=/absolute/path/where/shapefiles/actually/are -``` - -Once the jobs are finished, you can again inspect the outcome as described in [Section 4.3](#43-viewing-the-benchmarking-output-in-your-browser) - ## 6. Fix your setup with ilamb_doctor `ilamb_doctor ` is a script you can use to diagnosing some missing model values or what is incorrect or missing from a given analysis. It takes options similar to `ilamb-run` and is used in the following way: diff --git a/docs/models/configurations/access-am.md b/docs/models/configurations/access-am.md index ad06de143..c4405f668 100644 --- a/docs/models/configurations/access-am.md +++ b/docs/models/configurations/access-am.md @@ -4,23 +4,33 @@ ACCESS AM model -The ACCESS-AM model is a coupled model between the atmosphere and the land. The atmospheric model component is the [UM model][UM-hive]. The UM model comes by default coupled to the [JULES][JULES-hive] land model. That is why the first configurations and experiments released of ACCESS-AM will be UM-JULES configurations. But the ACCESS-NRI is working to ensure subsequent releases of ACCESS-AM use the [CABLE][CABLE-hive] land model instead. +The ACCESS **A**tmosphere **M**odel (ACCESS-AM) is a global model with atmosphere and land surface components. It is often used in Atmospheric Model Intercomparison Project (AMIP) experiments where it is driven by historically observed sea surface temperature and sea ice data. -### Getting started information +ACCESS-NRI will release supported ACCESS-AM configurations. The first release, ACCESS-AM2, will be derived from the [CSIRO ACCESS-CM2 configuration](access-cm.md#access-cm2) and will include [atmosphere] and [land] components. -[On this page][UMstart], you will find information on how to gain access to the UM model and start using the model. You will also find links to various configurations and experiments you can use as a basis to design your experiment. +##
ACCESS-AM2
-### Configurations +This is the model configuration used for the AMIP experiments contributed to the World Climate Research Programme’s Coupled Model Intercomparison Project Phase 6 (CMIP6). Note that the CMIP model naming is the same for both the AM and CM configurations, so the CMIP6 experiments are ACCESS-CM2 AMIP rather than ACCESS-AM2. +The component models are the same as ACCESS-CM2: -### Experiments +- Atmosphere model (UM vn10.6, GA7.1 science configuration): N96 resolution (1.875° x 1.25°, 85 levels). Physical model only – no carbon cycle. -Some experiments already run with the UM are listed on: +- Land surface model (CABLE2.5) + +[**Citation** [@Bi2020-vj]][ACCESS-CM2-cite] + +### Other configurations + +Some experiments already run with other atmospheric model configurations are listed at: - [CLEX CMS wiki][UMexperiments] +[atmosphere]: ../model_components/atmosphere.md +[land]: ../model_components/land.md [UM-hive]: ../model_components/atmosphere.md#the-unified-model [JULES-hive]: ../model_components/land.md#jules [CABLE-hive]: ../model_components/land.md#cable [UMstart]: http://climate-cms.wikis.unsw.edu.au/Unified_Model [UMexperiments]: http://climate-cms.wikis.unsw.edu.au/UM_Experiments +[ACCESS-CM2-cite]: https://www.publish.csiro.au/es/ES19040 diff --git a/docs/models/configurations/access-cm.md b/docs/models/configurations/access-cm.md index 266cd2d5e..9c3fe89cd 100644 --- a/docs/models/configurations/access-cm.md +++ b/docs/models/configurations/access-cm.md @@ -1,38 +1,34 @@ #
ACCESS-CM
-ACCESS-CM2 (ACCESS Coupled Model 2) is a global fully-coupled climate model that includes the atmosphere, ocean and sea-ice components, and produces physical climate simulations. ACCESS-CM2 is one of the two models run by the Australian climate community for the - Coupled Model Intercomparison Project, CMIP. +The ACCESS **C**oupled **M**odel (ACCESS-CM) is a fully-coupled global climate model that includes atmosphere, land, ocean and sea ice components, and produces physical climate simulations. Coupled models run by the Australian climate community are contributed to the + Coupled Model Intercomparison Project (CMIP).
+ACCESS-NRI will release supported ACCESS-CM configurations. The first release of ACCESS-CM will be derived from the [CSIRO ACCESS-CM2 configuration](#access-cm2) and will include [atmosphere], [land], [ocean] and [sea ice] components. + ACCESS CM model -## ACCESS-CM2 configurations +##
[ACCESS-CM2]
-- Atmosphere model (UM10.6): N96 resolution (1.875° x 1.25°, 85 levels). Physical model only – no carbon cycle. +ACCESS-CM2 [@Bi2020-vj] is one of Australia’s contributions to the World Climate Research Programme’s Coupled Model Intercomparison Project Phase 6 (CMIP6). -- Land surface model (CABLE2.5) +The component models are: -- Ocean model (MOM5): Tripolar grid, 1° resolution, 50 levels. +- Atmosphere model (UM vn10.6, GA7.1 science configuration): N96 resolution (1.875° x 1.25°, 85 levels). Physical model only – no carbon cycle. -- Sea ice model (CICE5.1) +- Land surface model (CABLE2.5) - | COMPONENT | MODEL | VERSION | - | ------------- | ------------- | --------------------- | - | Atmosphere | UM | 10.6 | - | Land Surface | CABLE | 2.5 (integrated in UM)| - | Ocean | MOM | 5 | - | Sea Ice | CICE | 5.1 | - | Coupler | OASIS-MCT | 3 | +- Ocean model (MOM5): Tripolar grid, 1° resolution, 50 levels. -ACCESS-NRI will release an ACCESS-CM model configuration. The first release of ACCESS-CM will be derived from the [CSIRO ACCESS-CM2 configuration](#access-cm2) and will include [atmosphere], [land], [ocean] and [sea ice] components. +- Sea ice model (CICE5.1.2): Same grid as ocean. -## [ACCESS-CM2] +- Coupler (OASIS3-MCT) + +Compared to previous model versions, ACCESS-CM2 shows better global hydrological balance, more realistic ocean water properties (in terms of spatial distribution) and meridional overturning circulation in the Southern Ocean. It does, however, produce a poorer simulation of the Antarctic sea ice and a larger energy imbalance at the top of atmosphere. ACCESS-CM2 has a relatively high equilibrium climate sensivity of 4.7°C for doubled CO2 concentration. [**Citation** [@Bi2020-vj]][ACCESS-CM2-cite] | [**Tutorial**][ACCESS-CM2-tute] -ACCESS-CM2 [@Bi2020-vj] is one of Australia’s contributions to the World Climate Research Programme’s Coupled Model Intercomparison Project Phase 6 (CMIP6). The component models are: UM10.6 GA7.1 for the atmosphere, CABLE2.5 for the land surface, MOM5 for the ocean, and CICE5.1.2 for the sea ice. Compared to previous model versions ACCESS-CM2 shows better global hydrological balance, more realistic ocean water properties (in terms of spatial distribution) and meridional overturning circulation in the Southern Ocean but a poorer simulation of the Antarctic sea ice and a larger energy imbalance at the top of atmosphere. This energy imbalance reflects a noticeable warming trend of the global ocean over the spin-up period. - [atmosphere]: ../model_components/atmosphere.md [land]: ../model_components/land.md [ocean]: ../model_components/ocean.md diff --git a/docs/models/configurations/access-esm.md b/docs/models/configurations/access-esm.md index be3227cda..cb0e23853 100644 --- a/docs/models/configurations/access-esm.md +++ b/docs/models/configurations/access-esm.md @@ -4,20 +4,38 @@ ACCESS CM model -ACCESS-ESM stands for ACCESS **E**arth **S**ystem **M**odel. Earth system model means it is a fully-coupled model that includes carbon cycle components. +The ACCESS **E**arth **S**ystem **M**odel (ACCESS-ESM) is a fully-coupled global climate model that also includes representations of land and ocean biogeochemisty. This means it can simulate both the physical climate and global biogeochemical cycles (the carbon cycle in particular). ACCESS-NRI will release an ACCESS-ESM model configuration. The first release of ACCESS-ESM will be derived from the [CSIRO ACCESS-ESM1.5 configuration](#access-esm15) and will include [atmosphere], [land] and [land biogeochemistry], [ocean] and [ocean biogeochemistry], and [sea ice] components. ## [ACCESS-ESM1.5] +ACCESS-ESM1.5 [@Ziehn2020-fq] is a fully-coupled climate model with land and ocean carbon cycle components. ACCESS-ESM1.5 was developed primarily to enable Australia to participate in the Coupled Model Intercomparison Project Phase 6 (CMIP6) with an ESM version. + +The model component are: + +- Atmosphere model (UM vn7.3, GA7.1): N96 resolution (1.875° x 1.25°, 38 levels). + +- Land surface model (CABLE2.4) + +- Land biogeochemistry (CASA-CNP) + +- Ocean model (MOM5): Tripolar grid, 1° resolution, 50 levels. + +- Ocean biogeochemistry (WOMBAT) + +- Sea ice model (CICE4.1): Same grid as the ocean. + +- Coupler (OASIS3-MCT) + +ACCESS-ESM1.5 has an equilibrium climate sensitivity of 3.87°C for doubled CO2 concentration. + [**Citation** [@Ziehn2020-fq]][ACCESS-ESM1.5-cite] [**ACCESS Training Workshop (AMOS 2021)**][ACCESS-AMOS-Workshop] [**Webinar: *Getting Started with ACCESS-CM2 and ACCESS-ESM1.5* **][ACCESS-ESM1.5-tute] -ACCESS-ESM1.5 [@Ziehn2020-fq] is a fully-coupled climate model with land and ocean carbon cycle components. ACCESS-ESM1.5 has mainly been developed to enable Australia to participate in the Coupled Model Intercomparison Project Phase 6 (CMIP6) with an ESM version. An assessment of the climate response to CO2 forcing indicates that ACCESS-ESM1.5 has an equilibrium climate sensitivity of 3.87°C. - [atmosphere]: ../model_components/atmosphere.md [land]: ../model_components/land.md [land biogeochemistry]: ../model_components/bgc_land.md @@ -29,4 +47,3 @@ ACCESS-ESM1.5 [@Ziehn2020-fq] is a fully-coupled climate model with land and oce [ACCESS-ESM1.5-cite]: https://www.publish.csiro.au/es/ES19035 [ACCESS-ESM1.5-tute]: https://nespclimate.com.au/wp-content/uploads/2020/10/Webinar-slides-Getting_started_with_ACCESS.pdf [ACCESS-AMOS-Workshop]: https://confluence.csiro.au/display/ACCESS/Setting+up+for+ACCESS-ESM1.5 - diff --git a/docs/models/configurations/access-om.md b/docs/models/configurations/access-om.md index 144a4c47f..30ea72bfc 100644 --- a/docs/models/configurations/access-om.md +++ b/docs/models/configurations/access-om.md @@ -6,23 +6,23 @@ https://forum.access-hive.org.au/t/access-om2-control-runs/258 --> ACCESS CM model -The ACCESS **O**cean **M**odel, ACCESS-OM, is a global coupled ocean and sea ice configuration. It couples the ocean and sea ice components via a coupler. The atmospheric fields that drive the model are provided by a data product, usually derived from reanalysis. +The ACCESS **O**cean **M**odel (ACCESS-OM) is a global coupled ocean and sea ice configuration with ocean and sea ice models connected via a coupler. The atmospheric fields that drive the model are provided by a data product, usually derived from reanalysis. ACCESS-NRI will release supported ACCESS-OM configurations. The first release will be derived from the COSIMA [ACCESS-OM2][COSIMA-models] suite and will include [ocean] and [sea ice] components. ## [ACCESS-OM2][COSIMA-models] -[**Citation** [@Kiss2020-gmd]][ACCESS-OM2-cite] | -[**Documentation**][ACCESS-OM2-docs] +ACCESS-OM2 [@Kiss2020-gmd] is a suite of coupled ocean-sea ice models developed by the Consortium for Ocean-Sea Ice Modelling in Australia ([COSIMA][COSIMA]). All models use the [MOM5] ocean model coupled to the [CICE5] sea ice model via the OASIS3-MCT coupler. -ACCESS-OM2 [@Kiss2020-gmd] is a suite of coupled ocean-sea ice models developed by the Consortium for Ocean-Sea Ice Modelling in Australia ([COSIMA][COSIMA]). All models use the [MOM5] ocean model coupled to the [CICE5] sea ice model via an OASIS3-MCT coupler. +The ACCESS-OM2 suite has models at three different spatial resolutions: -The models in the ACCESS-OM2 suite differ by their grid spatial resolution: + - [ACCESS-OM2][ACCESS-OM2] at 1° with 50 vertical levels. + - [ACCESS-OM2-025][ACCESS-OM2-025] at 0.25° with 50 vertical levels. + - [ACCESS-OM2-01][ACCESS-OM2-01] at 0.1° with 75 vertical levels. - - [ACCESS-OM2][ACCESS-OM2] at 1° with 50 vertical levels - - [ACCESS-OM2-025][ACCESS-OM2-025] at 0.25° with 50 vertical levels - - [ACCESS-OM2-01][ACCESS-OM2-01] at 0.1° with 75 vertical levels +[**Citation** [@Kiss2020-gmd]][ACCESS-OM2-cite] | +[**Documentation**][ACCESS-OM2-docs] [ocean]: ../model_components/ocean.md [sea ice]: ../model_components/sea-ice.md @@ -36,4 +36,4 @@ The models in the ACCESS-OM2 suite differ by their grid spatial resolution: [ACCESS-OM2-01]: http://cosima.org.au/index.php/models/access-om2-01-2/ [ACCESS-OM2-cite]: https://gmd.copernicus.org/articles/13/401/2020/ -[ACCESS-OM2-docs]: https://github.com/COSIMA/access-om2/wiki \ No newline at end of file +[ACCESS-OM2-docs]: https://github.com/COSIMA/access-om2/wiki diff --git a/docs/models/model_components/bgc_ocean.md b/docs/models/model_components/bgc_ocean.md index bd9c5b603..ae589df8e 100644 --- a/docs/models/model_components/bgc_ocean.md +++ b/docs/models/model_components/bgc_ocean.md @@ -6,13 +6,12 @@ -## WOMBAT -WOMBAT is the ocean carbon model (World Ocean Model of Biogeochemistry And Trophic-dynamics), developed in Australia. It calculates the carbon fluxes of the ocean, by simulating the evolution of phosphate, oxygen, dissolved inorganic carbon, alkalinity and iron with one class of phytoplankton and zooplankton. +##
WOMBAT
-WOMBAT is a Nutrient, Phytoplankton, Zooplankton and Detritus (NPZD) model, with one zooplankton and one phytoplankton class. +The World Ocean Model of Biogeochemistry And Trophic-dynamics (WOMBAT) is the ocean biogeochemistry module added to ACCESS models. The core of WOMBAT is a Nutrient, Phytoplankton, Zooplankton and Detritus (NPZD) cycle. WOMBAT simulates the evolution of open-ocean phosphate, oxygen, dissolved inorganic carbon, alkalinity, iron and carbon fluxes with one zooplankton and one phytoplankton class. ### How is WOMBAT used? +WOMBAT is applied as a tracer package in the ACCESS ocean model [MOM5][mom5-github]. In the ACCESS-OM2 configuration, WOMBAT is used in MOM5 and coupled with sea ice biogeochemistry. WOMBAT is also applied in [MOM5 of the ACCESS-ESM1.5 configuration][MOM5-esm-code] used for CMIP6. -WOMBAT is [coupled to the MOM5 ocean model][MOM5-WOMBAT-code] in the ACCESS-ESM1.5 and ACCESS-OM2 models. - -[MOM5-WOMBAT-code]: https://github.com/COSIMA/ACCESS-ESM1.5-MOM5 +[mom5-github]: https://github.com/mom-ocean/MOM5 +[MOM5-esm-code]: https://github.com/COSIMA/ACCESS-ESM1.5-MOM5 diff --git a/docs/models/model_components/land.md b/docs/models/model_components/land.md index 33da7840b..b8f393083 100644 --- a/docs/models/model_components/land.md +++ b/docs/models/model_components/land.md @@ -8,11 +8,11 @@ ## [CABLE][cable-wiki] -[Community Atmosphere Biosphere Land Exchange (CABLE)][cable-web] is a land surface model, used to calculate the fluxes of momentum, energy, water and carbon between the land surface and the atmosphere. It also models the main biogeochemical cycles of the land ecosystem when used in conjunction with [the CASA-CNP module][casa-cnp]. +[Community Atmosphere Biosphere Land Exchange (CABLE)][cable-web] is a land surface model used to calculate the fluxes of momentum, energy, water and carbon between the land surface, vegetation canopy and the atmospheric boundary layer. It also includes descriptions of thermal and hydrological processes in the soil and snow, and models the main biogeochemical cycles of the land ecosystem when used in conjunction with the [CASA-CNP][casa-cnp] module. ### How is CABLE used? -CABLE can be run as a standalone model, for a single location, a region or globally. Coupled to the Met Office [Unified Model (UM)](um-web), CABLE provides the land surface component of the ACCESS Earth System Model (ACCESS-ESM) and ACCESS Coupled Model (ACCESS-CM). +CABLE provides the land surface component of the ACCESS Earth System Model (ACCESS-ESM) and the ACCESS Coupled Model (ACCESS-CM). Directly coupled into the [Unified Model (UM)](um-web), CABLE replaces relevant parts of the functionality of the UM’s own land surface scheme (JULES). CABLE can also be run as a standalone model, for a single location, a region or globally. CABLE is an open source model developed by a community of Australian climate science researchers. [Registration][cable-wiki] is required to access the CABLE code repository.