ashao/fre-nctools

Tools for manipulating and creating netCDF inputs for FMS managed models

FRE-NCtools

FRE NCtools are a collection of tools to help with the creation and mamnipulation of netCDF files used or written out by the climate models developed at the Geophysical Fluid Dynamics Laboratory (GFDL). These tools were primarally written by members of the GFDL Modeling Systems Group to be used in the Flexible Modeling System (FMS) Runtime Environment (FRE).

Tools

The tools available in FRE-NCtools are:

• combine_blobs --
• combine_restarts -- Combine restart files generated by a FMS enabled model
• iceberg_comb -- Combine iceberg history files
• combine-ncc -- Combine distributed unstructured FMS grid netCDF files
• decompress-ncc -- Convert an unstructured FMS grid file to a standard lat-lon grid
• scatter-ncc -- Distribute an unstructured FMS grid netCDF file for initializing a FMS climate model
• is-compressed -- Determine if a netCDF file has an unstructured FMS grid
• list_ncvars -- List the variables in a netCDF file
• mppnccombine -- Combine destributed FMS netCDF files
• plevel -- Interpolates data from model levels to pressure levels
• split_ncvars -- Write the variables in a FMS netCDF file into multiple netCDF files, one file per netCDf field
• timavg -- Create a time average netCDF file
• check_mask
• fregrid -- Convert from one grid resolution to another
• make_coupler_mosaic
• make_hgrid
• make_land_domain
• make_quick_mosaic
• make_regional_mosaic
• make_solo_mosaic
• make_topog
• make_vgrid
• mppncscatter -- Distribute FMS netCDF file for initializing a FMS climate model
• ncexists
• remap_land
• river_regrid
• runoff_regrid
• transfer_to_mosaic_grid

Install

FRE NCtools is configured to be built with a modern version of the Intel C and Fortran compilers. Using other compilers (GCC/GFortran) should be possible, but is not tested by the Modeling Systems group at GFDL and will require the creating of Makefiles for the chosen compiler.

The script fre-nctools-make-package is used to build and install FRE-NCtools. This script will use a set of site configuration files found in the site-configs directory. Each site will have a directory with the same name as the site (e.g. site-configs/ncrc4 contains the files required to build fre-nctools on the ncrc4 site). In each site directory are two required files: env.sh and build.mk which contain the instructions to setup the build environment and compile/link options for the site respectively. The env.sh file contains the bash commands required to modify the environment to find the compiler, and required librarys for the build. The build.mk file contains several make macros to allow the compiler and linker to know where certain libraries (namely the netCDF C and Fortran libraries). The make macros that can be modified in the build.mk site are:

# Macros to override the compiler
FC := # Fortran Compiler
CC := # C Compiler
MPICC := # C Compiler for building MPI applications

# Macros to add additional include paths or CPP/FPP Macros to the compiler
CFLAGS_SITE :=
FFLAGS_SITE :=

# Macros to add additional library paths to the linker
CLIBS_SITE :=
FLIBS_SITE :=

# Path to the installation of NetCDF and HDF5 libraries
NETCDF_HOME :=
HDF5_HOME :=

# Macro to pass the static link option to the compiler
# If blank, then the executables will be dynamically linked
STATIC :=

# NOPARALLEL controls if some tools also build the parallel (MPI) version of the
# executable.  If NOPARALLEL is non-blank, then the parallel version will not be
# built.
NOPARALLEL :=

To build and install the fre-nctools package, run the fre-nctools-make-package script with following syntax:

fre-nctools-make-package -s <site> <package_name>

where <site> is the name of the site directory in the site-configs directory, and <package_name> is a string that describes something about the build. The Modeling System groups uses the string to describe the FRE version of the build (e.g. bronx-11, bronx-12). Run the fre-nctools-make-packate with the -h option to see more options.

The fre-nctools-make-package script will perform each build in a separate build.fre-nctools.<site>.<package_name>.XXXXX directory, where <site> and <package_name> are the same as defined on the command line, and XXXXX are randomly generated alpha-numeric characters.

The script will copy the site configuration files env.sh and build.mk files into the build directory, along with a master Makefile and will then call make (unless the -n option is given on the command line).

If the build is successful, fre-nctools-make-package will then run make install to install executables, and scripts into a sub-directory <package_name> in the build directory. The location to install the package can be modified with the -P <prefix> option. Using this option will install the package to <prefix>/<package_name>.

Install Documentation

Some of the commands have man pages. To install these man pages, run fre-nctools-make-package with the -d option (or enter the build directory and run make install-docs. To build the documentation, the command ASCIIdoc to Docbook command a2x must be availabe on the system.