This document describes how to build CAM-readable SST and sea ice
concentration boundary datasets at an arbitrary resolution.  Two
Fortran-based executables are required to complete the process.  The first
(regrid) area averages or linearly interpolates input data to a target grid.
The second (bcgen) computes a climatology and modifies monthly mean values to
produce mid-month values such that linear time interpolation (e.g. as done in
a model) will reproduce the monthly means.  Algorithms devised by Karl Taylor
of PCMDI are used to accomplish these tasks.  His descriptions of these
algorithms are included as Fortran comments in the file bcgen/bcgen.f90.  The
final product is two boundary condition netcdf files suitable for input to
CAM.  One contains climatological mid-month SST values and ice
concentrations, and the other a multi-year time series of mid-month values of
these quantities.

Two netcdf files containing SST and sea ice concentration data, respectively,
are required input to start the process.  The data are on a one-degree grid,
and were created by Jim Hurrell and Dennis Shea of NCAR's Climate Analysis
Section.  These input data contain monthly averaged values for some number of
years.  Values over land are interpolated, so no land mask is required.

The codes have been tested on Linux, AIX, and IRIX systems.  In addition to
an f90 compiler (pgf90 or lf95 on a PC) and gnumake, it is assumed that the
netcdf library is available.  If netcdf does not live in the default
location of /usr/local, gnumake macros LIB_NETCDF (for libnetcdf.a) and
INC_NETCDF (for netcdf.inc) need to be set either in the Makefile directly
or as environment variables.

An example session containing the commands needed to build a T5 dataset on a
Linux PC are given next, followed by a description of what each of the
commands does.  On Linux systems, lf95 is the default compiler.  pgf90 can
also be used.  To do so, set USER_FC=pgf90, and change the definition of r16
in regrid/precision.f90 to selected_real_kind(12).  The latter change is
needed because pgf90 does not allow a real*16 data type.

gmake
cd regrid
./regrid -i MODEL.had+oiv2.ice.mnly.49-01.unf.nc \
         -s MODEL.had+oiv2.sst.mnly.49-01.unf.nc \
         -g /fs/cgd/csm/inputdata/atm/cam/coords/gauss_8x16.nc \
         -o sstice.nc
cd ../bcgen
ln -s ../regrid/sstice.nc .
./bcgen -i sstice.nc -c sstice_clim.nc -t sstice_ts.nc < namelist

An elaboration on the above steps follows.

The first command (gmake) builds required executables in subdirectories
regrid/ and bcgen/.

The command "./regrid -i ..." converts the 1-degree data to the output
grid.  For resolutions coarser than the 1-degree input, by default the data
are converted using area averaging, and finer resolutions default to linear
interpolation.  These defaults can be overridden via a command-line
argument (-l for linear, -a for area averaging).  If running in verbose
mode (-v included on command line), points with both ice fraction greater
than 50% and SST greater than 6 deg. C are printed.  This is only a
diagnostic and not necessarily an indication of a problem.  After running
regrid, the file sstice.nc (specified by the -o option) will contain SST
and ice concentration data on the grid in the file specified by the -g
command-line option.  The grid file is assumed to contain latitude and
longitude coordinate variables with the names "lat" and "lon" respectively.
If the output is a reduced grid then this file must also contain the
variables "nlon" which contains the number of longitudes at each latitude,
and "rlon" which is a 2D array of the reduced grid longitudes.  It is also
assumed that the centers of the cells at the west edge of the grid are
located on the Greenwich meridian.  In fact only the number of longitudes
will be read from the grid file, and the cell center and edge longitude
values will be computed.

The last step (./bcgen -i ...) creates the climatological mid-month values
and multi-year time series boundary data.  To run this code, first copy or
link sstice.nc into the directory ../bcgen.  The file driver.f90 contains
descriptions of the namelist variables.  An example namelist is provided.
The filepaths of input and output files are given on the command-line since
they are resolution specific, while the variables in the namelist are
relevent to the time samples contained in the raw 1x1 data and are spatial
resolution independent.

In this example, output files sstice_clim.nc and sstice_ts.nc will
contain the CAM-readable boundary condition SSTs (variable SST_cpl) and ice
concentrations (variable ice_cov).  Versions of these variables prior to
modification for retaining the monthly mean via linear interpolation are
included in these files.  The variable names have "_prediddle" appended.

The following explanation of the namelist variables is taken from the
bcgen.f90 file:

!  Namelist details:
!
!    SPECIFY the first and last month and year for period in which 
!        observed monthly mean data will be read. (The first month
!        read must not preceed mon1, iyr1, and the last month must
!        not follow monn, iyrn).  For example:
           
!      mon1rd = 1            !AMIP
!      iyr1rd = 1956         !AMIP

!      monnrd = 8            !AMIP
!      iyrnrd = 2002         !AMIP

!    SPECIFY first and last month and year for entire period that will
!        be treated (i.e., the period of interest plus buffers at ends).
!        Note that the entire period treated should be an integral   
!        number of years.  For example:

!      mon1 = 1            !AMIP
!      iyr1 = 1955         !AMIP

!      monn = 12           !AMIP
!      iyrn = 2003         !AMIP

!     SPECIFY the first and last month and year that will be included in
!         climatological mean.  (This must be an interval within the 
!         observed period).  For example:

!      mon1clm = 1            !AMIP
!      iyr1clm = 1982         !AMIP

!      monnclm = 12           !AMIP
!      iyrnclm = 2001         !AMIP

!     SPECIFY the first and last month and year written to the output 
!         file.  (Try to begin at east a few months after the mon1rd,
!         iyr1rd, and end a few months before monnrd, iyrnrd, to avoid
!         sensitivity to the artificial data outside the observed 
!         period.)  For example:
 
!      mon1out = 1            !AMIP
!      iyr1out = 1956         !AMIP
!      
!      monnout = 6            !AMIP
!      iyrnout = 2002         !AMIP
!               

One important note on the climatological averaging period.  In general the
namelist variables defining it should NOT change from 1982-2001.  The code
checks for this and errors out if the values are set inappropriately.  It
also prints a message explaining how to change the climatological averaging
period if the user really wishes to do so.


History:

2003-04-16 Jim Rosinski  
Original version

2005-05-25 Brian Eaton
1. The regrid program was modified to read the grid from a file that is
   separate from the file that the output data is written to.  Previously
   the regrid procedure required an extra step to create a template file
   that contained the grid which was then modified by adding the regridded
   sst/ice data.

2. A timestamp was added to the history attribute written to output files
   produced by the regrid program.

3. The bcgen program was modified so that the input and output filename are
   specified on the command-line rather than in a namelist file.

4. A history attribute was added to files produced by the bcgen program.
   This contains the history from the regrid program since the output file
   from that program is the input to this one.  The final output files now
   contain a complete history of the files used to produce them, along with
   timestamps for when the programs were run.

2006-04-18 B. Eaton

1. regrid/regrid.f90 was modified to check the units attribute of the time
   variable to determine if the 1x1 data uses a new or old style time
   coordinate (added wrap_nf_get_att_text method to wrap_nf.f90).  If old
   style (units = 'YYYYMMDD') then the date info is contained in the time
   variable, and if new style (units = 'days since ...') then the date info
   is contained in the date variable.

2. bcgen/solver.f90 was modified by replacing nmont by nmax, and setting
   nmax to 12*250.  This was done to accomodate the new boundary datasets
   which begin in 1870 rather than 1949.
