diff --git a/README.CHECKLIST.new_case b/README.CHECKLIST.new_case deleted file mode 100644 index 71ba4a8284..0000000000 --- a/README.CHECKLIST.new_case +++ /dev/null @@ -1,42 +0,0 @@ -$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. - The "-bgc" option of either Satellite Phenology (sp), or - Full BioGeoChemistry (bgc), or FATES (fates) - (./xmlquery -p CLM_BLDNML_OPTS) - - Also 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 right forcing years - (usually ./xmlquery -p DATM_YR) - - Again for an "I compset" make sure the DATM streams are operating over the right 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 diff --git a/README.CHECKLIST.new_case.md b/README.CHECKLIST.new_case.md new file mode 100755 index 0000000000..e4a01ce424 --- /dev/null +++ b/README.CHECKLIST.new_case.md @@ -0,0 +1,40 @@ +$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. + The "-bgc" option of either Satellite Phenology (sp), or + Full BioGeoChemistry (bgc), or FATES (fates) + (./xmlquery \-p CLM\_BLDNML\_OPTS) + \- Also 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 right forcing years + (usually ./xmlquery \-p DATM\_YR) + \- Again for an "I compset" make sure the DATM streams are operating over the right 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 \ No newline at end of file diff --git a/README_GITFLEXIMOD.md b/README_GITFLEXIMOD.md new file mode 100755 index 0000000000..704f962c7f --- /dev/null +++ b/README_GITFLEXIMOD.md @@ -0,0 +1,91 @@ +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: + +# 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. + +# 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\`\_ 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: + +# Modify the relevant entry/entries in \*\*.gitmodules\*\* +e.g., changing \`\`cime6.0.246\`\` to \`\`cime6.0.247\`\` above + +# Checkout the new submodule(s):: + + ./bin/git-fleximod update \ + +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" diff --git a/README_GITFLEXIMOD.rst b/README_GITFLEXIMOD.rst deleted file mode 100644 index d1ab767645..0000000000 --- a/README_GITFLEXIMOD.rst +++ /dev/null @@ -1,118 +0,0 @@ -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: - -#. 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. - -#. 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`_ 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: - -#. Modify the relevant entry/entries in **.gitmodules** (e.g., changing - ``cime6.0.246`` to ``cime6.0.247`` above) - -#. Checkout the new submodule(s):: - - ./bin/git-fleximod update - -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" - diff --git a/README b/README_on_CTSM.md similarity index 97% rename from README rename to README_on_CTSM.md index deca3cd8d2..fd9ae4afcd 100644 --- a/README +++ b/README_on_CTSM.md @@ -76,11 +76,11 @@ components/rtm ---------------------- CESM River Transport Model. Top level documentation ($CTSMROOT): -README ------------------- This file +README_on_CTSM.md -------- This file README.md ---------------- File that displays on github under https::/github.com/ESCOMP/CTSM.git -README.rst --------------- File that displays under the project in github -README_GITFLEXIMOD.rst --- Information on how to work with git-fleximod for CTSM -WhatsNewInCTSM5.4.md ----- Overview document of the changes between ctsm5.3 and ctsm5.4 +README_GITFLEXIMOD.md ---- Information on how to work with git-fleximod for CTSM +README.CHECKLIST.new_case.md - Information on starting a new case (i.e. simulation) +WhatsNewInCTSM5.4.md ----- Overview document of the changes between ctsm5.3 and ctsm5.4 (earlier versions in /doc) Copyright ---------------- CESM Copyright file doc/UpdateChangeLog.pl --- Script to add documentation on a tag to the ChangeLog/ChangeSum files @@ -91,7 +91,7 @@ doc/design --------------- Software Engineering and code design document files Checklists for standard Software Engineering tasks -./doc/README.CHECKLIST.master_tags +./doc/README.CHECKLIST.master_tags.md ./bld/namelist_files/README.CHECKLIST.interpolating_initial_conditions.md Documentation of Namelist Items: (view the following in a web browser)