diff --git a/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst b/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst index 95e0333d6d..a397834c2b 100644 --- a/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst +++ b/doc/source/users_guide/using-clm-tools/building-the-clm-tools.rst @@ -4,96 +4,9 @@ .. include:: ../substitutions.rst -The CLM FORTRAN tools all have similar makefiles, and similar options for building. The tools **cprnc** and **gen_domain** use the CIME configure/build system which is described in the next section. +The tools **cprnc** and **gen_domain** use the CIME configure/build system which is described in the next section. -The Makefiles (for **mksurfdata_esmf** and **mkprocdata_map**) use GNU Make extensions and thus require that you use GNU make to use them. They also auto detect the type of platform you are on, using "uname -s" and set the compiler, compiler flags and such accordingly. There are also environment variables that can be set to set things that must be customized. All the tools use NetCDF and hence require the path to the NetCDF libraries and include files. On some platforms (such as Linux) multiple compilers can be used, and hence there are env variables that can be set to change the FORTRAN and/or "C" compilers used. The tools also allow finer control, by also allowing the user to add compiler flags they choose, for both FORTRAN and "C", as well as picking the compiler, linker and and add linker options. Finally the tools allow you to turn optimization on (which is off by default but on for **mksurfdata_esmf**) with the OPT flag so that the tool will run faster. - -Options used by all: **mksurfdata_esmf** - -- ``LIB_NETCDF`` -- sets the location of the NetCDF library. -- ``INC_NETCDF`` -- sets the location of the NetCDF include files. -- ``USER_FC`` -- sets the name of the FORTRAN compiler. - -Options used by: **mkprocdata_map**, and **mksurfdata_esmf** - -- ``MOD_NETCDF`` -- sets the location of the NetCDF FORTRAN module. -- ``USER_LINKER`` -- sets the name of the linker to use. -- ``USER_CPPDEFS`` -- adds any CPP defines to use. -- ``USER_CFLAGS`` -- add any "C" compiler flags to use. -- ``USER_FFLAGS`` -- add any FORTRAN compiler flags to use. -- ``USER_LDFLAGS`` -- add any linker flags to use. -- ``USER_CC`` -- sets the name of the "C" compiler to use. -- ``OPT`` -- set to TRUE to compile the code optimized (TRUE or FALSE) -- ``SMP`` -- set to TRUE to turn on shared memory parallelism (i.e. OpenMP) (TRUE or FALSE) -- ``Filepath`` -- list of directories to build source code from. -- ``Srcfiles`` -- list of source code filenames to build executable from. -- ``Makefile`` -- customized makefile options for this particular tool. -- ``mkDepends`` -- figure out dependencies between source files, so make can compile in order.. -- ``Makefile.common`` -- General tool Makefile that should be the same between all tools. - -More details on each environment variable. - -``LIB_NETCDF`` - This variable sets the path to the NetCDF library file (``libnetcdf.a``). If not set it defaults to ``/usr/local/lib``. In order to use the tools you need to build the NetCDF library and be able to link to it. In order to build the model with a particular compiler you may have to compile the NetCDF library with the same compiler (or at least a compatible one). - -``INC_NETCDF`` - This variable sets the path to the NetCDF include directory (in order to find the include file ``netcdf.inc``). if not set it defaults to ``/usr/local/include``. - -``MOD_NETCDF`` - This variable sets the path to the NetCDF module directory (in order to find the NetCDF FORTRAN-90 module file when NetCDF is used with a FORTRAN-90 **use statement**. When not set it defaults to the ``LIB_NETCDF`` value. - -``USER_FC`` - This variable sets the command name to the FORTRAN-90 compiler to use when compiling the tool. The default compiler to use depends on the platform. And for example, on the AIX platform this variable is NOT used - -``USER_LINKER`` - This variable sets the command name to the linker to use when linking the object files from the compiler together to build the executable. By default this is set to the value of the FORTRAN-90 compiler used to compile the source code. - -``USER_CPPDEFS`` - This variable adds additional optional values to define for the C preprocessor. Normally, there is no reason to do this as there are very few CPP tokens in the CLM tools. However, if you modify the tools there may be a reason to define new CPP tokens. - -``USER_CC`` - This variable sets the command name to the "C" compiler to use when compiling the tool. The default compiler to use depends on the platform. And for example, on the AIX platform this variable is NOT used - -``USER_CFLAGS`` - This variable adds additional compiler options for the "C" compiler to use when compiling the tool. By default the compiler options are picked according to the platform and compiler that will be used. - -``USER_FFLAGS`` - This variable adds additional compiler options for the FORTRAN-90 compiler to use when compiling the tool. By default the compiler options are picked according to the platform and compiler that will be used. - -``USER_LDFLAGS`` - This variable adds additional options to the linker that will be used when linking the object files into the executable. By default the linker options are picked according to the platform and compiler that is used. - -``SMP`` - This variable flags if shared memory parallelism (using OpenMP) should be used when compiling the tool. It can be set to either TRUE or FALSE, by default it is set to FALSE, so shared memory parallelism is NOT used. When set to TRUE you can set the number of threads by using the OMP_NUM_THREADS environment variable. Normally, the most you would set this to would be to the number of on-node CPU processors. Turning this on should make the tool run much faster. - -.. warning:: Note, that depending on the compiler answers may be different when SMP is activated. - -``OPT`` - This variable flags if compiler optimization should be used when compiling the tool. It can be set to either ``TRUE`` or ``FALSE``, by default it is set to for both **mksurfdata_esmf** and **mkprocdata_map**. Turning this on should make the tool run much faster. - -.. warning:: Note, you should expect that answers will be different when ``OPT`` is activated. - -``Filepath`` - All of the tools are stand-alone and don't need any outside code to operate. The Filepath is the list of directories needed to compile and hence is always simply "." the current directory. Several tools use copies of code outside their directory that is in the CESM distribution (either ``csm_share`` code or CLM source code). - -``Srcfiles`` - The ``Srcfiles`` lists the filenames of the source code to use when building the tool. - -``Makefile`` - The ``Makefile`` is the custom GNU Makefile for this particular tool. It will customize the ``EXENAME`` and the optimization settings for this particular tool. - -``Makefile.common`` - The ``Makefile.common`` is the copy of the general GNU Makefile for all the CLM tools. This file should be identical between the different tools. This file has different sections of compiler options for different Operating Systems and compilers. - -``mkDepends`` - The ``mkDepends`` is the copy of the perl script used by the ``Makefile.common`` to figure out the dependencies between the source files so that it can compile in the necessary order. This file should be identical between the different tools. - -.. note:: There are several files that are copies of the original files. By having copies the tools can all be made stand-alone, but any changes to the originals will have to be put into the tool directories as well. - -The *README.filecopies* (which can be found in ``$CTSMROOT/tools``) is repeated here. - -.. include:: ../../../../tools/README.filecopies - :literal: +The only CLM FORTRAN tool is mksurfdata_esmf which has it's own build system that takes advantage of the cime build. ================================================================ Building the CLM tools that use the CIME configure/build system diff --git a/doc/source/users_guide/using-clm-tools/what-are-the-clm-tools.rst b/doc/source/users_guide/using-clm-tools/what-are-the-clm-tools.rst index 664e23a220..4778294df9 100644 --- a/doc/source/users_guide/using-clm-tools/what-are-the-clm-tools.rst +++ b/doc/source/users_guide/using-clm-tools/what-are-the-clm-tools.rst @@ -18,15 +18,13 @@ The list of generally important scripts and programs are as follows. #. *mksurfdata_esmf* to create surface datasets from grid datasets (clm4_0 and |version| versions). -#. *./mkprocdata_map* to interpolate output unstructured grids (such as the CAM HOMME dy-core "ne" grids like ne30np4) into a 2D regular lat/long grid format that can be plotted easily. Can be used by either clm4_0 or |version|. - #. *$CIMEROOT/tools/mapping/gen_domain_files/gen_domain* to create a domain file for datm from a mapping file. The domain file is then used by BOTH datm AND CLM to define the grid and land-mask. #. *$CIMEROOT/tools/cprnc* to compare two NetCDF files. In the sections to come we will go into detailed description of how to use each of these tools in turn. First, however we will discuss the common environment variables and options that are used by all of the FORTRAN tools. Second, we go over the outline of the entire file creation process for all input files needed by CLM for a new resolution, then we turn to each tool. In the last section we will discuss how to customize files for particular observational sites. -The FORTRAN tools (mksurfdata_esmf and mkprocdata_map) run, with a namelist (mksurfdata_esmf) to provide options, or with command line arguments (mkprocdata_map). +The FORTRAN tool (mksurfdata_esmf) runs, with a namelist and has a namelist builder for it. In the following sections, we will outline how to make these files available for build-namelist so that you can easily create simulations that include them. In the chapter on single-point and regional datasets we also give an alternative way to enter new datasets without having to edit files. @@ -39,29 +37,13 @@ Running FORTRAN tools with namelists ./program < namelist -There is a sample namelist called ``$CTSMROOT/tools/mksurfdata_esmf/mksurfdata_esmf.namleist`` that shows you what the namelist should look like. **mksurfdata_esmf** also has a script that creates the namelist and runs the program for you. Namelists that you create should be similar to the example namelist. The namelist values are also documented along with the other namelists in the: +**mksurfdata_esmf** also has a script that creates the namelist and runs the program for you. The namelist values are also documented along with the other namelists in the: :: - $CTSMROOT/bld/namelist_files/namelist_definition.xml`` file - and default values in the: - $CTSMROOT/bld/namelist_files/namelist_defaults_clm_tools.xml`` file. + $CTSMROOT/tools/mksurfdata_esmf/gen_mksurfdata_namelist.xml`` file ----------------------------------------------- Running FORTRAN tools with command line options ----------------------------------------------- -**gen_domain**, mkprocdata_map, and **cprnc** run with command line arguments. The detailed sections below will give you more information on the command line arguments specific to each tool. Also running the tool without any arguments will give you a general synopsis on how to run the tool. - ------------------------------------------ -Running FORTRAN tools built with SMP=TRUE ------------------------------------------ - -When you enable ``SMP=TRUE`` on your build of one of the tools that make use of it, you are using OpenMP for shared memory parallelism (SMP). In SMP loops are run in parallel with different threads run on different processors all of which access the same memory (called on-node). Thus you can only usefully run up to the number of processors that are available on a single-node of the machine you are running on. For example, on the NCAR machine cheyenne there are 36 processors per node, so you can use up to 36 processors. - -.. _using-ncl: - ---------- -Using NCL ---------- - -In the tools directory ``$CTSMROOT/tools/ncl_scripts`` and in a few other locations there are scripts that use NCAR Command Language (NCL). Unlike the FORTRAN tools, you will need to get a copy of NCL in order to use them. You also won't have to build an executable in order to use them, hence no Makefile is provided. NCL is provided for free download as either binaries or source code from: `http://www.ncl.ucar.edu/ `_. The NCL web-site also contains documentation on NCL and it's use. These scripts are stand-alone and at most use environment variables to control how to use them. In some cases there are perl scripts with command line arguments that call the NCL scripts to control what they do. +**gen_domain** and **cprnc** run with command line arguments. The detailed sections below will give you more information on the command line arguments specific to each tool. Also running the tool without any arguments will give you a general synopsis on how to run the tool.