# How to run some special cases

In this chapter we describe how to run some special cases that take more than one step to do. The straightforward cases have compsets and/or build-namelist use-cases setup for them or require simple editing of a single-case. All of the cases here require you to do at least two simulations with different configurations, or require more complex editing of the case (changing the streams files).

The nine cases we will describe are:

1. Running with the prognostic crop model on

2. Running with the irrigation model on

3. Spinning up the Satellite Phenology Model (&clmsp; spinup)

4. Spinning up the biogeochemistry Carbon-Nitrogen Model (CN spinup)

5. Spinning up the Carbon-Nitrogen Dynamic Global Vegetation Model (CNDV spinup)

6. Running with MOAR data as atmospheric forcing to spinup the model

7. Running with your own previous simulation as atmospheric forcing to spinup the model

8. Doing perturbation error growth tests

9. Running stand-alone &clm; with transient historical &CO2; concentration

The cases in this chapter are more sophisticated and require more technical knowledge and skill than cases in previous chapters. The user should be very familiar with doing simple cases before moving onto the cases described here.

## Running with the prognostic crop model on

In &clmcesm103; a prognostic crop model was added to &clm4;. The prognostic crop model is setup to work with CN for present day conditions and we have surface and initial condition datasets at f19 resolution. In order to use the initial condition file, we need to set the `RUN_TYPE` to `startup` rather than `hybrid` since the compset for f19 sets up to use an initial condition file without crop active. To activate the crop model we simply add "-crop on" to &CLMCONFIG;.

### Example Crop Simulation

    > cd scripts
    > ./create_newcase -case CROP -res f19_g16 -compset ICN -mach bluefire
    > cd CROP
    # Append "-crop on" to &CLMCONFIG; in env_conf.xml (you could also use an editor)
    > ./xmlchange -file env_conf.xml -id &CLMCONFIG; -val "-crop on" -append
    # Change to startup type so uses spunup initial conditions file for crop if it exists
    # By default the model will do a hybrid startup with an initial condition file
    # incompatible with the crop surface dataset.
    > ./xmlchange -file env_conf.xml -id RUN_TYPE -val startup
    > ./configure -case
    # Now build and run normally
    > ./CROP.bluefire.build
    > ./CROP.bluefire.submit

## Running with the irrigation model on

In &clmcesm103; an irrigation model for generic crop was added to &clm4;. Currently, irrigation and crop can NOT be used together see bug number 1326 in the &KnownBugs; file. The irrigation model is tuned to work only with &clmsp; see the caution below for for more information on this. To turn on irrigation we simply add "-irrig on" to &CLMBLDNML;. Just as in the crop example we also change `RUN_TYPE` to `startup` so that we don't use an initial condition file that is incompatible with irrigation.

### Example Irrigation Simulation

    > cd scripts
    # Note here we do a &clmsp; simulation as that is what has been validated
    > ./create_newcase -case IRRIG -res f19_g16 -compset I -mach bluefire
    > cd IRRIG
    # Append "-irrig on" to &CLMBLDNML; in env_conf.xml (you could also use an editor)
    > ./xmlchange -file env_conf.xml -id &CLMBLDNML; -val "-irrig" -append
    # Change to startup type so uses spunup initial conditions file for irrigation if it exists
    # By default the model will do a hybrid startup with an initial condition file
    # incompatible with the irrigation surface dataset.
    > xmlchange -file env_conf.xml -id RUN_TYPE -val startup
    > ./configure -case
    # Now build and run normally
    > ./IRRIG.bluefire.build
    > ./IRRIG.bluefire.submit

We have only run the irrigation model with &clmsp; (i.e. without the CN model). We recommend that if you want to run the irrigation model with CN, that you do a spinup as outlined in the examples below. But, more than that you may need to make the adjustments we discuss in .

## Spinning up the Satellite Phenology Model (&clmsp; spinup)

To spin-up the &clmsp; model you merely need to run &clmsp; for 50 simulation years starting from arbitrary initial conditions. You then use the final restart file for initial conditions in other simulations. Because, this is a straight forward operation we will NOT give the details on how to do that here, but leave it as an exercise for the reader. See the as an example of doing this as the last step for &clmcn;.

## Spinning up the biogeochemistry Carbon-Nitrogen Model (CN spinup)

To get the &clmcn; model to a steady state, you first run it from arbitrary initial conditions using the "accelerated decomposition spinup" (-ad_spinup in configure) mode for 600 simulation years. After this you branch from this mode in the "exit spinup" (-exit_spinup in configure), run for a simulation year, and then save a restart from that and use it as initial conditions for further spinup of CN (at least 50 simulation years).

### Spinup of &clmcn;

1. ### AD_SPINUP

   For the first step of running 600 years in "-ad_spinup" mode, you will setup a case, and then edit the values in `env_conf.xml` and `env_run.xml` so that the right configuration is turned on and the simulation is setup to run for the required length of simulation time. So do the following:

   ### Example AD_SPINUP Simulation

       > cd scripts
       > ./create_newcase -case CN_spinup -res f19_g16 -compset ICN -mach bluefire
       > cd CN_spinup
       # Append "-ad_spinup on" to &CLMCONFIG; in env_conf.xml
       > ./xmlchange -file env_conf.xml -id &CLMCONFIG; -val "-ad_spinup on" -append
       # The following sets &CLMFORCECOLD; to "on" in env_conf.xml (you could also use an editor)
       > ./xmlchange -file env_conf.xml -id &CLMFORCECOLD; -val on
       # Make the output history files only annual, by adding the following to the &usernlclm; namelist
       > echo '&clm_inparm hist_nhtfrq = -8760 /' > &usernlclm;
       # Now configure
       > ./configure -case
       > ./xmlchange -file env_run.xml -id STOP_DATE -val 6010101
       # Now build
       > ./CN_spinup.bluefire.build
       # The following sets RESUBMIT to 30 times in env_run.xml (you could also use an editor)
       > ./xmlchange -file env_run.xml -id RESUBMIT -val 30
       # The following sets STOP_OPTION to "nyears" in env_run.xml (you could also use an editor)
       > ./xmlchange -file env_run.xml -id STOP_OPTION -val nyears
       # The following sets STOP_N to 20 years in env_run.xml (you could also use an editor)
       > ./xmlchange -file env_run.xml -id STOP_N -val 20
       # The following sets STOP_DATE to Jan/1 of year 601 in env_run.xml (you could also use an editor)
       # Now run normally
       > ./CN_spinup.bluefire.submit

   Afterwards save the last restart file from this simulation to use in the next step.

2. ### EXIT_SPINIP

   ### Example EXIT_SPINUP Simulation

       > cd scripts
       > ./create_newcase -case CN_exitspinup -res f19_g16 -compset ICN -mach bluefire
       > cd CN_exitspinup
       # Append "-exit_spinup on" to &CLMCONFIG; in env_conf.xml
       > ./xmlchange -file env_conf.xml -id &CLMCONFIG; -val "-exit_spinup on" -append
       # Change run type to branch and branch from the last year of the last simulation
       > ./xmlchange -file env_conf.xml -id RUN_TYPE    -val branch
       > ./xmlchange -file env_conf.xml -id RUN_REFCASE -val CN_spinup
       > ./xmlchange -file env_conf.xml -id RUN_REFDATE -val 0601-01-01
       > ./xmlchange -file env_conf.xml -id GET_REFCASE -val FALSE
       > ./configure -case
       # Go ahead and build, so that the run directory is created
       > ./CN_exitspinup.bluefire.build
       # Now, Copy the last restart files from the earlier case into your run directory
       > cp /ptmp/$LOGIN/archive/CN_spinup/rest/CN_spinup.*.r*.0601-01-01-00000* /ptmp/$LOGIN/CN_exitspinup
       # And copy the rpointer files for datm and drv from the earlier case
       > cp /ptmp/$LOGIN/archive/CN_spinup/rest/rpointer.atm /ptmp/$LOGIN/CN_exitspinup
       > cp /ptmp/$LOGIN/archive/CN_spinup/rest/rpointer.drv /ptmp/$LOGIN/CN_exitspinup
       # The following sets STOP_OPTION to "nyears" in env_run.xml (you could also use an editor)
       > ./xmlchange -file env_run.xml -id STOP_OPTION -val nyears
       > ./xmlchange -file env_run.xml -id STOP_N      -val 1
       # Now run normally
       > ./CN_exitspinup.bluefire.submit

3. ### Final spinup

   Next save the last restart file from this step and use it as the "finidat" file to use for one more spinup for at least 50 years in normal mode. So do the following:

   ### Example Final CN Spinup Simulation

       > cd scripts
       > ./create_newcase -case CN_finalspinup -res f19_g16 -compset ICN -mach bluefire
       > cd CN_finalspinup
       # The following sets &CLMFORCECOLD; to "on" in env_conf.xml (you could also use an editor)
       > ./xmlchange -file env_conf.xml -id &CLMFORCECOLD; -val on
       # Now, Copy the last &clm; restart file from the earlier case into your run directory
       > cp /ptmp/$LOGIN/archive/CN_exitspinup/rest/CN_exitspinup.clm*.r*.0602-01-01-00000.nc \
       /ptmp/$LOGIN/CN_finalspinup
       # And copy the rpointer files for datm and drv from the earlier case
       > cp /ptmp/$LOGIN/archive/CN_exitspinup/rest/rpointer.atm /ptmp/$LOGIN/CN_finalspinup
       > cp /ptmp/$LOGIN/archive/CN_exitspinup/rest/rpointer.drv /ptmp/$LOGIN/CN_finalspinup
       # Set the finidat file to the last restart file saved in previous step
       > echo '&clm_inparm finidat = "CN_exitspinup.clm2.r.0602-01-01-00000.nc" /' > &usernlclm;
       # Now configure
       > ./configure -case
       > $EDITOR Buildconf/clm.buildnml.csh
       > Now build
       > .CN_finalspinup.bluefire.build
       # The following sets RESUBMIT to 5 times in env_run.xml (you could also use an editor)
       > ./xmlchange -file env_run.xml -id RESUBMIT -val 5
       # The following sets STOP_OPTION to "nyears" in env_run.xml (you could also use an editor)
       > ./xmlchange -file env_run.xml -id STOP_OPTION -val nyears
       # The following sets STOP_N to 10 years in env_run.xml (you could also use an editor)
       > ./xmlchange -file env_run.xml -id STOP_N -val 10
       > Now run as normal
       > .CN_finalspinup.bluefire.submit

   To assess if the model is spunup plot trends of CN variables of interest. If you see a trend, you may need to run the simulation longer. Finally save the restart file from the end of this simulation to use as an "finidat" file for future simulations.

## Spinning up the Carbon-Nitrogen Dynamic Global Vegetation Model (CNDV spinup)

To spinup the &clm; CNDV model -- you first follow the procedures above to spinup the CN model. Then you take the CN initial state file you created for the spinup with just CN, and run CNDV for 200 more years. We've provided such spunup files for two resolutions (f09 and f19) and two time-periods (1850 and 2000), so in this example we will use the files provided to start from. We've also provided a spinup file at f19 resolution for CNDV, hence the following is NOT required when running at f19. If you were to start from your own &clmcn; spunup files -- the procedure would require some modification. There are no compsets using CNDV, so in `env_conf.xml` change `CLM_CONFIG_OPTS` to `-bgc cndv`.

### Example CNDV Spinup Simulation

    > cd scripts
    > ./create_newcase -case CNDV_spinup -res f09_g16 -compset ICN -mach bluefire
    > cd CNDV_spinup
    # Set run type to startup and do a cold start
    > ./xmlchange -file env_conf.xml -id RUN_TYPE -val startup
    # The following sets CLM_CONFIG_OPTS to "-bgc cndv" in env_conf.xml (you could also use an editor)
    > ./xmlchange -file env_conf.xml -id CLM_CONFIG_OPTS  -val "-bgc cndv"
    # Make the default primary history file annual and add an annual 1D vector auxiliary file
    # By putting the following in a &usernlclm; file.
    > cat << EOF > &usernlclm;
    &clm_inparm
     hist_nhtfrq = -8760, -8760
     hist_mfilt  =     1, 1
     hist_fincl2 = 'TLAI', 'TSAI', 'HTOP', 'HBOT', 'NPP'
     hist_dov2xy = .true., .false.
    /
    > ./configure -case
    # NOTE: If you were using your own CN spinup files you would edit the namelist to use it
    # $EDITOR Buildconf/clm.buildnml.csh
    #
    # Now build and run as normal
    > ./CNDV_spinup.bluefire.build
    # The following sets RESUBMIT to 10 times in env_run.xml (you could also use an editor)
    > ./xmlchange -file env_run.xml -id RESUBMIT -val 10
    # The following sets STOP_OPTION to "nyears" in env_run.xml (you could also use an editor)
    > ./xmlchange -file env_run.xml -id STOP_OPTION -val nyears
    # The following sets STOP_N to 20 years in env_run.xml (you could also use an editor)
    > ./xmlchange -file env_run.xml -id STOP_N -val 20
    # Make sure you turn archiving on, so you save your files to long term archival
    > ./xmlchange -file env_run.xml -id DOUT_L_MS -val TRUE
    > ./CNDV_spinup.bluefire.submit

There is a build bug with &clmcesm103; see bug 1370 in the &KnownBugs; on how to address this.

In a data analysis tool you should examine the auxiliary file and examine the `pfts1d_wtgcell` to see where and what types of vegetation have been established. See the caution in for more information on visualizing and analyzing 1D vector fields.

CNDV also writes out two vector fields to "hv" auxiliary files, on an annual basis by default.

We've provided a spinup file for CNDV at f19 resolution, you could also use `interpinic` to interpolate this file to other resolutions.

## Running with MOAR data as atmospheric forcing to spinup the model

Because it takes so long to spinup the CN model (as we just saw previously), if you are doing fully coupled simulations with active atmosphere and ocean, you will want to do the spinup portion of this "offline". So instead of doing expensive fully coupled simulations for the spinup duration, you run &clm; in a very cheap "I" compset using atmospheric forcing from a shorter fully coupled simulation (or a simulation run previously by someone else).

In this example we will use the `I1850SPINUPCN` compset to setup &clm; to run with atmospheric forcing from a previous fully coupled simulation with data that is already stored on disk on bluefire. There are several simulations that have high frequency data for which we can do this. You can also do this on a machine other than bluefire, but would need to download the data from the Earth System Grid and change the datapath similar to . This compset is designed for constant 1850 conditions, but unfortunately (because of bug 1354 see the &KnownBugs; file) by default it points to a transient simulation instead of an 1850 simulation. Here we point to an 1850 simulation and setup the forcing years to run over.

### Example Simulation with MOAR Data on bluefire

    > cd scripts
    > ./create_newcase -case MOARforce1850 -res f19_g16 -compset I1850SPINUPCN -mach bluefire
    > cd MOARforce1850
    # The following sets the casename to point to for atm forcing (you could also use an editor)
    > ./xmlchange -file env_conf.xml -id DATM_CPL_CASE -val b40.1850.track1.1deg.006a
    # The following sets the align year and years to run over for atm forcing
    #  (you could also use an editor)
    > ./xmlchange -file env_conf.xml -id DATM_CPL_YR_ALIGN -val 1
    > ./xmlchange -file env_conf.xml -id DATM_CPL_YR_START -val 960
    > ./xmlchange -file env_conf.xml -id DATM_CPL_YR_END -val 1030
    > ./configure -case
    # Now build and run as normal
    > ./MOARforce1850.bluefire.build
    > ./MOARforce1850.bluefire.submit

Because of bug 1339 (see the &KnownBugs; file on this) you can't run with 83 or more years of forcing. If you do need to run with more years of forcing, you'll need to address the issue as outlined in the &KnownBugs; file.

## Running with your own previous simulation as atmospheric forcing to spinup the model

Another way that you might want to spinup the model is to run your own simulation for a relatively short period (either a B, E, or F compset) and then use it as forcing for your "I" case later. By only running 20 to 50 years for the fully coupled case, you'll save a substantial amount of computer time rather than running the entire spinup period with a fully coupled model.

The first thing we need to do is to run a fully coupled case and save the atmospheric coupling fields on a three hourly basis. In this example, we will run on bluefire and archive the data to a local disk that we can then use in the next simulation.

### Example Fully Coupled Simulation to Create Data to Force Next Example Simulation

    > cd scripts
    > ./create_newcase -case myBCN1850 -res f09_g16 -compset B1850CN  -mach bluefire
    > cd myBCN1850
    > ./configure -case
    # Set histaux_a2x3hr to .true. in cpl.buildnml.csh so output from the atmosphere model
    # will be saved 3 hourly
    $EDITOR BuildConf/cpl.buildnml.csh
    # Now build
    > ./myBCN1850.bluefire.build
    # The following sets the archival disk space (you could also use an editor)
    > ./xmlchange -file env_run.xml -id DOUT_S_ROOT -val '/glade/home/$USER/$CASE'
    # Make sure files are archived to disk, but NOT to long term storage
    # (you could also use an editor)
    > ./xmlchange -file env_run.xml -id DOUT_S -val TRUE
    > ./xmlchange -file env_run.xml -id DOUT_L_MS -val FALSE
    # Set the run length to run a total of 20 years (you could also use an editor)
    > ./xmlchange -file env_run.xml -id RESUBMIT -val 9
    > ./xmlchange -file env_run.xml -id STOP_OPTION -val nyears
    > ./xmlchange -file env_run.xml -id STOP_N -val 2
    # Now run as normal
    > ./myBCN1850.bluefire.submit

Now we run an I compset forced with the data from the previous simulation using the &CPLHIST; option to DATM_MODE. See for more information on the &datm; settings for &CPLHIST; mode.

### Example Simulation Forced with Data from the Previous Simulation

    > cd scripts
    > ./create_newcase -case frcwmyBCN1850 -res f09_g16 -compset I1850SPINUPCN -mach bluefire
    > cd frcWmyBCN1850
    # The following sets the casename to point to for atm forcing (you could also use an editor)
    > ./xmlchange -file env_conf.xml -id DATM_CPL_CASE -val "myBCN1850"
    # The following sets the align year and years to run over for atm forcing
    #  (you could also use an editor)
    > ./xmlchange -file env_conf.xml -id DATM_CPL_YR_ALIGN -val "1"
    > ./xmlchange -file env_conf.xml -id DATM_CPL_YR_START -val "1"
    > ./xmlchange -file env_conf.xml -id DATM_CPL_YR_END -val "20"
    # Set the datapath in the template to the archival path from the case above
    > sed -E 's#set datapath = ".+"#set datapath = "/glade/home/$USER/%c/cpl/hist"#' \
      Tools/Templates/datm.cpl7.template > new.datm.cpl7.template
    > mv -f new.datm.cpl7.template Tools/Templates/datm.cpl7.template
    > chmod +x Tools/Templates/datm.cpl7.template
    > ./configure -case
    # Now build and run as normal
    > ./frcwmyBCN1850.bluefire.build
    > ./frcwmyBCN1850.bluefire.submit

In order to accomplish this we needed to edit the &datm; template file. See for more information on doing this. If your input case was at a resolution besides f09 you would have to edit the &datm; template file even further to use a domain file at the input resolution.

## Doing perturbation error growth tests

Doing perturbation error growth tests is a way to validate a port of the model to a new machine or to verify that changes are only roundoff. The steps are the same in either case, but in the discussion below I will assume you are doing a port validation to a new machine (but in parentheses I will put a reminder that it could also be for code-mods). The basic idea is to run a case on the trusted machine (trusted code) and another with initial conditions perturbed by roundoff and compare the results of the two. The difference between these two simulations (the error) will grow over time and describe a curve that we compare with the error growth on the new machine (code changes). The error growth on the new machine is the difference between the non-perturbed state on the trusted machine and the non-perturbed state on the new machine (code changes). If the new machine (code changes) are well-behaved the plot of this error growth compared to the error growth curve on the trusted machine should be similar. If the changes are NOT well-behaved the changes from the new machine (code changes) will be larger than the perturbation changes. In summary the simulations and steps that need to be performed are:

1. Run a simulation with the trusted code on the trusted machine. (optionally you can use a dataset from inputdata repository).

2. Run a simulation with the trusted code on the trusted machine with initial conditions perturbed by roundoff (using a namelist item to do so). (this is optional is you are using inputdata repository datasets)

3. Run a simulation with the new code on the non-trusted machine (code changes).

4. Do a plot of the RMS difference of history variables between simulation 1 and simulation 2.

5. Do a plot of the RMS difference of history variables between simulation 1 and simulation 3.

6. Compare the two plots in steps 4 and 5.

7. If the plots compare well the new machine (code changes) is running as well as the trusted machine.

8. If the plots do NOTcompare well the new machine is NOTrunning as well as the trusted machine. Typically the recommendation here is to lower the optimization level on the new machine and try again (or in the case of code changes, modify or simplify the code changes to get something that should be closer).

   The history variables we have used to do this is either 'TSOI', and/or 'TSA'. 'TSOI' are the 3D snow and soil temperatures for vegetated land-units. If there is a change in soil physics it should show up in this field (and it should show up even for something that is at a pretty deep soil depth). However, as 'TSOI' is only for vegetated land-units, changes in lake or urban land-units -- will NOT show up. 'TSA' by contrast is the 2m surface temperature across all land-units, so changes in urban or lake land-units will show up. However, changes in deep soil physics will only show up as it propagates to the surface. So one field may show something that the other doesn't. In the examples, we use 'TSOI', but 'TSA' can be used as well. And in most cases you should check both.

Now we will give a detailed description of the procedure with examples and the exact steps to perform.

### Using Perturbation Error Growth Analysis to Verify a Port to a New Machine

1. ### Running non-perturbed on trusted machine

   The first step is to run a non-perturbed case on the trusted machine. You need to run all of the steps with the same compset and same resolution. For these examples we will use 2-degree resolution with the ICN compset for 2000 conditions. You need to run for three days with a cold-start.

   As we describe below, This is optional if you will be using datasets from the inputdata repository to take place of this step.

   ### Example non-perturbed error growth simulation

       > cd scripts
       > ./create_newcase -case trustedMachinePergro0 -compset ICN -res f19_g16 \
       -mach bluefire
       > cd trustedMachinePergro0
       # Set the non-perturbed PERGRO use-case
       > ./xmlchange -file env_conf.xml -id CLM_NML_USE_CASE -val pergro0_pd
       # Set coldstart on so arbitrary initial conditions will be used
       > ./xmlchange -file env_conf.xml -id CLM_FORCE_COLDSTART -val on
       > ./xmlchange -file env_conf.xml -id RUN_TYPE -val startup
       # Set PERGRO on in the configure
       > ./xmlchange -file env_conf.xml -id &CLMCONFIG; -val "-pergro on" -append
       # Now configure and build
       > ./configure -case
       > ./trustedMachinePergro0.bluefire.build
       # Set it to run for three days and turn archiving off
       > ./xmlchange -file env_run.xml -id STOP_N -val 3
       > ./xmlchange -file env_run.xml -id DOUT_S -val FALSE
       # Run the case and then you will save the history file output for later use
       > ./trustedMachinePergro0.bluefire.submit

   If you aren't able to do this step, as you don't have access to a trusted machine, you can use datasets that are available from the svn inputdata repository to take place of running it yourself. The disadvantage is that this is only done for certain model versions and for exactly the configuration/namelist given here. You won't be able to test it for your own custom code or configurations.

2. ### Running perturbed on the trusted machine

   The next step is to run a perturbed case on the trusted machine.

   ### Example perturbed error growth simulation

       > cd scripts
       > ./create_newcase -case trustedMachinePergroRnd -compset ICN -res f19_g16 \
       -mach bluefire
       > cd trustedMachinePergroRnd
       # Set the perturbed PERGRO use-case
       > ./xmlchange -file env_conf.xml -id CLM_NML_USE_CASE -val pergro_pd
       # Set coldstart on so arbitrary initial conditions will be used
       > ./xmlchange -file env_conf.xml -id RUN_TYPE -val startup
       > ./xmlchange -file env_conf.xml -id CLM_FORCE_COLDSTART -val on
       # Set PERGRO on in the configure
       > ./xmlchange -file env_conf.xml -id &CLMCONFIG; -val "-pergro on" -append
       # Now configure and build
       > ./configure -case
       > ./trustedMachinePergroRnd.bluefire.build
       # Set it to run for three days and turn archiving off
       > ./xmlchange -file env_run.xml -id STOP_N -val 3
       > ./xmlchange -file env_run.xml -id DOUT_S -val FALSE
       # Run the case and then you will save the history file output for later use
       > ./trustedMachinePergroRnd.bluefire.submit

   If you aren't able to do this step, as you don't have access to a trusted machine, you can use datasets that are available from the svn inputdata repository to take place of running it yourself. The disadvantage is that this is only done for certain model versions and for exactly the configuration/namelist given here. You won't be able to test it for your own custom code or configurations.

3. ### Running non-perturbed on the new machine

   The next step is to run a non-perturbed case on the new machine. Here we will demonstrate using the machine intrepid. For the previous two steps you have the option of using datasets provided in the subversion inputdata repository to take their place -- however this step is required.

       > cd scripts
       > ./create_newcase -case newMachinePergro0 -compset ICN -res f19_g16 \
       -mach intrepid
       > cd newMachinePergro0
       # Set the non-perturbed PERGRO use-case
       > ./xmlchange -file env_conf.xml -id CLM_NML_USE_CASE -val pergro0_pd
       > ./xmlchange -file env_conf.xml -id CLM_FORCE_COLDSTART -val on
       > ./xmlchange -file env_conf.xml -id RUN_TYPE -val startup
       # Set PERGRO on in the configure
       > ./xmlchange -file env_conf.xml -id &CLMCONFIG; -val "-pergro on" -append
       # Now configure and build
       > ./configure -case
       > ./newMachinePergro0.intrepid.build
       # Set it to run for three days and turn archiving off
       > ./xmlchange -file env_run.xml -id STOP_N -val 3
       > ./xmlchange -file env_run.xml -id DOUT_S -val FALSE
       # Run the case and then you will save the history file output for later use
       > ./newMachinePergro0.intrepid.submit

4. ### Plotting the differences

   You can use the `cprnc` program to compute root mean square differences between the relevant history files. See for more information on it and how to build it. On many platforms you will need to set some environment variables in order to complete the build (see for more information on building the tools).

       # Build the cprnc program
       > cd models/lnd/clm/tools/cprnc
       > gmake
       # Now go to your case directory and run cprnc on the trusted-machine with and without
       # perturbation
       > cd ../../../../../scripts/trustedMachinePergro0
       > ../../models/lnd/clm/tools/cprnc/cprnc trustedMachinePergro0.clm2.h0.001-01-01.00000.nc \
       ../trustedMachinePergroRnd/trustedMachinePergroRnd.clm2.h0.001-01-01.00000.nc > trustedPergro.log
       # Copy the history file from the new machine to here
       #
       # And now run cprnc on the trusted-machine and the new machine both without perturbation
       > ../../models/lnd/clm/tools/cprnc/cprnc trustedMachinePergro0.clm2.h0.001-01-01.00000.nc \
       ../newMachinePergro0/newMachinePergro0.clm2.h0.001-01-01.00000.nc > newPergro.log
       # Now extract out the RMS differences of TSOI for both
       # You may want to extract out the RMS differences for TSA as well
       # Changes in urban or lake land-units won't be detected with TSOI
       > grep "RMS TSOI" trustedPergro.log | awk '{print $3}' > RMStrusted.dat
       > grep "RMS TSOI" newPergro.log     | awk '{print $3}' > RMSnewmachine.dat
       # And plot the two curves up to your screen
       > env TYPE=x11 RMSDAT=RMSnewmachine.dat RMSDAT2=RMStrusted.dat ncl \
       ../../models/lnd/clm/tools/ncl_scripts/pergroPlot.ncl

   Here is a sample plot for several trusted machines: bluefire, intrepid, jaguar, and edinburgh (with both the lahey and intel compilers). The green line is the error growth for bluefire, the red is the error growth for intrepid, the dashed navy is for jaguar, the dashed maroon is for the intel compiler on edinburgh, and the thick dashed goldenrod line is for edinburgh with the lahey compiler. Note, the data for this plot is in `models/lnd/clm/tools/ncl_scripts` the files are named: according to the legend. Note, that the lines tend to cluster together and follow quite closely to the bluefire line which is our main trusted machine.

   ### Sample Good Perturbation Error Growth Curves (within roundoff)

   When you do NOT have access to a trusted machine you can use the trusted file from bluefire that is available on the inputdata repository.

       # Build the cprnc program
       > cd models/lnd/clm/tools/cprnc
       > gmake
       # Get the unperturbed file from the subversion repository
       > cd ../../../../../scripts/newMachinePergro0
       > set dir = "lnd/clm2/pergrodata"
       > set file = bluefirePergro0.ICN.0001-01-01_1.9x2.5_gx1v6_simyr2000_clm4-cesm1_0_3.c110617.nc
       > echo "trustedfile = DIN_LOC_ROOT/$dir/$file" > clm.input_data_list
       > ../ccsm_utils/Tools/check_input_data -datalistdir . -export -inputdata $DIN_LOC_ROOT
       # And now run cprnc on the bluefire file and the new machine both without perturbation
       > ../../models/lnd/clm/tools/cprnc/cprnc $file \
       ../newMachinePergro0/newMachinePergro0.clm2.h0.001-01-01.00000.nc > newPergro.log
       # Now extract out the RMS difference
       # You may want to extract out the RMS differences for TSA as well
       # Changes in urban or lake land-units won't be detected with TSOI
       > grep "RMS TSOI" newPergro.log     | awk '{print $3}' > RMSnewmachine.dat
       # And plot the new curve versus the trusted curve up to your screen
       > env TYPE=x11 RMSDAT=RMSnewmachine.dat \
       RMSDAT2=../../models/lnd/clm/tools/ncl_scripts/RMSbluefire.dat  \
       ../../models/lnd/clm/tools/ncl_scripts/pergroPlot.ncl

   In the figure below we now show example of curves for changes that are larger than roundoff. Once again the green curve is the trusted error growth from bluefire. The other curves are for changes that may be fairly small, but are larger than roundoff. The goldenrod curve is for using the 1850, and the navy is for using the 1999 Nitrogen deposition files rather than for year 2000. The red is for using the 1850 aerosol dataset rather than 2000, and the maroon is for adding the snow combination bug in. The differences in changes that are greater than roundoff is that the curves climb very steeply to the 10-6 value and then level off, while the curve for bluefire climbs much more slowly and gradually. The curves also don't mimic each other in any way, like the trusted machine plots do.

   ### Sample Bad Perturbation Error Growth Curves (changes greater than roundoff)

## Running stand-alone &clm; with transient historical &CO2; concentration

In this case you want to run a simulation with stand-alone &clm; responding to changes in &CO2; for a historical period. For this example, we will start with the "I_1850-2000_CN" compset that has transient: land-use, Nitrogen and Aerosol deposition already. You could also use another compset if you didn't want these other features to be transient. In order to get &CO2; to be transient we need to edit the &datm; template so that we add an extra streams file to describe how &CO2; varies over the historical period. You also need a &netcdf; datafile that datm can read that gives the variation. You could supply your own file, but we have a standard file that is used by CAM for this and our example will make use of this file.

Most everything here has to do with changing datm rather than &clm; to allow this to happen. As such the user that wishes to do this should first become more familiar with datm and read the &cesm; Data Model User's Guide especially as it pertains to the datm. Note, also that in this example we show how to edit the datm "buildnml" file for your case, but you could do something similar by editing the datm template.

This section documents the process for doing something that is non-standard. There may be errors with the documentation and process, and you may have to do some work before all of this works for you. If that is the case, we recommend that you do further research into understanding the process and the files, as well as understanding the datm and how it works. You may have to read documentation found in the code for datm as well as "csm_share".

The datm has "streams" files that have rough XML-like syntax and specify the location and file to get data from, as well as information on the variable names and the data locations of the grid points. The datm expects specific variable names and the datm "maps" the expected variable names from the file to the names expected by datm. The file we are working with here is a file with a single-point, that covers the entire globe (so the vertices go from -90 to 90 degrees in latitude and 0 to 360 degrees in longitude). Since it's a single point it's a little easier to work with than datasets that may be at a given horizontal resolution. The datm also expects that variables will be in certain units, and only expects a limited number of variables so arbitrary fields can NOT be exchanged this way. However, the process would be similar for datasets that do contain more than one point.

The three things that are needed: a domain file, a data file, and a streams text file. The domain file is a CF-compliant &netcdf; file that has information on the grid points (latitudes and longitudes for cell-centers and vertices, mask , fraction, and areas). The datafile is a CF-compliant &netcdf; file with the data that will be mapped. The streams text file is the XML-like file that tells datm how to find the files and how to map the variables datm knows about to the variable names on the &netcdf; files. Note, that in our case the domain file and the data file are the same file. In other cases, the domain file may be separate from the data file.

First we are going to create a case, and we will edit the `Buildconf/datm.buildnml.csh` so that we add a &CO2; data stream in. There is a streams text file available in `models/lnd/clm/doc/UsersGuide/co2_streams.txt`, that includes file with a &CO2; time-series from 1765 to 2007.

### Example Transient Simulation with Historical &CO2;

    > cd scripts
    > ./create_newcase -case DATM_CO2_TSERIES -res f19_g16 -compset I_1850-2000_CN \
    -mach bluefire
    > cd DATM_CO2_TSERIES
    # Set CCSM_BGC to CO2A so that CO2 will be passed from atmosphere to land
    > ./xmlchange -file env_conf.xml -id CCSM_BGC -val CO2A
    # Set CLM_CO2_TYPE to diagnostic so that the land will use the value sent from the atmosphere
    > ./xmlchange -file env_conf.xml -id CLM_CO2_TYPE -val diagnostic
    > ./configure -case
    > cd Buildconf
    # Copy the sample streams file over
    > cp ../../../models/lnd/clm/doc/UsersGuide/co2_streams.txt .

The first thing we will do is to edit the datm buildnml script to add a CO2 file stream in. To do this we will apply a patch with the differences needed. The patch file `addco2_datm.buildnml.diff` is in `models/lnd/clm/doc/UsersGuide` and looks like this...

    &co2streams_diff;

So to apply the patch you do this...

    > cd scripts/DATM_CO2_TSERIES/Buildconf
    > patch < ../../../models/lnd/clm/doc/UsersGuide/addco2_datm.buildnml.diff

Once, you've done that you can build and run your case normally.

The patch assumes you are using a `I_1850-2000_CN` compset out of the box, with `DATM_PRESAERO` equal to `trans_1850-2000`. So it assumes standard Qian atmosphere forcing, and transient prescribed aerosols from streams files. If your case changes anything here the patch will fail, and you will need to put the changes in by hand.

If the patch fails, you will have to add the changes to the `datm.buildnml.csh` found in the above patch file by hand. Basically, it adds an extra streams file for &CO2; to the end of the streams variable, and other arrays associated with streams (adding mapalgo as a new array with bilinear for everything, but the &CO2; file which should be "nn" for nearest neighbor).

The streams file above is hard-coded for the path of the file on &ncar; computers. To use it on an outside machine you'll need to edit the filepath in the streams file to point to the location where you have the file.

After going through these steps, you will have a case where you have datm reading in an extra streams text file that points to a data file with &CO2; data on it that will send that data to the &clm;.