$Id: preface.xml 36692 2012-04-27 18:39:55Z tcraig $ I want to acknowledge all of the people that helped review or edit the model documentation: David Lawrence, Samuel Levis, Keith Oleson, and Sean Swenson. Thank you for your help in catching errors, and making the document more understandable and readable. Our readers thank you as well, as now it is much easier for them to digest. Any mistakes, or errors are all mine. If you run across one of those errors, please let us know, by following . I also want to thank Sheri Mickelson, for her work in doing perturbation analysis on bluefire and intrepid, which was used in our initial versions of this User's Guide. We also want to thank the original authors of &ptclm;: Daniel M. Ricciuto, Dali Wang, Peter E. Thornton, Wilfred M. Post, and R. Quinn Thomas for providing a nice addition to the &cesm; effort. We also want to thank the folks at University of Michigan Biological Stations (US-UMB) who allowed us to use their Fluxnet station data and import it into our inputdata repository, especially Gil Bohrer the PI on record for this site (see for permission information on using this data). The Community Land Model (&clmrel;) is the latest in a series of global land models developed by the &cesm; Land Model Working Group (LMWG) and maintained at the National Center for Atmospheric Research (&ncar;). This guide is intended to instruct both the novice and experienced user on running &clm;. This guide pertains to the latest version &clmrel; available for download from the public release subversion repository as a part of &cesmrel;. Documentation may be different if you are using an older version, you should either update to the latest version, or use the documentation inside your own source tree. There is information in the ChangeLog file and in the regarding the changes from previous versions of &cesm;. The novice user should read in detail before beginning work, while the expert user should read and chapters, and then use the more detailed chapters as reference. Before novice users go onto more technical problems covered in , , , or they should know the material covered in and be able to replicate some of the examples given there. All users should read the and sections to understand the document conventions and the various ways of getting help on using &clm4;. Users should also read the section to see if their planned use of the model is something that has been scientifically validated and well tested. Users that are NOT using &ncar; machines or our list of well tested machines should also read the section to make sure they have all the required UNIX utilities on the system they want to do their work. What is in here anyway? Here in the introduction we first give a simple guide to understand the document conventions in . The next section describes the differences between &clmrel; and &clm40; (for each &cesm; release version up to &cesmrel;) as well as between &clm40; and &clm35;, both from a scientific as well as a software engineering point of view. It also talks about differences in the configuration, namelist, and history fields. The next section is for users that are already experts in using &clm; and gives a quickstart guide to the bare details on how to use &clm4;. The next tells you about what has been extensively tested and scientifically validated (and maybe more importantly) what has NOT. lists the UNIX utilities required to use &clm4; and is important if you are running on non-&ncar; machines, generic local machines, or machines NOT as well tested by us at &ncar;. Next we have to detail some of the best practices for using &clm4; for science. The last introductory section is which lists different resources for getting help with &cesm1; and &clm4;. goes into detail on how to setup and run simulations with &clm4; and especially how to customize cases. Details of &configure; modes and &buildnml; options as well as namelist options are given in this chapter. gives instructions on the &clm4; tools for creating input datasets for use by &clm;, for the expert user. There's an overview of what each tool does, and some general notes on how to build the FORTRAN tools. Then each tool is described in detail along with different ways in which the tool might be used. A final section on how to customize datasets for observational sites for very savvy expert users is given as the last section of this chapter. As a followup to the tools chapter, tells how to add files to the XML database for &buildnml; to use. This is important if you want to use the XML database to automatically select user-created input files that you have created when you setup new cases with &clm;. In , again for the expert user, we give details on how to do some particularly difficult special cases. For example, we give the protocol for spinning up both the &clmcn; model and &clm; with dynamic vegetation active (CNDV). We give instructions to do a spinup case from a previous case with Coupler history output for atmospheric forcing. We also give instructions on running both the prognostic crop and irrigation models. We also review how to validate a port to a new machine using the Perturbation error growth technique. Lastly we tell the user how to use the DATM model to send historical &CO2; data to &clm;. outlines how to do single-point or regional simulations using &clm4;. This is useful to either compare &clm; simulations with point observational stations, such as tower sites (which might include your own atmospheric forcing), or to do quick simulations with &clm; for example to test a new parameterization. There are several different ways given on how to perform single-point simulations which range from simple &PTSMODE; to more complex where you create all your own datasets, tying into and also to add the files into the &buildnml; XML database. After this chapter chapter outlines how to use the &ptclm; python script to help you run single-point simulations. Finally, gives some guidance on trouble-shooting problems when using &clm4;. It doesn't cover all possible problems with &clm;, but gives you some guidelines for things that can be done for some common problems. In the appendices we talk about some issues that are useful for advanced users and developers of &clm;. In we give some basic background to the &clm; developer on how to edit the models/lnd/clm/bld/clm.cpl7.template. This is a very difficult exercise and we don't recommend it for any, but the most advanced users of &clm; who are also experts in UNIX and UNIX scripting. In we go over how to run the script runinit_ibm.csh" that will interpolate standard resolution initial condition dataset to several other resolutions at once. It also runs &clm; to create template files as well as doing the interpolation using interpinic. In general this is only something that a developer would want to do. Most users will only want to interpolate for a few specific resolutions. In we go over the automated testing scripts for validating that the &clm; is working correctly. The test scripts run many different configurations and options with &clm; making sure that they work, as well as doing automated testing to verify restarts are working correctly, and testing at many different resolutions. In general this is an activity important only for a developer of &clm;, but could also be used by users who are doing extensive code modifications and want to ensure that the model continues to work correctly. Finally in we give instructions on how to build the documentation associated with &clm; (i.e. how to build this document). This document is included in every &clm; distribution and can be built so that you can view a local copy rather than having to go to the &cesm; website. This also could be useful for developers who need to update the documentation due to changes they have made. When running with CN, it is critical to begin with initial conditions hat are provided with the release or to spin the model up following the CN spinup procedure before conducting scientific runs (see . Simulations without a proper spinup will effectively be starting from an unvegetated world. See for information on how to provide initial conditions for your simulation. Initial condition files are provided for fully coupled BCN and offline ICN cases for 1850 and 2000 at 1deg, 2deg, and T31 resolutions. There's also an initial condition file for ICN with the prognostic crop model for 2000 at 2deg resolution, and one with &clmsp; for 2000 at 2deg resolution. We also have initial conditions for offline CNDV for 1850. And there are interpolated datasets for 4x5 and 10x15 resolution for 1850. The 1850 initial condition files are in 'reasonable' equilibrium. The 2000 initial condition files represent the model state for the year 2000, and have been taken from transient simulations. Therefore, by design the year 2000 initial condition files do not represent an equilibrium state. Note also that spinning the 2000 initial conditions out to equilibrium will not reflect the best estimate of the real carbon/nitrogen state for the year 2000. Users can generate initial condition files at different resolutions by using the &clm; tool interpinic to interpolate from one of the provided resolutions to the resolution of interest. Interpolated initial condition files may no longer be in 'reasonable' equilibrium. Aerosol deposition is a required field to &clm4; sent from the atmosphere model. Simulations without aerosol deposition will exhibit unreasonably high snow albedos. The model sends aerosol deposition from the atmospheric model (either CAM or &datm;). When running with prescribed aerosol the atmosphere model will interpolate the aerosols from 2-degree resolution to the resolution the atmosphere model is running at. $EDITOR Conventions used in the document for code and commands This section provides the details in using &clm; with the &cesm; modeling system. Links to descriptions and definitions have been provided in the code below. We use the same conventions used in the &cesm; documentation as outlined below. Throughout the document this style is used to indicate shell commands and options, fragments of code, namelist variables, etc. Where examples from an interactive shell session are presented, lines starting with > indicate the shell prompt. A backslash "\" at the end of a line means the line continues onto the next one (as it does in standard UNIX shell). Note that $EDITOR" is used to refer to the text editor of your choice. $EDITOR is a standard UNIX environment variable and should be set on most UNIX systems. Comment lines are signaled with a "#" sign, which is the standard UNIX comment sign as well. $CSMDATA is used to denote the path to the inputdata directory for your &cesm; data. > This is a shell prompt with commands \ that continues to the following line. > $EDITOR filename # means you are using a text editor to edit "filename" # This is a comment line &clmcn; &clmsp; In this section we list the updates that have occurred to &clm4; since previous public releases. In the first sections we describe changes in &clmrel; since the &ccsm4; release, and in the last one we describe changes from &clm35; to &clm40; release. Note, that the changes in the last section do NOT include the more recent changes given in the first section, but only list the changes from &clm35; to the &clm40; release that was part of the &ccsm4; public release. We will describe both the changes in the science in the model as the software engineering changes. Software engineering changes includes the configure and namelist changes, as well as the new history fields. A prognostic crop model option was added in (based on Agro-IBIS) from work by Samuel Levis. The crop model adds in four new vegetation types for: soybean, winter and spring temperate cereals, and corn on their own separate columns. Winter cereal was added as a PFT type, but doesn't exist in the input datasets, only spring cereal is used. Winter cereal also has NOT been scientifically validated or tested. The model manages these by modeling both planting and harvesting. See for an example of running with it. Also an irrigation model was added from work by Samuel Levis and Bill Sacks. This model takes water from runoff and adds it to the generic crop for those areas equipped for irrigation. See for an example of running with it. Please note that the irrigation model does not currently work with the new crop model described above, but rather only works with the generic crop Since &clmcesm102; all Input/Output uses &pio; (Parallel Input/Output package). Restart history files are now &netcdf;. Input and output files can be read/written in parallel using PIO. We removed a list of old CPP defines and removed the old misc/preproc.h files. Also a new tool for working with single-point sites was added into the &cesm; scripts the Python tool &ptclm;. We have a complete chapter on it's use. New configuration options: -crop -noio Configuration options removed: -dust -progsslt New build-namelist options: -irrig -co2_ppmv -rtm_res -rtm_tstep New precedence for build-namelist options is... Values set on the command-line using the -namelist option (&CLMNAMELIST;). Values read from the file specified by -infile (&usernlclm; file). Datasets from the -clm_usr_name option (&CLMUSRDAT;). Values set from a use-case scenario, e.g., -use_case (&CLMUSECASE;). Values from the namelist defaults file. Namelist options renamed: carbon_only => suplnitro (can be set to NONE, PROG_CROP_ONLY, or ALL) namelist options removed: carbon_only => suplnitro scaled_harvest hist_crtinic hist_pioflag ncd_lowmem2d ncd_pio_def ncd_pio_UseRearranger ncd_pio_UseBoxRearr ncd_pio_SerialCDF ncd_pio_IODOF_rootonly ncd_pio_DebugLevel ncd_pio_num_iotasks New history fields: A5TMIN 5-day running mean of min 2-m temperature (K) A10TMIN 10-day running mean of min 2-m temperature (K) GDD0 Growing degree days base 0C from planting (ddays) GDD8 Growing degree days base 8C from planting (ddays) GDD10 Growing degree days base 10C from planting (ddays) GDD020 Twenty year average of growing degree days base 0C from planting (ddays) GDD820 Twenty year average of growing degree days base 8C from planting (ddays) GDD1020 Twenty year average of growing degree days base 10C from planting (ddays) GDDPLANT Accumulated growing degree days past planting date for crop (ddays) GDDHARV Growing degree days (gdd) needed to harvest (ddays) GDDTSOI Growing degree-days from planting (top two soil layers) (ddays) QIRRIG water added through irrigation (mm/s) SNOWLIQ and SNOWICE changed from average to instantaneous output. Since, &clm4010; in the &cesm101; release there were several developments made to &clmrel;. Several new namelist items were added a few new history fields. There were also some updates for running the model with single-point mode. Configuration options that were renamed: prog_seasalt => progsslt Namelist items removed: prog_seasalt => progsslt A long simulation at the course resolution of T31 (typically used for Paleo-climate studies) was done and an spun-up initial condition file was provided for this resolution (also by default the namelist variable ice_runoff was turned off for T31). Also a new surface dataset and transient land-cover dataset was provided for half-degree resolution. New configuration options sitespf_pt sitespf_pt is used for single-point/regional mode and is set to the site-name that will be used (see the config_definition.xml for the list of valid options). Configuration options that were renamed: prog_seasalt => progsslt Namelist items removed: faerdep fndepdat fndepdyn use_ndepstream Nitrogen deposition datasets are now only entered through the ndepdyn_nml namelist (removing fndepdat, fndepdyn, and use_ndepstream). Aerosol deposition is now a required input from the atmosphere model, hence faerdep is removed. New history fields: U10 10-m wind (m/s) U10_DUST 10-m wind for dust model (m/s) VA atmospheric wind speed plus convective velocity (m/s) VOLR RTM storage: LIQ (m3) VOLR_ICE RTM storage: ICE (m3) From, &clm40; in the &ccsm4; release to &clm4010; there were several developments made to &clm;. A glacier multiple elevation class option was added that allows the use of &clm4; with a glacier land ice model the Community Ice Sheet Model (CISM). A bug-fix for the snow hydrology was added. Several new namelist items were added a few new history fields. Also the capability of reading aerosol and nitrogen deposition from stream files at one resolution and regridded on the fly rather than with datasets at the model resolution was added in. This was important for higher resolutions so that large datasets do not have to be created before running the model, nor are datasets for every resolution required. In general, snow layers should not be thinner than dzmin = wice/rhoice + wliq/rholiq If dz < dzmin, then the value of "void" computed in subroutine SnowCompaction is negative, which is unphysical. This doesn't cause problems with the compaction itself, but results in unrealistic values of vol_ice, vol_liq, and eff_porosity in subroutine SnowWater. We can have vol_ice = 1 and vol_liq = 0 even when liquid is present, which cuts off the runoff (qout) from the lowest snow layer. Liquid water then accumulates in the snow column without draining, which leads to further problems and eventually a code crash. The solution to this problem was to adjust layer thickness dz for any water+ice content changes in excess of previous layer thickness, e.g., dz(c,j) = max(dz(c,j),h2osoi_liq(c,j)/denh2o + h2osoi_ice(c,j)/denice) at appropriate steps in the snow hydrology subroutines. Snow hydrology bug fix. Add multiple elevation class option for glaciers so can interact with the land ice sheet model. New configuration options glc_nec glc_nec can be 1,3,5, or 10 and MUST match the number on the input surface dataset the elevation classes themselves are read from the surface dataset New namelist items: carbon_only create_glacier_mec_landunit glc_dyntopo glc_smb ice_runoff ndepmapalgo scaled_harvest carbon_only = If true, and CLMCN carbon-nitrogen model is on, Nitrogen is unlimited rather than prognosed and vegetation will be over-productive (replaces the supplemental Nitrogen #ifdef) create_glacier_mec_landunit (= T when these landunits are created; F by default) glc_smb (= T if passing surface mass balance to GLC; else pass PDD info; T by default) glc_dyntopo (= T if &clm; topography changes dynamically; currently F) (NOT fully implemented yet) ice_runoff = If true, river runoff will be split up into liquid and ice streams, otherwise ice runoff will be zero and all runoff directed to liquid stream ndepmapalgo = Mapping method from Nitrogen deposition input file to the model resolution (can be bilinear,nn,nnoni,nnonj,spval,copy, bilinear by default) scaled_harvest = If true, harvesting will be scaled according to coefficients determined by Johann Feddema, 2009 New history fields: aais_area Antarctic ice area (km^2) aais_mask Antarctic mask (unitless) gris_area Greenland ice area (km^2) gris_mask Greenland mask (unitless) QICE ice growth/melt (mm/s) QICEYR ice growth/melt (mm/s) QTOPSOIL water input to surface (mm/s) VOLR RTM storage: LIQ (m3) VOLR_ICE RTM storage: ICE (m3) From &clm35; to &clm40; there were advances in both the science and the software infrastructure. There were also new configure and namelist options as well as new history fields. In this section we will describe each of these changes in turn. The following aspects are changes to the science in &clm40; since &clm35;. Changes to &clm40; beyond &clm35; (Oleson et al., 2008a; Stockli et al., 2008) include updates throughout the model. The hydrology scheme has been modified with a revised numerical solution of the Richards equation (Zeng and Decker, 2009; Decker and Zeng, 2009); a revised soil evaporation parameterization that removes the soil resistance term introduced in &clm35; and replaces it with a so-called &Bgr; formulation, as well as accounts for the role of litter and within- canopy stability (Sakaguchi and Zeng, 2009). &clm4; also includes a representation of the thermal and hydraulic properties of organic soil that operates in conjunction with the mineral soil properties (Lawrence and Slater, 2008). The ground column has been extended to ~50-m depth by adding five additional hydrologically inactive ground layers (making a total of 15 ground layers, 10 soil layers and 5 bedrock layers; Lawrence et al., 2008). An urban landunit and associated urban canyon model (&clmu;) has been added which permits the study of urban climate and urban heat island effects (Oleson et al., 2008b). The snow model is significantly modified via incorporation of SNICAR (SNow and Ice Aerosol Radiation) which represents the effect of aerosol deposition (e.g. black and organic carbon and dust) on albedo, introduces a grain-size dependent snow aging parameterization, and permits vertically resolved snowpack heating (Flanner and Zender, 2005; Flanner and Zender, 2006; Flanner et al., 2007). The new snow model also includes a new density-dependent snow cover fraction parameterization (Niu and Yang, 2007), a revised snow burial fraction over short vegetation (Wang and Zeng, 2009) and corrections to snow compaction (Lawrence and Slater, 2009). The PFT distribution is as in Lawrence and Chase (2007) except that a new cropping dataset is used (Ramankutty et al., 2008) and a grass PFT restriction has been put in place to reduce a high grass PFT bias in forested regions by replacing the herbaceous fraction with low trees rather than grass. Grass and crop PFT optical properties have been adjusted according to values presented in Asner et al. (1998), resulting in significantly reduced albedo biases. Soil colors have been re-derived according to the new PFT distribution. The model is extended with a carbon-nitrogen biogeochemical model (Thornton et al., 2007; Thornton et al., 2009; Randerson et al., 2009) which is referred to as &clmcn;. CN is based on the terrestrial biogeochemistry Biome-BGC model with prognostic carbon and nitrogen cycle (Thornton et al., 2002; Thornton and Rosenbloom, 2005). &clmcn; is prognostic with respect to carbon and nitrogen state variables in the vegetation, litter, and soil organic matter. Vegetation phenology and canopy heights are also prognostic. A detailed description of the biogeochemical component can be found in Thornton et al. (2007). Note that &clm40; can be run with either prescribed satellite phenology (&clmsp;) or with prognostic phenology provided by the carbon- nitrogen cycle model (&clmcn;). Additionally, a transient land cover and land use change, including wood harvest, capability has been introduced that enables the evaluation of the impact of historic and future land cover and land use change on energy, water, and momentum fluxes as well as carbon and nitrogen fluxes. The dynamic global vegetation model in &clm3; has been revised such that the carbon dynamics (e.g. productivity, decomposition, phenology, allocation, etc.) are controlled by CN and only the dynamic vegetation biogeography (competition) aspect of the &clm3; DGVM is retained. The biogenic volatile organic compounds model (BVOC) that was available in &clm3; has been replaced with the MEGAN BVOC model (Heald et al. 2008). Several other minor changes have been incorporated including a change to the atmospheric reference height so that it is the height above zo+d for all surface types. The convergence of canopy roughness length zo and displacement height d to bare soil values as the above-ground biomass, or the sum of leaf and stem area indices, goes to zero is ensured (Zeng and Wang, 2007). Several corrections have been made to the way the offline forcing data is interpreted. The main change is a vastly improved and smooth diurnal cycle of incoming solar radiation that conserves the total incoming solar radiation from the forcing dataset. Additionally, in offline mode rather than partitioning incoming solar radiation into a constant 70%/30% direct vs diffuse split, it is partitioned according to empirical equations that are a function of total solar radiation. Finally, to improve global energy conservation in fully coupled simulations, runoff is split into separate liquid and ice water streams that are passed separately to the ocean. Input to the ice water comes from excess snowfall in snow-capped regions. Taken together, these augmentations to &clm35; in &clm40; result in improved soil moisture dynamics that lead to higher soil moisture variability and drier soils. Excessively wet and unvarying soil moisture was recognized as a deficiency in &clm35; (Oleson et al. 2008a, Decker and Zeng, 2009). The revised model also simulates, on average, higher snow cover, cooler soil temperatures in organic-rich soils, greater global river discharge, lower albedos over forests and grasslands, and higher transition-season albedos in snow covered regions, all of which are improvements compared to &clm35;. The following aspects are changes to the software infrastructure in &clm40; since &clm35;. Update to cpl7 and scripts. Remove offline and cpl6 modes. Remove support for CASA model. Update to datm8 atmospheric data model. Add gx3v7 land mask for T31 and fv-4x5 horizontal resolutions. Add gx1v6 land mask for f05, f09, and f19 horizontal resolutions. Add tx1v1 land mask and 1.9x2.5_tx1v1 horizontal resolution. Add in 2.5x3.33 horizontal resolution. Add in T62 horizontal resolution so can run at same resolution as input &datm; data. Allow first history tape to be 1D. Add ability to use own version of input datasets with &CLMUSRDAT; variable. Add a script to extract out regional datasets. New &buildnml; system with XML file describing all namelist items. Add glacier_mec use-case and stub glacier model. Make default of maxpatch_pft=numpft+1 instead of 4. Only output static 3D fields on first h0 history file to save space. Add new fields for VOC (Volatile Organic Compounds) on surface datasets, needed for the new MEGAN VOC model. Add irrigation area to mksurfdata tool (NOT used in &clm; yet). Add multiple elevation class option for glaciers in mksurfdata tool (NOT used in &clm; yet). Add ascale field to land model in support of model running on it's own grid. Describe any changes made to build system: Change directory structure to match &ccsm;. Add BGP target. Add choice between ESMF and MCT frameworks. Start removing #ifdef and directives that supported Cray-X1 Phoenix as now decommissioned. Make default of maxpatch_pft=numpft+1 instead of 4 for all configurations. By default turn on CLAMP when either CN or CASA is enabled New SNICAR_FRC, CARBON_AERO, and C13 CPP ifdef tokens. New options added to &configure;: More information on options to &clm; &configure; are given in . OptionDescription -comp_intf <name>Component interface to use (ESMF or MCT) (default MCT) -nofireTurn off wildfires for bgc setting of CN (default includes fire for CN) -pio <name>Switch enables building with Parallel I/O library. [on | off] (default is on) -snicar_frc <name>Turn on SNICAR radiative forcing calculation. [on | off] (default is off) More information on options to &clm; &configure; are given in . &buildnml; now checks the validity of your namelist you generate by looking at data in the namelist_definition.xml file. In order to add new namelist items you need to change the code and also edit this file (e.g. a namelist option required for your research project that is not currently an option in &clm40;). To view information on the namelist view the file: models/lnd/clm/bld/namelist_files/namelist_definition.xml in a browser and you'll see the names, type, description and valid_values for all namelist variables. Changes to &buildnml;: Allow simulation year entered to include ranges of years (i.e. 1850-2000) Remove cam_hist_case option. Make sure options ONLY used for stand-alone testing have a "drv_" or "datm_" prefix in them and list these options all together and last when asking for help from &buildnml;. New option to &buildnml;: -clm_usr_name "name" Dataset resolution/descriptor for personal datasets. Default: not used Example: 1x1pt_boulderCO_c090722 to describe location, number of pts, and date files created New list options to &buildnml; cd models/lnd/clm/bld ./&buildnml; -res list # List valid resolutions ./&buildnml; -mask list # List valid land-masks ./&buildnml; -sim_year list # List valid simulation years and simulation year ranges ./&buildnml; -clm_demand list # List namelist variables including those you could # demand to be set. ./&buildnml; -use_case list # List valid use-cases New use-cases for &buildnml;: 1850_control = Conditions to simulate 1850 land-use 2000_control = Conditions to simulate 2000 land-use 20thC_transient = Simulate transient land-use, aerosol and Nitrogen deposition from 1850 to 2005 New namelist items: urban_hac = OFF, ON or ON_WASTEHEAT (default OFF) Flag for urban Heating and Air-Conditioning OFF = Building internal temperature is un-regulated. ON = Building internal temperature is bounded to reasonable range. ON_WASTEHEAT = Building internal temperature is bounded and resultant waste heat is given off. urban_traffic = .true. or .false. Flag to include additional multiplicative factor of urban traffic to sensible heat flux. (default .false.) fsnowoptics = filename file for snow/aerosol optical properties (required) fsnowaging = filename file for snow aging parameters (required) More information on the &buildnml; options are given in . and in &CLMBLDNML;. More information on the &buildnml; options are given in in . New history variables: (note watt vs. W in units, 26 vs. 76) NameLong-nameUnitsActive/Inactive BCDEPtotal BC deposition (dry+wet) from atmospherekg/m^2/s BIOGENCObiogenic CO fluxuGC/M2/H C13_PRODUCT_CLOSSC13 total carbon loss from wood product poolsgC13/m^2/s DSTDEPtotal dust deposition (dry+wet) from atmospherekg/m^2/s EFLX_DYNBALdynamic land cover change conversion energy fluxW/m^2 FGR12heat flux between soil layers 1 and 2watt/m^2 FSATfractional area with water table at surfaceunitless FSH_NODYNLNDUSEsensible heat flux not including correction for land use change watt/m^2 GC_HEAT1initial gridcell total heat contentJ/m^2 GC_HEAT2post land cover change total heat contentJ/m^2inactive GC_ICE1initial gridcell total ice contentmm/s GC_ICE2post land cover change total ice contentmm/sinactive GC_LIQ1initial gridcell total liq contentmm GC_LIQ2initial gridcell total liq content mminactive H2OSNO_TOPmass of snow in top snow layerkg HEAT_FROM_ACsensible heat flux put into canyon due to heat removed from air conditioningwatt/m^2 HKhydraulic conductivitymm/sinactive ISOPRENEisoprene fluxuGC/M2/H LAND_USE_FLUXtotal C emitted from land cover conversion and wood product poolsgC/m^2/s LAND_UPTAKENEE minus LAND_USE_FLUX, negative for updategC/m^2/s LWupupwelling longwave radiationwatt/m^2inactive MONOTERPmonoterpene fluxuGC/M2/H NBPnet biome production, includes fire, landuse, and harvest flux, positive for sinkgC/m^2/s OCDEPtotal OC deposition (dry+wet) from atmospherekg/m^2/s OVOCother VOC fluxuGC/M2/H ORVOCother reactive VOC fluxuGC/M2/H PBOTatmospheric pressurePa PCO2atmospheric partial pressure of &CO2;Pa PRODUCT_CLOSStotal carbon loss from wood product poolsgC/m^2/s PRODUCT_NLOSStotal N loss from wood product poolsgN/m^2/s Qairatmospheric specific humiditykg/kginactive Qanthanthropogenic heat fluxwatt/m^2inactive Qtaumomentum fluxkg/m/s^2 QFLX_LIQ_DYNBALliq dynamic land cover change conversion runoff fluxmm/s QFLX_ICE_DYNBALice dynamic land cover change conversion runoff fluxmm/s QRUNOFF_NODYNLNDUSEtotal liquid runoff not including correction for land use change (does not include QSNWCPICE) mm/s QSNWCPICEexcess snowfall due to snow cappingmm/s QSNWCPICE_NODYNLNDUSEexcess snowfall due to snow capping not including correction for land use change mm/s QSNWCPLIQexcess rainfall due to snow cappingmm/sinactive SMPsoil matric potentialmminactive SNOAERFRC2Lsurface forcing of all aerosols in snow, averaged only when snow is present (land) watt/m^2 SNOAERFRCLsurface forcing of all aerosols in snow (land)watt/m^2 SNOBCFRCLsurface forcing of BC in snow (land)watt/m^2 SNOBCMCLmass of BC in snow columnkg/m2 SNOBCMSLmass of BC in top snow layerkg/m2 SNOdTdzLtop snow layer temperature gradient (land)K/m SNODSTFRC2Lsurface forcing of dust in snow, averaged only when snow is present (land) watt/m^2 SNODSTFRCLsurface forcing of dust in snow (land)watt/m^2 SNODSTMCLmass of dust in snow columnkg/m2 SNODSTMSLmass of dust in top snow layerkg/m2 SNOFSRNDdirect nir reflected solar radiation from snowwatt/m^2inactive SNOFSRNIdiffuse nir reflected solar radiation from snowwatt/m^2inactive SNOFSRVDdirect vis reflected solar radiation from snowwatt/m^2inactive SNOFSRVIdiffuse vis reflected solar radiation from snowwatt/m^2inactive SNOFSDSNDdirect nir incident solar radiation on snowwatt/m^2inactive SNOFSDSNIdiffuse nir incident solar radiation on snowwatt/m^2inactive SNOFSDSVDdirect vis incident solar radiation on snowwatt/m^2inactive SNOFSDSVIdiffuse vis incident solar radiation on snowwatt/m^2inactive SNOLIQFLtop snow layer liquid water fraction (land)fractioninactive SNOOCMCLmass of OC in snow columnkg/m2 SNOOCMSLmass of OC in top snow layerKg/m2 SNOOCFRC2Lsurface forcing of OC in snow, averaged only when snow is present (land) watt/m^2 SNOOCFRCLsurface forcing of OC in snow (land)watt/m^2 SNORDSLtop snow layer effective grain radiusm^-6inactive SNOTTOPLsnow temperature (top layer)K/minactive SWupupwelling shortwave radiationwatt/m^2inactive TSOI_10CMsoil temperature in top 10cm of soilK URBAN_ACurban air conditioning fluxwatt/m^2 URBAN_HEATurban heating fluxwatt/m^2 VOCFLXTtotal VOC flux into atmosphereuGC/M2/H Windatmospheric wind velocity magnitudem/sinactive WOOD_HARVESTCwood harvest (to product pools)gC/m^2/s WOOD_HARVESTwood harvest (to product pools)gN/m^2/s History field name changes: OldNew ANNSUM_PLANT_NDEMAND= ANNSUM_POTENTIAL_GPP ANNSUM_RETRANSN= ANNMAX_RETRANSN C13_DWT_PROD10C_LOSS= C13_PROD10C_LOSS C13_DWT_PROD100C_LOSS= C13_PROD100C_LOSS C13_DWT_PROD10N_LOSS= C13_PROD10N_LOSS C13_DWT_PROD100C_LOSS= C13_PROD100C_LOSS DWT_PROD100N_LOSS= PROD10N_LOSS DWT_PROD100N_LOSS= PROD100N_LOSS DWT_PROD100C_LOSS= PROD10C_LOSS DWT_PROD100C_LOSS= PROD100C_LOSS HCSOISNO= HC TEMPSUM_PLANT_NDEMAND= TEMPSUM_POTENTIAL_GPP TEMPSUM_RETRANSN= TEMPMAX_RETRANSN History field names deleted include: SNOWAGE, TSNOW, FMICR, FCO2, DMI, QFLX_SNOWCAP Add new urban oriented _U, and _R (Urban and Rural) for the following history variables: EFLX_LH_TOT, FGR, FIRA, FSH, FSM, Q2M, QRUNOFF, RH2M, SoilAlpha, TG, TREFMNAV, TREFMXAV, and TSA (missing _R for SoilAlpha as the regular SoilAlpha is only defined for rural areas anyway) We are missing the Rural soil-alpha variable: SoilAlpha_R on purpose. SoilAlpha_U is only defined over pervious road, and missing everywhere else. SoilAlpha is defined only for rural areas. Before working with &clm4; read the QuickStart Guide in the &cesmrel; Scripts User's Guide. Once you are familiar with how to setup cases for any type of simulation with &cesm; you will want to direct your attention to the specifics of using &clm;. For some of the details of setting up cases for &clm4; read the README and text files available from the "models/lnd/clm/doc" directory (see the "&clm; Web pages" section for a link to the list of these files). Here are the important ones that you should be familiar with. README file describing the directory structure. Quickstart.userdatasets file describing how to use your own datasets in the model (also see ). &KnownBugs; file describing known problems in &clm4; (that we expect to eventually fix). KnownLimitations file describing known limitations in &clm4; and workarounds that we do NOT expect to fix. The IMPORTANT_NOTES file is given in the next chapter on what is functional/validated in &clm4;? The ChangeLog/ChangeSum files are largely explained in the previous chapter on "What is new with &clm4;?" Note other directories have README files that explain different components and tools used when running &clm; and are useful in understanding how those parts of the model work and should be consulted when using tools in those directories. For more details on configuring and customizing a case with &clm; see . The Quickstart.GUIDE (which can be found in models/lnd/clm/doc) is repeated here. &quickstart_guide; In this section we go over what has been extensively tested and scientifically validated with &clm4;, and maybe more importantly what has NOT been tested and may NOT be scientifically validated. You can use all features of &clm;, but need to realize that some things haven't been tested extensively or validated scientifically. When you use these features you may run into trouble doing so, and will need to do your own work to make sure the science is reasonable. The standard version of the model is &clmcn; at 1-degree horizontal resolution (0.9x1.25). This version has been scientifically validated with long simulations for: fully coupled simulations ("B" cases), coupled to atmosphere model CAM ("F" cases), and stand-alone &clm; cases ("I" cases). We've also done both long simulations for 1850 conditions, and transient 20th century simulations from 1850 to 2005 (with transient land-use, Nitrogen and Aerosol deposition). There have also been transient future scenario simulations done for fully coupled cases for different "representative concentration pathway" (RCP) scenarios (RCP2.6, RCP4.5, RCP6.0, and RCP8.5). To a lesser extent there have also been simulations done at T31 and 2-degree horizontal resolution (1.9x2.5), and with &clmsp; for these resolutions. As such we have provided appropriate 1-degree, 2-degree, and T31 initial condition datasets for these configurations. The irrigation and prognostic crop models were both validated at 2-degree resolution. The irrigation model for &clmsp; for present day conditions for an "I" compset, and the prognostic crop model for present day conditions for a case coupled to the active land model, but using a data ocean model (an "F" compset). Other resolutions, configurations, and namelist options are less well tested or scientifically validated. The further you get away from the standard configurations and resolutions, the more likely you are to run into trouble, and/or need to scientifically validate your work. In the sections below we go through configuration and/or namelist options or modes that the user should be especially wary of using. You are of course free to use these options, and you may find that they work functionally. Although in some cases you will find issues even with functionality of using them. If so you will need to test, debug and find solutions for these issues on your own. But in every case you will need to go through more extensive work to validate these options from a scientific standpoint. C13(-c13) The C13 mode for bgc=cn is NOT scientifically validated or documented and is NOT recommended for use. CASA(-bgc casa) The bgc=casa mode is NOT scientifically validated or documented and is NOT recommended for use. SNICAR_FRC(-snicar_frc) This mode is tested and functional, but is NOT constantly scientifically validated, and should be considered experimental. -irrig with -bgc cn 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. But, more than that you may need to make adjustments to irrig_factor in models/lnd/clm/src/biogeophys/CanopyFluxesMod.F90. See the notes on this in the description of the irrigation model in the Technical Descriptions of the Interactive Crop Management and Interactive Irrigation Models. -irrig with -crop on Irrigation doesn't work with the prognostic crop model. Irrigation is only applied to generic crop currently, which negates it's practical usage. We also have a known problem when both are on (see bug 1326 in the &KnownBugs; file). If you try to run in this mode, the &clm; &buildnml; will return with an error. -lnd_res: Fine-mesh mode, functional, but experimental -rcp: Representative Concentration Pathway (RCP) for future scenarios, functional for limited resolutions, but experimental -datm_*: All options that start with "datm_" they are only used for &clm; stand-alone testing. -drv_*: All options that start with "drv_" they are only used for &clm; stand-alone testing. casa namelist options: lnpp, lalloc, q10, spunup, and fcpool CASA has NOT been scientifically validated in &clm4;. fine-mesh namelist options: flndtopo, and fatmtopo. These options are functional but experimental. See the -lnd_res option above. suplnitro='ALL' The suplnitro namelist option to the CN Biogeochemistry model supplies unlimited nitrogen and therefore vegetation is over-productive in this mode. urban_traffic: Not currently functional Running the &clm; requires a suite of UNIX utilities and programs and you should make sure you have all of these available before trying to go forward with using it. If you are missing one of these you should contact the systems administrator for the machine you wish to run on and make sure they are installed. &FORTRAN90; compiler "C" compiler GNU make UNIX csh and tcsh shells UNIX sh shell UNIX bash shell UNIX awk UNIX sed &netcdf; library MPI Library "C" pre-processor &perl; Autoconf m4 macro processor Parallel &netcdf; (optional) &ncl; (for some of the offline tools for creating/modifying &clm; input datasets see for more information on &ncl;) Python (optional, needed for &ptclm;) xsltproc, docbook and docbook utilities (optional, needed to build the Users-Guide) protex and latex2html (optional, needed to build the Code-Reference Guide) &cesm; Online Bulletin Board &cesmrel; Scripts User's Guide In addition to this users-guide there are several other resources that are available to help you use &clm4;. The first one is the &cesm; User's-Guide, which documents the entire process of creating cases with &cesm;. The next is the &cesm; bulletin board which is a web-site for exchanging information between users of &cesm;. There are also &clm; web-pages specific for &clm;, and finally there is an email address to report bugs that you find in &cesm1;. &clmrel; is always run from within the standard &cesmrel; build and run scripts. Therefore, the user of &clm4; should familiarize themselves with the &cesmrel; scripts and understand how to work with them. User's-Guide documentation on the &cesmrel; scripts are available from the following web-page. The purpose of this &clmrel; User's Guide is to give the &clm4; user more complete details on how to work with &clm; and the set of tools that support &clm;, as well as to give examples that are unique to the use of &clm;. However, the &cesmrel; Scripts User's-Guide remains the primary source to get detailed information on how to build and run the &cesm; system. &cesm1; Scripts User's-Guide There is a rich and diverse set of people that use the &cesm;, and often it is useful to be in contact with others to get help in solving problems or trying something new. To facilitate this we have an online Bulletin Board for questions on the &cesm;. There are also different sections in the Bulletin Board for the different component models or for different topics. &cesm; Online Bulletin Board The main &clm; web page contains information on the &clm;, it's history, developers, as well as downloads for previous model versions. There are also documentation text files in the models/lnd/clm/doc directory that give some quick information on using &clm;. &clm; web page &clm; Documentation Text Files Also note that several of the XML database files can be viewed in a web browser to get a nice table of namelist options, namelist defaults, or compsets. Simply view them as a local file and bring up one of the following files: models/lnd/clm/bld/namelist_files/namelist_definition.xml -- definition of &clm; namelist items. models/lnd/clm/bld/namelist_files/namelist_defaults_clm.xml -- default values for &clm; namelist items. scripts/ccsm_utils/Case.template/config_definition.xml -- definition of all env_*.xml items. scripts/ccsm_utils/Case.template/config_compsets.xml -- definition of all the compsets. models/lnd/clm/bld/namelist_files/history_fields.xml -- definition of &clm; history fields. If you have any problems, additional questions, bug reports, or any other feedback, please send an email to cesmhelp@cgd.ucar.edu. If you find bad, wrong, or misleading information in this users guide send an email to erik@ucar.edu. The current list of known issues for &clmrel; is in the &KnownBugs; file, and the list of issues for &cesmrel; is at... &cesmwebmodelrel;/tags/cesm1_0_3/#PROBLEMS .