Merge pull request #472 from ACCESS-Hive/dev/sven/cookbook

Dev/sven/cookbook

docs/model_evaluation/model_evaluation_getting_started/model_evaluation_getting_started.md

@@ -1,8 +1,8 @@
-# Model Evaluation Environment at NCI's Gadi
+# Model Evaluation Environment at NIC's Gadi
 
 At this stage of *Getting Started*, we assume that you already have access to NCI's Gadi. If this is not the case, please go to our instructions on how to get [access to NCI's Gadi](../../get_started/index.md).
 
-Here we describe where you can find, load, and evalulate observational and model data on Gadi.
+Here we describe the additional information to get started with model evaluation that is supported by ACCESS-NRI.
 
 ???+ warning "ACCESS-NRI provides code and support, but not computing resources"
     You do not automatically have access to all of Gadi's storage at `/g/data/`, but need to be part of a `$PROJECT` to see files at `/g/data/$PROJECT`. Furthermore, if you use Gadi's job submission system PBS (Portable Batch System), you need to add the relevant storage to the `#PBS -l storage=gdata/xp65+gdata/kj13` (if you want the job to have access to `xp65` and `kj13` in this example).
@@ -23,10 +23,43 @@ If you are planning to run your code through JupyterLab on [NCI's ARE](https://a
 
 You are now able to use the scripts of our currated environment, including `python3`, `intake`, `jupyter`, `esmvaltool`, or `ilamb`. The complete list of dependencies can be found in the `environment.yml` file of our [GitHub repository](https://github.com/ACCESS-NRI/MED-condaenv/blob/main/scripts/environment.yml):
 
-[![Raise Issue](../../assets/model_evaluation/condaenv_list.png)](https://github.com/ACCESS-NRI/MED-condaenv/issues)
 
-<!-- ## 3 If you need more packages
+<div style="text-align: center;">
+    <a href="https://github.com/ACCESS-NRI/MED-condaenv/blob/main/scripts/environment.yml" target="_blank"><img src="../../../assets/model_evaluation/condaenv_list.png" alt="List of packages that are provided as part of the xp65 access-med environment" width="75%"/></a>
+</div>
+
+## 3 Interactive computing on NCI via the Australian Research Environment (ARE)
+
+NCI also supports an interactive coding environment called the Australian Research Environment (ARE). It's use is quite similar to submitting a computing job via `qsub -I`, but it comes with dedicated graphical user interfaces for jupyter notebooks. To use it, you need an NCI account and be part of a project that gives you computing resources (see our [getting started](../../get_started/index.md)).
+
+You can then easily go to [https://are.nci.org.au](https://are.nci.org.au) and login. After you are logged in, you can click on the featured app button "JupyterLab" to start a JupyterLab instance. This will progress you to a window with many input fields. You need to at least fill in the following (we show default values, but you need to adjust them for your given use case and projects):  
+
+- **Walltime (hours)** `1` 
+- **Queue** `normalbw` 
+- **Compute Size** `tiny` 
+- **Project** `iq82` (exchange with your project with computing resources) 
+- **Storage** `gdata/xp65+gdata/hh5` (exchange with the gdata-project storage that you need access to) 
+- *Advanced Options ...* (click button to expand) 
+- **Module directories** `/g/data/xp65/public/modules` (exchange with your module directory, like `/g/data/hh5/public/modules/`) 
+- **Modules** `conda/are` (exchange with your modules, like `conda/analysis3`) 
+- *Launch* (click to submit) 
+
+This will launch a JupyterLab session with a Session ID and display it in the list of interactive sessions (you can also find it under **My Interactive Sessions** in the top left of the ARE website).
+The session appears blue while it is loading, yellow or red in case of warnings or errors, and green when it is successfully running, as in the following example:
+
+<div style="text-align: center;">
+    <img src="../../../assets/getting_started/are_1.png" alt="Example of a successfully started ARE Session" width="75%"/>
+</div>
+
+You can then **Open JupyterLab** via a button at the bottom of the session. This will bring you to a window with a directory structure to the left and a jupyter notebook to the right (see the example below). If you have loaded the modules from `hh5` or `xp65`, you should then be able to import python packes like `numpy`, `xarray` or `intake`, as shown in the screenshot below.
+
+<div style="text-align: center;">
+    <img src="../../../assets/getting_started/are_2.png" alt="Example of a JupyterLab session with directory tree to the left and jupyter notebook to the right, showing successfully imported python packages." width="75%" />
+</div>
+
+<!-- ## 4 If you need more packages
 
 Simply raise an issue to *add a package* in our [ACCESS-NRI/MED-condaenv GitHub repository](https://github.com/ACCESS-NRI/MED-condaenv/issues):
 
-[![Raise Issue](../../assets/model_evaluation/condaenv_raise_issue.png)](https://github.com/ACCESS-NRI/MED-condaenv/issues) -->
+[![Raise Issue](../../assets/model_evaluation/condaenv_raise_issue.png)](https://github.com/ACCESS-NRI/MED-condaenv/issues) -->
+

docs/model_evaluation/model_evaluation_on_gadi/model_evaluation_on_gadi_pangeo_cosima.md

@@ -1,27 +1,34 @@
-# COSIMA cookbooks on NCI's Gadi
-<!-- # COSIMA cookbooks and Pangeo on NCI's Gadi -->
+# COSIMA Cookbook on NCI's Gadi
 
-COSIMA is the Consortium for Ocean-Sea Ice Modelling in Australia, which brings together Australian researchers involved in global ocean and sea ice modelling. The consortium provides a collection of `cosmia-recipes` for the evaluation of ocean-sea ice modelling that are currated for you on Gadi.
+COSIMA is the [Consortium for Ocean-Sea Ice Modelling in Australia](http://cosima.org.au/), which brings together Australian researchers involved in global ocean and sea ice modelling.
 
-<!-- [Pangeo](https://pangeo.io) is a community of people working collaboratively to develop software environments around the Xarray and Dask packages. -->
+The COSIMA Cookbook is a framework for analysing output from ocean-sea ice models. The focus is on the [ACCESS-OM2](../../models/configurations/access-om.md) suite of models being developed and run by members of [COSIMA]((http://cosima.org.au/)). But this framework is suited to analysing any MOM5/MOM6 output, as well as output from other models.
+
+???+ warning "The COSIMA Cookbook is a framework by COSIMA"
+    The COSIMA Cookbook itself is maintained by the COSIMA members.
+    ACCESS-NRI is only providing support for the COSIMA Cookbook and its collection of `cosmia-recipes` for the evaluation of ocean-sea ice modelling on Gadi.
 
 ## Getting Started
 
-The easiest way to use the COSIMA Cookbook is through NCI's HPC systems. The cookbook is preinstalled both in the `conda/analysis3` (project hh5) environments.
+The easiest way to use the COSIMA Cookbook is through the [Australian Research Environment (ARE)](https://are.nci.org.au) access of the [National Computational Infrastructure](https://nci.org.au). Here, we assume that you already [got started](../../get_started/index.md), that is, you have an NCI account and can log onto Gadi via secure shell (ssh).
+
+To use the COSIMA Cookbook that is preinstalled in the `conda/analysis3` of NCI proejct `hh5`, you need to [join NCI project `hh5`](https://my.nci.org.au/mancini/project/hh5).
 
-1. Clone the <a href="https://github.com/COSIMA/cosima-recipes"><code>cosima-recipes</code></a> repository to your local file space.  
-2. Start an [ARE JupyterLab session on NCI](https://are.nci.org.au) or a jupyter notebook on Gadi:  
-  *If you are using ARE*:  
-  **Storage**: gdata/hh5+gdata/ik11  
+1. Log onto Gadi via secure shell (ssh) and clone the <a href="https://github.com/COSIMA/cosima-recipes"><code>cosima-recipes</code></a> repository to your local file space.  
+2. Check out the recipes that you want to run, and make sure that you have access to the specific projects and their storage (e.g. project `ik11` to get access to `/g/data/ik11`).
+3. Start an [ARE JupyterLab session on NCI](https://are.nci.org.au):  
+  **Storage**: gdata/hh5 (add the specific storage that you need for the recipes you want to run)
   **Module directories**: /g/data/hh5/public/modules  
   **Modules**: conda/analysis3
-3. Navigate to one of the COSIMA recipes and run the analysis.
+  You can check out our [Getting Started with ARE](../model_evaluation_getting_started/model_evaluation_getting_started.md) instructions if you have not used ARE before.
+4. Within the ARE environment, navigate to one of the COSIMA recipes and run the analysis.
+
+## More information about the Cookbook
 
-## Using the Cookbook
+For more information, we refer to the [Cookbook github repository](https://github.com/COSIMA/cosima-cookbook) as well as a list of recipes:
 
-The COSIMA Cookbook is a framework for analysing output from ocean-sea ice models. The focus is on the ACCESS-OM2 suite of models being developed and run by members of [COSIMA: Consortium for Ocean-Sea Ice Modelling in Australia](http://cosima.org.au/). But this framework is suited to analysing any MOM5/MOM6 output, as well as output from other models.
+- [Tutorials](https://github.com/COSIMA/cosima-recipes/tree/main/Tutorials),
+- [Notebooks](https://github.com/COSIMA/cosima-recipes/tree/main/ACCESS-OM2-GMD-Paper-Figs) to reproduce figures of the [ACCESS-OM2 announcement paper](https://gmd.copernicus.org/articles/13/401/2020/),
+- [Documented Example](https://github.com/COSIMA/cosima-recipes/tree/main/DocumentedExamples), and
+- [Contributed Examples](https://github.com/COSIMA/cosima-recipes/tree/main/ContributedExamples)
 
-The cookbook is structured as follows:  
-    * This repository includes boiler-plate code and scripts that underpin the cookbook.
-    * The [cosima-recipes](https://github.com/COSIMA/cosima-recipes) repository includes example notebooks on which you can base your analyses, including a [collection of useful examples](https://cosima-recipes.readthedocs.io/en/latest/documented_examples.html).
-    * The cosima-recipes [template](https://github.com/COSIMA/cosima-recipes/blob/master/Tutorials/Template_For_Notebooks.ipynb) provides you with a template if you want to contribute your own scripts to the analysis.