diff --git a/.github/workflows/pr-docs-check.yml b/.github/workflows/pr-docs-check.yml new file mode 100644 index 0000000000..e23e9940da --- /dev/null +++ b/.github/workflows/pr-docs-check.yml @@ -0,0 +1,14 @@ +name: "Pull Request Docs Check (SSR Fork)" +on: +- pull_request + +jobs: + docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v1 + - uses: samsrabin/sphinx-action@use-escomp-base-container + with: + docs-folder: "doc/source" + pre-build-command: "git lfs install && git lfs pull --exclude='' --include=''" + build-command: "sphinx-build -W --keep-going -n -b html . /home/user/mounted_home/_build" diff --git a/doc/Makefile b/doc/Makefile index 49e9764b7a..c36990a15e 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -2,7 +2,7 @@ # # You can set these variables from the command line. -SPHINXOPTS = +SPHINXOPTS = -W --keep-going -n SPHINXBUILD = sphinx-build SPHINXPROJ = clmdoc SOURCEDIR = source diff --git a/doc/source/conf.py b/doc/source/conf.py index 6c00f5a686..7300102f74 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -80,7 +80,7 @@ # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = None +language = "en" # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. @@ -178,7 +178,7 @@ # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'https://docs.python.org/': None} +intersphinx_mapping = {'python': ('https://docs.python.org/', None)} numfig = True numfig_format = {'figure': 'Figure %s', diff --git a/doc/source/lilac/specific-atm-models/wrf-nesting.rst b/doc/source/lilac/specific-atm-models/wrf-nesting.rst index f4c4570f2f..db3b6f05cb 100644 --- a/doc/source/lilac/specific-atm-models/wrf-nesting.rst +++ b/doc/source/lilac/specific-atm-models/wrf-nesting.rst @@ -50,13 +50,7 @@ A full description of all steps for a WRF-CTSM run are included here. Therefore, we are not repeating the steps necessary for building WRF and CTSM. -In this example we use a nested domain over the CONUS as shows below: - -.. _Figure ctsm-ndown: - -.. figure:: ndown_ctsm_diagram.svg - - Flowchart for WRF-CTSM one-way nested simulations +In this example we use a nested domain over the continental United States. Nested Simulations : Pre-processing (geogrid.exe) ------------------------------------------------- diff --git a/doc/source/users_guide/index.rst b/doc/source/users_guide/index.rst index 75a2949bec..8c675c79db 100644 --- a/doc/source/users_guide/index.rst +++ b/doc/source/users_guide/index.rst @@ -24,7 +24,6 @@ adding-new-resolutions/index.rst running-special-cases/index.rst running-single-points/index.rst - running-PTCLM/index.rst trouble-shooting/index.rst testing/index.rst diff --git a/doc/source/users_guide/overview/getting-help.rst b/doc/source/users_guide/overview/getting-help.rst index 74765d1ad0..7c33071db9 100644 --- a/doc/source/users_guide/overview/getting-help.rst +++ b/doc/source/users_guide/overview/getting-help.rst @@ -146,9 +146,6 @@ MOSART PFT Plant Function Type (PFT). A type of vegetation that CLM parameterizes. -PTCLM - PoinT CLM (PTCLM) a python script that operates on top of CLM for |version| to run single point simulations for CLM. - ROF River runOff Model to route flow of surface water over land out to the ocean. |cesmrelease| has two components options for this the new model MOSART and previous model RTM. diff --git a/doc/source/users_guide/overview/introduction.rst b/doc/source/users_guide/overview/introduction.rst index bc7c1fd82c..e02fa3e422 100644 --- a/doc/source/users_guide/overview/introduction.rst +++ b/doc/source/users_guide/overview/introduction.rst @@ -60,9 +60,7 @@ As a followup to the tools chapter, :ref:`adding-new-resolutions-section` tells In :ref:`running-special-cases-section`, 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 the |version|-BGC and CLMCN models as well as 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. Lastly we tell the user how to use the DATM model to send historical CO2 data to CLM. -:ref:`running-single-points` outlines how to do single-point or regional simulations using |version|. This is useful to either compare |version| 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 PTS_MODE to more complex where you create all your own datasets, tying into :ref:`using-clm-tools-section` and also :ref:`adding-new-resolutions-section` to add the files into the build-namelist XML database. The PTCLM python script to run single-point simulations was added back in for this release (but it has bugs that don't allow it to work out of the box). CLM4 in CESM1.0.5 has a fully working versions of PTCLM. - -Need :ref:`running-PTCLM` blurb... +:ref:`running-single-points` outlines how to do single-point or regional simulations using |version|. This is useful to either compare |version| 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 PTS_MODE to more complex where you create all your own datasets, tying into :ref:`using-clm-tools-section` and also :ref:`adding-new-resolutions-section` to add the files into the build-namelist XML database. :ref:`troubleshooting-index` gives some guidance on trouble-shooting problems when using |version|. It doesn't cover all possible problems with CLM, but gives you some guidelines for things that can be done for some common problems. diff --git a/doc/source/users_guide/running-PTCLM/adding-ptclm-site-data.rst b/doc/source/users_guide/running-PTCLM/adding-ptclm-site-data.rst deleted file mode 100644 index b95831427f..0000000000 --- a/doc/source/users_guide/running-PTCLM/adding-ptclm-site-data.rst +++ /dev/null @@ -1,88 +0,0 @@ -.. include:: ../substitutions.rst - -.. _adding-ptclm-site-data: - -============================ -Adding PTCLMmkdata Site Data -============================ - -The "sitegroupname" option to PTCLMmkdata looks for groups of sites in the files in the ``PTCLM_sitedata`` directory under the PTCLMmkdata directory. You can add new names available for this option including your own lists of sites, by adding more files in this directory. There are three files for each "sitegroupname": ``$SITEGROUP_sitedata.txt``, ``$SITEGROUP_soildata.txt`` and ``$SITEGROUP_pftdata.txt`` (where ``$SITEGROUP`` is the name that would be entered as "sitegroupname" to PTCLMmkdata). Each file needs to have the same list of sites, but gives different information: site data, PFT data, and soil data respectively. Although the site codes need to be the same between the three files, the files do NOT have to be in the same order. Each file has a one-line header that lists the contents of each column which are separated by commas. The first column for each of the files is the "site_code" which must be consistent between the three files. The site code can be any unique character string, but in general we use the AmeriFlux site code. - -Site data file:`` $SITEGROUP_sitedata.txt``): The header for this file is: -:: - - site_code,name,state,lon,lat,elev,startyear,endyear,alignyear - -The columns: name, state, and elevation are informational only. Name is a longer descriptive name of the site, and state is the state for U.S. sites or country for non U.S. sites. The columns: lon and lat are the longitude and latitude of the location in decimal degrees. The last three columns are the start and ending year for the data and the align year for an 1850 case for the data. The align year is currently unused. - -Soil data file: ``$SITEGROUP_soildata.txt``): The header for this file is: -:: - - site_code,soil_depth,n_layers,layer_depth,layer_sand%,layer_clay% - -The first three fields after "site_code" are currently unused. The only two that are used are the percent sand and clay columns to set the soil texture. - -PFT data file: ``$SITEGROUP_pftdata.txt```): The header for this file is: -:: - - site_code,pft_f1,pft_c1,pft_f2,pft_c2,pft_f3,pft_c3,pft_f4,pft_c4,pft_f5,pft_c5 - -This file gives the vegetation coverage for the different vegetation types for the site. The file only supports up to five PFT's at the same time. The columns with "pft_f" are the fractions for each PFT, and the columns with "pft_c" is the integer index of the given PFT. Look at the pft-physiology file to see what the PFT index for each PFT type is. - ----------------------------------------------------- -Dynamic Land-Use Change Files for use by PTCLMmkdata ----------------------------------------------------- - -There is a mechanism for giving site-specific land-use change in PTCLMmkdata. Adding site specific files to the ``PTCLM_sitedata`` directory under PTCLMmkdata allows you to specify the change in vegetation and change in harvesting (for the CN model) for that site. Files are named: ``$SITE_dynpftdata.txt``. There is a sample file for the US-Ha1 site called: ``US-Ha1_dynpftdata.txt``. The file has a one-line header with the information that the file has, and then one-line for each year with a transition. The header line is as follows: -:: - - trans_year,pft_f1,pft_c1,pft_f2,pft_c2,pft_f3,pft_c3,pft_f4,pft_c4,pft_f5,pft_c5,har_vh1,har_vh2,har_sh1,har_sh2,har_sh3,graze,hold_harv,hold_graze - -This file only requires a line for each year where a transition or harvest happens. As in the "pftdata" file above "pft_f" refers to the fraction and "pft_c" refers to the PFT index, and only up to five vegetation types are allowed to co-exist. The last eight columns have to do with harvesting and grazing. The last two columns are whether to hold harvesting and/or grazing constant until the next transition year and will just be either 1 or 0. This file will be converted by the **PTCLM_sitedata/cnvrt_trnsyrs2_pftdyntxtfile.pl** script in the PTCLMmkdata directory to a format that **mksurfdata_esmf** can read that has an entry for each year for the range of years valid for the compset in question. - -.. _converting-ameriflux-for-ptclmmkdata: - ------------------------------------------------- -Converting AmeriFlux Data for use by PTCLMmkdata ------------------------------------------------- - -AmeriFlux data comes in comma separated format and is available from: `http://public.ornl.gov/ameriflux/dataproducts.shtml `_. Before you download the data you need to agree to the usage terms. - -Here is a copy of the usage terms from the web-site on June/13/2011. - -"The AmeriFlux data provided on this site are freely available and were furnished by individual AmeriFlux scientists who encourage their use. Please kindly inform the appropriate AmeriFlux scientist(s) of how you are using the data and of any publication plans. Please acknowledge the data source as a citation or in the acknowledgments if the data are not yet published. If the AmeriFlux Principal Investigators (PIs) feel that they should be acknowledged or offered participation as authors, they will let you know and we assume that an agreement on such matters will be reached before publishing and/or use of the data for publication. If your work directly competes with the PI's analysis they may ask that they have the opportunity to submit a manuscript before you submit one that uses unpublished data. In addition, when publishing, please acknowledge the agency that supported the research. Lastly, we kindly request that those publishing papers using AmeriFlux data provide preprints to the PIs providing the data and to the data archive at the Carbon Dioxide Information Analysis Center (CDIAC)." - -The above agreement applies to the "US-UMB" dataset imported into our repository as well, and Gil Bohrer is the PI on record for that dataset. - -The CESM can NOT handle missing data, so we recommend using the "Level 4" Gap filled datasets. The fields will also need to be renamed. The "WS" column becomes "WIND", "PREC" becomes "PRECmms", "RH" stays as "RH", "TA" becomes "TBOT", "Rg" becomes "FSDS", "Rgl" becomes "FLDS", "PRESS" becomes "PSRF". "ZBOT" can just be set to the constant of "30" (m). The units of Temperature need to be converted from "Celsius" to "Kelvin" (use the value in ``SHR_CONST_TKFRZ`` in the file ``models/csm_share/shr/shr_const.F90`` of ``273.15``. The units of Pressure also need to be converted from "kPa" to "Pa". LATIXY, and LONGXY should also be set to the latitude and longitude of the site. - ------------------------------------------------------------------ -Example: PTCLMmkdata transient example over a shorter time period ------------------------------------------------------------------ - -This is an example of using PTCLMmkdata for Harvard Forest (AmeriFlux site code US-Ha1) for transient land use 1991-2006. In order to do this we would've needed to have converted the AmeriFlux data into NetCDF format as shown in :ref:`converting-ameriflux-for-ptclmmkdata` section above. Also note that this site has a site-specific dynamic land-use change file for it ``PTCLM_sitedata/US-Ha1_dynpftdata.txt`` in the PTCLMmkdata directory and this file will be used for land-use change and harvesting rather than the global dataset. - -:: - - > cd $CTSMROOT/tools/PTCLM - # We are going to use forcing data over 1991 to 2006, but we need to start with - # a transient compset to do so, so we use the 20th Century transient: 1850-2000 - # Note: When creating the fpftdyn dataset for this site it will use the - # PTCLM_sitedata/US-Ha1_dynpftdata.txt - # file for land-use change and harvesting - > ./PTCLMmkdata -s US-Ha1 -d $MYCSMDATA --sitegroupname AmeriFlux - > mkdir $MYCSMDATA/atm/datm7/CLM1PT_data/1x1pt_US-Ha1 - > cd $MYCSMDATA/atm/datm7/CLM1PT_data/1x1pt_US-Ha1 - # Copy data in NetCDF format to this directory, filenames should be YYYY-MM.nc - # The fieldnames on the file should be: - # FLDS,FSDS,LATIXY, LONGXY, PRECTmms,PSRF,RH,TBOT,WIND,ZBOT - # With units - # W/m2,W/m2,degrees_N,degrees_E,mm/s, Pa, %, K, m/s, m - # The time coordinate units should be: days since YYYY-MM-DD 00:00:00 - > cd ../../../../../US-Ha1_I20TRCRUCLM45BGC - # Now we need to set the start date to 1991, and make sure the align year is for 1991 - > ./xmlchange RUN_STARTDATE=1991-01-01,DATM_CLMNCEP_YR_ALIGN=1991 - # Similarly for Nitrogen deposition data we cycle over: 1991 to 2006 - > cat << EOF >> user_nl_clm - model_year_align_ndep=1991,stream_year_first_ndep=1991,stream_year_last_ndep=2006 - EOF diff --git a/doc/source/users_guide/running-PTCLM/index.rst b/doc/source/users_guide/running-PTCLM/index.rst deleted file mode 100644 index 0b44c01b49..0000000000 --- a/doc/source/users_guide/running-PTCLM/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. on documentation master file, created by - sphinx-quickstart on Tue Jan 31 19:46:36 2017. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -.. include:: ../substitutions.rst - -.. _running-PTCLM: - -##################################### -Running PTCLM -##################################### - -.. toctree:: - :maxdepth: 2 - - introduction-to-ptclm.rst - using-ptclm.rst - ptclm-examples.rst - adding-ptclm-site-data.rst diff --git a/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst b/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst deleted file mode 100644 index 9ae4186d2c..0000000000 --- a/doc/source/users_guide/running-PTCLM/introduction-to-ptclm.rst +++ /dev/null @@ -1,135 +0,0 @@ -.. _introduction-to-ptclm.rst: - -.. include:: ../substitutions.rst - -.. _what-is-ptclm: - -===================== - What is PTCLMmkdata? -===================== - -PTCLMmkdata (pronounced Pee-Tee Cee-L-M make data is a Python script to help you set up PoinT CLM simulations. - -It runs the CLM tools for you to get datasets set up, and copies them to a location you can use them including the changes needed for a case to use the dataset with namelist and XML changes. - -Then you run **create_newcase** and point to the directory so that the namelist and XML changes are automatically applied. - -PTCLMmkdata has a simple ASCII text file for storing basic information for your sites. - -We also have complete lists for AmeriFlux and Fluxnet-Canada sites, although we only have the meteorology data for one site. - -For other sites you will need to obtain the meteorology data and translate it to a format that the CESM datm model can use. - -But, even without meteorology data PTCLMmkdata is useful to setup datasets to run with standard ``CLM_QIAN`` data. - -The original authors of PTCLMmkdata are: Daniel M. Ricciuto, Dali Wang, Peter E. Thornton, Wilfred M. Post all at Environmental Sciences Division, Oak Ridge National Laboratory (ORNL) and R. Quinn Thomas at Cornell University. It was then modified fairly extensively by Erik Kluzek at NCAR. We want to thank all of these individuals for this contribution 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. - -.. _details-of-ptclm: - -======================= - Details of PTCLMmkdata -======================= - -To get help on PTCLM2_180611 use the "--help" option as follows. -:: - - > cd $CTSMROOT/tools/PTCLM - > ./PTCLMmkdata --help - -The output to the above command is as follows: -:: - - Usage: PTCLM.py [options] -d inputdatadir -m machine -s sitename - - Python script to create cases to run single point simulations with tower site data. - - Options: - --version show program's version number and exit - -h, --help show this help message and exit - - Required Options: - -d CCSM_INPUT, --csmdata=CCSM_INPUT - Location of CCSM input data - -m MYMACHINE, --machine=MYMACHINE - Machine, valid CESM script machine (-m list to list valid - machines) - -s MYSITE, --site=MYSITE - Site-code to run, FLUXNET code or CLM1PT name (-s list to list - valid names) - - Configure and Run Options: - -c MYCOMPSET, --compset=MYCOMPSET - Compset for CCSM simulation (Must be a valid 'I' compset [other - than IG compsets], use -c list to list valid compsets) - --coldstart Do a coldstart with arbitrary initial conditions - --caseidprefix=MYCASEID - Unique identifier to include as a prefix to the case name - --cesm_root=BASE_CESM - Root CESM directory (top level directory with models and scripts - subdirs) - --debug Flag to turn on debug mode so won't run, but display what would - happen - --finidat=FINIDAT Name of finidat initial conditions file to start CLM from - --list List all valid: sites, compsets, and machines - --namelist=NAMELIST - List of namelist items to add to CLM namelist (example: - --namelist="hist_fincl1='TG',hist_nhtfrq=-1" - --QIAN_tower_yrs Use the QIAN forcing data year that correspond to the tower - years - --rmold Remove the old case directory before starting - --run_n=MYRUN_N Number of time units to run simulation - --run_units=MYRUN_UNITS - Time units to run simulation (steps,days,years, etc.) - --quiet Print minimul information on what the script is doing - --sitegroupname=SITEGROUP - Name of the group of sites to search for you selected site in - (look for prefix group names in the PTCLM_sitedata directory) - --stdurbpt If you want to setup for standard urban namelist settings - --useQIAN use QIAN input forcing data instead of tower site meterology data - --verbose Print out extra information on what the script is doing - - Input data generation options: - These are options having to do with generation of input datasets. Note: When - running for supported CLM1PT single-point datasets you can NOT generate new - datasets. For supported CLM1PT single-point datasets, you MUST run with the - following settings: --nopointdata And you must NOT set any of these: --soilgrid - --pftgrid --owritesrf - - --nopointdata Do NOT make point data (use data already created) - --owritesrf Overwrite the existing surface datasets if they exist (normally - do NOT recreate them) - --pftgrid Use pft information from global gridded file (rather than site - data) - --soilgrid Use soil information from global gridded file (rather than site - data) - - Main Script Version Id: $Id: PTCLM.py 47576 2013-05-29 19:11:16Z erik $ Scripts URL: $HeadURL: https://svn-ccsm-models.cgd.ucar.edu/PTCLM/trunk_tags/PTCLM1_130529/PTCLM.py $: - -Here we give a simple example of using PTCLMmkdata for a straightforward case of running at the US-UMB Fluxnet site on cheyenne where we already have the meteorology data on the machine. Note, see :ref:`converting-ameriflux-for-ptclmmkdata` for permission information to use this data. - -Example 6-1. Example of running PTCLMmkdata for US-UMB on cheyenne ------------------------------------------------------------------- -:: - - > setenv CSMDATA $CESMDATAROOT/inputdata - > setenv MYDATAFILES `pwd`/mydatafiles - > setenv SITE US-UMB - > setenv MYCASE testPTCLM - - # Next build all of the clm tools you will need - > cd $CTSMROOT/tools/PTCLM - > buildtools - # next run PTCLM (NOTE -- MAKE SURE python IS IN YOUR PATH) - > cd $CTSMROOT/tools/PTCLM - # Here we run it using qcmd so that it will be run on a batch node - > qcmd -- ./PTCLMmkdata --site=$SITE --csmdata=$CSMDATA --mydatadir=$MYDATAFILES >& ptclmrun.log & - > cd $CIMEROOT/scripts - > ./create_newcase --user-mods-dir $MYDATAFILES/1x1pt_$SITE --case $MYCASE --res CLM_USRDAT --compset I1PtClm50SpGs - # Next setup, build and run as normal - > cd $MYCASE - > ./case.setup - -PTCLMmkdata includes a README file that gives some extra details and a simple example. - -.. include:: ../../../../tools/PTCLM/README - :literal: diff --git a/doc/source/users_guide/running-PTCLM/ptclm-examples.rst b/doc/source/users_guide/running-PTCLM/ptclm-examples.rst deleted file mode 100644 index 6801c5f3d8..0000000000 --- a/doc/source/users_guide/running-PTCLM/ptclm-examples.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. include:: ../substitutions.rst - -.. _ptclm-examples: - -============================== - Examples of using PTCLMmkdata -============================== - -Now let's give a few more complex examples using some of the options we have discussed above. - -Now, let's demonstrate using a different group list, doing a spinup, running with Qian global forcing data, but using tower years to set the years to run over. This uses the options: sitegroupname, useQIAN, and QIANtower_years. - -Example: Running PTCLMmkdata without tower years ------------------------------------------------- -:: - - > cd $CTSMROOT/tools/PTCLM - > ./PTCLMmkdata -s US-Ha1 -d $CSMDATA --sitegroupname AmeriFlux --donot_use_tower_yrs - > cd ../../../../../US-Ha1_ICRUCLM45BGC_QIAN - # Now build and run normally - ``` - -Finally, let's demonstrate using a generic machine (which then requires the scratchroot option), using the global grid for PFT and soil types, and setting the run length to two months. - -Example: Running PTCLMmkdata with global PFT and soil types dataset -------------------------------------------------------------------- -:: - - > cd $CTSMROOT/tools/PTCLM - # Note, see the the Section called Converting AmeriFlux Data for use by PTCLMmkdata with permission information - # to use the US-UMB data. - > ./PTCLMmkdata -s US-UMB -d $CSMDATA --pftgrid --soilgrid - > cd ../../../../../US-UMB_ICRUCLM45BGC diff --git a/doc/source/users_guide/running-PTCLM/using-ptclm.rst b/doc/source/users_guide/running-PTCLM/using-ptclm.rst deleted file mode 100644 index e7be79bee6..0000000000 --- a/doc/source/users_guide/running-PTCLM/using-ptclm.rst +++ /dev/null @@ -1,114 +0,0 @@ -.. include:: ../substitutions.rst - -.. _using-ptclm.rst: - -************************** -Using PTCLMmkdata -************************** - -There are two types of options to PTCLMmkdata: required and optional. The three required options are the three settings that MUST be specified for PTCLMmkdata to work at all. The other settings have default values that will default to something useful. Most options use a double dash "--" "longname" such as "--list", but the most common options also have a short-name with a single dash. - -The required options to PTCLMmkdata are: inputdata directory (-d) and site-name (-s). Inputdata directory is the directory where you have the CESM inputdata files. Finally site-name is the name of the site that you want to run for. Site-name is a Fluxnet site name from the list of sites you are running on (see the --sitegroupname for more information about the site lists). - -After PTCLMmkdata is run you can run **create_newcase** to setup a case to use the datasets created. It also creates a ``README.PTCLM`` in that directory that documents the commandline options to PTCLMmkdata that were used to create it. - -After "help" the "list" option is one of the most useful options for getting help on using PTCLMmkdata. This option gives you information about some of the other options to PTCLMmkdata. To get a list of the sites that can be used for PTCLMmkdata use the "--list" option as follows. -:: - - > cd $CTSMROOT/tools/PTCLM - > ./PTCLMmkdata --list - -The output to the above command is as follows: -:: - - /bin/sh: line 1: PTCLMmkdata: command not found - -Steps in running PTCLMmkdata -============================ - -1. Build the CLM tools Next you need to make sure all the CLM FORTRAN tools are built. - :: - - > cd $CTSMROOT/tools/PTCLM - > ./buildtools - > gmake clean - -2. Run PTCLMmkdata Next you actually run PTCLMmkdata which does the different things listed below: - - a. PTCLMmkdata names your output file directory based on your input - :: - - [Prefix_]SiteCode - - Where: - ``Prefix`` is from the caseidprefix option (or blank if not used). - - ``SiteCode`` is the site name you entered with the -s option. - - For example, the casename for the following will be: - :: - - > cd scripts - > ./PTCLMmkdata -s US-UMB -d $MYCSMDATA - - b. PTCLMmkdata creates datasets for you It will populate $MYCSMDATA with new datasets it creates using the CLM tools. - - c. If a transient compset and PTCLMmkdata finds a _dynpftdata.txt file If you are running a transient compset (such as the "I_1850-2000_CN" compset) AND you there is a file in the PTCLM_sitedata directory under the PTCLMmkdata directory called $SITE_dynpftdata.txt it will use this file for the land-use changes. Otherwise it will leave land-use constant, unless you use the pftgrid option so it uses the global dataset for landuse changes. See the Section called Dynamic Land-Use Change Files for use by PTCLMmkdata for more information on this. There is a sample transient dataset called US-Ha1_dynpftdata.txt. Transient compsets, are compsets that create transient land-use change and forcing conditions such as: 'I_1850-2000', 'I_1850-2000_CN', 'I_RCP8.5_CN', 'I_RCP6.0_CN', 'I_RCP4.5_CN', or 'I_RCP2.6_CN'. - - d. PTCLMmkdata creates a pft-physiology for you PTCLMmkdata will create a local copy of the pft-physiology specific for your site that you could then customize with changes specific for that site. - - e. PTCLMmkdata creates a README.PTCLM for you PTCLMmkdata will create a simple text file with the command line for it in a file called README.PTCLM in the case directory it creates for you. - -3. Run create_newcase pointing to the directory created - -4. Customize, setup, build and run case as normal You then customize your case as you would normally. See the Chapter 1 chapter for more information on doing this. - -PTCLMmkdata options -========================= - -Next we discuss the setup and run-time options, dividing them up into setup, initial condition (IC), and run-time options. - -Configure options include: - -- --cesm_root=BASE_CESM -- --sitegroupname=SITEGROUP -- --donot_use_tower_yrs - -``--cesm_root`` - This option is for running PTCLMmkdata with a different root directory to CESM than the version PTCLMmkdata exists in. Normally you do NOT need to use this option. - -``--sitegroupname`` - In the PTCLMmkdata directory there is a subdirectory "PTCLM_sitedata" that contains files with the site, PFT and soil data information for groups of sites. These site groups are all separate ASCII files with the same prefix followed by a "_*data.txt" name. See :ref:`adding-ptclm-site-data` for more information on these files. By default we have provided three different valid group names: - -EXAMPLE -------- -AmeriFlux - -Fluxnet-Canada - -The EXAMPLE is the group used by default and ONLY includes the US-UMB site as that is the only site we have data provided for. The other two site groups include the site information for all of both the AmeriFlux and Fluxnet-Canada sites. You can use the "sitegroupname" option to use one of the other lists, or you can create your own lists using the EXAMPLE file as an example. Your list of sites could be real world locations or could be theoretical "virtual" sites given to exercise CLM on differing biomes for example. Note, see :ref:`converting-ameriflux-for-ptclmmkdata` with permission information to use the US-UMB data. - -``--donot_use_tower_yrs`` - This option is used with the "useQIAN" option to set the years to cycle over for the Qian data. In this case Qian atmospheric forcing will be used, but the simulation will run over the same years that tower site is available for this site. - -**Run-time options include:** - -- --debug - -This option tells PTCLMmkdata to echo what it would do if it were run, but NOT actually run anything. So it will show you the dataset creation commands it would use. It does however, run **create_newcase**, but then it only displays the **xmlchange** commands and changes that it would do. Also note that if you give the "--rmold" option it won't delete the case directory beforehand. Primarily this is intended for debugging the operation of PTCLMmkdata. - -**The dataset generation options are:** - -- --pftgrid -- --soilgrid - -The options that with a "grid" suffix all mean to create datasets using the global gridded information rather than using the site specific point data. By default the site specific point data is used. The "nopointdata" and "owritesrfaer" options have to do with file creation. - -Because supported single-point datasets already have the data created for them, you MUST use the "nopointdata" and "ndepgrid" options when you are using a supported single-point site. You must use "ndepgrid" even for a compset without CN. You also can NOT use the options: "soilgrid", "pftgrid", "aerdepgrid", or "owritesrfaer". - -``--pftgrid`` - This option says to use the PFT values provided on the global dataset rather than using the specific site based values from the PTCLM_sitedata/\*_pftdata.txt file when creating the surface dataset. This option must NOT be used when you you are using a site that is a supported single point dataset. - -``--soilgrid`` - This option says to use the soil values provided on the global dataset rather than using the specific site based values from the PTCLM_sitedata/\*_soildata.txt file when creating the surface dataset. This option must NOT be used when you you are using a site that is a supported single point dataset. - diff --git a/doc/source/users_guide/running-single-points/single-point-and-regional-grid-configurations.rst b/doc/source/users_guide/running-single-points/single-point-and-regional-grid-configurations.rst index 34a199ebe8..0edc07f187 100644 --- a/doc/source/users_guide/running-single-points/single-point-and-regional-grid-configurations.rst +++ b/doc/source/users_guide/running-single-points/single-point-and-regional-grid-configurations.rst @@ -16,11 +16,6 @@ There are three different ways to do this for normal-supported site ``CLM_USRDAT_NAME`` runs using your own datasets (single-point or regional). -``PTCLMmkdata`` - easily setup simulations to run for tower sites.. - -.. note:: ``PTS_MODE`` and ``PTCLMmkdata`` only works for a single point, while the other two options can also work for regional datasets as well. - .. _options-for-single-points: ========================================= @@ -33,7 +28,5 @@ In general :ref:`pts_mode` is the quick and dirty method that gets you started w Next, ``CLM_USRDAT_NAME`` is the best way to setup cases quickly where you have to create your own datasets (see :ref:`running-single-point-datasets`). With this method you don't have to change DATM or add files to the XML database -- but you have to follow a strict naming convention for files. However, once the files are named and in the proper location, you can easily setup new cases that use these datasets. This is good for treating all the required datasets as a "group" and for a particular model version. For advanced CLM developers who need to track dataset changes with different model versions you would be best off adding these datasets as supported datasets with the "normal supported datasets" method. -Lastly *PTCLMmkdata* is a great way to easily create datasets, setup simulations and run simulations for tower sites. It takes advantage of both normal supported site functionality and CLM_USRDAT_NAME internally. A big advantage to it, is that it's one-stop shopping, it runs tools to create datasets, and runs **create_newcase** and sets the appropriate env variables for you. So you only have to learn how to run one tool, rather than work with many different ones. PTCLMmkdata is described in the next chapter, :ref:`running-PTCLM`. - -Finally, if you also have meteorology data that you want to force your CLM simulations with you'll need to setup cases as described in :ref:`creating-your-own-singlepoint-dataset`. You'll need to create CLM datasets either according to ``CLM_USRDAT_NAME``. You may also need to modify DATM to use your forcing data. And you'll need to change your forcing data to be in a format that DATM can use. :ref:`converting-ameriflux-for-ptclmmkdata` tells you how to use AmeriFlux data for atmospheric forcing. +Finally, if you also have meteorology data that you want to force your CLM simulations with you'll need to setup cases as described in :ref:`creating-your-own-singlepoint-dataset`. You'll need to create CLM datasets either according to ``CLM_USRDAT_NAME``. You may also need to modify DATM to use your forcing data. And you'll need to change your forcing data to be in a format that DATM can use. diff --git a/doc/source/users_guide/testing/testing.rst b/doc/source/users_guide/testing/testing.rst index bad1183fff..ab51931aa7 100644 --- a/doc/source/users_guide/testing/testing.rst +++ b/doc/source/users_guide/testing/testing.rst @@ -42,14 +42,3 @@ If something went wrong, you can find the failing tests like so: :: > grep -E "^[0-9]+/[0-9]+ < [a-zA-Z]+" namelist_test.log | grep -v "PASS" - -Testing PTCLM -============= - -.. include:: ../../../../tools/PTCLM/README - :literal: - -To run on cheyenne, you do the following: - -.. include:: ../../../../tools/PTCLM/test/README.run_cheyenne - :literal: diff --git a/doc/source/users_guide/using-clm-tools/observational-sites-datasets.rst b/doc/source/users_guide/using-clm-tools/observational-sites-datasets.rst index 50a7969281..05fe461db2 100644 --- a/doc/source/users_guide/using-clm-tools/observational-sites-datasets.rst +++ b/doc/source/users_guide/using-clm-tools/observational-sites-datasets.rst @@ -6,6 +6,6 @@ Observational Sites Datasets ******************************* -There are two ways to customize datasets for a particular observational site. The first is to customize the input to the tools that create the dataset, and the second is to overwrite the default data after you've created a given dataset. Depending on the tool it might be easier to do it one way or the other. In Table :numref:`reqd-files-table` we list the files that are most likely to be customized and the way they might be customized. Of those files, the ones you are most likely to customize are: ``fatmlndfrc``, ``fsurdat``, ``faerdep`` (for DATM), and ``stream_fldfilename_ndep``. Note ``mksurfdata_esmf`` as documented previously has options to overwrite the vegetation and soil types. For more information on this also see :ref:`creating-your-own-singlepoint-dataset`. ``PTCLM`` uses these methods to customize datasets; see Chapter :numref:`running-PTCLM`. +There are two ways to customize datasets for a particular observational site. The first is to customize the input to the tools that create the dataset, and the second is to overwrite the default data after you've created a given dataset. Depending on the tool it might be easier to do it one way or the other. In Table :numref:`reqd-files-table` we list the files that are most likely to be customized and the way they might be customized. Of those files, the ones you are most likely to customize are: ``fatmlndfrc``, ``fsurdat``, ``faerdep`` (for DATM), and ``stream_fldfilename_ndep``. Note ``mksurfdata_esmf`` as documented previously has options to overwrite the vegetation and soil types. For more information on this also see :ref:`creating-your-own-singlepoint-dataset`. -Another aspect of customizing your input datasets is customizing the input atmospheric forcing datasets; see :ref:`creating-your-own-singlepoint-dataset` for more information on this. :ref:`converting-ameriflux-for-ptclmmkdata` has information on using the AmeriFlux tower site data as atmospheric forcing. +Another aspect of customizing your input datasets is customizing the input atmospheric forcing datasets; see :ref:`creating-your-own-singlepoint-dataset` for more information on this.