Convert READMEs to markdown

.github/workflows/docs-build-and-deploy.yml

@@ -11,8 +11,8 @@ on:
       - '!doc/*ChangeSum*'
       - '!doc/UpdateChangelog.pl'
       # Include all include::ed files outside doc/ directory!
-      - 'src/README.unit_testing'
-      - 'tools/README'
+      - 'src/README.unit_testing.md'
+      - 'tools/README.md'
       - 'doc/test/test_container_eq_ctsm_pylib.sh'
 
   # Allows you to run this workflow manually from the Actions tab

.github/workflows/docs.yml

@@ -13,8 +13,8 @@ on:
       - '!doc/UpdateChangelog.pl'
       - '.github/workflows/docs-common.yml'
       # Include all include::ed files outside doc/ directory!
-      - 'src/README.unit_testing'
-      - 'tools/README'
+      - 'src/README.unit_testing.md'
+      - 'tools/README.md'
       - 'doc/test/test_container_eq_ctsm_pylib.sh'
 
   pull_request:
@@ -27,8 +27,8 @@ on:
       - '!doc/UpdateChangelog.pl'
       - '.github/workflows/docs-common.yml'
       # Include all include::ed files outside doc/ directory!
-      - 'src/README.unit_testing'
-      - 'tools/README'
+      - 'src/README.unit_testing.md'
+      - 'tools/README.md'
       - 'doc/test/test_container_eq_ctsm_pylib.sh'
 
   workflow_dispatch:

README.CHECKLIST.new_case.md

@@ -0,0 +1,27 @@
+$CTSMROOT/README.CHECKLIST.new\_case                       03/01/2021
+
+This is a check list of things to do when setting up a new case in order to help ensure everything is correct. There are lots of tiny details that need to be right and it's easy to get something wrong. So the first screening to make sure it's right is for you to carefully check through your case and make sure it's right.
+
+The following assumes you have created a new case and are in it's case directory.
+
+General Checklist to always do:
+
+- Make sure CLM\_ env settings are correct: ./xmlquery \-p CLM  
+- Make sure you are using the correct CLM\_PHYSICS\_VERSION: ./xmlquery \-p CLM\_PHYSICS\_VERSION  
+- Make sure you are running the appropriate overall CLM vegetation model, i.e. the "-bgc" option of either Satellite Phenology (sp) or Full BioGeoChemistry (bgc) or FATES (fates): ./xmlquery \-p CLM\_BLDNML\_OPTS
+- If you are running the bgc model, check to see if you should be running the prognostic crop model: option \-crop in CLM\_BLDNML\_OPTS
+- Make sure the LND\_TUNING\_MODE is correct: ./xmlquery LND\_TUNING\_MODE
+- For an "I compset" make sure you are running over the correct forcing years: usually ./xmlquery \-p DATM\_YR  
+- For an "I compset" make sure the DATM streams are operating over the correct years: look at the CaseDocs/datm.streams.xml file
+- First and align year for streams should be the start year of a historical simulation: ./xmlquery RUN\_STARTDATE; grep stream\_year\_first CaseDocs/lnd\_in; grep model\_year\_align CaseDocs/lnd\_in
+- Last year for streams should be the last year you are going to run to (or beyond it): grep stream\_year\_last CaseDocs/lnd\_in
+- Make sure you are starting from appropriate spunup initial conditions:
+    - Check the run-type with: ./xmlquery RUN\_TYPE
+    - Check finidat for a startup or hybrid simulation: grep finidat CaseDocs/lnd\_in
+    - Check nrevsn for a branch simulation: grep nrevsn CaseDocs/lnd\_in  
+- Run for a month (or some short period) and go over the log files and especially the settings and files read in them: for an I case you especially want to look at the lnd.log and atm.log files
+
+Some other suggestions on things that can be done:
+
+- Compare namelist files to an existing case if you are doing something almost the same as a previous simulation
+- Ask another collaborator to look over your case directory

README_GITFLEXIMOD.md

@@ -0,0 +1,110 @@
+# Obtaining the full model code and associated scripting infrastructure
+
+CTSM is released via GitHub. You will need some familiarity with git in order
+to modify the code and commit these changes. However, to simply checkout and run the
+code, no git knowledge is required other than what is documented in the following steps.
+
+To obtain the CTSM code you need to do the following:
+
+1.  Clone the repository. :
+
+        git clone https://github.com/ESCOMP/CTSM.git my_ctsm_sandbox
+
+    This will create a directory `my_ctsm_sandbox/` in your current working directory.
+
+2.  Run **./bin/git-fleximod update**. :
+
+        cd my_ctsm_sandbox
+        ./bin/git-fleximod update
+        ./bin/git-fleximod --help  # for a user's guide
+
+    **git-fleximod** is a package manager that will
+    populate the ctsm directory with the relevant versions of each of the
+    components along with the CIME infrastructure code.
+    Additional documentation for git-fleximod appears here:
+    <https://github.com/ESMCI/git-fleximod?tab=readme-ov-file#git-fleximod>
+
+\"components\" here refers to seperate git repositories for seperable parts of
+the code (such as the MOSART or mizuRoute river models). Because they are
+managed with \"submodule\" in git hereafter we will refer to them as \"submodule(s)\".
+
+At this point you have a working version of CTSM.
+
+To see full details of how to set up a case, compile and run, see the CIME documentation at <http://esmci.github.io/cime/> .
+
+## More details on git-fleximod
+
+The file **.gitmodules** in your top-level CTSM directory tells
+**git-fleximod** which tag/branch of each submodule
+should be brought in to generate your sandbox.
+
+NOTE: If you manually modify a submodule without updating .gitmodules,
+e.g. switch to a different tag, then rerunning git-fleximod will warn you of
+local changes you need to resolve.
+git-fleximod will not change a modified submodule back to what is specified in
+.gitmodules without the \--force option.
+See below documentation [Customizing your CTSM sandbox](#customizing-your-ctsm-sandbox) for more details.
+
+**You need to rerun git-fleximod whenever .gitmodules has
+changed** (unless you have already manually updated the relevant
+submodule(s) to have the correct branch/tag checked out). Common times
+when this is needed are:
+
+- After checking out a new CTSM branch/tag
+- After merging some other CTSM branch/tag into your currently
+  checked-out branch
+
+# Customizing your CTSM sandbox
+
+There are several use cases to consider when you want to customize or modify your CTSM sandbox.
+
+## Switching to a different CTSM branch or tag
+
+If you have already checked out a branch or tag and **HAVE NOT MADE ANY
+MODIFICATIONS** it is simple to change your sandbox. Say that you
+checked out ctsm5.2.0 but really wanted to have ctsm5.3.0;
+you would simply do the following:
+
+    git checkout ctsm5.3.0
+    ./bin/git-fleximod update
+
+You should **not** use this method if you have made any source code
+changes, or if you have any ongoing CTSM cases that were created from
+this sandbox. In these cases, it is often easiest to do a second **git
+clone**.
+
+## Pointing to a different version of a submodule
+
+Each entry in **.gitmodules** has the following form (we use CIME as an
+example below):
+
+    [submodule "cime"]
+    path = cime
+    url = https://github.com/ESMCI/cime
+    fxtag = cime6.0.246
+    fxrequired = ToplevelRequired
+    fxDONOTUSEurl = https://github.com/ESMCI/cime
+
+Each entry specifies either a tag or a hash. To point to a new tag or hash:
+
+1.  Modify the relevant entry/entries in **.gitmodules** (e.g., changing
+    `cime6.0.246` to `cime6.0.247` above)
+
+2.  Checkout the new submodule(s):
+
+        ./bin/git-fleximod update <submodule>
+
+Keep in mind that changing individual submodule from a tag may result
+in an invalid model (won\'t compile, won\'t run, not scientifically
+meaningful) and is unsupported.
+
+### Committing your change to .gitmodules
+
+After making this change, it\'s a good idea to commit the change in your
+local CTSM git repository. First create a branch in your local
+repository, then commit it. Feel free to create whatever local branches
+you\'d like in git. For example:
+
+    git checkout -b my_ctsm_branch
+    git add .gitmodules
+    git commit -m "Update CIME to cime6.0.247"