The last kind of customization that you can do for a case, before configure is run is to edit the templates. The &clm; template is in models/lnd/clm/bld/clm.cpl7.template, the &datm; template is in models/atm/datm/bld/datm.cpl7.template, and the driver templates are in the models/drv/bld directory and are named: ccsm.template and cpl.template. When a case is created they are also copied to the Tools/Templates directory underneath your case. If you want to make changes that will impact all your cases, you should edit the template files under the models directory, but if you want to make a change ONLY for a particular case you should edit the template under that specific case. Editing the template files is NOT for the faint of heart! We recommend this ONLY for experts! It's difficult to do because the template is a script that actually creates another script. So part of the script is echoing the script to be created and part of it is a script that is run when "configure -case" is run. As a result any variables in the part of the script that is being echoed have to be escaped like this: \$VARIABLE But, in other parts of the script that is run, you can NOT escape variables. So you need to understand if you are in a part of the script that is echoing the script to be created, or in the part of the script that is actually run. If you can customize your case using: compsets, env_*.xml variables, or a user namelist, as outlined in you should do so. The main reason to actually edit the template files, is if you are in a situation where the template aborts when you try it run it when "configure -case" is run. The other reason to edit the template is if you are &clm; developer and need to make adjustments to the template because of code or script updates. An example of modifying the &datm; template is in where sed is used to modify the path for &CPLHIST; data. The outline of the &clm; template is as follows: # set up options for clm configure and then run clm configure $CODEROOT/lnd/clm*/bld/configure <options> # set up options for clm build-namelist and then run clm build-namelist $CODEROOT/lnd/clm*/bld/build-namelist <options> # echo the $CASEBUILD/clm.buildnml.csh script out cat >! $CASEBUILD/clm.buildnml.csh << EOF1 # NOTE: variables in this section must be escaped EOF1 # Remove temporary namelist files # echo the $CASEBUILD/clm.buildexe.csh script out cat > $CASEBUILD/clm.buildexe.csh <<EOF2 # NOTE: variables in this section must be escaped EOF2 # Remove temporary configure files The outline of the &datm; template is as follows: # Check $GRID to set the $DOMAINFILE and $DOMAINPATH # Check DATM_PRESAERO to set the prescribed aerosol option # If &CLMUSRDAT; is set and $DOMAINFILE is NOT -- set it by &CLMUSRDAT; # Ensure $DOMAINFILE is set or else abort #============================================================================== # Create resolved prestage data script #============================================================================== cat >! $CASEBUILD/datm.buildnml.csh << EOF1 # NOTE: variables in this section must be escaped EOF1 # Major if blocks look at DATM_MODE: # the if blocks setup streams and run Tools/build_streams to create stream files #----- CLM_QIAN mode ---------------------------------------------------------- else if ($DATM_MODE == "&CLMQIAN;" ) then . # Customize &CLMQIAN; options here # A.) Setup datm_atm_in namelist cat >! $CASEBUILD/datm.buildnml.csh << EOF cat >! datm_atm_in << EOF1 # NOTE: variables in this section must be escaped EOF1 EOF # B.) Setup options to build_streams . . . #----- CLM1PT mode ---------------------------------------------------------- else if ($DATM_MODE == "CLM1PT" ) then . # Customize CLM1PT options here # A.) Setup datm_atm_in namelist cat >! $CASEBUILD/datm.buildnml.csh << EOF cat >! datm_atm_in << EOF1 # NOTE: variables in this section must be escaped EOF1 EOF # B.) Setup options to build_streams . . . . #----- CPLHIST 3-hourly time-averaging mode ---------------------------------------------------------- else if ($DATM_MODE == "&CPLHIST;" ) then . # Customize &CPLHIST; options here # A.) Setup datm_atm_in namelist cat >! $CASEBUILD/datm.buildnml.csh << EOF cat >! datm_atm_in << EOF1 # NOTE: variables in this section must be escaped EOF1 EOF # B.) Setup options to build_streams . . . . #----- INVALID mode -----------------------------------------------------------else echo "ERROR: unrecognized DATM_MODE = \$DATM_MODE " exit -1 endif #============================================================================== # Create prescribed aero streams if appropriate #============================================================================== . . . #============================================================================== # Create remaining resolved namelist #============================================================================== cat >! $CASEBUILD/datm.buildnml.csh << EOF cat >! datm_in << EOF1 # NOTE: variables in this section must be escaped . . . EOF1 EOF #============================================================================== # Create script to build executable #============================================================================== cat > $CASEBUILD/datm.buildexe.csh <<EOF #! /bin/csh -f # NOTE: variables in this section must be escaped EOF #============================================================================== # end of script #============================================================================== As you can see from above there are major "if" blocks for the different DATM_MODE's. So adding a new DATM_MODE means adding a new "if" block. The two major parts of each DATM_MODE block are: Setup datm_atm_in namelist Setup options to build_streams See for some notes about the &datm; namelist and streams files. That and the &datm; User's Guide should give you guidance on how to setup the namelist for your case. The next part of the "if" block in the &datm; template file to work with is the call to build_streams. You may need to add additional options to it. You may also need to call it multiple times for multiple streams. You will also likely need to add a new source option to it with the "-s" option. For more information on build_streams do the following. > scripts/ccsm_utils/Tools/build_streams -help The output of the above command is: &build_streams_help; As part of modifying the behavior of build_streams you will also have to edit the models/atm/datm7/bld/datm.template.streams.xml file as well (or the local version in your $CASENAME/Tools/Templates directory for a particular case). The template is an XML file much like the output streams file, but there are attributes to distinguish which fields will be used based on things like: RESOLUTION or datasource. And there are filename indicators (starting with a "%") that get translated into various things such as: %c = Case (from above -case command line option) %do = Use domain file %y = Year (through range given from begyear to endyear) %ym = Year-Month (all 12 months through year range) %6ym = Like %ym but 6 digit year (ie. %YYYYYY-MM). (can replace the 6 with any digit 1-9) Adding a new DATM_MODE also requires adding a new valid_value to scripts/ccsm_utils/Case.template/config_definition.xml. This enables the scripts to recognize the new value as a valid option to DATM_MODE in the &envconf; file. All of the documentation for &clm; can be built using GNU Makefiles that are available in the appropriate directories. The Makefiles require the following utilities: docbook2html, docbook2pdf, protex, and latex2html. To build the Users Guide for &clm; (requires docbook). > cd models/lnd/clm/doc/UsersGuide > gmake Note, that when the Users-Guide is built it will get output from other &clm; utilities that by nature abort, and hence stop the make from continuing. However, this is expected so you should simply run gmake again until it either completes or comes upon a legitimate issue. Here is what a sample warning looks like when gmake is run. The following line will fail in the make as it calls die -- but that is expected Check that the output config_help.tlog is good and redo your make ../../bld/configure -help >&` config_help.tlog make: *** [config_help.tlog] Error 255 To build the Code Reference Guide for &clm; (requires protex and latex2html). The make here uses a Filepath file that points to the list of directories that you want protex to run over. You should examine this file and make sure it is appropriate for what you need to do, before running the make. > cd models/lnd/clm/doc/CodeReference > gmake To build the table of tests for the &clm; test suite. The make here runs a UNIX shell script to create a html table of the list of tests run on the different machines from the &clm; test suite. > cd models/lnd/clm/test/system > gmake