From 4e9bebc9c1eb870d83d7f4169a4bdddc860f4577 Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Fri, 13 Nov 2026 20:46:16 -0700 Subject: [PATCH 01/14] Fix a syntax error in the Jinha substitutions --- notebooks/resources/tutorial_specific.ipynb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/notebooks/resources/tutorial_specific.ipynb b/notebooks/resources/tutorial_specific.ipynb index dc52941..e40b9e7 100644 --- a/notebooks/resources/tutorial_specific.ipynb +++ b/notebooks/resources/tutorial_specific.ipynb @@ -24,7 +24,7 @@ ":::{container} highlight\n", "``` {parsed-literal}\n", "./xmlchange PROJECT={{ '`' + PROJECT_CODE + '`' }}\n", - "```""\n", + "```\n", ":::" ] }, @@ -377,4 +377,4 @@ }, "nbformat": 4, "nbformat_minor": 5 -} +} \ No newline at end of file From 2b727bb9e058ddce1002fb90bc749431090e33d1 Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Fri, 13 Nov 2026 20:47:05 -0700 Subject: [PATCH 02/14] Initial commit of code that Claude made to render the substitutions --- render_substitutions.py | 120 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 120 insertions(+) create mode 100755 render_substitutions.py diff --git a/render_substitutions.py b/render_substitutions.py new file mode 100755 index 0000000..25a00b0 --- /dev/null +++ b/render_substitutions.py @@ -0,0 +1,120 @@ +#!/usr/bin/env python3 +""" +Render the MyST/Jinja2 substitutions (parse: myst_substitutions in _config.yml) +into the notebooks, so they read correctly in plain JupyterLab (e.g. NCAR JupyterHub). + +Only markdown cells are rendered (that's all MyST substitutes). Because JupyterLab +doesn't know the {parsed-literal} directive, those fences are turned into plain +code fences and inline-code backticks inside them are removed. + +This is from Claude Opus 5.5 medium, on Nov 13th, 2026 by Erik Kluzek. + +Usage: + ./render_substitutions.py -o OUTDIR # copy notebooks/ and images/ into OUTDIR, render the copy + ./render_substitutions.py --in-place # render notebooks/ in place (destroys the templates!) +""" +import argparse +import json +import pathlib +import re +import shutil +import sys + +import jinja2 +import yaml + +ROOT = pathlib.Path(__file__).resolve().parent + +# ``` {parsed-literal} ... ``` +# (an unclosed fence runs to the end of the cell) +PARSED_LITERAL = re.compile(r"^(`{3,}) *\{parsed-literal\}[^\n]*\n(.*?)(?:^\1[ \t]*$|\Z)", re.M | re.S) +# :::{container} ... and its closing ::: +CONTAINER = re.compile(r"^:{3,}(\{container\}.*)?[ \t]*(\n|\Z)", re.M) + + +def get_substitutions(): + """Read the substitution values from _config.yml""" + with open(ROOT / "_config.yml", encoding="utf-8") as cfg: + config = yaml.safe_load(cfg) + return config["parse"]["myst_substitutions"] + + +def fix_parsed_literal(text): + """Turn {parsed-literal} blocks into plain code blocks without inline-code markup""" + + def repl(match): + fence, body = match.group(1), match.group(2) + # drop inline-code markup and the \: used to stop MyST auto-linking URLs + body = body.replace("`", "").replace("\\:", ":") + if not body.endswith("\n"): + body += "\n" + return fence + "\n" + body + fence + + text = PARSED_LITERAL.sub(repl, text) + # JupyterLab shows the :::{container} wrapper lines as text, drop them + return CONTAINER.sub("", text) + + +def render_notebook(path, env, subs): + """Render the markdown cells of one notebook, return True if it changed""" + try: + with open(path, encoding="utf-8") as fh: + nb = json.load(fh) + except json.JSONDecodeError as err: + print(f"WARNING: skipping invalid notebook {path}: {err}", file=sys.stderr) + return False + + changed = False + for cell in nb["cells"]: + if cell["cell_type"] != "markdown": + continue + source = "".join(cell["source"]) + new = source + if "{{" in source or "{%" in source: + try: + new = env.from_string(source).render(**subs) + except jinja2.TemplateError as err: + sys.exit(f"ERROR rendering {path}: {err}") + new = fix_parsed_literal(new) + # Jinja strips a single trailing newline, keep the original ending + if source.endswith("\n") and not new.endswith("\n"): + new += "\n" + if new != source: + cell["source"] = new.splitlines(keepends=True) + changed = True + + if changed: + with open(path, "w", encoding="utf-8") as fh: + json.dump(nb, fh, indent=1, ensure_ascii=False) + fh.write("\n") + return changed + + +def main(): + parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) + group = parser.add_mutually_exclusive_group(required=True) + group.add_argument("-o", "--outdir", type=pathlib.Path, help="Directory to write rendered notebooks/ to") + group.add_argument("--in-place", action="store_true", help="Overwrite the notebooks in notebooks/") + args = parser.parse_args() + + src = ROOT / "notebooks" + if args.in_place: + dest = src + else: + outdir = args.outdir.resolve() + if outdir.exists(): + sys.exit(f"ERROR: {outdir} already exists") + dest = outdir / "notebooks" + shutil.copytree(src, dest) + # Notebooks reference ../../images etc., keep those relative links working + shutil.copytree(ROOT / "images", outdir / "images") + + env = jinja2.Environment(undefined=jinja2.StrictUndefined, keep_trailing_newline=True) + subs = get_substitutions() + notebooks = sorted(p for p in dest.rglob("*.ipynb") if ".ipynb_checkpoints" not in p.parts) + nchanged = sum(render_notebook(nb, env, subs) for nb in notebooks) + print(f"Rendered {nchanged} notebooks under {dest}") + + +if __name__ == "__main__": + main() From 404b70f62638ca9d5732cec2ebbee12c86991e18 Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Fri, 13 Nov 2026 21:13:36 -0700 Subject: [PATCH 03/14] A couple preferences from me --- render_substitutions.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/render_substitutions.py b/render_substitutions.py index 25a00b0..0007a07 100755 --- a/render_substitutions.py +++ b/render_substitutions.py @@ -56,12 +56,12 @@ def repl(match): def render_notebook(path, env, subs): - """Render the markdown cells of one notebook, return True if it changed""" + """Render the markdown cells of one notebook, return True if it changed, abort if bad syntax""" try: with open(path, encoding="utf-8") as fh: nb = json.load(fh) except json.JSONDecodeError as err: - print(f"WARNING: skipping invalid notebook {path}: {err}", file=sys.stderr) + sys.exit(f"ERROR:invalid notebook {path}: {err}") return False changed = False @@ -114,6 +114,7 @@ def main(): notebooks = sorted(p for p in dest.rglob("*.ipynb") if ".ipynb_checkpoints" not in p.parts) nchanged = sum(render_notebook(nb, env, subs) for nb in notebooks) print(f"Rendered {nchanged} notebooks under {dest}") + print( "Successfully rendered all notebooks") if __name__ == "__main__": From b6ed2aa544d680660bab335984ab64a276a21c40 Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Fri, 13 Nov 2026 21:14:06 -0700 Subject: [PATCH 04/14] Remove python extension in the script name --- render_substitutions.py => render_substitutions | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename render_substitutions.py => render_substitutions (100%) diff --git a/render_substitutions.py b/render_substitutions similarity index 100% rename from render_substitutions.py rename to render_substitutions From 95a199a0a9306437c3543d8c092b6208a864b317 Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Fri, 13 Nov 2026 21:41:39 -0700 Subject: [PATCH 05/14] Close two {parsed-literal} fences that weren't closed --- notebooks/diagnostics/cupid/clm_cupid_ldf_ilamb.ipynb | 3 ++- notebooks/diagnostics/ldf/ldf_basics.ipynb | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/notebooks/diagnostics/cupid/clm_cupid_ldf_ilamb.ipynb b/notebooks/diagnostics/cupid/clm_cupid_ldf_ilamb.ipynb index 0930bac..f4468bc 100644 --- a/notebooks/diagnostics/cupid/clm_cupid_ldf_ilamb.ipynb +++ b/notebooks/diagnostics/cupid/clm_cupid_ldf_ilamb.ipynb @@ -83,7 +83,8 @@ "git clone -b branch_tags/{{ '`' + CTSM_CUPID_TAG + '`' }} https\\://github.com/ESCOMP/ctsm.git {{ '`' + CTSM_CUPID_TAG + '`' }}\n", "cd {{ '`' + CTSM_CUPID_TAG + '`' }}\n", "./bin/git-fleximod update\n", - "cd tools/CUPiD" + "cd tools/CUPiD\n", + "```" ] }, { diff --git a/notebooks/diagnostics/ldf/ldf_basics.ipynb b/notebooks/diagnostics/ldf/ldf_basics.ipynb index 8262e1b..7d06d5a 100644 --- a/notebooks/diagnostics/ldf/ldf_basics.ipynb +++ b/notebooks/diagnostics/ldf/ldf_basics.ipynb @@ -101,7 +101,8 @@ "metadata": {}, "source": [ "``` {parsed-literal}\n", - "qsub -I -X -l select=1:ncpus=8:mem=64GB -A {{ PROJECT_CODE }} -q casper@casper-pbs -l walltime=02:00:00\n" + "qsub -I -X -l select=1:ncpus=8:mem=64GB -A {{ PROJECT_CODE }} -q casper@casper-pbs -l walltime=02:00:00\n", + "```\n" ] }, { From d752dafa6445a61318b4df02949be58a1e994963 Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Fri, 13 Nov 2026 22:12:34 -0700 Subject: [PATCH 06/14] I asked Claude to preserve the indentation level, so we can easily see that nothing else got changed accidentally, I did show that it's doing the right thing with a 'diff -r -wb new old', but let's not change any formatting here --- render_substitutions | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/render_substitutions b/render_substitutions index 0007a07..e2fbb9d 100755 --- a/render_substitutions +++ b/render_substitutions @@ -57,9 +57,13 @@ def fix_parsed_literal(text): def render_notebook(path, env, subs): """Render the markdown cells of one notebook, return True if it changed, abort if bad syntax""" + with open(path, encoding="utf-8") as fh: + text = fh.read() + # Keep the notebook's own JSON indent (Jupyter uses 1, some editors use 2 or 4) + match = re.search(r'^( +)"', text, re.M) + indent = len(match.group(1)) if match else 1 try: - with open(path, encoding="utf-8") as fh: - nb = json.load(fh) + nb = json.loads(text) except json.JSONDecodeError as err: sys.exit(f"ERROR:invalid notebook {path}: {err}") return False @@ -85,8 +89,9 @@ def render_notebook(path, env, subs): if changed: with open(path, "w", encoding="utf-8") as fh: - json.dump(nb, fh, indent=1, ensure_ascii=False) - fh.write("\n") + json.dump(nb, fh, indent=indent, ensure_ascii=False) + if text.endswith("\n"): + fh.write("\n") return changed From 8137bb8928046a356110ed9e4bd87c9419bec27b Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Fri, 13 Nov 2026 22:28:59 -0700 Subject: [PATCH 07/14] My changes to make the parsed-literal blocks into bash code --- render_substitutions | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/render_substitutions b/render_substitutions index e2fbb9d..c1b01e6 100755 --- a/render_substitutions +++ b/render_substitutions @@ -27,7 +27,7 @@ ROOT = pathlib.Path(__file__).resolve().parent # ``` {parsed-literal} ... ``` # (an unclosed fence runs to the end of the cell) -PARSED_LITERAL = re.compile(r"^(`{3,}) *\{parsed-literal\}[^\n]*\n(.*?)(?:^\1[ \t]*$|\Z)", re.M | re.S) +PARSED_LITERAL = re.compile(r"^(`{3,}) *\{(parsed-literal)\}[^\n]*\n(.*?)(?:^\1[ \t]*$|\Z)", re.M | re.S) # :::{container} ... and its closing ::: CONTAINER = re.compile(r"^:{3,}(\{container\}.*)?[ \t]*(\n|\Z)", re.M) @@ -40,15 +40,16 @@ def get_substitutions(): def fix_parsed_literal(text): - """Turn {parsed-literal} blocks into plain code blocks without inline-code markup""" + """Turn {parsed-literal} blocks into plain bash code blocks without inline-code markup""" + # NOTE: This is tightly coupled to the PARSED_LITERAL regex above. def repl(match): - fence, body = match.group(1), match.group(2) + fence, code_type, body = match.group(1), match.group(2), match.group(3) # drop inline-code markup and the \: used to stop MyST auto-linking URLs body = body.replace("`", "").replace("\\:", ":") if not body.endswith("\n"): body += "\n" - return fence + "\n" + body + fence + return fence + "bash" + "\n" + body + fence text = PARSED_LITERAL.sub(repl, text) # JupyterLab shows the :::{container} wrapper lines as text, drop them From dbaba168df98bee11f100dc62d685402fc3cfdba Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Fri, 13 Nov 2026 22:34:02 -0700 Subject: [PATCH 08/14] Claude changed it so that blocks that should be tcsh are labeled as tcsh rather than bash, and it fixes the syntax of the continuation lines that had to be escaped, I also didn't really need to capture the parsed-literal group, so it removed that --- render_substitutions | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/render_substitutions b/render_substitutions index c1b01e6..d15bf7a 100755 --- a/render_substitutions +++ b/render_substitutions @@ -27,7 +27,7 @@ ROOT = pathlib.Path(__file__).resolve().parent # ``` {parsed-literal} ... ``` # (an unclosed fence runs to the end of the cell) -PARSED_LITERAL = re.compile(r"^(`{3,}) *\{(parsed-literal)\}[^\n]*\n(.*?)(?:^\1[ \t]*$|\Z)", re.M | re.S) +PARSED_LITERAL = re.compile(r"^(`{3,}) *\{parsed-literal\}[^\n]*\n(.*?)(?:^\1[ \t]*$|\Z)", re.M | re.S) # :::{container} ... and its closing ::: CONTAINER = re.compile(r"^:{3,}(\{container\}.*)?[ \t]*(\n|\Z)", re.M) @@ -40,16 +40,18 @@ def get_substitutions(): def fix_parsed_literal(text): - """Turn {parsed-literal} blocks into plain bash code blocks without inline-code markup""" + """Turn {parsed-literal} blocks into plain bash/tcsh code blocks without inline-code markup""" - # NOTE: This is tightly coupled to the PARSED_LITERAL regex above. def repl(match): - fence, code_type, body = match.group(1), match.group(2), match.group(3) - # drop inline-code markup and the \: used to stop MyST auto-linking URLs - body = body.replace("`", "").replace("\\:", ":") + fence, body = match.group(1), match.group(2) + # drop inline-code markup + body = body.replace("`", "") + # undo markdown backslash escapes (\\ -> \, \: -> :, ...) as parsed-literal renders them + body = re.sub(r"\\([!-/:-@\[-`{-~])", r"\1", body) if not body.endswith("\n"): body += "\n" - return fence + "bash" + "\n" + body + fence + lang = "tcsh" if re.match(r"\s*(setenv|set)\s", body) else "bash" + return fence + lang + "\n" + body + fence text = PARSED_LITERAL.sub(repl, text) # JupyterLab shows the :::{container} wrapper lines as text, drop them From 4af858d6ff32030c1835ed166e8697f5245df90e Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Fri, 13 Nov 2026 22:36:10 -0700 Subject: [PATCH 09/14] Results after running the script, which looks acceptable --- notebooks/basics/code/git_download_ctsm.ipynb | 10 ++--- .../basics/exercises/change_compsets.ipynb | 4 +- notebooks/basics/exercises/first_I1850.ipynb | 8 ++-- .../cupid/clm_cupid_ldf_ilamb.ipynb | 8 ++-- notebooks/diagnostics/diagnostics_intro.ipynb | 2 +- notebooks/diagnostics/ldf/ldf_basics.ipynb | 4 +- .../exercise_clm_history_frequency.ipynb | 8 ++-- .../exercises/exercise_clm_history_vars.ipynb | 10 ++--- .../exercises/exercise_fates_complexity.ipynb | 6 +-- .../xml/exercises/xml_datm_exercise.ipynb | 6 +-- .../xml/exercises/xml_length_exercise.ipynb | 4 +- .../xml/exercises/xml_runtype_exercise.ipynb | 6 +-- notebooks/prereqs/prereqs_overview.ipynb | 2 +- notebooks/resources/ncar_hpc.ipynb | 2 +- notebooks/resources/ncar_hpc_login.ipynb | 2 +- notebooks/resources/profile.ipynb | 32 +++++++------- .../resources/tutorial_one_time_setup.ipynb | 26 ++++-------- .../resources/tutorial_queue_account.ipynb | 26 +++++------- notebooks/resources/tutorial_specific.ipynb | 42 ++++++++----------- .../sensitivity/03_submit_ensemble.ipynb | 6 +-- .../singlepoint/exercises/runtower_NEON.ipynb | 4 +- .../exercises/runtower_PLUMBER2.ipynb | 10 ++--- .../exercises/troubleshooting_cam.ipynb | 6 +-- 23 files changed, 106 insertions(+), 128 deletions(-) diff --git a/notebooks/basics/code/git_download_ctsm.ipynb b/notebooks/basics/code/git_download_ctsm.ipynb index 2d69d52..42a1646 100644 --- a/notebooks/basics/code/git_download_ctsm.ipynb +++ b/notebooks/basics/code/git_download_ctsm.ipynb @@ -24,9 +24,9 @@ "source": [ "
\n", "\n", - "**We will use the CLM6 tutorial tag: {{ CTSM_TUTORIAL_TAG }}**\n", + "**We will use the CLM6 tutorial tag: `ctsm5.4.067`**\n", "\n", - "**Note: **At the time of the tutorial, the final CLM6 release has not yet been completed. Therefore, we will use a preliminary tag ({{ CTSM_TUTORIAL_TAG }}) that contains the CLM6 code base and configuration needed for the exercises. The exact tag used in the tutorial may differ from the final CLM6 release.\n", + "**Note: **At the time of the tutorial, the final CLM6 release has not yet been completed. Therefore, we will use a preliminary tag (`ctsm5.4.067`) that contains the CLM6 code base and configuration needed for the exercises. The exact tag used in the tutorial may differ from the final CLM6 release.\n", "\n", "
" ] @@ -101,10 +101,10 @@ " \n", "- **Download the CLM code to your code workspace directory as `my_clm_code`:**\n", "\n", - "```{parsed-literal}\n", + "```bash\n", "git clone https://github.com/ESCOMP/CTSM.git my_clm_code\n", "cd my_clm_code\n", - "git checkout {{ '`' + CTSM_TUTORIAL_TAG + '`' }}\n", + "git checkout ctsm5.4.067\n", "```\n", "The directory name `my_clm_code` is only an example. You may choose any directory name you prefer. Outside of this tutorial, many users choose names that identify the CLM version they are working with (for example, `ctsm6.0`, `ctsm5.5` or `clm6.0_Tutorial2026`).\n", "\n", @@ -118,7 +118,7 @@ "\n", "which should return:\n", "\n", - " {{ CTSM_TUTORIAL_TAG }}\n", + " `ctsm5.4.067`\n", "" ] }, diff --git a/notebooks/basics/exercises/change_compsets.ipynb b/notebooks/basics/exercises/change_compsets.ipynb index 2f40930..19dcb80 100644 --- a/notebooks/basics/exercises/change_compsets.ipynb +++ b/notebooks/basics/exercises/change_compsets.ipynb @@ -165,8 +165,8 @@ "```\n", "\n", "Change the queue to the 'tutorial' queue:\n", - "``` {parsed-literal}\n", - "./xmlchange JOB_QUEUE={{ '`' + TUTORIAL_QUE + '`' }} --force\n", + "```bash\n", + "./xmlchange JOB_QUEUE=tutorial --force\n", "```\n", "\n", "Extend the length of the run to 1 month:\n", diff --git a/notebooks/basics/exercises/first_I1850.ipynb b/notebooks/basics/exercises/first_I1850.ipynb index 9bf79ba..22e96d6 100644 --- a/notebooks/basics/exercises/first_I1850.ipynb +++ b/notebooks/basics/exercises/first_I1850.ipynb @@ -61,8 +61,8 @@ "```\n", "\n", "Change the queue to the 'tutorial' queue:\n", - "``` {parsed-literal}\n", - "./xmlchange JOB_QUEUE={{ '`' + TUTORIAL_QUE + '`' }} --force\n", + "```bash\n", + "./xmlchange JOB_QUEUE=tutorial --force\n", "```\n", "\n", "Make sure you use the correct information for the CASE, RES, and COMPSET inputs.\n", @@ -113,8 +113,8 @@ "```\n", "\n", "Change the queue to the 'tutorial' queue:\n", - "``` {parsed-literal}\n", - "./xmlchange JOB_QUEUE={{ '`' + TUTORIAL_QUE + '`' }} --force\n", + "```bash\n", + "./xmlchange JOB_QUEUE=tutorial --force\n", "```\n", "\n", "Do not make any other changes since we are running an out-of-the-box simulation.\n", diff --git a/notebooks/diagnostics/cupid/clm_cupid_ldf_ilamb.ipynb b/notebooks/diagnostics/cupid/clm_cupid_ldf_ilamb.ipynb index f4468bc..9088a11 100644 --- a/notebooks/diagnostics/cupid/clm_cupid_ldf_ilamb.ipynb +++ b/notebooks/diagnostics/cupid/clm_cupid_ldf_ilamb.ipynb @@ -66,7 +66,7 @@ "We hope to eventually release a version of the CLM that includes CUPiD. For now we have you clone a branch that tests this idea in a recent version of the CLM.\n", "\n", "The following lines:\n", - "- clone the branch into a new directory {{ CTSM_CUPID_TAG }}\n", + "- clone the branch into a new directory `CUPiD.n01_ctsm5.4.017`\n", "- enter the directory just created\n", "- update submodules, one of which is CUPiD\n", "- enter the directory tools/CUPiD\n", @@ -79,9 +79,9 @@ "id": "943f6b99-58d0-4cb2-8abe-2255e0b1cebb", "metadata": {}, "source": [ - "```{parsed-literal}\n", - "git clone -b branch_tags/{{ '`' + CTSM_CUPID_TAG + '`' }} https\\://github.com/ESCOMP/ctsm.git {{ '`' + CTSM_CUPID_TAG + '`' }}\n", - "cd {{ '`' + CTSM_CUPID_TAG + '`' }}\n", + "```bash\n", + "git clone -b branch_tags/CUPiD.n01_ctsm5.4.017 https://github.com/ESCOMP/ctsm.git CUPiD.n01_ctsm5.4.017\n", + "cd CUPiD.n01_ctsm5.4.017\n", "./bin/git-fleximod update\n", "cd tools/CUPiD\n", "```" diff --git a/notebooks/diagnostics/diagnostics_intro.ipynb b/notebooks/diagnostics/diagnostics_intro.ipynb index a155d75..3fdfe92 100644 --- a/notebooks/diagnostics/diagnostics_intro.ipynb +++ b/notebooks/diagnostics/diagnostics_intro.ipynb @@ -110,7 +110,7 @@ "|---|---|\n", "| **Resource Selection** | Casper PBS Batch |\n", "| **Queue or Reservation** | casper |\n", - "| **Project Account** | {{ PROJECT_CODE }} |\n", + "| **Project Account** | UCGD0011 |\n", "| **Wall Time in Hours** | 3 |" ] }, diff --git a/notebooks/diagnostics/ldf/ldf_basics.ipynb b/notebooks/diagnostics/ldf/ldf_basics.ipynb index 7d06d5a..41caba7 100644 --- a/notebooks/diagnostics/ldf/ldf_basics.ipynb +++ b/notebooks/diagnostics/ldf/ldf_basics.ipynb @@ -100,8 +100,8 @@ "id": "da9828ff-197c-4309-b038-cc0a53ae4b4f", "metadata": {}, "source": [ - "``` {parsed-literal}\n", - "qsub -I -X -l select=1:ncpus=8:mem=64GB -A {{ PROJECT_CODE }} -q casper@casper-pbs -l walltime=02:00:00\n", + "```bash\n", + "qsub -I -X -l select=1:ncpus=8:mem=64GB -A UCGD0011 -q casper@casper-pbs -l walltime=02:00:00\n", "```\n" ] }, diff --git a/notebooks/modifications/namelist/exercises/exercise_clm_history_frequency.ipynb b/notebooks/modifications/namelist/exercises/exercise_clm_history_frequency.ipynb index 5b03a4e..d9cc486 100644 --- a/notebooks/modifications/namelist/exercises/exercise_clm_history_frequency.ipynb +++ b/notebooks/modifications/namelist/exercises/exercise_clm_history_frequency.ipynb @@ -111,12 +111,12 @@ "**Change the wallclock time, job queue, and account number**\n", "\n", "Change the wallclock time. If needed, change `job queue` and `account number`.
\n", - "For instance, to run in the queue `tutorial` and the project number {{ PROJECT_CODE }} (You should use the project number given for this tutorial), use the command:\n", + "For instance, to run in the queue `tutorial` and the project number UCGD0011 (You should use the project number given for this tutorial), use the command:\n", "\n", - "``` {parsed-literal}\n", + "```bash\n", "./xmlchange JOB_WALLCLOCK_TIME=01:00:00\n", - "./xmlchange JOB_QUEUE={{ '`' + TUTORIAL_QUE + '`' }}\n", - "./xmlchange PROJECT={{ '`' + PROJECT_CODE + '`' }} --force\n", + "./xmlchange JOB_QUEUE=tutorial\n", + "./xmlchange PROJECT=UCGD0011 --force\n", "```\n", "\n", "**Build and submit**\n", diff --git a/notebooks/modifications/namelist/exercises/exercise_clm_history_vars.ipynb b/notebooks/modifications/namelist/exercises/exercise_clm_history_vars.ipynb index ab39bd0..74e039a 100644 --- a/notebooks/modifications/namelist/exercises/exercise_clm_history_vars.ipynb +++ b/notebooks/modifications/namelist/exercises/exercise_clm_history_vars.ipynb @@ -83,7 +83,7 @@ "\n", "Create a new case called `i2000_bgc_hist_update`:\n", "\n", - "``` {parsed-literal}\n", + "```bash\n", "cd /glade/u/home/$USER/code/my_clm_code/cime/scripts/\n", "\n", "./create_newcase --case ~/cases/i2000_bgc_hist_update \\\n", @@ -122,12 +122,12 @@ "\n", "**Change the job queue, wallclock time, and account number**\n", "\n", - "Update the wallclock time. If needed, change the job queue and project number. For example, to run in the {{ '`' + TUTORIAL_QUE + '`' }} queue using project {{ '`' + PROJECT_CODE + '`' }}, use:\n", + "Update the wallclock time. If needed, change the job queue and project number. For example, to run in the `tutorial` queue using project `UCGD0011`, use:\n", "\n", - "``` {parsed-literal}\n", + "```bash\n", "./xmlchange JOB_WALLCLOCK_TIME=01:00:00\n", - "./xmlchange JOB_QUEUE={{ '`' + TUTORIAL_QUE + '`' }}\n", - "./xmlchange PROJECT={{ '`' + PROJECT_CODE + '`' }} --force\n", + "./xmlchange JOB_QUEUE=tutorial\n", + "./xmlchange PROJECT=UCGD0011 --force\n", "```\n", "\n", "Use the project number provided for the tutorial.\n", diff --git a/notebooks/modifications/namelist/exercises/exercise_fates_complexity.ipynb b/notebooks/modifications/namelist/exercises/exercise_fates_complexity.ipynb index f892caf..b67442e 100644 --- a/notebooks/modifications/namelist/exercises/exercise_fates_complexity.ipynb +++ b/notebooks/modifications/namelist/exercises/exercise_fates_complexity.ipynb @@ -138,10 +138,10 @@ "\n", "If needed:\n", "\n", - "``` {parsed-literal}\n", + "```bash\n", "./xmlchange JOB_WALLCLOCK_TIME=01:00:00\n", - "./xmlchange JOB_QUEUE={{ '`' + TUTORIAL_QUE + '`' }}\n", - "./xmlchange PROJECT={{ '`' + PROJECT_CODE + '`' }} --force\n", + "./xmlchange JOB_QUEUE=tutorial\n", + "./xmlchange PROJECT=UCGD0011 --force\n", "```\n", "\n", "Use the project number provided for the tutorial.\n", diff --git a/notebooks/modifications/xml/exercises/xml_datm_exercise.ipynb b/notebooks/modifications/xml/exercises/xml_datm_exercise.ipynb index 3129993..85beb27 100644 --- a/notebooks/modifications/xml/exercises/xml_datm_exercise.ipynb +++ b/notebooks/modifications/xml/exercises/xml_datm_exercise.ipynb @@ -82,7 +82,7 @@ " \n", "2. In your case directory, change the runtime variables:\n", " \n", - "``` {parsed-literal}\n", + "```bash\n", "cd /glade/u/home/$USER/cases/i2000_forcing_years\n", "./xmlchange DATM_YR_START=2005\n", "./xmlchange DATM_YR_END=2009\n", @@ -90,8 +90,8 @@ "./xmlchange STOP_N=1\n", "./xmlchange STOP_OPTION='nyears'\n", "./xmlchange JOB_WALLCLOCK_TIME=1:00:00\n", - "./xmlchange JOB_QUEUE={{ '`' + TUTORIAL_QUE + '`' }} --force\n", - "``` \n", + "./xmlchange JOB_QUEUE=tutorial --force\n", + "```\n", "\n", "3. Set up the case:\n", " \n", diff --git a/notebooks/modifications/xml/exercises/xml_length_exercise.ipynb b/notebooks/modifications/xml/exercises/xml_length_exercise.ipynb index 5c53968..a0ca5b3 100644 --- a/notebooks/modifications/xml/exercises/xml_length_exercise.ipynb +++ b/notebooks/modifications/xml/exercises/xml_length_exercise.ipynb @@ -75,11 +75,11 @@ " \n", "In your case directory, change debugging levels and set runtime variables:\n", "\n", - "``` {parsed-literal}\n", + "```bash\n", "cd /glade/u/home/$USER/cases/i1850_sp.length\n", "./xmlchange PIO_DEBUG_LEVEL=1,STOP_N=6,STOP_OPTION=nmonths\n", "./xmlchange --subgroup case.run JOB_WALLCLOCK_TIME=2:00:00\n", - "./xmlchange JOB_QUEUE={{ '`' + TUTORIAL_QUE + '`' }} --force\n", + "./xmlchange JOB_QUEUE=tutorial --force\n", "```\n", "
\n", " \n", diff --git a/notebooks/modifications/xml/exercises/xml_runtype_exercise.ipynb b/notebooks/modifications/xml/exercises/xml_runtype_exercise.ipynb index a944e55..bf6b693 100644 --- a/notebooks/modifications/xml/exercises/xml_runtype_exercise.ipynb +++ b/notebooks/modifications/xml/exercises/xml_runtype_exercise.ipynb @@ -86,13 +86,13 @@ "\n", "3. Set run time variables: \n", " \n", - "``` {parsed-literal}\n", + "```bash\n", "./xmlchange STOP_OPTION=nmonths\n", "./xmlchange STOP_N=1\n", "./xmlchange RESUBMIT=1\n", "./xmlchange JOB_WALLCLOCK_TIME=02:00:00\n", - "./xmlchange JOB_QUEUE={{ '`' + TUTORIAL_QUE + '`' }} --force\n", - "``` \n", + "./xmlchange JOB_QUEUE=tutorial --force\n", + "```\n", "\n", "4. Set up the case:\n", " \n", diff --git a/notebooks/prereqs/prereqs_overview.ipynb b/notebooks/prereqs/prereqs_overview.ipynb index cc55770..22b057c 100644 --- a/notebooks/prereqs/prereqs_overview.ipynb +++ b/notebooks/prereqs/prereqs_overview.ipynb @@ -160,7 +160,7 @@ "\n", "![Entering options for server on JupyterHub](../../images/resources/OnDemand_launch_Jupyter_batch.png)\n", "*

Figure: Entering options for server on JupyterHub.

*\n", - "Select the “Casper PBS Batch” option in the drop-down menu. Afterward, you will need to make other choices to select the right resources: 3 hours wall time to ensure your server is active for the entire hands-on activity session and Project Account {{ '`' + PROJECT_CODE + '`' }}. Now launch the server.\n", + "Select the “Casper PBS Batch” option in the drop-down menu. Afterward, you will need to make other choices to select the right resources: 3 hours wall time to ensure your server is active for the entire hands-on activity session and Project Account `UCGD0011`. Now launch the server.\n", "\n", "**Step 5. Connect to Jupyter**\n", "\n", diff --git a/notebooks/resources/ncar_hpc.ipynb b/notebooks/resources/ncar_hpc.ipynb index fa06fd3..f92f676 100644 --- a/notebooks/resources/ncar_hpc.ipynb +++ b/notebooks/resources/ncar_hpc.ipynb @@ -141,7 +141,7 @@ "\n", "![Entering options for server on JupyterHub](../../images/resources/OnDemand_launch_Jupyter_batch.png)\n", "*

Figure: Entering options for server on JupyterHub.

*\n", - "Select the “Casper PBS Batch” option in the drop down menu. Afterward, you will need to make other choices to select the right resources: 3 hours wall time to ensure your server is active for the entire hands-on activity session and Project Account {{ '`' + PROJECT_CODE + '`' }}. Now launch the server.\n", + "Select the “Casper PBS Batch” option in the drop down menu. Afterward, you will need to make other choices to select the right resources: 3 hours wall time to ensure your server is active for the entire hands-on activity session and Project Account `UCGD0011`. Now launch the server.\n", "\n", "**Step 5. Connect to Jupyter**\n", "\n", diff --git a/notebooks/resources/ncar_hpc_login.ipynb b/notebooks/resources/ncar_hpc_login.ipynb index ba7555c..7948a7a 100644 --- a/notebooks/resources/ncar_hpc_login.ipynb +++ b/notebooks/resources/ncar_hpc_login.ipynb @@ -141,7 +141,7 @@ "\n", "![Entering options for server on JupyterHub](../../images/resources/OnDemand_launch_Jupyter_batch.png)\n", "*

Figure: Entering options for server on JupyterHub.

*\n", - "Select the “Casper PBS Batch” option in the drop down menu. Afterward, you will need to make other choices to select the right resources: 3 hours wall time to ensure your server is active for the entire hands-on activity session and Project Account {{ '`' + PROJECT_CODE + '`' }}. Now launch the server.\n", + "Select the “Casper PBS Batch” option in the drop down menu. Afterward, you will need to make other choices to select the right resources: 3 hours wall time to ensure your server is active for the entire hands-on activity session and Project Account `UCGD0011`. Now launch the server.\n", "\n", "**Step 5. Connect to Jupyter**\n", "\n", diff --git a/notebooks/resources/profile.ipynb b/notebooks/resources/profile.ipynb index ce6fa71..adae282 100644 --- a/notebooks/resources/profile.ipynb +++ b/notebooks/resources/profile.ipynb @@ -17,7 +17,7 @@ "\n", "
\n", "\n", - "You should have access to project account **{{ PROJECT_CODE }}** and use this for your simulations.\n", + "You should have access to project account **UCGD0011** and use this for your simulations.\n", "
\n", "\n" ] @@ -50,13 +50,11 @@ "source": [ "In theory, you _should_ be able to automatically use this account and the reservation queues if you correctly set up your NCAR HPC environment using your `.profile` or `.tcshrc` files, as described below. If you need to change the values for a run, you can change the account and reservation queue in your case directory using the following command:\n", "\n", - ":::{container} highlight\n", - "``` {parsed-literal}\n", - "./xmlchange --force JOB_QUEUE={{ '`' + TUTORIAL_QUE + '`' }}\n", - "./xmlchange PROJECT={{ '`' + PROJECT_CODE + '`' }}\n", + "```bash\n", + "./xmlchange --force JOB_QUEUE=tutorial\n", + "./xmlchange PROJECT=UCGD0011\n", "```\n", "\n", - ":::\n", "\n", "You should not have to set the `PROJECT` more than once during the tutorial if your profile is set up, as described below, but we include it for your reference in case you are having trouble." ] @@ -175,8 +173,8 @@ "\n", "Copy over the `.profile` file into your home directory: \n", " \n", - "``` {parsed-literal}\n", - "cp {{ '`' + CLM_TUTORIAL_DIR + '`' }}/tutorial_env//profile ~/.profile\n", + "```bash\n", + "cp /glade/campaign/cgd/tss/tutorials/clm_2026/tutorial_env//profile ~/.profile\n", "```\n", "
\n", "\n", @@ -224,7 +222,7 @@ "id": "42432d90-eaef-4205-b4fe-39cf3c7b5881", "metadata": {}, "source": [ - "**NOTE:** You should already have a `.tcshrc` file in your home directory. If you do not wish to overwrite the existing `.tcshrc` file, please save this file to a new name OR copy the contents of the {{ CLM_TUTORIAL_DIR }}/tutorial_env//tcshrc file to your `.tcshrc` file using a text editor." + "**NOTE:** You should already have a `.tcshrc` file in your home directory. If you do not wish to overwrite the existing `.tcshrc` file, please save this file to a new name OR copy the contents of the /glade/campaign/cgd/tss/tutorials/clm_2026/tutorial_env//tcshrc file to your `.tcshrc` file using a text editor." ] }, { @@ -247,8 +245,8 @@ "
\n", "\n", "Copy over the `.tcshrc` file to your home directory:\n", - "``` {parsed-literal}\n", - "cp {{ '`' + CLM_TUTORIAL_DIR + '`' }}/tutorial_env//tcshrc ~/.tcshrc\n", + "```bash\n", + "cp /glade/campaign/cgd/tss/tutorials/clm_2026/tutorial_env//tcshrc ~/.tcshrc\n", "```\n", " \n", "
\n", @@ -319,9 +317,9 @@ "\n", "Add to your .profile: \n", "\n", - "``` {parsed-literal}\n", - "export PROJECT={{ '`' + PROJECT_CODE + '`' }} #<- This should never change over the course of the tutorial\n", - "export TUTORIAL_QUEUE={{ '`' + TUTORIAL_QUE + '`' }}\n", + "```bash\n", + "export PROJECT=UCGD0011 #<- This should never change over the course of the tutorial\n", + "export TUTORIAL_QUEUE=tutorial\n", "```\n", "\n", "Source the file:
\n", @@ -336,9 +334,9 @@ "
\n", "\n", "Add to your .tcshrc: \n", - "``` {parsed-literal}\n", - "setenv PROJECT {{ '`' + PROJECT_CODE + '`' }} #<-This should never change over the course of the tutorial\n", - "setenv TUTORIAL_QUEUE {{ '`' + TUTORIAL_QUE + '`' }}\n", + "```tcsh\n", + "setenv PROJECT UCGD0011 #<-This should never change over the course of the tutorial\n", + "setenv TUTORIAL_QUEUE tutorial\n", "```\n", " \n", "Source the file:
\n", diff --git a/notebooks/resources/tutorial_one_time_setup.ipynb b/notebooks/resources/tutorial_one_time_setup.ipynb index 088e7cd..764c4fe 100644 --- a/notebooks/resources/tutorial_one_time_setup.ipynb +++ b/notebooks/resources/tutorial_one_time_setup.ipynb @@ -122,12 +122,10 @@ "\n", "Copy over the `.profile` file into your home directory: \n", " \n", - ":::{container} highlight\n", - "``` {parsed-literal}\n", - "cp {{ '`' + CLM_TUTORIAL_DIR + '`' }}/tutorial_env/profile ~/.profile\n", + "```bash\n", + "cp /glade/campaign/cgd/tss/tutorials/clm_2026/tutorial_env/profile ~/.profile\n", "```\n", "\n", - ":::\n", "\n", "
\n", "\n", @@ -161,7 +159,7 @@ "id": "42432d90-eaef-4205-b4fe-39cf3c7b5881", "metadata": {}, "source": [ - "**NOTE:** You should already have a `.tcshrc` file in your home directory. If you do not wish to overwrite the existing `.tcshrc` file, please save this file to a new name OR copy the contents of the {{ CLM_TUTORIAL_DIR }}/tutorial_env/tcshrc file to your `.tcshrc` file using a text editor." + "**NOTE:** You should already have a `.tcshrc` file in your home directory. If you do not wish to overwrite the existing `.tcshrc` file, please save this file to a new name OR copy the contents of the /glade/campaign/cgd/tss/tutorials/clm_2026/tutorial_env/tcshrc file to your `.tcshrc` file using a text editor." ] }, { @@ -185,12 +183,10 @@ "\n", "Copy over the `.tcshrc` file to your home directory:\n", "\n", - ":::{container} highlight\n", - "``` {parsed-literal}\n", - "cp {{ '`' + CLM_TUTORIAL_DIR + '`' }}/tutorial_env/tcshrc ~/.tcshrc\n", + "```bash\n", + "cp /glade/campaign/cgd/tss/tutorials/clm_2026/tutorial_env/tcshrc ~/.tcshrc\n", "```\n", "\n", - ":::\n", " \n", "
\n", "\n", @@ -249,12 +245,10 @@ "\n", "Add to your .profile: \n", "\n", - ":::{container} highlight\n", - "``` {parsed-literal}\n", - "export PROJECT={{ '`' + PROJECT_CODE + '`' }} #<- This should never change over the course of the tutorial\n", + "```bash\n", + "export PROJECT=UCGD0011 #<- This should never change over the course of the tutorial\n", "```\n", "\n", - ":::\n", "\n", "Source the file:
\n", "\n", @@ -269,12 +263,10 @@ "\n", "Add to your .tcshrc: \n", "\n", - ":::{container} highlight\n", - "``` {parsed-literal}\n", - "setenv PROJECT {{ '`' + PROJECT_CODE + '`' }} #<-This should never change over the course of the tutorial\n", + "```tcsh\n", + "setenv PROJECT UCGD0011 #<-This should never change over the course of the tutorial\n", "```\n", "\n", - ":::\n", " \n", "Source the file:
\n", "\n", diff --git a/notebooks/resources/tutorial_queue_account.ipynb b/notebooks/resources/tutorial_queue_account.ipynb index 9eb04f2..3da951a 100644 --- a/notebooks/resources/tutorial_queue_account.ipynb +++ b/notebooks/resources/tutorial_queue_account.ipynb @@ -17,18 +17,16 @@ "\n", "
\n", "\n", - "You should have access to project account {{ PROJECT_CODE }} and use this for your simulations.\n", + "You should have access to project account UCGD0011 and use this for your simulations.\n", "\n", "
\n", "\n", "You can change the account in your case directory using the following command:\n", "\n", - ":::{container} highlight\n", - "``` {parsed-literal}\n", - "./xmlchange PROJECT={{ '`' + PROJECT_CODE + '`' }}\n", + "```bash\n", + "./xmlchange PROJECT=UCGD0011\n", "```\n", - "\n", - ":::" + "\n" ] }, { @@ -42,7 +40,7 @@ "\n", "**Tutorial Reservation Queues**\n", " \n", - "- We have a special queue called **{{ TUTORIAL_QUE }}** during the lab sessions to ensure you get through the derecho queues quickly and get your jobs run. This queue is only active during the day. \n", + "- We have a special queue called **tutorial** during the lab sessions to ensure you get through the derecho queues quickly and get your jobs run. This queue is only active during the day. \n", "\n", "- Outside the lab sessions, you should use the queue **main** to run CLM.\n", " \n", @@ -52,12 +50,10 @@ "\n", "During the lab sessions:\n", "\n", - ":::{container} highlight\n", - "``` {parsed-literal}\n", - "./xmlchange JOB_QUEUE={{ '`' + TUTORIAL_QUE + '`' }} --force\n", + "```bash\n", + "./xmlchange JOB_QUEUE=tutorial --force\n", "```\n", "\n", - ":::\n", "\n", "Outside the lab sessions:\n", "\n", @@ -79,16 +75,14 @@ "id": "6ddf7177-0dd6-4ce3-be1e-ee70e5be9419", "metadata": {}, "source": [ - "By default, we compile CTSM on a shared queue called `develop`. However, as we want to avoid long wait time during the labs, we will compile in the special reservation queue {{ TUTORIAL_QUE }}.\n", + "By default, we compile CTSM on a shared queue called `develop`. However, as we want to avoid long wait time during the labs, we will compile in the special reservation queue tutorial.\n", "\n", "During the lab sessions, use\n", "\n", - ":::{container} highlight\n", - "``` {parsed-literal}\n", - "qcmd -q {{ '`' + TUTORIAL_QUE + '`' }} -- ./case.build \n", + "```bash\n", + "qcmd -q tutorial -- ./case.build \n", "```\n", "\n", - ":::\n", "\n", "\n", "Outside the lab sessions, use\n", diff --git a/notebooks/resources/tutorial_specific.ipynb b/notebooks/resources/tutorial_specific.ipynb index e40b9e7..b2d9997 100644 --- a/notebooks/resources/tutorial_specific.ipynb +++ b/notebooks/resources/tutorial_specific.ipynb @@ -16,16 +16,14 @@ "### Tutorial Project Account\n", "\n", "
\n", - "You should have access to project account **{{ PROJECT_CODE }}** and use this for your simulations.\n", + "You should have access to project account **UCGD0011** and use this for your simulations.\n", "
\n", "\n", "You can change the account in your case directory using the following command:\n", "\n", - ":::{container} highlight\n", - "``` {parsed-literal}\n", - "./xmlchange PROJECT={{ '`' + PROJECT_CODE + '`' }}\n", - "```\n", - ":::" + "```bash\n", + "./xmlchange PROJECT=UCGD0011\n", + "```\n" ] }, { @@ -39,7 +37,7 @@ "\n", "Schedule for Tutorial Reservation Queues\n", " \n", - "- We have a special queue **{{ TUTORIAL_QUE }}** during the lab sessions to ensure you get through the derecho queues quickly and get your jobs run. This queue is only active during our lab sessions. \n", + "- We have a special queue **tutorial** during the lab sessions to ensure you get through the derecho queues quickly and get your jobs run. This queue is only active during our lab sessions. \n", "\n", "- Outside the lab sessions, you should use the queue cpu\n", " \n", @@ -50,12 +48,10 @@ "\n", "During the lab sessions:\n", "\n", - ":::{container} highlight\n", - "``` {parsed-literal}\n", - "./xmlchange JOB_QUEUE={{ '`' + TUTORIAL_QUE + '`' }} --force\n", + "```bash\n", + "./xmlchange JOB_QUEUE=tutorial --force\n", "```\n", "\n", - ":::\n", "\n", "Outside the lab sessions:\n", "``` bash\n", @@ -195,12 +191,10 @@ "\n", "Copy over the `.profile` file into your home directory: \n", " \n", - ":::{container} highlight\n", - "``` {parsed-literal}\n", - "cp {{ '`' + CLM_TUTORIAL_DIR + '`' }}/tutorial_env/profile ~/.profile\n", + "```bash\n", + "cp /glade/campaign/cgd/tss/tutorials/clm_2026/tutorial_env/profile ~/.profile\n", "```\n", "\n", - ":::\n", "\n", "
\n", "\n", @@ -234,7 +228,7 @@ "id": "42432d90-eaef-4205-b4fe-39cf3c7b5881", "metadata": {}, "source": [ - "**NOTE:** You should already have a `.tcshrc` file in your home directory. If you do not wish to overwrite the existing `.tcshrc` file, please save this file to a new name OR copy the contents of the {{ CLM_TUTORIAL_DIR }}/tutorial_env/tcshrc` file to your `.tcshrc` file using a text editor." + "**NOTE:** You should already have a `.tcshrc` file in your home directory. If you do not wish to overwrite the existing `.tcshrc` file, please save this file to a new name OR copy the contents of the /glade/campaign/cgd/tss/tutorials/clm_2026/tutorial_env/tcshrc` file to your `.tcshrc` file using a text editor." ] }, { @@ -257,8 +251,8 @@ "
\n", "\n", "Copy over the `.tcshrc` file to your home directory:\n", - "``` {parsed-literal}\n", - "cp {{ '`' + CLM_TUTORIAL_DIR + '`' }}/tutorial_env/tcshrc ~/.tcshrc\n", + "```bash\n", + "cp /glade/campaign/cgd/tss/tutorials/clm_2026/tutorial_env/tcshrc ~/.tcshrc\n", "```\n", " \n", "
\n", @@ -315,9 +309,9 @@ "\n", "Add to your .profile: \n", "\n", - "``` {parsed-literal}\n", - "export PROJECT={{ '`' + PROJECT_CODE + '`' }} #<- This should never change over the course of the tutorial\n", - "export TUTORIAL_QUEUE={{ '`' + TUTORIAL_QUE + '`' }} #<- Special queue for the tutorial\n", + "```bash\n", + "export PROJECT=UCGD0011 #<- This should never change over the course of the tutorial\n", + "export TUTORIAL_QUEUE=tutorial #<- Special queue for the tutorial\n", "```\n", "\n", "Source the file:
\n", @@ -332,9 +326,9 @@ "
\n", "\n", "Add to your .tcshrc: \n", - "``` {parsed-literal}\n", - "setenv PROJECT {{ '`' + PROJECT_CODE + '`' }} #<-This should never change over the course of the tutorial\n", - "setenv TUTORIAL_QUEUE {{ '`' + TUTORIAL_QUE + '`' }} #<- Special queue for the tutorial\n", + "```tcsh\n", + "setenv PROJECT UCGD0011 #<-This should never change over the course of the tutorial\n", + "setenv TUTORIAL_QUEUE tutorial #<- Special queue for the tutorial\n", "```\n", " \n", "Source the file:
\n", diff --git a/notebooks/sensitivity/03_submit_ensemble.ipynb b/notebooks/sensitivity/03_submit_ensemble.ipynb index 1f642a4..ee7dc34 100644 --- a/notebooks/sensitivity/03_submit_ensemble.ipynb +++ b/notebooks/sensitivity/03_submit_ensemble.ipynb @@ -262,7 +262,7 @@ "source": [ "Each member's case will be named `___`, so the first member's case will be `BONA.FATESsp_oat_fates_oat_0000_run`.\n", "\n", - "The cell below writes this file for us. Be sure to replace `XXXXXXXX` with your project code ({{ PROJECT_CODE }} for this tutorial)." + "The cell below writes this file for us. Be sure to replace `XXXXXXXX` with your project code (UCGD0011 for this tutorial)." ] }, { @@ -449,8 +449,8 @@ "
\n", "\n", "**Note:** The queue here is for the _setup job_, not the actual CLM-FATES case. To modify the job queues for your actual CLM jobs, use xmlchange commands inside the stage script.\n", - "``` {parsed-literal}\n", - "./xmlchange JOB_QUEUE={{ '`' + TUTORIAL_QUE + '`' }}\n", + "```bash\n", + "./xmlchange JOB_QUEUE=tutorial\n", "```\n", "
" ] diff --git a/notebooks/singlepoint/exercises/runtower_NEON.ipynb b/notebooks/singlepoint/exercises/runtower_NEON.ipynb index 954e381..66b7647 100644 --- a/notebooks/singlepoint/exercises/runtower_NEON.ipynb +++ b/notebooks/singlepoint/exercises/runtower_NEON.ipynb @@ -108,8 +108,8 @@ "\n", "Create a new case ABBY.transient with the command:\n", "\n", - "```{parsed-literal}\n", - "./run_tower --neon-sites ABBY --output-root ~/cases/. --xmlchange PROJECT={{ '`' + PROJECT_CODE + '`' }}\n", + "```bash\n", + "./run_tower --neon-sites ABBY --output-root ~/cases/. --xmlchange PROJECT=UCGD0011\n", "```\n", "\n", "During this time `run_tower` will complete steps 1-4 listed above.\n", diff --git a/notebooks/singlepoint/exercises/runtower_PLUMBER2.ipynb b/notebooks/singlepoint/exercises/runtower_PLUMBER2.ipynb index 6b1a7d0..1b9da51 100644 --- a/notebooks/singlepoint/exercises/runtower_PLUMBER2.ipynb +++ b/notebooks/singlepoint/exercises/runtower_PLUMBER2.ipynb @@ -149,11 +149,11 @@ "cd /glade/u/home/$USER/code/my_clm_code/tools/site_and_regional\n", "```\n", "\n", - "```{parsed-literal}\n", - "./run_tower --plumber-sites BR-Sa3 \\\\\n", - "--output-root /glade/u/home/$USER/cases \\\\\n", - "--experiment test0 \\\\\n", - "--xmlchange PROJECT={{ '`' + PROJECT_CODE + '`' }}\n", + "```bash\n", + "./run_tower --plumber-sites BR-Sa3 \\\n", + "--output-root /glade/u/home/$USER/cases \\\n", + "--experiment test0 \\\n", + "--xmlchange PROJECT=UCGD0011\n", "```\n", "\n", "Move to your case directory: BR-Sa3.test0.ad:\n", diff --git a/notebooks/troubleshooting/exercises/troubleshooting_cam.ipynb b/notebooks/troubleshooting/exercises/troubleshooting_cam.ipynb index a0d189e..3991804 100644 --- a/notebooks/troubleshooting/exercises/troubleshooting_cam.ipynb +++ b/notebooks/troubleshooting/exercises/troubleshooting_cam.ipynb @@ -123,10 +123,10 @@ "**# Change the job queue and account number**\n", "\n", "If needed, change `job queue` and `account number`.
\n", - "For instance, to run in the queue `tutorial` and the project number {{ PROJECT_CODE }} (you should use the project number given for this tutorial), use the command:\n", + "For instance, to run in the queue `tutorial` and the project number UCGD0011 (you should use the project number given for this tutorial), use the command:\n", "\n", - "``` {parsed-literal}\n", - "./xmlchange JOB_QUEUE={{ '`' + TUTORIAL_QUE + '`' }},PROJECT={{ '`' + PROJECT_CODE + '`' }} --force\n", + "```bash\n", + "./xmlchange JOB_QUEUE=tutorial,PROJECT=UCGD0011 --force\n", "```\n", "\n", "**# Build and submit**\n", From e81028244ee8c6000e9752c56e76efd339b4739e Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Fri, 13 Nov 2026 22:48:28 -0700 Subject: [PATCH 10/14] Remove the script that did the Jinja removal --- render_substitutions | 129 ------------------------------------------- 1 file changed, 129 deletions(-) delete mode 100755 render_substitutions diff --git a/render_substitutions b/render_substitutions deleted file mode 100755 index d15bf7a..0000000 --- a/render_substitutions +++ /dev/null @@ -1,129 +0,0 @@ -#!/usr/bin/env python3 -""" -Render the MyST/Jinja2 substitutions (parse: myst_substitutions in _config.yml) -into the notebooks, so they read correctly in plain JupyterLab (e.g. NCAR JupyterHub). - -Only markdown cells are rendered (that's all MyST substitutes). Because JupyterLab -doesn't know the {parsed-literal} directive, those fences are turned into plain -code fences and inline-code backticks inside them are removed. - -This is from Claude Opus 5.5 medium, on Nov 13th, 2026 by Erik Kluzek. - -Usage: - ./render_substitutions.py -o OUTDIR # copy notebooks/ and images/ into OUTDIR, render the copy - ./render_substitutions.py --in-place # render notebooks/ in place (destroys the templates!) -""" -import argparse -import json -import pathlib -import re -import shutil -import sys - -import jinja2 -import yaml - -ROOT = pathlib.Path(__file__).resolve().parent - -# ``` {parsed-literal} ... ``` -# (an unclosed fence runs to the end of the cell) -PARSED_LITERAL = re.compile(r"^(`{3,}) *\{parsed-literal\}[^\n]*\n(.*?)(?:^\1[ \t]*$|\Z)", re.M | re.S) -# :::{container} ... and its closing ::: -CONTAINER = re.compile(r"^:{3,}(\{container\}.*)?[ \t]*(\n|\Z)", re.M) - - -def get_substitutions(): - """Read the substitution values from _config.yml""" - with open(ROOT / "_config.yml", encoding="utf-8") as cfg: - config = yaml.safe_load(cfg) - return config["parse"]["myst_substitutions"] - - -def fix_parsed_literal(text): - """Turn {parsed-literal} blocks into plain bash/tcsh code blocks without inline-code markup""" - - def repl(match): - fence, body = match.group(1), match.group(2) - # drop inline-code markup - body = body.replace("`", "") - # undo markdown backslash escapes (\\ -> \, \: -> :, ...) as parsed-literal renders them - body = re.sub(r"\\([!-/:-@\[-`{-~])", r"\1", body) - if not body.endswith("\n"): - body += "\n" - lang = "tcsh" if re.match(r"\s*(setenv|set)\s", body) else "bash" - return fence + lang + "\n" + body + fence - - text = PARSED_LITERAL.sub(repl, text) - # JupyterLab shows the :::{container} wrapper lines as text, drop them - return CONTAINER.sub("", text) - - -def render_notebook(path, env, subs): - """Render the markdown cells of one notebook, return True if it changed, abort if bad syntax""" - with open(path, encoding="utf-8") as fh: - text = fh.read() - # Keep the notebook's own JSON indent (Jupyter uses 1, some editors use 2 or 4) - match = re.search(r'^( +)"', text, re.M) - indent = len(match.group(1)) if match else 1 - try: - nb = json.loads(text) - except json.JSONDecodeError as err: - sys.exit(f"ERROR:invalid notebook {path}: {err}") - return False - - changed = False - for cell in nb["cells"]: - if cell["cell_type"] != "markdown": - continue - source = "".join(cell["source"]) - new = source - if "{{" in source or "{%" in source: - try: - new = env.from_string(source).render(**subs) - except jinja2.TemplateError as err: - sys.exit(f"ERROR rendering {path}: {err}") - new = fix_parsed_literal(new) - # Jinja strips a single trailing newline, keep the original ending - if source.endswith("\n") and not new.endswith("\n"): - new += "\n" - if new != source: - cell["source"] = new.splitlines(keepends=True) - changed = True - - if changed: - with open(path, "w", encoding="utf-8") as fh: - json.dump(nb, fh, indent=indent, ensure_ascii=False) - if text.endswith("\n"): - fh.write("\n") - return changed - - -def main(): - parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter) - group = parser.add_mutually_exclusive_group(required=True) - group.add_argument("-o", "--outdir", type=pathlib.Path, help="Directory to write rendered notebooks/ to") - group.add_argument("--in-place", action="store_true", help="Overwrite the notebooks in notebooks/") - args = parser.parse_args() - - src = ROOT / "notebooks" - if args.in_place: - dest = src - else: - outdir = args.outdir.resolve() - if outdir.exists(): - sys.exit(f"ERROR: {outdir} already exists") - dest = outdir / "notebooks" - shutil.copytree(src, dest) - # Notebooks reference ../../images etc., keep those relative links working - shutil.copytree(ROOT / "images", outdir / "images") - - env = jinja2.Environment(undefined=jinja2.StrictUndefined, keep_trailing_newline=True) - subs = get_substitutions() - notebooks = sorted(p for p in dest.rglob("*.ipynb") if ".ipynb_checkpoints" not in p.parts) - nchanged = sum(render_notebook(nb, env, subs) for nb in notebooks) - print(f"Rendered {nchanged} notebooks under {dest}") - print( "Successfully rendered all notebooks") - - -if __name__ == "__main__": - main() From 44ac8ac33e75d79eb61edce7e71a85ef957676cd Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Fri, 13 Nov 2026 23:02:05 -0700 Subject: [PATCH 11/14] Add execute to the link check script so can be run by hand outside of an action --- .github/scripts/run-linkcheck.sh | 0 1 file changed, 0 insertions(+), 0 deletions(-) mode change 100644 => 100755 .github/scripts/run-linkcheck.sh diff --git a/.github/scripts/run-linkcheck.sh b/.github/scripts/run-linkcheck.sh old mode 100644 new mode 100755 From 084746694d638f9b31482c7a18bdb216ee22877c Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Fri, 13 Nov 2026 23:02:37 -0700 Subject: [PATCH 12/14] Comment out the Jinja substitutions, for documentation in case of future use --- _config.yml | 22 +++++++++------------- 1 file changed, 9 insertions(+), 13 deletions(-) diff --git a/_config.yml b/_config.yml index 4e64b8f..2a1aeab 100644 --- a/_config.yml +++ b/_config.yml @@ -73,19 +73,15 @@ html: extra_navbar : "" parse: - # Jinja-2 Substitutions to make throughout all notebooks - # For example add: - # {{ CTSM_TUTORIAL_TAG }} - # For code blocks (make the code block a parsed-literal and do this: - # {{ '`' + CTSM_TUTORIAL_TAG + '`' }} - # To have it substitute the above from the substitutions.yml file below - # NOTE: this won't work for raw HTML blocks in markdown, so make the substitution outside of raw HTML. - myst_substitutions: - CTSM_TUTORIAL_TAG: "`ctsm5.4.067`" - CLM_TUTORIAL_DIR: "/glade/campaign/cgd/tss/tutorials/clm_2026" - CTSM_CUPID_TAG: "`CUPiD.n01_ctsm5.4.017`" - PROJECT_CODE: "UCGD0011" - TUTORIAL_QUE: "tutorial" + # Jinja-2 Substitutions that was a failed experiment + # Leaving here commented-out so we can figure out what the substitutions were next time: + # See https://github.com/NCAR/CLM-Tutorial/pull/141 + #myst_substitutions: + # CTSM_TUTORIAL_TAG: "`ctsm5.4.067`" + # CLM_TUTORIAL_DIR: "/glade/campaign/cgd/tss/tutorials/clm_2026" + # CTSM_CUPID_TAG: "`CUPiD.n01_ctsm5.4.017`" + # PROJECT_CODE: "UCGD0011" + # TUTORIAL_QUE: "tutorial" launch_buttons: From ec518c3446e32bf832e9cf42a366e1514abbf9f3 Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Fri, 13 Nov 2026 23:38:26 -0700 Subject: [PATCH 13/14] More comments on Jinja2 substitution, and remove the bit about the copy button for parsed-literal --- _config.yml | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/_config.yml b/_config.yml index 2a1aeab..387d042 100644 --- a/_config.yml +++ b/_config.yml @@ -34,9 +34,10 @@ sphinx: linkcheck_anchors: false # skip checking #anchors, which is often flaky linkcheck_report_timeouts_as_broken: False # - # Have the copy button appear on code blocks including the above parse-literal blocks + # Have the copy button appear on code blocks including the Jinja parse-literal blocks talked about below + # (Commented out as discussed below) # - copybutton_selector: "div.highlight pre, pre.literal-block" + #copybutton_selector: "div.highlight pre, pre.literal-block" # Force re-execution of notebooks on each build. # See https://jupyterbook.org/content/execute.html @@ -75,13 +76,15 @@ html: parse: # Jinja-2 Substitutions that was a failed experiment # Leaving here commented-out so we can figure out what the substitutions were next time: - # See https://github.com/NCAR/CLM-Tutorial/pull/141 + # See PR: https://github.com/NCAR/CLM-Tutorial/pull/141 + # See Discussion: https://github.com/NCAR/CLM-Tutorial/discussions/142 #myst_substitutions: # CTSM_TUTORIAL_TAG: "`ctsm5.4.067`" # CLM_TUTORIAL_DIR: "/glade/campaign/cgd/tss/tutorials/clm_2026" # CTSM_CUPID_TAG: "`CUPiD.n01_ctsm5.4.017`" # PROJECT_CODE: "UCGD0011" # TUTORIAL_QUE: "tutorial" + #END OF SUBSTITUTIONS: launch_buttons: From 9a222560cb2b2ada4be74d13e549adc24b298618 Mon Sep 17 00:00:00 2001 From: Erik Kluzek Date: Fri, 13 Nov 2026 23:49:03 -0700 Subject: [PATCH 14/14] Add a note about running the linkchecker script by hand --- .github/scripts/run-linkcheck.sh | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.github/scripts/run-linkcheck.sh b/.github/scripts/run-linkcheck.sh index 6afc1ae..ac76c4e 100755 --- a/.github/scripts/run-linkcheck.sh +++ b/.github/scripts/run-linkcheck.sh @@ -9,6 +9,11 @@ # Usage: run-linkcheck.sh BOOK_DIR FULL_LOG LINKCHECK_JSON # # Used by gh-page_builder.yml. +# +# Example: to run by hand outside of a github action on your local clone: +# ./.github/scripts/run-linkcheck.sh . full.log linkcheck.json +# # you then examine full.log and linkcheck.json if there were errors, but usually you don't care when run by hand +# set -u -o pipefail book_dir="$1"