Skip to content

Commit fdb210b

Browse files
cecilehannaycecilehannay
authored
Merge pull request #328 from cecilehannay/main
namelist notyebooks (partial)
2 parents af78ab9 + f019298 commit fdb210b

4 files changed

Lines changed: 150 additions & 113 deletions

File tree

‎notebooks/basics/code/cesm_code_explore.ipynb‎

Lines changed: 102 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -67,9 +67,9 @@
6767
"```\n",
6868
"<br>\n",
6969
"\n",
70-
"- If your output matches the path above, you are already in the CESM source code directory and can continue to the next step. (If you have not done anything since the last exercise then you will already be in the `$SRCROOT` location)\n",
70+
"If your output matches the path above, you are already in the CESM source code directory and can continue to the next step. (If you have not done anything since the last exercise then you will already be in the `$SRCROOT` location)\n",
7171
"\n",
72-
"- If your output is different, navigate to the CESM source code directory:\n",
72+
"If your output is different, navigate to the CESM source code directory:\n",
7373
"\n",
7474
"```\n",
7575
"cd /glade/u/home/$USER/code/my_cesm_code\n",
@@ -110,15 +110,18 @@
110110
"source": [
111111
"## Step 2. Examine the CIME Directory\n",
112112
"\n",
113-
"One of the most important directories in CESM is the CIME directory. CIME (Common Infrastructure for Modeling the Earth) provides the framework that integrates the CESM component models and manages the workflow for configuring, building, and running simulations.\n",
113+
"One of the most important directories in CESM is the **CIME** directory. \n",
114+
"\n",
115+
"The CIME(Common Infrastructure for Modeling the Earth) directory provides the framework that integrates the CESM component models and manages the workflow for configuring, building, and running simulations.\n",
114116
"\n",
115117
"<div class=\"alert alert-info\">\n",
116118
"<strong>Exercise </strong><br>\n",
117119
"- Move into the CIME directory:\n",
120+
"\n",
118121
"```\n",
119122
"cd cime\n",
120123
"```\n",
121-
" \n",
124+
"\n",
122125
"- List its contents:\n",
123126
"```\n",
124127
"ls -1\n",
@@ -143,15 +146,21 @@
143146
"```\n",
144147
"ls -l\n",
145148
"```\n",
146-
"Notice the following commands:\n",
149+
"Notice the following scripts:\n",
147150
"```\n",
148151
"create_newcase\n",
149152
"create_clone\n",
150153
"create_test\n",
151154
"query_config\n",
152155
"query_testlists\n",
153156
"```\n",
154-
"Throughout this tutorial, create_newcase will be one of the most frequently used commands.\n",
157+
"Throughout this tutorial, **create_newcase** will be one of the most frequently used commands.\n",
158+
"\n",
159+
"**Check Your Understanding**\n",
160+
"\n",
161+
"What is the purpose of the `create_newcase` command?\n",
162+
"\n",
163+
"*Hint: It is used to create a new CESM experiment (or \"case\") that can later be configured, built, and run.*\n",
155164
" \n",
156165
"</div>\n"
157166
]
@@ -169,7 +178,7 @@
169178
"*<p style=\"text-align: center;\"> Figure: CESM2 Code Components </p>*\n",
170179
"\n",
171180
"<div class=\"alert alert-info\">\n",
172-
"<strong>Change back to the Code Workspace Location: </strong><br>\n",
181+
"- Change back to the Code Workspace Location:\n",
173182
"\n",
174183
"```\n",
175184
"cd /glade/u/home/$USER/code/my_cesm_code\n",
@@ -182,33 +191,54 @@
182191
"\n",
183192
"<br>\n",
184193
" \n",
185-
"<strong>Change into the Components area of the Code Workspace: </strong><br>\n",
194+
"- Change into the `components` area of the code workspace: <br>\n",
186195
"\n",
187196
"```\n",
188197
"cd components\n",
189198
"```\n",
190199
"<br>\n",
191200
"\n",
192-
"<strong>List the contents of the Components Directory: </strong><br>\n",
201+
"- List the contents of the Components Directory: <br>\n",
193202
"\n",
194203
"```\n",
195-
"ls -l\n",
204+
"ls -1\n",
196205
"```\n",
197206
"<br>\n",
198207
" \n",
199-
"<strong>Expected Output: </strong><br>\n",
200-
"\n",
201-
"```\n",
202-
"total 8\n",
203-
"drwxr-xr-x 12 $USER ncar 4096 Jun 4 09:34 cam\n",
204-
"drwxr-xr-x 7 $USER ncar 4096 Jun 4 09:32 cice\n",
205-
"drwxr-xr-x 14 $USER ncar 4096 Jun 4 09:32 cism\n",
206-
"drwxr-xr-x 12 $USER ncar 4096 Jun 4 09:31 clm\n",
207-
"drwxr-xr-x 6 $USER ncar 4096 Jun 4 09:31 mosart\n",
208-
"drwxr-xr-x 15 $USER ncar 4096 Jun 4 09:32 pop\n",
209-
"drwxr-xr-x 6 $USER ncar 4096 Jun 4 09:32 rtm\n",
210-
"drwxr-xr-x 6 $USER ncar 4096 Jun 4 09:31 ww3\n",
211-
"```\n",
208+
"Expected Output: <br>\n",
209+
"\n",
210+
"```\n",
211+
"cam\n",
212+
"cdeps\n",
213+
"cice\n",
214+
"cism\n",
215+
"clm\n",
216+
"cmeps\n",
217+
"mizuRoute\n",
218+
"mom\n",
219+
"mosart\n",
220+
"rtm\n",
221+
"ww3\n",
222+
"```\n",
223+
"\n",
224+
"Each directory contains the source code for a different Earth system component or supporting infrastructure:\n",
225+
"\n",
226+
"| Component | Description |\n",
227+
"|------------|------------|\n",
228+
"| CAM | Community Atmosphere Model (atmosphere) |\n",
229+
"| CLM | Community Land Model (land) |\n",
230+
"| MOM | Modular Ocean Model (ocean) |\n",
231+
"| CICE | Sea Ice Model |\n",
232+
"| CISM | Community Ice Sheet Model (land ice) |\n",
233+
"| MOSART | Model for Scale Adaptive River Transport |\n",
234+
"| mizuRoute | River routing model |\n",
235+
"| RTM | Runoff Transport Model (legacy routing infrastructure) |\n",
236+
"| WW3 | WaveWatch III (ocean waves) |\n",
237+
"| CMEPS | Coupling infrastructure used to exchange information between component models |\n",
238+
"| CDEPS | Data components used to provide prescribed atmosphere, ocean, land, ice, and other forcing datasets |\n",
239+
"\n",
240+
"Together, these components represent the major elements of the Earth system. During a CESM simulation, information such as heat, moisture, momentum, runoff, and sea-ice state is exchanged between components through the coupling infrastructure provided by CMEPS.\n",
241+
"Together, these components represent the major elements of the Earth system. During a CESM simulation, information such as heat, moisture, momentum, runoff, and sea-ice state is exchanged between components through the coupling infrastructure provided by CMEPS.\n",
212242
"\n",
213243
"</div>"
214244
]
@@ -220,17 +250,19 @@
220250
"source": [
221251
"## Step 4. Look at the Community Atmosphere Model (CAM) Component Model\n",
222252
"\n",
223-
"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",
253+
"As a final exercise, let's take a quick look at the Community Atmosphere Model (CAM), which provides the atmospheric component of CESM.\n",
224254
"\n",
225255
"<div class=\"alert alert-info\">\n",
226-
"<strong>Change into the CAM Directory of the Components area: </strong><br>\n",
256+
"<strong>Exercise</strong><br>\n",
257+
"\n",
258+
"- Change into the CAM source directory:\n",
227259
"\n",
228260
"```\n",
229261
"cd cam\n",
230262
"```\n",
231263
"<br>\n",
232264
"\n",
233-
"<strong>List the contents of the CAM Directory: </strong><br>\n",
265+
"- List the contents of the CAM Directory: <br>\n",
234266
"\n",
235267
"```\n",
236268
"ls -l\n",
@@ -240,66 +272,57 @@
240272
"<strong>Expected Output: </strong><br>\n",
241273
"\n",
242274
"```\n",
243-
"total 26\n",
244-
"drwxr-xr-x 6 $USER ncar 4096 Jun 4 09:32 bld\n",
245-
"drwxr-xr-x 10 $USER ncar 4096 Jun 4 09:34 chem_proc\n",
246-
"drwxr-xr-x 4 $USER ncar 4096 Jun 4 09:32 cime_config\n",
247-
"-rw-r--r-- 1 $USER ncar 7501 Jun 4 09:32 CODE_OF_CONDUCT.md\n",
248-
"drwxr-xr-x 2 $USER ncar 4096 Jun 4 09:32 doc\n",
249-
"-rw-r--r-- 1 $USER ncar 685 Jun 4 09:32 Externals_CAM.cfg\n",
250-
"-rw-r--r-- 1 $USER ncar 1155 Jun 4 09:32 Externals.cfg\n",
251-
"drwxr-xr-x 5 $USER ncar 4096 Jun 4 09:32 manage_externals\n",
252-
"-rw-r--r-- 1 $USER ncar 1925 Jun 4 09:32 README_EXTERNALS\n",
253-
"-rw-r--r-- 1 $USER ncar 282 Jun 4 09:32 README.md\n",
254-
"drwxr-xr-x 11 $USER ncar 4096 Jun 4 09:32 src\n",
255-
"drwxr-xr-x 4 $USER ncar 4096 Jun 4 09:32 test\n",
256-
"drwxr-xr-x 11 $USER ncar 4096 Jun 4 09:32 tools\n",
275+
"bin\n",
276+
"bld\n",
277+
"ccs_config\n",
278+
"chem_proc\n",
279+
"cime\n",
280+
"cime_config\n",
281+
"components\n",
282+
"doc\n",
283+
"libraries\n",
284+
"LICENSE\n",
285+
"manage_externals\n",
286+
"README.md\n",
287+
"share\n",
288+
"src\n",
289+
"test\n",
290+
"tools\n",
257291
"```\n",
292+
"Several of these directories will become important as you begin working with CAM:\n",
258293
"\n",
259-
"</div>\n",
294+
"| Directory | Purpose |\n",
295+
"|------------|------------|\n",
296+
"| `src` | Main CAM source code |\n",
297+
"| `chem_proc` | Atmospheric chemistry infrastructure |\n",
298+
"| `test` | CAM test cases and testing tools |\n",
299+
"| `doc` | CAM documentation |\n",
300+
"| `tools` | Utilities for development and analysis |\n",
301+
"| `bld` | Build-related scripts and configuration files |\n",
260302
"\n",
261-
"**Congratulations, you have now completed the CESM code exploration exercises!!**"
303+
"The `src` directory is where most scientific development takes place and is the area you will explore in later exercises.\n",
304+
"</div>\n",
305+
"\n"
262306
]
263307
},
264308
{
265-
"cell_type": "code",
266-
"execution_count": null,
267-
"id": "50898f29-f9dd-470c-9918-a05df415b4a8",
268-
"metadata": {},
269-
"outputs": [],
270-
"source": []
271-
},
272-
{
273-
"cell_type": "code",
274-
"execution_count": null,
275-
"id": "80d816ff-6217-4a2b-a9d0-4e5ae5e7ab21",
276-
"metadata": {},
277-
"outputs": [],
278-
"source": []
279-
},
280-
{
281-
"cell_type": "code",
282-
"execution_count": null,
283-
"id": "ab049642-5bfe-4d46-92c7-c3c2ec6570fc",
284-
"metadata": {},
285-
"outputs": [],
286-
"source": []
287-
},
288-
{
289-
"cell_type": "code",
290-
"execution_count": null,
291-
"id": "18a9a811-0883-410d-bfb1-d3eb16e3fd75",
292-
"metadata": {},
293-
"outputs": [],
294-
"source": []
295-
},
296-
{
297-
"cell_type": "code",
298-
"execution_count": null,
299-
"id": "5191d62a-76ee-4f90-b46b-f70ec0af9909",
309+
"cell_type": "markdown",
310+
"id": "ced6e281-4f7b-4d4e-a6e1-f83d2fbc5a4a",
300311
"metadata": {},
301-
"outputs": [],
302-
"source": []
312+
"source": [
313+
"## Summary\n",
314+
"\n",
315+
"In this section, you:\n",
316+
"\n",
317+
"- Located the CESM source code directory (`$SRCROOT`).\n",
318+
"- Explored the CIME infrastructure used to create and manage CESM cases.\n",
319+
"- Examined the major CESM component models.\n",
320+
"- Explored the structure of the Community Atmosphere Model (CAM).\n",
321+
"\n",
322+
"Understanding the CESM directory structure will make it easier to navigate the code, locate relevant files, and modify model components in future exercises.\n",
323+
"\n",
324+
"**Congratulations! You have completed the CESM code exploration exercise.**"
325+
]
303326
}
304327
],
305328
"metadata": {

‎notebooks/namelist/documentation.ipynb‎

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,17 @@
77
"source": [
88
"# Namelist Variables Documentation\n",
99
"\n",
10+
"CESM provides extensive documentation for namelist variables, including descriptions, valid values, default settings, and the components in which they are used.\n",
1011
"\n",
1112
"<div class=\"alert alert-info\">\n",
1213
"\n",
1314
"Complete documentation about the namelist variables can be found on the [CESM webpage.](https://docs.cesm.ucar.edu/models/cesm2/settings/current/)\n",
1415
"\n",
15-
"\n",
16+
"**Note:** CESM3 documentation is still under active development. As a result, some of the online namelist documentation and examples currently refer to CESM2. While directory names, component names, and some implementation details may differ between CESM2 and CESM3, the overall approach to searching for, understanding, and modifying namelist variables remains the same. The CESM2 documentation is therefore still a useful reference for learning how namelist settings work in CESM3.\n",
1617
"</div>\n",
1718
"\n",
19+
"When modifying a namelist, it is often helpful to consult the CESM documentation to understand the purpose and allowable values of a variable before making changes.\n",
20+
"\n",
1821
"For instance, if you want to change the **_output frequency_** in CAM, go to the website and type the word ``frequency`` in the search box as illustrated in *Figure 1*. "
1922
]
2023
},
@@ -35,13 +38,30 @@
3538
"id": "42e1dd6f-c704-4f69-965a-a015d3d0baed",
3639
"metadata": {},
3740
"source": [
38-
"This will return the attributes of the namelist variable ``nhtfrq``, as illustrated in *Figure 2*. ``nhtfrq`` is the variable you need in order to change the output frequency of a history file. \n",
41+
"This will return the attributes of the namelist variablehe 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",
3942
"\n",
4043
"___\n",
4144
"![Attribute of a namelist variable](../../images/namelist/nhtfrq.png)\n",
4245
"\n",
4346
"*<p style=\"text-align: center;\"> Figure 2: Attribute of a namelist variable. Here the variable: ``nhtfrq``</p>*"
4447
]
48+
},
49+
{
50+
"cell_type": "markdown",
51+
"id": "419a5f30-7738-49b3-8cf2-607d39b43e40",
52+
"metadata": {},
53+
"source": [
54+
"This provides detailed information, including:\n",
55+
"\n",
56+
"- A description of the variable.\n",
57+
"- The valid values and their meanings.\n",
58+
"- The default value.\n",
59+
"- The namelist group where the variable is defined.\n",
60+
"\n",
61+
"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",
62+
"\n",
63+
"In the following sections, you will learn how to use variables such as `nhtfrq` to customize CESM output."
64+
]
4565
}
4666
],
4767
"metadata": {

‎notebooks/namelist/namelist.ipynb‎

Lines changed: 12 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -13,20 +13,18 @@
1313
"id": "285a23b4-2906-4422-a8a8-987546de6f0c",
1414
"metadata": {},
1515
"source": [
16-
"There are several ways in which the model can be modified using namelist settings. This is what we cover in this chapter:\n",
17-
"- The section **_Overview_** describes the steps to modify the namelists and provides a visual representation of the directories and files that need to be modified.\n",
18-
"- The section **_Documentation_** explains how to find information about the namelist variables on the CESM webpage.\n",
19-
"- The section **_Customizing output_** describes how to customize the output history files, such as changing the output frequency or adding variables to a file.\n",
20-
"- The section **_Exercises_** offers opportunities to practice the concepts learned in this chapter. "
16+
"\n",
17+
"Many aspects of a CESM simulation can be customized through **namelist settings**. Namelists allow users to modify model behavior, output settings, and component-specific options without changing the source code.\n",
18+
"\n",
19+
"In this chapter, you will learn how to work with CESM namelists and apply common modifications to your simulations.\n",
20+
"\n",
21+
"Specifically, this chapter covers:\n",
22+
"\n",
23+
"- **Overview** – Introduces the CESM namelist workflow, including the files and directories involved in customizing a case.\n",
24+
"- **Documentation** – Demonstrates how to find descriptions and valid values for namelist variables using the CESM documentation and online resources.\n",
25+
"- **Customizing Output** – Shows how to modify model output, including changing output frequency, selecting variables, and creating custom history files.\n",
26+
"- **Exercises** – Provides hands-on activities to practice creating and modifying namelist settings."
2127
]
22-
},
23-
{
24-
"cell_type": "code",
25-
"execution_count": null,
26-
"id": "f7cf2d79-da13-416d-8345-385bc1977b79",
27-
"metadata": {},
28-
"outputs": [],
29-
"source": []
3028
}
3129
],
3230
"metadata": {
@@ -45,7 +43,7 @@
4543
"name": "python",
4644
"nbconvert_exporter": "python",
4745
"pygments_lexer": "ipython3",
48-
"version": "3.9.12"
46+
"version": "3.10.13"
4947
}
5048
},
5149
"nbformat": 4,

0 commit comments

Comments
 (0)