CESM Models

CESM Models: What's New in Release 1.4.0 of the NCAR CSM Ocean Model (NCOM)



Many of the changes to the NCAR CSM ocean model are functional, rather than physical or numerical, and include:


Other NCOM changes, of a physical and numerical nature, include:

New Directory Organization and Resolution Naming Conventions

Directories and files have been reorganized in NCOM version 1.4.0. The parent directory, ncom1.4.0, now contains source code and resolution-dependent subdirectories, and the scripts directory is now a subdirectory of ncom1.4.0. The netcdf filter directory has been eliminated entirely, because it is now possible to generate netcdf-format files directly from NCOM during model execution.

All references to model resolutions which previously were embedded in the code are now separated out into resolution-dependent directories. The directory "102x74x25" contains all Fortran code related to the resolution formerly referred to as the "3x3" or simply the "x3"; the directory "152x111x45" contains everything related to the old "2x2" or "x2" resolution. There are also two new resolution-dependent directories: the "102x116x25", which contains code for the resolution we sometimes refer to as the "x3 '", and the "152x173x45" , or "x2 '".

Within each resolution-dependent subdirectory, the user will find a copy of the file param_dims.h, which contains all resolution- dependent parameter statements; this file is included in the main- directory file, param.h. Similarly, the new file, blkdta.h, which contains all resolution-dependent data statements, is included in the main-directory file, blkdta.F.

Namelist input files now reside in the Namelists subdirectory found in each of the resolution directories ("102x74x25", etc). Copies of namelist eddy, which may contain different values for the stand-alone and coupled-model versions, sit in the subdirectories Namelists/Coupled and Namelists/Stand_Alone.

All major new model features such as river runoff, sigma coordinates, co2 and carbon 14 passive tracers, etc, will appear in special subdirectories of the ncom1.4.0 main directory after futher testing and development.

[back to contents]

History Files in NetCDF Format

The NCOM user can now select from the following history-file options and file formats by selecting the corresponding Cpp options:

instantaneous AND/OR time-averaged fields

netCDF OR native binary output file format

The portions of NCOM code devoted to history-file writing have been changed considerably.

Recall that in NCOM 1.3, the slab-wise time-averaged history variables are accumulated in 3-D arrays, whereas the instantaneous history variables are written slab-wise, directly from subroutine step.

For netCDF efficiency, the slab-wise instantaneous history variables should be written as three-dimensional arrays. Although it is unnecessary to do so in the native-binary instantaneous option, the NCOM code, for consistency, is now designed to store all time-average or instantaneous slab-wise history variables in 3-D arrays, then write the full arrays in either binary or netCDF format.

If the user selects -Dinst_hist, the model memory requirement is increased from NCOM 1.3 by approximately (3+nt) 3-D arrays for cases without isopycnal mixing, and (6+nt) 3-D arrays for those with isopycnal mixing, where nt is the number of passive tracers (default is 2). If the user selects -Dtime_average, the model memory requirement is only slightly greater than that in NCOM 1.3 with the same option, because a few new 2-D arrays have been added.

All NCOM history variables are now written to a single, large history file. The large size of the history file may pose difficulties for some users (26Mb for the 152x111x45 resolution). For binary files, it is a relatively simple matter to modify the bin_write_avg and bin_write_inst subroutines in file bin_util.F to split the file into a few smaller files. For the netcdf files, it is still possible to split the files, but it may require a bit more effort from the user (see file nc_util.F). In either case, the user must also add calls to subroutine dump for each new history output file s/he creates.

Several new time-average fields have been added to the NCOM history files. [details]

[back to contents]

Other History File Formats

The NCOM developers recognize that netCDF may not be the file-format of choice for all NCOM users. The development of code to write history files in other formats is straightforward, but time-consuming. The NCOM developers would welcome the contribution of the alternate format equivalents of nc_util.F.

[back to contents]

Regionmask Changes

The horizontal regionmask files have been changed in many minor ways. First, the generic "Marginal Seas" category, which had been assigned region 7 in NCOM 1.3, has been expanded, with each marginal sea now individually identified.

Also, each region is now identified according to the following scheme:

Regionmask Value Identified Region
< 0 Marginal Sea
= 0 Land
> 0 Active Ocean

Finally, the format of the regionmask file has been changed, in order to allow for signed integers with absolute values ranging from 0 to 99; thus the formats in reg1st.F have been changed accordingly.

For computational convenience, a second regionmask, rmaska, is defined for use in those instances in which only the absolute value of the regionmask is required. This regionmask is defined internally, so the user needn't be concerned with it, although s/he should be aware that this regionmask is also written to the netcdf file, for use by plotting programs which do not easily handle the signed-integer regionmask file.

[back to contents]

Strong-Restoring Regions

Earlier versions of the stand-alone NCOM allowed the option of restoring surface temperature and salinity to reference values in the Mediterranean (via the obsolete Cpp option, restormed). In the stand-alone NCOM 1.4, users can specify any region for which strong restoring is to be in effect.

A new namelist, regsr, has been added, which contains two new variables. The first, n_strong_restore, is the number of strong-restoring basins; the second,strong_restore_names, is an array of the basin names in which strong restoring is to be applied (typically marginal seas).

After the strong-restoring information is read into NCOM, a new mask, mskhr_sr, is defined in subroutine make_mskhr_sr (in reg1st.F). This new mask is then used in subroutine sflx_create_weights (sfkx.F) to set the restoring weights to their proper values.

[back to contents]

C Preprocessor Options

IMPORTANT NOTE: NCOM users should never define a Cpp option name which is identical to an NCOM variable, subroutine, or common-block name; doing so causes the substitution of the number "1" for the name whenever that Cpp option is enabled and the Cray f90 -F flag is used.

List of Deleted C Preprocessor Options

C Preprocessor Option Name Definition Replacement
kmixnori Use background values of vertical viscosity and diffusivity below the boundary layer. Algorithm has been changed; see subroutine ri_iwmix in the file kmixs.F
Obsolete reference to model resolution Model resolution is now selected via the job script by the user. The script automatically selects the resolution-dependent versions of parameter, block-data, and input files.
restormed Restore sea-surface temperature and salinity back to specified values in the Mediterranean Sea region Use the more general method of defining strong-restoring regions in the input file regsr.


List of New C Preprocessor Options

C Preprocessor Option Name Definition
inst_hist Creates instantaneous history files
netcdf Creates history files in netcdf file format; defaults to files in native-binary format.
HP Invokes HP optimization directives
NOMSS Indicates the NCAR mass-storage system is unavailable or not to be used; restart and history files are instead mv'd to a permanent filename created from input values and the model date.
SX4 Invokes SX4 optimization directives and SX4-specific code
  • "task common"
  • "local common"
  • "common"
Replace each instance of TASKCOMMON with:
  • "task common" (CRAY and HP platforms)
  • "local common" (SX4)
  • "common" (SGI and others)
co2 Selects carbon dioxide passive tracer; presently under development
c14 Selects carbon 14 passive tracer; presently under development
ideal_age Selects ideal-age passive tracer
runoff Distributes river runoff from land model to the ocean (a coupled-model option); presently under development
sigma Use sigma vertical coordinates; presently under development

[back to contents]

Obsolete Logical Control Switches

Logical Variable Name Input or Internally Computed Definition
Internal Timestep for archiving various history ("H") files.
Replaced by h_dump
Internal Timestep for writing various history ("H") files.
Replaced by h_write
ltime_avg_dump Internal Timestep for computing time-averaged quantities and archiving the time-averaged history file
Replaced by h_dump and other logic
time_averages Internal Timestep to control the "H4" history file
Replaced by h_write and other logic


Renamed Logical Control Switches

Old Logical Variable Name Input or Internally Computed New Logical Variable Name
wrt_history_at_eod Internal write_at_eod_history
wrt_restrt_at_eod Internal write_at_eod_history


New Logical Control Switches

Logical Variable Name Input or Internally Computed Definition .TRUE. Indicates:
h_write Internal Timestep for writing history file.
Replaces lwrth1,2,3,4.
h_dump Internal Timestep for archiving history file.
Replaces ldmph1,2,3,4.
mixtsp1 Internal Timestep aftera mixing timestep.
read_binary_mask Input (namelist contrl) Read binary-format regionmask; otherwise, read ascii-format regionmask.
sample_qflux_ts Internal Timetep for sampling qflux for time-averaging.
write_at_mom Input Timestep is at the middle of the month, and history files should be both written and archived this timestep.
Presently, this option is only valid with the time_average option.
write_ta_eng Internal If, when time-averaging, it is permissible to write engint, engext, ekt, plicin, plicex to the history file.
If these quantities have not been properly sampled, they will not be written.

[back to contents]

Modifications for SGI,HP, and SX4

The SGI, HP, and SX4 modifications to NCOM were implemented in order to extend the range of architectures on which NCOM will compile and execute. These modifications were developed by John Dennis of NCAR's Scientific Computing facility, David Parks, formerly of NEC, and others. These are preliminary, but necessary, steps towards improving NCOM portability to these platforms.

See the definition of the three C-preprocessor options related to SGI/HP/SX4 platforms under the "C Preprocessor Options" heading (TASKCOMMON, HP, and SX4).

The NCOM 1.4 makefiles have been modified to include the "-F" flag on the Fortran 90 compiler statement, which enables the macro expansion of TASKCOMMON.

[back to contents]

Makefile and Job Script

The job scripts for NCOM 1.4.0 are quite similar to version 1.3. A test on the architecture (ARCH) is performed in the new job scripts, permitting the selection of the proper local (ie, NCAR) mpi library path. Users at other sites should modify this library path appropriately.

The new job scripts also define INCLDIR, in the file Include, which defines the location of the netcdf library include files. INCLDIR is then used within the makefile, Makefile.F90.

[back to contents]

Enhanced Merridional Resolution at the Equator

Two new model resolutions have been added to NCOM 1.4.0, both with enhanced merridional resolution near the Equator, but otherwise similar to the standard 3° (102x74x25) and 2° (152x111x45) resolutions.

The new 3° and 2° resolution-dependent code, parameters, and input are found in the ncom1.4.0/102x116x45 and ncom1.4.0/152x173x45 directories, respectively.

In order to select a given model resolution, the user sets the OCNRES variable in the job script (ocn.setup.csh for coupled integrations and stand-alone.csh for stand-alone).

[back to contents]

Spatially Varying Viscosity Formulation

A spatially varying eddy viscosity was developed for use with the enhanced merridional resolutions. This option is enabled by setting the new namelist eddy variable, am_xy_constant = .false. Please refer to the NCOM 1.4.0 file create_am_xy.F for full details.

By default, am_xy_constant = .true. in the 102x74x25 and 152x111x45 resolutions, and am_xy_constant = .false. in the 102x116x25 and 152x173x45 resolutions.

[back to contents]

Vertical Smoothing in KPP

The KPP subroutine ri_iwmix in the file kmixs.F was reformulated by William Large in December, 1997, and now includes vertical smoothing of the Richardson number. See kmixs.F for details.

[back to contents]