CCSM3.0 Parallel Ocean Program (POP)
User Guide

A Modified Version of the POP User's Guide
Original LANL Version Information:
Version 1.4.3
February 24, 2001
Los Alamos National Laboratory

With documentation of the modifications necessary for the
Community Climate System Model (CCSM3.0 Release of POP
23 June 2004
National Center for Atmospheric Research

Brief Remarks

Manual Contents

Brief Remarks

This manual is a modified version of the official one supplied by LANL for their standard release of POP 1.4.3, with additions that are specific to the CCSM3.0 version of the POP code ("CCSM3 POP").

Topics include:

• How to compile POP, including compile-time options for standard LANL POP and CCSM POP
• How to run POP, including run-time options in namelist input for standard LANL POP and CCSM POP
• Procedures for preparing auxiliary input files that are needed if you are setting up a new grid
• Options for model diagnostics
• Options for model output files and formats for standard LANL POP and CCSM POP

Throughout this manual, it is assumed that the operating system is some variant of Unix. However, POP will run on PCs with Windows NT using the Digital Fortran90 compiler; see Appendix 7.6 for details.

To keep the User Guide as short as possible, other manuals are provided. For the stand-alone LANL POP, the Installation Guide tells how to set up POP on any computer system that supports Fortran90 and, if it is a multi-processor system, MPI or SHMEM; for the CCSM POP, the CCSM3.0 User's Guide provides comparable information. The Scientific Desciption manual is directed toward those users who seek an in-depth understanding of the code, such as would be needed to make changes to the source code. It contains a thorough description of the code, including the model equations, their discretized form, and the numerical methods used for their solution. The principal modules and subroutines are explained, the organization of the code is outlined, and the principal variables are defined. The Code Reference manual is designed to be a reference for users who are interested in modifying CCSM POP code to suit their own research. Presently, the Code Reference contains streamlined CCSM POP calling tree and a table mapping symbols used in the Scientific Desciption manual to the corresponding variable names used in the CCSM POP code modules.

Whenever POP is run, the version number and release date of the source code on your local system is output at the beginning of the log file (see section 4.2). They should agree with the information on the front cover of this manual (compare standard-release LANL POP release stamp with the LANL version information, the CCSM stamp with the CCSM information.

If you obtained POP directly from LANL, technical support is provided by John Davis (jfd@lanl.gov, 505-667-4793) and Phil Jones (pwjones@lanl.gov, 505-667-6386). If you are using POP as a component of the CCSM, the technical contact is Nancy Norton ( njn01@ucar.edu, 303-497-1363).

We are always interested in learning about your experiences with POP, favorable or otherwise. Send your comments and suggestions for improvements to pop_feedback@acl.lanl.gov. Los Alamos maintains an e-mail-driven database of bug reports at pop_bugs@acl.lanl.gov.

Bug reports on problems specifically related to CCSM extensions or modifications of POP should be e-mailed to ccsm-bugs@cgd.ucar.edu.

Table of Contents

• 1 Introduction
• 1.1 Brief history of POP development
• 1.2 Improvements introduced in POP
• 1.2.1 Surface-pressure formulation of barotropic mode
• 1.2.2 Free-surface boundary condition
• 1.2.3 Latitudinal scaling of horizontal diffusion
• 1.2.4 Pressure-averaging
• 1.2.5 Designed for parallel computers
• 1.2.6 General orthogonal coordinates in horizontal
• 1.2.7 Displaced-pole grid
• 1.3 POP applications to date
• 1.3.1 High-resolution global and regional modeling
• 1.3.2 Coupled models
• 2 Compiling POP
• 2.1 Make procedure
• 2.1.1 CCSM coupled model make procedure
• 2.1.2 Standard LANL stand-alone model make procedure
• 2.2 Compile-time options
• 2.2.1 Model size
• 2.2.2 Processor configuration
• 2.2.3 Implicit vertical mixing
• 2.2.4 Coupled model runs
• 3 Running POP
• 3.1 Operational control
• 3.1.1 Input/Output
• 3.1.2 Time management
• 3.2 Grid and bottom-topography definition
• 3.3 Initializing the model state
• 3.3.1 Temperature and salinity distribution
• 3.3.1.1 LANL POP init_ts_options
• 3.3.1.2 CCSM POP init_ts_options
• 3.3.2 Restart control
• 3.3.2.1 LANL POP restart filenames
• 3.3.2.2 CCSM POP restart filenames
• 3.4 Computational options
• 3.4.1 Barotropic-mode solver
• 3.4.2 Advection methods
• 3.4.3 Pressure-averaging of horizontal pressure gradient
• 3.5 Vertical mixing parameterizations
• 3.5.1 Constant coefficients
• 3.5.2 Richardson-number mixing
• 3.5.3 Convective adjustment
• 3.5.4 KPP mixing
• 3.6 Horizontal mixing parameterizations
• 3.6.1 Gent-McWilliams isopycnal mixing parameterization
• 3.6.2 Anisotropic viscosity
• 3.7 Physical process options
• 3.7.1 Equation of state approximation
• 3.7.2 Baroclinic-mode parameters
• 3.7.3 Sea-ice emulation parameters
• 3.7.4 Topographic stress
• 3.8 Forcing options
• 3.8.1 Periodicity of forcing data
• 3.8.2 Temporal interpolation of forcing data
• 3.8.3 Forcing formulation
• 3.8.3.1 shf_formulation options
• 3.8.3.1.1 sw_absorption options (CCSM only)
• 3.8.3.2 sfwf_formulation options
• 3.8.3.3 {pt,s}_interior_formulation options
• 3.8.4 Forcing files
• 3.8.5 Forcing units
• 3.8.6 Updating the forcing values
• 3.8.7 Forcing modules
• 3.8.8 Forcing namelists
• 3.8.8.1 Windstress
• 3.8.8.2 Surface heat flux
• 3.8.8.2.1 Short-wave absorption (CCSM only)
• 3.8.8.3 Surface fresh water flux
• 3.8.8.4 Atmospheric pressure
• 3.8.8.5 Potential temperature – interior
• 3.8.8.6 Salinity - interior
• 3.9 Forcing options (coupled mode)
• 3.9.1 Partially-coupled option (CCSM POP only)
• 3.10 Input datasets
• 3.10.1 Input datasets for LANL POP
• 3.10.2 Input datasets for CCSM POP
• 3.11 Trouble-shooting
• 3.11.1 Checking the timestep stability criteria
• 3.11.2 Checking the global energy and work balances
• 3.11.3 Getting the right combination of vertical mixing options
• 3.11.4 Getting the right combination of horizontal mixing options
• 3.11.5 Getting the right combination of forcing options
• 3.11.6 Properly normalizing input salinity values
• 3.11.7 Real-time X-window display
• 4 Model diagnostics and output
• 4.1 File-naming conventions
• 4.1.1 LANL POP file-naming convention
• 4.1.2 CCSM POP file-naming convention
• 4.2 Model diagnostics
• 4.2.1 Transport diagnostics
• 4.2.2 Budget diagnostics
• 4.2.3 Meridional overturning and northward tracer transports (CCSM only)
• 4.3 Model output files
• 4.3.1 Time-averaged history files
• 4.3.2 Snapshot history files
• 4.3.3 Snapshot movie files
• 4.3.4 Current meters, drifters and hydrographic sections
• 4.4 Output formats
• 4.4.1 Binary for parallel IO
• 4.4.2 netCDF
• 4.4.2.1 Conversion to netCDF (LANL POP)
• 4.4.2.2 netCDF in CCSM POP
• 4.4.3 Off-line extraction of subsets to netCDF (Standard LANL POP Only)
• 5 Visualizing output
• 5.1 FERRET using netCDF files
• 5.2 VCS using netCDF files
• 5.3 Transformations from DP-grid to Mercator
• 6 References
• 6.1 POP development
• 6.2 POP simulations
• 6.3 Other POP topics
• 6.4 Other references
• 7 Appendices
• 7.1 Ancestry of POP
• 7.2 Generating grid and bottom topography files
• 7.2.1 Horizontal grid
• 7.2.2 Vertical grid
• 7.2.3 Bottom topography
• 7.2.4 Examples
• 7.2.5 Displaced-pole grid details
• 7.2.6 Land-ocean grid incompatibilities in coupled models
• 7.3 Benchmark test problem (LANL POP only)
• 7.4 Performance on selected computers
• 7.5 bin2nc and extract programs (LANL POP only)
• 7.6 Running POP on PCs with Windows NT