Merge pull request #225 from cecilehannay/main

review chapter cesm workspace, code and some resources

_toc.yml

@@ -12,9 +12,9 @@ chapters:
     - file: notebooks/intro/coupling
   - file: notebooks/intro/cesm_webpage
     sections:
-    - file: notebooks/intro/project
-    - file: notebooks/intro/getting_help
+    - file: notebooks/intro/project 
     - file: notebooks/intro/getting_involved
+    - file: notebooks/intro/getting_help
   - file: notebooks/intro/community_experiments
     sections:
     - file: notebooks/intro/cesm_expts/clim_data_gateway

notebooks/basics/basics_overview.ipynb

@@ -61,7 +61,7 @@
    "id": "9d6954eb-3505-4a58-b6fa-bea7047c63cf",
    "metadata": {},
    "source": [
-    "Every time you log onto the NCAR HPC you want to ensure you have the correct modules loaded. Please refer to the [NCAR HPC environment](https://ncar.github.io/CESM-Tutorial/notebooks/resources/profile.html) section to make sure you are setting up your environment properly. \n",
+    "Every time you log onto the NCAR HPC you want to ensure you have the correct modules loaded. Please refer to the [NCAR HPC environment](https://ncar.github.io/CESM-Tutorial/notebooks/resources/profile.html#setting-up-your-ncar-hpc-environment) section to make sure you are setting up your environment properly. \n",
     "\n",
     "**YOU SHOULD ENSURE YOU CHECK THIS EVERY TIME YOU ARE BUILDING A NEW CASE**\n",
     "\n"
@@ -74,6 +74,14 @@
    "metadata": {},
    "outputs": [],
    "source": []
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "715674b2-a858-49ae-b044-7f7fc61a750c",
+   "metadata": {},
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {
@@ -92,7 +100,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.12"
+   "version": "3.10.13"
   },
   "toc-showcode": false
  },

notebooks/basics/cesm_workflow.ipynb

@@ -11,7 +11,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "CESM has been designed to be easy to use. Once you have completed the one-time set up steps, a CESM case can be run with a set of 4 commands."
+    "CESM has been designed to be easy to use. Once you have downloaded the CESM code, a CESM `case` can be run with a set of 4 commands. \n",
+    "\n",
+    "*Note: In CESM jargon, a case refers to a specific instance of a model simulation.*"
    ]
   },
   {

notebooks/basics/cesm_workspaces.ipynb

@@ -66,14 +66,20 @@
    "id": "19acc3aa-fb98-44af-966f-16ca49710135",
    "metadata": {},
    "source": [
-    "## Create CESM Code Directory\n"
+    "____\n",
+    "\n",
+    "## Setting your workspaces\n",
+    "\n",
+    "You will need to create a directory for the CESM Code and a directory when you will keep all your cases. \n",
+    "In the CESM jargon, a `case` refers to a specific instance of a model simulation."
    ]
   },
   {
    "cell_type": "markdown",
    "id": "1c6bda59-5302-4454-88bb-dfe5c4bd3209",
    "metadata": {},
    "source": [
+    "- ### Create CESM Code Directory\n",
     "Create a workspace location where you can put your CESM code on the derecho glade file system. In all exercises in this tutorial `$USER` is a placeholder and you should use your NCAR HPC login name when completing the exercise.\n"
    ]
   },
@@ -97,7 +103,7 @@
    "id": "76f14c71-ffae-4d67-b496-d6b075d4652d",
    "metadata": {},
    "source": [
-    "## Create Cases Workspace Location\n"
+    "- ### Create Cases Workspace Location\n"
    ]
   },
   {
@@ -128,7 +134,7 @@
    "id": "3a779263-cb21-443e-a3d8-0bd4a0e267e8",
    "metadata": {},
    "source": [
-    "## Other Workspace Locations\n"
+    "- ### Other Workspace Locations\n"
    ]
   },
   {
@@ -140,6 +146,14 @@
     "\n",
     "We will not directly set up your `Build/Run` or `Archive` workspace locations. These directories will be automatically created when you create a CESM case."
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d0ddf488-72e4-40f8-a797-cc2d1b958208",
+   "metadata": {},
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {

notebooks/basics/code/cesm_code_explore.ipynb

@@ -40,7 +40,7 @@
    "id": "44f8925f-4703-44d9-baa7-5ac59da0ede1",
    "metadata": {},
    "source": [
-    "# Step 1. Locate Your Code Workspace Area\n",
+    "## Step 1. Locate Your Code Workspace Area\n",
     "\n",
     "Returning to your terminal window we will now locate your `$SRCROOT` location on the NCAR HPC file system.\n",
     "\n",
@@ -103,7 +103,7 @@
    "id": "d3d8846b-cfa4-4b89-b262-39892ebdb52a",
    "metadata": {},
    "source": [
-    "# Step 2. Examine the CIME Directory\n",
+    "## Step 2. Examine the CIME Directory\n",
     "\n",
     "In your terminal window we will now move to the CIME directory and examine the contents. Remember that CIME is the Common Infrastructure for Modeling the Earth. It is a python-based framework that integrates the various components of the CESM into a single modeling framework. The CIME Scripts directory will be the location where you will start the Workflow of creating a new case through the rest of the Tutorial.\n",
     "\n",
@@ -182,7 +182,7 @@
    "id": "37af6f2c-34ce-4de6-a13e-593e61a90f52",
    "metadata": {},
    "source": [
-    "# Step 3. Examine the CESM Components Area\n",
+    "## Step 3. Examine the CESM Components Area\n",
     "\n",
     "In your terminal window we will now move to the Components Directory and examine the contents of the individual sub models. \n",
     "\n",
@@ -239,7 +239,7 @@
    "id": "aa9fb22c-de5f-41d7-ac25-07ba585ad2a9",
    "metadata": {},
    "source": [
-    "# Step 4. Look at the Community Atmosphere Model (CAM) Component Model\n",
+    "## Step 4. Look at the Community Atmosphere Model (CAM) Component Model\n",
     "\n",
     "As a final task in this exercise we are going to have a quick look at the Community Atmosphere Model (CAM) component model. At this point we are just exploring the Workspace. \n",
     "\n",

notebooks/basics/code/git_download_cesm.ipynb

@@ -13,29 +13,70 @@
    "id": "9d121236-47a7-48ef-8b67-40ef3b827178",
    "metadata": {},
    "source": [
-    "Having explored the CESM Github pages we are going to return to the derecho terminal window to download the Tutorial branch tag code into your own personal CESM workspace. Follow the three steps, below, to setup your CESM workspace.\n",
-    "\n",
-    "Downloading and setting up the Tutorial branch tag is an important step as this will be the code workspace we will be using throughout the rest of the Tutorial. If you have problems here please ask for help."
+    "You are going to download the CESM code from github into your own personal CESM workspace. Follow the three steps, below, to setup your CESM Code workspace.\n",
+    "\n"
    ]
   },
   {
    "cell_type": "markdown",
-   "id": "e980a755-b914-46eb-b217-3fe15781aeb3",
+   "id": "458e826c-60cb-4c5a-980f-b89f47cd06d1",
    "metadata": {},
    "source": [
-    "## Step 1. Download CESM Code with Git Clone"
+    "<div class=\"alert alert-warning\">\n",
+    "<strong>We will use the CESM release version `release-cesm2.1.5` for use in this tutorial. </strong><br><br>\n",
+    "</div>"
    ]
   },
   {
    "cell_type": "markdown",
-   "id": "458e826c-60cb-4c5a-980f-b89f47cd06d1",
+   "id": "c029d6bc-bd76-471a-8126-e888616e70d0",
    "metadata": {},
    "source": [
-    "<div class=\"alert alert-warning\">\n",
-    "<strong>We will use the CESM release version `release-cesm2.1.5` for use in this tutorial. </strong><br><br>\n",
+    "Downloading the CESM code is an important step as this will be the code workspace we will be using throughout the rest of the Tutorial. **If you have problems here please ask for help**."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "88f98dea-ada2-4186-bdf6-97c383755fdc",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "## Step 1: Create CESM Code Directory"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "986d1b83-f863-4294-b65b-5c9c65a8ac58",
+   "metadata": {},
+   "source": [
+    "\n",
+    "Create a workspace location where you can put your CESM code on the derecho glade file system. In all exercises in this tutorial `$USER` is a placeholder and you should use your NCAR HPC login name when completing the exercise."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d95a81b5-16b9-4291-9490-4058f98dcb3f",
+   "metadata": {},
+   "source": [
+    "<div class=\"alert alert-info\">\n",
+    "\n",
+    "```\n",
+    "cd /glade/work/$USER\n",
+    "mkdir code\n",
+    "```\n",
+    "   \n",
     "</div>"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "id": "e980a755-b914-46eb-b217-3fe15781aeb3",
+   "metadata": {},
+   "source": [
+    "## Step 2. Download CESM Code with Git Clone"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "76ef78ca-bb75-4340-996f-04f95233c84f",
@@ -160,6 +201,7 @@
     "release-cesm2.1.5\n",
     "release-cesm2.2.0\n",
     "release-cesm2.2.1\n",
+    "release-cesm2.2.2\n",
     "\n",
     "```\n",
     "\n",
@@ -172,7 +214,7 @@
    "id": "88bd0742-e990-4fcf-9b40-5c8b21a9ec43",
    "metadata": {},
    "source": [
-    "## Step 2. Download the Component Models with checkout_externals"
+    "## Step 3. Download the Component Models with checkout_externals"
    ]
   },
   {
@@ -181,7 +223,7 @@
    "metadata": {},
    "source": [
     "\n",
-    "The CESM code downloaded with the branch tag does not include all of the code and support for the component models. These are developed and maintained in other Github repositories. To include all of the component models into your code workspace you need to download them as an additional step. The checkout_externals tool is located in manage_externals directory in the `my_cesm_code` code directory.\n",
+    "The CESM code downloaded with the branch tain the previous step does not include all of the code and support for the component models. These are developed and maintained in other Github repositories. To include all of the component models into your code workspace you need to download them as an additional step. The checkout_externals tool is located in manage_externals directory in the `my_cesm_code` code directory.\n",
     "\n",
     "<div class=\"alert alert-info\">\n",
     "<strong>Exercise: Run the `checkout_externals` command to download all the component models: </strong><br>\n",
@@ -233,7 +275,7 @@
    "id": "74d14003-78cc-48e6-bcbc-622f0150dfed",
    "metadata": {},
    "source": [
-    "- The path `/glade/work/$USER/code/my_cesm_code` is your workspace `SRCROOT`, as described in the [workspaces section](https://ncar.github.io/CESM-Tutorial/notebooks/basics/cesm_workspaces.html#workspace-overview)."
+    "- The path `/glade/work/$USER/code/my_cesm_code` is your workspace `$SRCROOT`, as described in the [workspaces section](https://ncar.github.io/CESM-Tutorial/notebooks/basics/cesm_workspaces.html#workspace-overview)."
    ]
   },
   {

notebooks/basics/exercises_overview.ipynb

@@ -46,7 +46,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.12"
+   "version": "3.10.13"
   }
  },
  "nbformat": 4,

notebooks/intro/components.ipynb

@@ -9,7 +9,7 @@
    "source": [
     "# What is CESM ? \n",
     "\n",
-    "CESM is a coupled Earth system model for simulating Earth’s climate system and connected component systems. The model is composed of **separate models** that simultaneously simulate the Earth’s atmosphere, ocean, land, river run-off, land-ice, and sea-ice. The model components that are coupled through the Common Infrastructure for  Modeling the Earth known as **CIME**. \n"
+    "CESM is a coupled Earth system model for simulating Earth’s climate system and connected component systems. The model is composed of **separate models** that simultaneously simulate the Earth’s atmosphere, ocean, land, river run-off, land-ice, and sea-ice. The model components that are coupled through the Common Infrastructure for  Modeling the Earth known as **[CIME](https://esmci.github.io/cime/versions/master/html/index.html)**. \n"
    ]
   },
   {

notebooks/intro/coupling.ipynb

@@ -15,7 +15,7 @@
    "id": "b247f4d7-ca36-4b62-bc4d-007c42ed9892",
    "metadata": {},
    "source": [
-    "The Combined Model Components form the coupled CESM through a shared common set of tools and infrastructure and coupling framework. Here we describe the Common Infrastructure for Modeling the Earth otherwise known as CIME, as well as the current CESM2 and future coupling frameworks.\n"
+    "The Combined Model Components form the coupled CESM through a shared common set of tools and infrastructure and coupling framework. Here we describe the Common Infrastructure for Modeling the Earth otherwise known as [CIME](https://esmci.github.io/cime/versions/master/html/index.html), as well as the current CESM2 and future coupling frameworks.\n"
    ]
   },
   {

notebooks/intro/project.ipynb

@@ -82,7 +82,9 @@
    "id": "09ca207c-608c-4933-b640-e8155e100b10",
    "metadata": {},
    "source": [
-    "**We welcome and strongly encourage anyone interested to join the relevant CESM working groups to participate more fully in the CESM project and model development.**"
+    "**We welcome and strongly encourage anyone interested to join the relevant CESM working groups to participate more fully in the CESM project and model development.** \n",
+    "\n",
+    "**Check the webpage [\"Getting Involved\"](https://ncar.github.io/CESM-Tutorial/notebooks/intro/getting_involved.html) for more information.**"
    ]
   },
   {
@@ -92,6 +94,14 @@
    "metadata": {},
    "outputs": [],
    "source": []
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "603ca3b9-3c17-4697-9bb3-02526745b130",
+   "metadata": {},
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {

notebooks/prereqs/exercises.ipynb

@@ -99,11 +99,11 @@
    ]
   },
   {
-   "cell_type": "markdown",
-   "id": "24704ecd-13d2-475f-99f0-157bcda05f19",
+   "cell_type": "raw",
+   "id": "b32ec2e7-06f8-4f26-905f-6d495c4cf299",
    "metadata": {},
    "source": [
-    "Feel free to look around more of the NCAR HPC system. The links on the previous page about using derecho may be useful in learning what other parts of the file system may be particularly relevant to you."
+    "Feel free to look around more of the NCAR HPC system. In the Resources chapter, you will find a section about the [NCAR Supercomputer](https://ncar.github.io/CESM-Tutorial/notebooks/resources/ncar_hpc.html) with links that may be particularly relevant to you."
    ]
   },
   {

notebooks/prereqs/prereqs_overview.ipynb

@@ -126,7 +126,7 @@
     "\n",
     "<div class=\"alert alert-info\" style=\"text-align: center;\">\n",
     "\n",
-    "[CISL Documentation on Using X11](https://arc.ucar.edu/knowledge_base/72581213#QuickstartonDerecho-LogginginonanNCARsystem)\n",
+    "[NCAR High Performance Computing (HPC)](https://ncar.github.io/CESM-Tutorial/notebooks/resources/ncar_hpc.html)\n",
     "    \n",
     "</div>"
    ]

notebooks/resources/terminals.ipynb

@@ -25,7 +25,7 @@
    "source": [
     "<div class=\"alert alert-info\" style=\"text-align: center;\">\n",
     "\n",
-    "[Logging into NCAR HPC](https://arc.ucar.edu/knowledge_base/87655186)\n",
+    "[Logging into NCAR HPC](https://ncar.github.io/CESM-Tutorial/notebooks/resources/ncar_hpc.html#logging-in-on-an-ncar-system)\n",
     "    \n",
     "</div>"
    ]
@@ -144,17 +144,13 @@
    "id": "ee17bae0-38d6-4556-94d0-5aada3603a77",
    "metadata": {},
    "source": [
-    "CISL has provided an option to log into casper via the fastX software. Detailed instructions are provided here:\n",
+    "CISL has provided an option to log into casper via the fastX software. Detailed instructions are provided [here](https://arc.ucar.edu/knowledge_base/72581391)\n",
     "\n",
-    "https://arc.ucar.edu/knowledge_base/72581391\n",
+    "- Note that you will not be able to use the first option \"Using FastX via web browser\" as this requires being on the internal UCAR network or VPN. \n",
     "\n",
-    "You will not be able to use the first option \"Using FastX via web browser\" as this requires being on the internal UCAR network or VPN. If you are able to install the desktop client, we would recommend that option:\n",
+    "- If you are able to install the [FastX desktop client](https://arc.ucar.edu/knowledge_base/72581391#UsingFastXforremotedesktops-UsingtheFastXdesktopclient), we would recommend that option\n",
     "\n",
-    "https://arc.ucar.edu/knowledge_base/72581391#UsingFastXforremotedesktops-UsingtheFastXdesktopclient\n",
-    "\n",
-    "Otherwise, you can create an ssh tunnel via a terminal window and then start the browser client:\n",
-    "\n",
-    "https://arc.ucar.edu/knowledge_base/72581391#UsingFastXforremotedesktops-UsingFastXviawebbrowserandsshtunnel\n"
+    "- Otherwise, you can create an [ssh tunnel via a terminal window and then start the browser client](https://arc.ucar.edu/knowledge_base/72581391#UsingFastXforremotedesktops-UsingFastXviawebbrowserandsshtunnel)\n"
    ]
   },
   {
@@ -170,10 +166,18 @@
    "id": "6b212673-a637-4073-9be5-817d32696560",
    "metadata": {},
    "source": [
-    "For older Windows laptops, it may require the use of PuTTY and Xmg. These might be installed on your machine already, but if not you can download them. Here is a nice guide from UC-Irvine:\n",
+    "For older Windows laptops, it may require the use of PuTTY and Xmg. These might be installed on your machine already, but if not you can download them. Here is a [nice guide](https://laptops.eng.uci.edu/engineering-software/using-linux/how-to-configure-putty-xming-on-your-laptop) from UC-Irvine.\n",
     "\n",
-    "https://laptops.eng.uci.edu/engineering-software/using-linux/how-to-configure-putty-xming-on-your-laptop\n"
+    "\n"
    ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c94441cd-66f7-4fe9-8ddf-2123048149b9",
+   "metadata": {},
+   "outputs": [],
+   "source": []
   }
  ],
  "metadata": {