CESM Models: What's New in Release 1.4.0 of the NCAR CSM Ocean Model (NCOM)
Introduction
Many of the changes to the NCAR CSM ocean model are functional, rather than physical or numerical, and include:
Contents
- New Directory Organization and Resolution Naming Conventions
- History Files in netCDF Format
- Other History File Formats
- Regionmask Changes
- Strong-Restoring Regions
- C Preprocessor Options
- Logical Control Switches
- Modifications for SGI,HP, and SX4
- Makefile and Job Script
Other NCOM changes, of a physical and numerical nature, include:
- Enhanced Merridional Resolution at the Equator
- Spatially Varying Viscosity Formulation
- Vertical Smoothing in KPP
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.
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
- -Dinst_hist
- -Dtime_average
netCDF OR native binary output file format
- -Dnetcdf (if this option is not set, native binary format is used)
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]
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.
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.
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.
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 |
| model1x1 and model3x3 |
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 |
TASKCOMMON=
|
Replace each instance of TASKCOMMON with:
|
| 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 |
Obsolete Logical Control Switches
| Logical Variable Name | Input or Internally Computed | Definition |
| ldmph1 ldmph2 ldmph3 ldmph4 |
Internal | Timestep for archiving various history ("H") files. Replaced by h_dump |
| lwrth1 lwrth2 lwrth3 lwrth4 |
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. |
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.
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.
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).
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.
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.