diff --git a/README.md b/README.md index a8dcc65f..18b960c8 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ This repository includes materials designed to be an introduction to running the ## Goals of This Tutorial -**Through this tutorial, you will learn how to: +Through this tutorial, you will learn how to: - Create and run CESM simulations. - Understand the structure and configuration of CESM experiments. @@ -17,7 +17,7 @@ This repository includes materials designed to be an introduction to running the - Analyze and interpret model output. - Design and perform simple scientific experiments using CESM. -The materials are primarily based on CESM3 concepts and workflows, although many of the principles apply to other versions of CESM as well.** +The materials are primarily based on CESM3 concepts and workflows, although many of the principles apply to other versions of CESM as well. ## Yearly In-Person Tutorials diff --git a/notebooks/basics/cesm_workspaces.ipynb b/notebooks/basics/cesm_workspaces.ipynb index 8a2d2b73..0edeeb78 100644 --- a/notebooks/basics/cesm_workspaces.ipynb +++ b/notebooks/basics/cesm_workspaces.ipynb @@ -79,7 +79,7 @@ "\n", "Before creating and running CESM simulations, you will create directories to store the CESM source code and a directory to store all your case directories. \n", "\n", - "In the CESM jargon, a `case` refers to a specific instance of a model simulation." + "In the CESM jargon, a `case` refers to a **model simulation**." ] }, { @@ -150,7 +150,7 @@ "id": "4e972986-5267-43a8-917b-1e36c7117323", "metadata": {}, "source": [ - "You do not need to create the input data directory (`$DIN_LOC_ROOT`) on NCAR systems, as these datasets are already available in a shared location.\n", + "You do not need to create the input data directory (`$DIN_LOC_ROOT`) on NCAR systems, as these datasets are already available in a shared location. This location is shared by all CESM users to save space on the NCAR supercomputer. \n", "\n", "Similarly, the build (`$EXEROOT`), run (`$RUNDIR`), and archive (`$DOUT_S_ROOT`) directories are created automatically when you create a CESM case." ] diff --git a/notebooks/basics/code/git_download_cesm.ipynb b/notebooks/basics/code/git_download_cesm.ipynb index 24a6a969..0e3322d8 100644 --- a/notebooks/basics/code/git_download_cesm.ipynb +++ b/notebooks/basics/code/git_download_cesm.ipynb @@ -88,14 +88,14 @@ "
\n", "Exercise: Clone the CESM Repository
\n", " \n", - "- Change the current directory to the code workspace directory: \n", + "- **Change the current directory to the code workspace directory**: \n", "\n", "```\n", " cd /glade/u/home/$USER/code\n", "```\n", "
\n", " \n", - "- Download the CESM code to your code workspace directory as `my_cesm_code`:\n", + "- **Download the CESM code to your code workspace directory as `my_cesm_code`:**\n", "\n", "```\n", " git clone https://github.com/ESCOMP/CESM.git my_cesm_code\n", @@ -104,7 +104,7 @@ "```\n", "The directory name `my_cesm_code` is only an example. You may choose any directory name you prefer. Outside of this tutorial, many users choose names that identify the CESM version they are working with (for example, `cesm3.0`, or `cesm3.0_Tutorial2026`).\n", "\n", - "- Verify the Tutorial Tag\n", + "- **Verify the Tutorial Tag**\n", "\n", "You can verify that you are using the correct version by running:\n", "\n", @@ -126,7 +126,7 @@ "metadata": {}, "source": [ "\n", - "
\n", + "
\n", "
\n", "\n", " Click here for example output \n", @@ -204,7 +204,7 @@ "\n", "One of the first decisions when starting a modeling project is choosing which version of CESM to use. Factors to consider include:\n", "\n", - "- Scientific and technical support for the version.\n", + "- Scientific and technical support for the version. As a rule of the thumb, release tags are the most supported version of CESM. \n", "- Availability of model features required for your research.\n", "- Consistency with community experiments or previous studies.\n", "- Compatibility with analysis tools and workflows.\n", @@ -239,11 +239,10 @@ "metadata": {}, "source": [ "\n", - "
\n", + "
\n", "
\n", "\n", " Click here for example output \n", - "\n", "
\n", " \n", "```\n", @@ -275,7 +274,7 @@ "\n", "## Step 3. Download Component Models with `git-fleximod` \n", "\n", - "The CESM repository itself does not contain all component model source code. Individual model components are maintained in separate repositories and must be downloaded after cloning CESM. \n", + "The CESM repository itself does not contain all component model source code. **Individual model components are maintained in separate repositories** and must be downloaded after cloning CESM. \n", "\n", "CESM3 uses `git-fleximod` to manage external repositories. \n", "\n", diff --git a/notebooks/basics/code_overview.ipynb b/notebooks/basics/code_overview.ipynb index 7a5c0483..60c67314 100644 --- a/notebooks/basics/code_overview.ipynb +++ b/notebooks/basics/code_overview.ipynb @@ -13,7 +13,7 @@ "id": "56f53601-ba7c-41b0-8d9e-d56f67689734", "metadata": {}, "source": [ - "Before you can start running the CESM, you must first download the CESM code from Github and set up your Workspace. This exercise is estimated to take around 30-60 minutes, depending on your previous experience with NCAR HPC and Github." + "Before you can start running the CESM, you must first **download the CESM code from Github and set up your Workspace**. This exercise is estimated to take around 30-60 minutes, depending on your previous experience with NCAR HPC and Github." ] }, { @@ -43,7 +43,7 @@ "id": "89b36bf1-182b-4460-af55-6f05b7a4a086", "metadata": {}, "source": [ - "If you are unfamiliar with logging into NCAR HPC resources, please review the[section](https://ncar.github.io/CESM-Tutorial/notebooks/prereqs/prereqs_overview.html#ncar-high-performance-computing-hpc) on logging into Derecho before continuing.\n", + "If you are unfamiliar with logging into NCAR HPC resources, please review the [section](https://ncar.github.io/CESM-Tutorial/notebooks/prereqs/prereqs_overview.html#ncar-high-performance-computing-hpc) on logging into Derecho before continuing.\n", "\n", "## GitHub and Git\n", "\n", diff --git a/notebooks/namelist/documentation.ipynb b/notebooks/namelist/documentation.ipynb index ca57aff9..4d63d590 100644 --- a/notebooks/namelist/documentation.ipynb +++ b/notebooks/namelist/documentation.ipynb @@ -38,10 +38,16 @@ "id": "42e1dd6f-c704-4f69-965a-a015d3d0baed", "metadata": {}, "source": [ - "The search results will include the namelist variable ``nhtfrq``, as illustrated in *Figure 2*. ``nhtfrq`` is the variable you need in order to controls the frequency at which CAM history files are written. \n", + "The search results will include the namelist variable ``nhtfrq``, as illustrated in *Figure 1*. ``nhtfrq`` is the variable you need in order to controls the frequency at which CAM history files are written. \n", "\n", - "If you click on **+** on the left of `nhtfrq`, this will return the attributes of the namelist variable. \n", + "If you click on **+** on the left of `nhtfrq`, this will return the attributes of the namelist variable as shown in *Figure 2*. \n", "\n", + "This provides detailed information, including:\n", + "\n", + "- A description of the variable.\n", + "- The valid values and their meanings.\n", + "- The default value.\n", + "- The namelist group where the variable is defined.\n", "___\n", "![Attribute of a namelist variable](../../images/namelist/nhtfrq.png)\n", "\n", @@ -53,12 +59,6 @@ "id": "419a5f30-7738-49b3-8cf2-607d39b43e40", "metadata": {}, "source": [ - "This provides detailed information, including:\n", - "\n", - "- A description of the variable.\n", - "- The valid values and their meanings.\n", - "- The default value.\n", - "- The namelist group where the variable is defined.\n", "\n", "When making namelist modifications, it is good practice to consult the documentation to verify that the variable exists, understand its behavior, and ensure that the specified values are valid.\n", "\n", diff --git a/notebooks/namelist/output.ipynb b/notebooks/namelist/output.ipynb index afb32278..74ef641d 100644 --- a/notebooks/namelist/output.ipynb +++ b/notebooks/namelist/output.ipynb @@ -13,7 +13,7 @@ "id": "34b38707-9fbb-4e2a-bb99-5d3ddac76dc0", "metadata": {}, "source": [ - "If you don't add anything to the namelist, CESM will generate its **``default output``**. This is what was done in previous chapters of this tutorial. By default, CESM components typically write monthly mean history files, along with a predefined set of variables. Some components may also produce additional output at higher temporal frequencies.\n", + "If you don't add anything to the namelist, CESM will generate its **default output** This is the output you got in the previous chapters exercises of this tutorial. By default, CESM components typically write **monthly mean history files, along with a predefined set of variables**. Some components may also produce additional output at higher temporal frequencies.\n", "\n", "Depending on your scientific goals, you may wish to customize the model output. Common modifications include:\n", "- Changing the output frequency (for example, from monthly to daily or hourly).\n", @@ -21,9 +21,9 @@ "- Adding variables that are not included in the default output.\n", "- Reducing the number of output variables to save disk space. \n", "\n", - "In this chapter **``Customizing output``**, we will cover how to output at a different frequency, add history files, or add variables to the history files.\n", + "In this chapter **Customizing output**, we cover how to output variables at a different frequency, add history files, or add variables to the history files.\n", "\n", - "In the sections below, we provide the basics of customizing the output for the different components (atm, lnd, ice, and pop). The section on **customizing CAM output** is the most comprehensive and introduces many of the concepts that are common across CESM components. We therefore **recommend reviewing that section first, even if your primary interest is another component model**." + "In particular, we provide the basics of customizing the output for the different components (atm, lnd, ice, and mom). The section on **customizing CAM output** is the most comprehensive and introduces many of the concepts that are common across CESM components. We therefore **recommend reviewing that section first, even if your primary interest is another component model**." ] } ], diff --git a/notebooks/namelist/output/output_cam.ipynb b/notebooks/namelist/output/output_cam.ipynb index 6e599236..ec434585 100644 --- a/notebooks/namelist/output/output_cam.ipynb +++ b/notebooks/namelist/output/output_cam.ipynb @@ -324,9 +324,9 @@ "fincl2 = 'T:I','Q:I','U:I','V:I'\n", "```\n", "\n", - "#### Output Files for Different Averaging Types\n", + "#### **Output Files for Different Averaging Types**\n", "\n", - "CAM may write variables with different averaging characteristics to separate output files.\n", + "In CESM3, CAM writes variables with different averaging characteristics to separate output files.\n", "\n", "For example:\n", "\n", @@ -345,7 +345,7 @@ "- `T:A` and `PRECT:A` are time-averaged variables.\n", "- `U:I` is an instantaneous variable.\n", "\n", - "CAM may place the averaged and instantaneous variables in separate output files because they require different temporal processing.\n", + "CAM will place the averaged and instantaneous variables in separate output files because they require different temporal processing.\n", "\n", "***Note**: The exact naming and grouping of history files can vary between CAM versions. If you do not find a variable in the expected history file, check the history files in the run directory to determine where CAM has written it.*\n", "\n", @@ -425,10 +425,11 @@ "source": [ "## Interpolating Output to a Latitude–Longitude Grid, `interpolate_output`\n", "\n", - "CAM is often run using the spectral-element (SE) dynamical core, \n", - "where model variables are stored on an unstructured cubed-sphere grid. \n", + "In CESM3, CAM is by default run using the **spectral-element (SE) dynamical core**, \n", + "where model variables are stored on an **unstructured cubed-sphere grid**. \n", "While this grid is advantageous for model simulations, many analysis \n", - "and visualization tools are designed to work with regular latitude–longitude grids.\n", + "and visualization tools are designed to work with regular latitude–longitude grids\n", + "However, CAM can **interpolate output to a latitude–longitude grid** on the fly. \n", "\n", "For example, to interpolate output to a 1° × 1° latitude–longitude grid, \n", "add the following lines to `user_nl_cam`:\n", @@ -445,7 +446,7 @@ "- `interpolate_nlat = 181` specifies the number of latitude points.\n", "- `interpolate_nlon = 360` specifies the number of longitude points.\n", "\n", - "The resulting output will be written on a regular 1° × 1° latitude–longitude grid.\n", + "The output will be written on a regular 1° × 1° latitude–longitude grid.\n", "\n", "***Note**: Interpolation affects only the history-file output. The model itself continues to run on its native spectral-element grid.*\n", "\n", @@ -485,6 +486,14 @@ "
" ] }, + { + "cell_type": "markdown", + "id": "b952d7fc-20c0-4ad7-83fa-fb991d9b5d94", + "metadata": {}, + "source": [ + "## " + ] + }, { "cell_type": "markdown", "id": "f22c3b80-b173-4e43-8af9-e684683aaf99", diff --git a/notebooks/namelist/output/output_cice.ipynb b/notebooks/namelist/output/output_cice.ipynb index d55704ec..cfcbc703 100644 --- a/notebooks/namelist/output/output_cice.ipynb +++ b/notebooks/namelist/output/output_cice.ipynb @@ -78,9 +78,12 @@ "- A second history stream is written daily.\n", "- The remaining history streams are disabled (`'x'`).\n", "\n", - "## Evaluate Your Understanding\n", + "\n", + "
\n", + "Evaluate your understanding\n", "\n", "How would you configure CICE to output 6-hourly instantaneous values?\n", + "
\n", "\n", "
\n", "Click here for the solution\n", @@ -95,13 +98,17 @@ "\n", "
\n", "\n", - "## Evaluate Your Understanding\n", "\n", - "How would you configure CICE to output daily averages?\n", + "
\n", + "Evaluate your understanding\n", "\n", - "
\n", - "Click here for the solution\n", + "How would you configure CICE to output daily averages?\n", + "
\n", "\n", + "
\n", + " \n", + "
\n", + "Click here for the solution
\n", "Add the following lines to `user_nl_cice`:\n", "\n", "```fortran\n", @@ -111,6 +118,7 @@ "```\n", "\n", "
\n", + "
\n", "\n", "> **Note**\n", ">\n", @@ -123,6 +131,14 @@ "For additional information about CICE history output and namelist settings, consult the CESM2 CICE documentation.\n", "\n" ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "cd5a30ad-a0d6-4c19-8e68-54d5f4069a85", + "metadata": {}, + "outputs": [], + "source": [] } ], "metadata": { diff --git a/notebooks/namelist/output/output_clm.ipynb b/notebooks/namelist/output/output_clm.ipynb index fa865501..efdfa93f 100644 --- a/notebooks/namelist/output/output_clm.ipynb +++ b/notebooks/namelist/output/output_clm.ipynb @@ -2,7 +2,7 @@ "cells": [ { "cell_type": "markdown", - "id": "8033848b-dcae-4998-b69a-0735997b93ed", + "id": "6a6bffcd-e5b1-47a9-942c-f68fd851d8da", "metadata": {}, "source": [ "# Customize CLM Output\n", @@ -21,7 +21,14 @@ "* `hist_mfilt`: maximum number of time samples written to each history file\n", "* `hist_fincl`: list of variables to add to each history stream\n", "\n", - "These variables should be added to `user_nl_clm`.\n", + "These variables should be added to `user_nl_clm`." + ] + }, + { + "cell_type": "markdown", + "id": "dee18bc9-4e87-4b9b-89d7-2fe16c3cd31b", + "metadata": {}, + "source": [ "\n", "## CLM history file names: `h0a`, `h0i`, `h1a`, `h1i`, ...\n", "\n", @@ -39,8 +46,14 @@ "h0i, h1i, h2i, ...\n", "```\n", "\n", - "For example, if `TSA` is written as an averaged field on the first history stream, it will appear in an `h0a` file. If `TSA:I` is requested as an instantaneous field on the second history stream, it will appear in an `h1i` file.\n", - "\n", + "For example, if `TSA` is written as an averaged field on the first history stream, it will appear in an `h0a` file. If `TSA:I` is requested as an instantaneous field on the second history stream, it will appear in an `h1i` file.\n" + ] + }, + { + "cell_type": "markdown", + "id": "de03efaf-874d-4827-b958-e55720df45ce", + "metadata": {}, + "source": [ "## Customizing CLM Output Frequency: `hist_nhtfrq`\n", "\n", "The namelist variable `hist_nhtfrq` controls how often CLM writes history output.\n", @@ -63,10 +76,13 @@ "\n", "means output every 24 model time steps.\n", "\n", - "## Evaluate Your Understanding\n", + "
\n", + "Evaluate your understanding\n", "\n", "How do you modify CLM output to write 3-hourly data?\n", + "
\n", "\n", + "
\n", "
\n", "Click here for the solution\n", "\n", @@ -79,7 +95,14 @@ "This writes output every 3 hours.\n", "\n", "
\n", - "\n", + "
\n" + ] + }, + { + "cell_type": "markdown", + "id": "1758916b-de89-4fd6-9a3e-308b64fdc70b", + "metadata": {}, + "source": [ "## Adding Extra Variables and History Streams: `hist_fincl`\n", "\n", "CLM can write multiple history streams. The history streams are numbered internally as:\n", @@ -112,8 +135,14 @@ "hist_fincl1 = 'TG:I'\n", "```\n", "\n", - "This would appear in an `h0i` file.\n", - "\n", + "This would appear in an `h0i` file." + ] + }, + { + "cell_type": "markdown", + "id": "0a9b62c4-9d73-4673-9501-b17bf4cb58d1", + "metadata": {}, + "source": [ "## Customizing the Number of Samples per File: `hist_mfilt`\n", "\n", "The namelist variable `hist_mfilt` controls the maximum number of time samples written to each history file.\n", @@ -140,10 +169,15 @@ "hist_mfilt = 1\n", "```\n", "\n", - "```{note}\n", - "For monthly output, `hist_mfilt` is generally set to 1. Monthly CLM history files are normally written with one monthly average per file.\n", - "```\n", "\n", + "For monthly output, `hist_mfilt` is generally set to 1. Monthly CLM history files are normally written with one monthly average per file.\n" + ] + }, + { + "cell_type": "markdown", + "id": "f7d823ff-20a0-43b6-81be-967b5ffc6a18", + "metadata": {}, + "source": [ "## Creating Additional History Streams\n", "\n", "The first history stream, `h0`, is the default CLM history stream. You can create additional streams by setting values for `hist_fincl2`, `hist_fincl3`, and so on.\n", @@ -158,16 +192,26 @@ "\n", "The first value in `hist_nhtfrq` and `hist_mfilt` applies to `h0`. The second value applies to `h1`.\n", "\n", - "Because `TG` and `TSA` are written as averaged fields here, they will appear in an `h1a` file.\n", + "Because `TG` and `TSA` are written as averaged fields here, they will appear in an `h1a` file.\n" + ] + }, + { + "cell_type": "markdown", + "id": "991b80ca-d2b5-4cab-beab-0a35b48beb8d", + "metadata": {}, + "source": [ "\n", - "## Evaluate Your Understanding\n", + "
\n", + "Evaluate your understanding\n", "\n", "What namelist settings would create:\n", "\n", "* a monthly `h1` file with `TG` and `TSA`\n", "* a daily `h2` file with `TG` and `TSA`\n", "* 10 time samples in each `h1` and `h2` file\n", + "
\n", "\n", + "
\n", "
\n", "Click here for the solution\n", "\n", @@ -198,11 +242,15 @@ "```\n", "\n", "
\n", + "
\n", "\n", - "## Evaluate Your Understanding\n", + "
\n", + "Evaluate your understanding\n", "\n", "What settings would generate CLM 3-hourly data for a month-long simulation, with one output file per day?\n", + "
\n", "\n", + "
\n", "
\n", "Click here for the solution\n", "\n", @@ -224,7 +272,14 @@ "```\n", "\n", "
\n", - "\n", + "
" + ] + }, + { + "cell_type": "markdown", + "id": "8033848b-dcae-4998-b69a-0735997b93ed", + "metadata": {}, + "source": [ "## Averaging Flags for `hist_fincl` Variables\n", "\n", "You can add an averaging flag after a variable name using a colon.\n", @@ -269,6 +324,7 @@ "hist_mfilt = 1, 30, 30, 8, 8\n", "```\n", "\n", + "
\n", "
\n", "Click here for the solution\n", "\n", @@ -287,11 +343,20 @@ "* `h4i` contains 8 three-hourly samples per file, or one day per file\n", "\n", "
\n", + "
\n", + "\n", "\n", - "```{note}\n", "Increasing output frequency or adding many variables can substantially increase the amount of data written and can slow down the model. Add only the variables and frequencies needed for your exercise.\n", - "```\n" + "\n" ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "714f1144-22f6-4d11-bf33-8b508368ae8c", + "metadata": {}, + "outputs": [], + "source": [] } ], "metadata": { diff --git a/notebooks/namelist/output/output_mom.ipynb b/notebooks/namelist/output/output_mom.ipynb index 8a4bdc8c..63f40c3c 100644 --- a/notebooks/namelist/output/output_mom.ipynb +++ b/notebooks/namelist/output/output_mom.ipynb @@ -9,7 +9,9 @@ "\n", "## Adding MOM6 Diagnostics\n", "\n", - "MOM6 diagnostics are controlled through a file called `diag_table`. During case setup, CESM generates a template file named:\n", + "MOM6 diagnostics are controlled through a file called `diag_table`. \n", + "\n", + "During case setup, CESM generates a template file named:\n", "\n", "```bash\n", "Buildconf/momconf/diag_table.unresolved\n", @@ -18,15 +20,12 @@ "To customize the diagnostics that MOM6 outputs, copy this file into your SourceMods directory:\n", "\n", "```bash\n", - "mkdir -p SourceMods/src.mom\n", "cp Buildconf/momconf/diag_table.unresolved SourceMods/src.mom/diag_table\n", "```\n", "\n", "You can then edit `SourceMods/src.mom/diag_table` to add, remove, or modify diagnostic output fields.\n", "\n", - "> **Note**\n", - ">\n", - "> CESM regenerates files in `Buildconf` during case setup. Therefore, user modifications should be made in `SourceMods/src.mom/diag_table`, which will override the default version and be preserved during subsequent builds.\n", + "**Note** *CESM regenerates files in `Buildconf` during case setup. Therefore, **user modifications should be made in `SourceMods/src.mom/diag_table`**, which will override the default version and be preserved during subsequent builds.*\n", "\n", "The `diag_table` specifies:\n", "\n", @@ -142,9 +141,7 @@ "\n", "writes a daily mean temperature.\n", "\n", - "> **Note**\n", - ">\n", - "> Increasing the output frequency or adding a large number of diagnostics can significantly increase output volume and reduce model throughput. Start with a small number of diagnostics and increase the frequency only when needed.\n", + "**Note**: *Increasing the output frequency or adding a large number of diagnostics can **significantly increase output volume and reduce model throughput**. Start with a small number of diagnostics and increase the frequency only when needed.*\n", "\n", "For additional details about the `diag_table` format and MOM6 diagnostics, see the MOM6 documentation.\n", "https://mom6.readthedocs.io/en/main/api/generated/pages/Diagnostics.html\n",