From dc33a931b046eff52529078bf03eedb8778bfba4 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 1 May 2026 12:27:06 -0600 Subject: [PATCH 1/8] UG: Convert cprnc doc from rST to md. --- .../users_guide/using-clm-tools/cprnc.md | 23 ++++++++++++++++++ .../users_guide/using-clm-tools/cprnc.rst | 24 ------------------- .../users_guide/using-clm-tools/index.rst | 2 +- 3 files changed, 24 insertions(+), 25 deletions(-) create mode 100644 doc/source/users_guide/using-clm-tools/cprnc.md delete mode 100644 doc/source/users_guide/using-clm-tools/cprnc.rst diff --git a/doc/source/users_guide/using-clm-tools/cprnc.md b/doc/source/users_guide/using-clm-tools/cprnc.md new file mode 100644 index 0000000000..6e8516e8e5 --- /dev/null +++ b/doc/source/users_guide/using-clm-tools/cprnc.md @@ -0,0 +1,23 @@ +```{eval-rst} +.. include:: ../substitutions.rst +``` + +(comparing-history-files)= + +# Comparing History Files + +`cprnc` is a tool shared by {{ cesmrelease }} to compare two NetCDF history files. It differences every field that is shared on both files, and reports a summary of the difference. The summary includes the three largest differences, as well as the root mean square (RMS) difference. It also gives some summary information on the field as well. You have to enter at least one file, and up to two files. With one file it gives you summary information on the file, and with two it gives you information on the differences between the two. At the end it will give you a summary of the fields compared and how many fields were different and how many were identical. + +Options: + +-m = do NOT align time-stamps before comparing + +-v = verbose output + +-ipr + +-jpr + +-kpr + +See the `cprnc` [README](https://github.com/ESMCI/cime/blob/master/CIME/non_py/cprnc/README) file for more details. diff --git a/doc/source/users_guide/using-clm-tools/cprnc.rst b/doc/source/users_guide/using-clm-tools/cprnc.rst deleted file mode 100644 index 81418877c9..0000000000 --- a/doc/source/users_guide/using-clm-tools/cprnc.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. include:: ../substitutions.rst - -.. _comparing-history-files: - -========================= - Comparing History Files -========================= - -``cprnc`` is a tool shared by |cesmrelease| to compare two NetCDF history files. It differences every field that is shared on both files, and reports a summary of the difference. The summary includes the three largest differences, as well as the root mean square (RMS) difference. It also gives some summary information on the field as well. You have to enter at least one file, and up to two files. With one file it gives you summary information on the file, and with two it gives you information on the differences between the two. At the end it will give you a summary of the fields compared and how many fields were different and how many were identical. - -Options: - --m = do NOT align time-stamps before comparing - --v = verbose output - --ipr - --jpr - --kpr - -See the ``cprnc`` `README `_ file for more details. - diff --git a/doc/source/users_guide/using-clm-tools/index.rst b/doc/source/users_guide/using-clm-tools/index.rst index b721b3e7d6..a61f0d20d1 100644 --- a/doc/source/users_guide/using-clm-tools/index.rst +++ b/doc/source/users_guide/using-clm-tools/index.rst @@ -21,5 +21,5 @@ Using CLM tools creating-surface-datasets.rst creating-domain-files.rst observational-sites-datasets.rst - cprnc.rst + cprnc.md paramfile-tools.md From a699a4078a0eb9969b16feb0330e04540c329983 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 1 May 2026 12:30:32 -0600 Subject: [PATCH 2/8] UG: Embed cprnc readme in our doc page. --- .github/workflows/docs-build-and-deploy.yml | 1 + .github/workflows/docs.yml | 2 ++ doc/source/users_guide/using-clm-tools/cprnc.md | 15 +++------------ 3 files changed, 6 insertions(+), 12 deletions(-) diff --git a/.github/workflows/docs-build-and-deploy.yml b/.github/workflows/docs-build-and-deploy.yml index 55ad033ed7..3c7b1008b0 100644 --- a/.github/workflows/docs-build-and-deploy.yml +++ b/.github/workflows/docs-build-and-deploy.yml @@ -14,6 +14,7 @@ on: - 'src/README.unit_testing' - 'tools/README' - 'doc/test/test_container_eq_ctsm_pylib.sh' + - 'cime/CIME/non_py/cprnc/README.md' # Allows you to run this workflow manually from the Actions tab workflow_dispatch: diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 6c211d2a3c..1553514c05 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -16,6 +16,7 @@ on: - 'src/README.unit_testing' - 'tools/README' - 'doc/test/test_container_eq_ctsm_pylib.sh' + - 'cime/CIME/non_py/cprnc/README.md' pull_request: # Run on pull requests that change the listed files @@ -30,6 +31,7 @@ on: - 'src/README.unit_testing' - 'tools/README' - 'doc/test/test_container_eq_ctsm_pylib.sh' + - 'cime/CIME/non_py/cprnc/README.md' workflow_dispatch: diff --git a/doc/source/users_guide/using-clm-tools/cprnc.md b/doc/source/users_guide/using-clm-tools/cprnc.md index 6e8516e8e5..7c6180e181 100644 --- a/doc/source/users_guide/using-clm-tools/cprnc.md +++ b/doc/source/users_guide/using-clm-tools/cprnc.md @@ -8,16 +8,7 @@ `cprnc` is a tool shared by {{ cesmrelease }} to compare two NetCDF history files. It differences every field that is shared on both files, and reports a summary of the difference. The summary includes the three largest differences, as well as the root mean square (RMS) difference. It also gives some summary information on the field as well. You have to enter at least one file, and up to two files. With one file it gives you summary information on the file, and with two it gives you information on the differences between the two. At the end it will give you a summary of the fields compared and how many fields were different and how many were identical. -Options: +The `cprnc` README is embedded below for your convenience. --m = do NOT align time-stamps before comparing - --v = verbose output - --ipr - --jpr - --kpr - -See the `cprnc` [README](https://github.com/ESMCI/cime/blob/master/CIME/non_py/cprnc/README) file for more details. +```{include} ../../../../cime/CIME/non_py/cprnc/README.md +``` From 6924bca275d164b3bdc8c76a1f8a6da6e018fabf Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 1 May 2026 12:31:53 -0600 Subject: [PATCH 3/8] UG: cprnc: Hard-code "CESM". --- doc/source/users_guide/using-clm-tools/cprnc.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/doc/source/users_guide/using-clm-tools/cprnc.md b/doc/source/users_guide/using-clm-tools/cprnc.md index 7c6180e181..47906c458d 100644 --- a/doc/source/users_guide/using-clm-tools/cprnc.md +++ b/doc/source/users_guide/using-clm-tools/cprnc.md @@ -1,12 +1,8 @@ -```{eval-rst} -.. include:: ../substitutions.rst -``` - (comparing-history-files)= # Comparing History Files -`cprnc` is a tool shared by {{ cesmrelease }} to compare two NetCDF history files. It differences every field that is shared on both files, and reports a summary of the difference. The summary includes the three largest differences, as well as the root mean square (RMS) difference. It also gives some summary information on the field as well. You have to enter at least one file, and up to two files. With one file it gives you summary information on the file, and with two it gives you information on the differences between the two. At the end it will give you a summary of the fields compared and how many fields were different and how many were identical. +`cprnc` is a tool shared across CESM to compare two NetCDF history files. It differences every field that is shared on both files, and reports a summary of the difference. The summary includes the three largest differences, as well as the root mean square (RMS) difference. It also gives some summary information on the field as well. You have to enter at least one file, and up to two files. With one file it gives you summary information on the file, and with two it gives you information on the differences between the two. At the end it will give you a summary of the fields compared and how many fields were different and how many were identical. The `cprnc` README is embedded below for your convenience. From 1a40247d4df3c767bd335feaae722543e39ae62f Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Fri, 1 May 2026 12:36:34 -0600 Subject: [PATCH 4/8] UG: cprnc: Add link to cprnc GitHub. --- doc/source/users_guide/using-clm-tools/cprnc.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/users_guide/using-clm-tools/cprnc.md b/doc/source/users_guide/using-clm-tools/cprnc.md index 47906c458d..7aebf6f6b6 100644 --- a/doc/source/users_guide/using-clm-tools/cprnc.md +++ b/doc/source/users_guide/using-clm-tools/cprnc.md @@ -2,7 +2,7 @@ # Comparing History Files -`cprnc` is a tool shared across CESM to compare two NetCDF history files. It differences every field that is shared on both files, and reports a summary of the difference. The summary includes the three largest differences, as well as the root mean square (RMS) difference. It also gives some summary information on the field as well. You have to enter at least one file, and up to two files. With one file it gives you summary information on the file, and with two it gives you information on the differences between the two. At the end it will give you a summary of the fields compared and how many fields were different and how many were identical. +`cprnc` ([GitHub](https://github.com/ESMCI/cprnc)) is a tool shared across CESM to compare two NetCDF history files. It differences every field that is shared on both files, and reports a summary of the difference. The summary includes the three largest differences, as well as the root mean square (RMS) difference. It also gives some summary information on the field as well. You have to enter at least one file, and up to two files. With one file it gives you summary information on the file, and with two it gives you information on the differences between the two. At the end it will give you a summary of the fields compared and how many fields were different and how many were identical. The `cprnc` README is embedded below for your convenience. From b5ee7e2ba215108b37797fa57ee4af97aca5f5a4 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Sun, 3 May 2026 15:50:08 -0600 Subject: [PATCH 5/8] Note that cprnc is available as module on derecho/casper. --- doc/source/users_guide/using-clm-tools/cprnc.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/source/users_guide/using-clm-tools/cprnc.md b/doc/source/users_guide/using-clm-tools/cprnc.md index 7aebf6f6b6..6fffc38d53 100644 --- a/doc/source/users_guide/using-clm-tools/cprnc.md +++ b/doc/source/users_guide/using-clm-tools/cprnc.md @@ -4,6 +4,8 @@ `cprnc` ([GitHub](https://github.com/ESMCI/cprnc)) is a tool shared across CESM to compare two NetCDF history files. It differences every field that is shared on both files, and reports a summary of the difference. The summary includes the three largest differences, as well as the root mean square (RMS) difference. It also gives some summary information on the field as well. You have to enter at least one file, and up to two files. With one file it gives you summary information on the file, and with two it gives you information on the differences between the two. At the end it will give you a summary of the fields compared and how many fields were different and how many were identical. +`cprnc` is available as a module (`module load cprnc`) on Derecho and Casper. + The `cprnc` README is embedded below for your convenience. ```{include} ../../../../cime/CIME/non_py/cprnc/README.md From cc9603895ad0590ee7f2514af7bef36386001a5a Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Sun, 3 May 2026 15:58:54 -0600 Subject: [PATCH 6/8] UG: Compare hist files: Mention nccmp. --- .../using-clm-tools/{cprnc.md => compare-history-files.md} | 6 ++++++ doc/source/users_guide/using-clm-tools/index.rst | 2 +- 2 files changed, 7 insertions(+), 1 deletion(-) rename doc/source/users_guide/using-clm-tools/{cprnc.md => compare-history-files.md} (75%) diff --git a/doc/source/users_guide/using-clm-tools/cprnc.md b/doc/source/users_guide/using-clm-tools/compare-history-files.md similarity index 75% rename from doc/source/users_guide/using-clm-tools/cprnc.md rename to doc/source/users_guide/using-clm-tools/compare-history-files.md index 6fffc38d53..fdaf2079aa 100644 --- a/doc/source/users_guide/using-clm-tools/cprnc.md +++ b/doc/source/users_guide/using-clm-tools/compare-history-files.md @@ -2,6 +2,12 @@ # Comparing History Files +## `nccmp` + +`nccmp` allows you to compare data and/or metadata between two netCDF files. It is available as a module (`module load nccmp`) on Derecho and Casper. See the project's [GitLab](https://gitlab.com/remikz/nccmp/-/blob/master/README.md) for more information and installation instructions. + +## `cprnc` + `cprnc` ([GitHub](https://github.com/ESMCI/cprnc)) is a tool shared across CESM to compare two NetCDF history files. It differences every field that is shared on both files, and reports a summary of the difference. The summary includes the three largest differences, as well as the root mean square (RMS) difference. It also gives some summary information on the field as well. You have to enter at least one file, and up to two files. With one file it gives you summary information on the file, and with two it gives you information on the differences between the two. At the end it will give you a summary of the fields compared and how many fields were different and how many were identical. `cprnc` is available as a module (`module load cprnc`) on Derecho and Casper. diff --git a/doc/source/users_guide/using-clm-tools/index.rst b/doc/source/users_guide/using-clm-tools/index.rst index a61f0d20d1..bf4d1ae072 100644 --- a/doc/source/users_guide/using-clm-tools/index.rst +++ b/doc/source/users_guide/using-clm-tools/index.rst @@ -21,5 +21,5 @@ Using CLM tools creating-surface-datasets.rst creating-domain-files.rst observational-sites-datasets.rst - cprnc.md + compare-history-files.md paramfile-tools.md From eeeee7621317ee045eba4aa27b6841278eba1d50 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Sun, 3 May 2026 16:06:12 -0600 Subject: [PATCH 7/8] UG: Compare hist files: Add cprnc build instructions. --- .../users_guide/using-clm-tools/compare-history-files.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/doc/source/users_guide/using-clm-tools/compare-history-files.md b/doc/source/users_guide/using-clm-tools/compare-history-files.md index fdaf2079aa..33f56518c9 100644 --- a/doc/source/users_guide/using-clm-tools/compare-history-files.md +++ b/doc/source/users_guide/using-clm-tools/compare-history-files.md @@ -10,7 +10,14 @@ `cprnc` ([GitHub](https://github.com/ESMCI/cprnc)) is a tool shared across CESM to compare two NetCDF history files. It differences every field that is shared on both files, and reports a summary of the difference. The summary includes the three largest differences, as well as the root mean square (RMS) difference. It also gives some summary information on the field as well. You have to enter at least one file, and up to two files. With one file it gives you summary information on the file, and with two it gives you information on the differences between the two. At the end it will give you a summary of the fields compared and how many fields were different and how many were identical. -`cprnc` is available as a module (`module load cprnc`) on Derecho and Casper. +`cprnc` is available as a module (`module load cprnc`) on Derecho and Casper. To install on a different machine, from the top level of a CTSM checkout, do: +```shell +cd cime/CIME/non_py/cprnc +mkdir bld +cd bld +cmake ../ +make +``` The `cprnc` README is embedded below for your convenience. From 98bd32345857a6e8552ca9eb2dc5db261440d866 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Mon, 4 May 2026 09:38:52 -0600 Subject: [PATCH 8/8] UG: cprnc: Embedded readme version might differ from local --- doc/source/users_guide/using-clm-tools/compare-history-files.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/users_guide/using-clm-tools/compare-history-files.md b/doc/source/users_guide/using-clm-tools/compare-history-files.md index 33f56518c9..af24eb5391 100644 --- a/doc/source/users_guide/using-clm-tools/compare-history-files.md +++ b/doc/source/users_guide/using-clm-tools/compare-history-files.md @@ -19,7 +19,7 @@ cmake ../ make ``` -The `cprnc` README is embedded below for your convenience. +The `cprnc` README is embedded below for your convenience. Note that this is for the version included with CTSM (via CIME), which might differ from the version (if any) available on your machine. ```{include} ../../../../cime/CIME/non_py/cprnc/README.md ```