In addition to restart files, POP produces many types of output files containing different types of model diagnostics. Each file type is described and the namelist that governs its production is presented.
Return to beginning of Chapter 4
Note: The LANL and CCSM POP naming conventions for output files are different enough from one another that the following discussion is split into two parts. The CCSM POP has been changed so that it does notgenerate LANL-like filenames; it will only generate filenames of the type described in the CCSM POP section. The information about LANL's default naming conventions is included here mainly for comparison purposes.
All output file names created by the standard LANL POP code have the form: root-filename.runid.time-indicator. Here root-filename is a name defined by the user through namelist input for each file type, runid is a character identifier for the run sequence (see section 3.1.2) and the time-indicator depends on the output frequency chosen.
A convention has been developed for naming standard POP output files in which the root filenames for restart, time-averaged history, snapshot history, and movie files are simply the one-letter names 'd', 't', 'h', 'm' respectively. These are the default values in the namelists in section 4.2, but you are not required to follow this convention, of course. The only requirement is that the root-filename must be distinct for each type of output file.
Because '.' is used to delimit runid in file names and '/' is reserved as a separator in Unix path names, neither should be used within runid.
If the output file is written at a frequency of nday, nmonth or nyear, the time-indicator is the date in yyyymmdd (where yyyy, mm and dd can be optionally separated by a character defined in the time manager namelist). If the output file is written every nstep steps, the time-indicator is the step number.
The output file names generated by the CCSM POP code are different from those generated by the standard LANL version, because the CCSM output file names are governed by the CCSM2.0.1 output file-naming conventions. With the default CCSM pop_in namelist settings, the CCSM POP output files are directed to three separate directories, depending on their type: the output log is written into the ocean-model execution directory, while the restart and history files are written into two subdirectories of the execution directory, rest and hist, respectively.
In a format similar to the LANL POP file names, the CCSM POP output filenames are of the following form, where [square brackets] indicate an optional quantity: root_filename/runid.pop.ccsm_type_code1[ccsm_type_code2].date_string[.suffix].
Both root_filename and runid are defined automatically by the CCSM ocean setup script when it modifies the pop_in file. root_filename is the file pathname and runid is required by the CCSM naming conventions to be the same as the CCSM $CASE environment variable name. Note that, unlike the standard LANL conventions, the CCSM conventions allow the character '.' to be embedded in the runid name. The root_filename full pathname must include a subdirectory named "hist", and the CCSM setup script automatically satisfies this requirement. However, if you are using the CCSM POP code without the CCSM ocean setup script, or if you are modifying the setup script, please note this restriction. The CCSM POP code tests to ensure the string "hist" is included in the filename and will print an error message and then stop if the string is not found.
ccsm_type_code1 is one of the CCSM2.0.1-defined single-character type codes ('r', for restart or 'h', for history) or another single character appropriate for the component model ('d', for diagnostic, for example, in the CCSM POP). ccsm_type_code2 is an optional type code to describe other component-specific output files. The optional ccsm_type_code2 values for CCSM POP include 'h' (history), 'm' (movie), 's' (snapshot), 'v' (viscosity), 't' (transport), and 'd' (diagnostics).Note that a single type code of 'h' indicates a time-averaged history file generated from the tavg.F module, but a type code of 'h' followed by any other single character simply means that the file is a generic history file of some other quantity (eg, 'hm' is a 'movie' file, 'hs' is a 'snapshot' file). There are no 'hh' files. A single type code of 'r' indicates a restart file generated by the restart.F module; a type code of 'r' followed by the single character 'h' means the file is a restart file for the time-averaged history file. All files with ccsm_type_code1 values of 'h' are put into the 'hist' subdirectory; all files with ccsm_type_code1 values of 'r' are put into the 'rest' subdirectory.
Presently, the following ccsm_type_code combinations are defined for the ocean model:
| ccsm_type_code combination | file contents | output directory |
|---|---|---|
| 'r' | restart file | rest |
| 'rh' | restart for time-averaged history file | rest |
| 'h' | history file (time-averaged) | hist |
| 'hm' | history movie file | hist |
| 'hs' | history snapshot file | hist |
| 'hv' | history anisotropic horizontal viscosity output | hist |
| 'dd' | diagnostics file (global diagnostics) | hist |
| 'dt' | diagnostics file (transports) | hist |
The ccsm_date_string takes various forms, from which the user can determine the type of time averaging associated with the file contents. The following ccsm_date_strings are defined:
| ccsm_date_string | file contents |
|---|---|
| yyyy-mm-dd-sssss | instantaneous fields |
| yyyy-mm-dd | daily time-averaged fields |
| yyyy-mm | monthly time-averaged fields |
| yyyy | annually time-averaged fields |
Here yyyy is the 4-digit year string, mm is the 2-digit month string, dd is the 2-digit day string, and sssss is the 5-digit string identifying the total number of seconds elapsed during that particular day.
The optional .suffix value is either '.nc', indicating the file contents are in netCDF format (see 4.4.2.2 netCDF in CCSM POP), or '.hdr', indicating an ascii header file containing information about a companion binary-format file whose name does not contain the '.hdr' suffix, but is otherwise identically named.
An example of the various CCSM POP output directories, filenames, and their contents for a test case named "test.a1" that is executing in the directory /ptmp/user follows:
| Example History Filenames | History File Contents |
|---|---|
| /ptmp/user/test.a1/ocn/hist/test.a1.pop.dd.0001-01-06-00000 | history diagnostics timeseries (global) in ascii format for times up to and including the model date 6 January 0001 at 00:00:00 (See Section 4.2) |
| /ptmp/user/test.a1/ocn/hist/test.a1.pop.dt.0001-01-06-00000 | history diagnostics timeseries (transports) in ascii format for times up to and including the model date 6 January 0001 at 00:00:00 (See Section 4.2) |
| /ptmp/user/test.a1/ocn/hist/test.a1.pop.h.0001-01-05.nc | daily time-averaged history fields in netCDF format for the model day 5 January 0001 |
| /ptmp/user/test.a1/ocn/hist/test.a1.pop.hm.0001-01-05 | movie history fields in binary format for the model day 5 January 0001 |
| /ptmp/user/test.a1/ocn/hist/test.a1.pop.hs.0001-01-06-00000 | instantaneous history ("snapshot") fields in binary format written at the model date 6 January 0001 at 00:00:00 |
| /ptmp/user/test.a1/ocn/hist/test.a1.pop.hv | anisotropic horizontal viscosity output in binary format |
| Example Restart Filenames | Restart File Contents |
|---|---|
| /ptmp/user/test.a1/ocn/rest/test.a1.pop.r.0001-01-06-00000 | model restart fields in binary format written at the model date 6 January 0001 at 00:00:00 |
| /ptmp/user/test.a1/ocn/rest/test.a1.pop.rh.0001-01-06-00000 | restart information for the time-averaged history fields in binary format written at the model date 6 January 0001 at 00:00:00 |
Return to beginning of Chapter 4
The progress of a POP simulation is recorded in a 'log file' that is either written to STDOUT or redirected to an optional log file (defined in the io namelist). A new log file should be created at each restart.
The CCSM POP log file is always redirected to a log file; the logfile's name is determined by the CCSM ocean setup script, where the pop_in io_nml string 'OUTPUT/../LOG_FILENAME' is replaced with information received from the CCSM master run script.
Values of the model version number, release date, date and time of the run, input namelist parameters, and initial or restart conditions are documented at the beginning of each log file. At the end of each model day, the CCSM POP model writes a model date stamp to the output log file, in a format identical to that used by the CCSM flux coupler.
Which diagnostics are computed and how often are set by parameters in namelist diagnostics_nml (below). The time-step counter, numerical stability criteria and selected diagnostics are written to the log file at regular intervals. You can monitor this output as the model runs using tail -f log_file to be sure that the model is behaving reasonably. If the model blows up, it is usually because one of the constraints on the time step (see section 3.10.1) was violated; which one can be determined from the stability criteria in the log file.
| &diagnostics_nml | generation of model diagnostics | |
| diag_global_freq_opt | ['never'],'nyear','nmonth','nday','nhour', 'nsecond','nstep'
['nmonth'] (CCSM) |
units of time for 'diag_global_freq' |
| diag_global_freq | [100000] [1] (CCSM) |
how often to compute and print global diagnostics |
| diag_cfl_freq_opt | ['never'],'nyear', 'nmonth', 'nday', 'nhour', 'nsecond','nstep'
['nmonth'] (CCSM) |
units of time for 'diag_cfl_freq' |
| diag_cfl_freq | [100000] [1] (CCSM) |
how often to compute and print CFL stability diagnostics |
| diag_transp_freq_opt | ['never'], 'nyear', 'nmonth', 'nday', 'nhour', 'nsecond','nstep'
['nmonth'] (CCSM) |
units of time for 'diag_transp_freq' |
| diag_transp_freq | no default value [1] (CCSM) |
how often to print transport diagnostics to output log file |
| diag_transport_file | '[unknown_transport_file]' ['INPUT/transport_contents'] |
input filename (with path) describing requested transports |
| diag_outfile | '[unknown_diag_outfile]' ['OUTPUTDd'] (CCSM) |
file to which global and cfl diagnostics are to be written |
| diag_transport_outfile | '[unknown_transport_outfile]' ['OUTPUTDt'] (CCSM) |
file to which transport diagnostics are to be written |
| diag_all_levels | [.false.], .true. | if .true., tracer mean diagnostics at all vertical levels are output |
| cfl_all_levels | [.false.], .true. | if .true., cfl diagnostics at all vertical levels are output |
| / |
The CCSM ocean setup script replaces the following strings:
In addition to printing these diagnostics to a log file, the diagnostics are also printed to output files in a format more suitable for various graphics programs. (See table in section 4.1.2) The output files are ASCII files with each line containing tday (decimal time in days for the entire simulation), the value of the diagnostic and a name for the diagnostic. The CCSM POP also creates these ASCII output files, but instead of printing tday into the file , the CCSM POP prints tday00, the decimal time in days since the reference date 0000-01-01.
There are three types of diagnostics. Global diagnostics compute a variety of globally averaged values of tracers, kinetic energy and several tendencies for checking balances. CFL diagnostics compute the Courant numbers for advection and diffusion terms. Transport diagnostics compute mass, heat and salt transports through various regions defined in an input file.
Return to beginning of Chapter 4
A single, sample transport input file is provided with the standard LANL distribution, whereas the CCSM POP distribution contains several resolution-specific transport_contents files, including those for the two officially supported resolutions, gx1v3 and gx3v4: gx1v3_transport_contents and gx3v4_transport_contents.
The first record of the transport file contains the integer number of transport regions, num_transports.
Each following record must contain 6 integers imin, imax, jmin, jmax, kmin, kmax which are global array indices which define the transport region. Note that the region must be a plane so that one of the horizontal dimensions must be fixed. Following these integers must be a 5-character string that specifies 'zonal' or 'merid' transport. Note that this descriptor defines the orientation of the section and not the direction of the velocity normal to it. A 'zonal' section implies the transport across that section uses the meridional velocity (velocity perpendicular to the section). The last item in each record is a name for the transport region (e.g. 'Drake Passage').
The following tables provide all of the transports specified in the CCSM POP gx1v3_transport_contents and gx3v4_transport_contents files.
| imin | imax | jmin | jmax | kmin | kmax | section | label |
| 297 | 297 | 24 | 47 | 1 | 40 | merid | Drake Passage |
| 65 | 76 | 103 | 103 | 1 | 40 | zonal | Mozambique Channel |
| 198 | 202 | 333 | 333 | 1 | 40 | zonal | Bering Strait |
| 198 | 202 | 333 | 333 | 1 | 40 | zonal | Bering Strait |
| 254 | 261 | 372 | 372 | 1 | 40 | zonal | Northwest Passage |
| 131 | 131 | 164 | 167 | 1 | 40 | merid | Indonesian Throughflow I |
| 138 | 159 | 156 | 156 | 1 | 40 | zonal | Indonesian Throughflow II |
| 163 | 163 | 147 | 151 | 1 | 40 | merid | Indonesian Throughflow III |
| 284 | 284 | 264 | 270 | 1 | 40 | merid | Florida Strait |
| 289 | 292 | 258 | 258 | 1 | 40 | zonal | Windward Passage I |
| 292 | 292 | 257 | 258 | 1 | 40 | merid | Windward Passage II |
| 32 | 32 | 290 | 295 | 1 | 40 | merid | Gibraltar |
| imin | imax | jmin | jmax | kmin | kmax | section | label |
| 93 | 93 | 9 | 15 | 1 | 25 | merid | Drake Passage |
| 61 | 64 | 100 | 100 | 1 | 25 | zonal | Bering Strait | 46 | 46 | 37 | 46 | 1 | 25 | merid | Indonesian Throughflow |
| 89 | 89 | 80 | 83 | 1 | 25 | merid | Florida Strait |
Return to beginning of Chapter 4
The budget diagnostics module, which presently is only available in CCSM POP, computes and prints to the output log file the global volume and tracer budgets for heat, salt, and fresh water within a given time-averaging interval. The budget diagnostics do not yet include any non-homogeneous side or bottom fluxes (i.e., bottom heat flux) nor the contributions from any internal source terms.
Because most of the analysis is based on some time-averaged variables, the budgets are correct if time-averaging starts from the beginning of an intended budget interval. Also, because the very first time step of a new integration is an Euler-forward time step, any budget including this first step will be slightly off balance. These budget diagnostics were designed for use with the 'avg' or 'avgfit' time-mixing options. Consequently, with the Matsuno time-mixing option, the diagnostics can be only approximations, if the surface fluxes do change every timestep. This is because time averaging is accumulated every timestep and the Matsuno mixing ignores one branch of forcing.
In order for the budgets to be computed, all of the following seven 2-D variables must be requested in the tavg_contents file, even if some of them are zero (which is possible, depending on the surface flux and surface layer options): SHF, SFWF, RESID_T, RESID_S, FW, TFW_T, TFW_S.
The units of the printed diagnostics are:
| &budget_diagnostics_nml ( CCSM only) |
generation of tracer budget diagnostics | |
| ldiag_global_tracer_budgets | [.false.], [.true.] (CCSM) |
if .true., compute and report tracer budget diagnostics |
| / |
In this section, we often refer to 'model dates' and 'model times' as corresponding to actual dates and times in the real world. This is only true if the model initial time was set appropriately and only has true meaning if the model is forced by actual observed forcing fields with proper dates associated with them. Otherwise, 'model time' simply refers to the model's internal calendar.
In the CCSM POP, the model dates are determined by the value of the CCSM environment variable, $BASEDATE, which allows the CCSM2.0.1 component models to coordinate their initial dates. Typically, $BASEDATE is a "real-world" date, but it can be set to whatever value the user wishes.
Return to beginning of Chapter 4
The namelist tavg_nml (see table below) controls the frequency and content of time-averaged history files. These files are constructed by accumulating in memory at each time-step the running sums of selected variables or correlation of variables. Consequently, time averaging can be very memory intensive and may not be feasible on your computer. Snapshot history files (see next section) provide an alternative, but at the price of having to recall many files from archival storage to compute the sums. The tavg_freq determines both the frequency at which the files are written as well as the interval over which the time average is to be performed.
Note that the fields in the completed output files are normalized by the time interval recorded in the tavg header file. Because the time averages are running averages, tavg restart files are written whenever a model restart file is written so that the averaging can continue upon restart. These files are not normalized until the end of the time interval is reached and they are converted into completed files. The time interval in the header file is needed if you want to combine monthly files into seasonal, annual or multi-year averages.
The tavg header has a first line containing: num_2d_fields, num_3d_fields, tavg_sum, nsteps_total, tday, yyyymmdd. This is followed by a list of fields in the same format as the sample_tavg_contents file (see below), except that in the header file, the ordering of units and description are reversed from the sample_tavg_contents file.
In CCSM POP, there exists the option for writing time-averaged history files in netCDF format, instead of binary format. Note that when the netCDF option is selected (see 4.4.2.2 netCDF in CCSM POP), no separate header file is generated. Instead, all header and data information are combined into a single netCDF file, which is identifiable by its suffix, '.nc'.
The user may also control when the time averaging will begin. For example, if the time averaging should be started after the model has equilibrated, the user can specify when time averaging should start through the tavg_start variables. The choices are similar to the model start options.
| &tavg_nml | generation of time-average history files | |
| tavg_freq_opt | 'nyear', 'nmonth', 'nday', 'nhour', 'nsecond', 'nstep','never'
['nmonth'] (CCSM) |
units of time for 'tavg_freq' |
| tavg_freq | [100000] [1] (CCSM) |
interval for computation and output of time-average history files |
| tavg_start_opt | 'nstep', 'nyear', 'nmonth', 'nday', 'date'
['nstep'] (CCSM) |
units for tavg_start ('date' implies yyyymmdd) |
| tavg_start | [0] [1] (CCSM) |
time after which to start accumulating time average |
| tavg_infile | ['unknown_tavg_infile']
['OUTPUTHrestart.end'] (CCSM) |
restart file for partial tavg sums if starting from restart (ignored if luse_pointer_files is enabled) |
| tavg_outfile | ['t'] ['OUTPUTH'] (CCSM) |
root filename (with path) for tavg output files (suffixes will be added) |
| tavg_contents | '[unknown_tavg_contents]' ['INPUT/tavg_contents'] (CCSM) |
input file containing descriptors of fields requested for tavg output |
| ltavg_use_ncdf (CCSM only) |
.false., [.true.] (CCSM) | if .true., create tavg output files in netCDF format; if .false., create tavg output files in binary format |
| debug_ncdf (CCSM only) |
[.false.], .true. (CCSM) | if .true., print all netCDF-related messages |
| / |
The CCSM ocean setup script replaces the following strings:
IMPORTANT: Before a new run-sequence is begun, careful thought should be given to the contents of the time-average history files. The same considerations apply to snapshot history and movie files. Although it is possible to redefine the contents at any time during the sequence, this is not recommended. Changing the contents can greatly complicate the process of combining short-interval (e.g., monthly) files into longer-interval files, such as seasonal, annual and multi-year composite files.
Standard LANL POP distributions include a file sample_tavg_contents to be used as a template for producing time-averaged history files containing fields of interest to the individual modellers, whereas CCSM POP includes a tavg_contents file for each CCSM-supported model resoltion: gx1v3_tavg_contents and gx3v4_tavg_contents. These tavg_contents files differ only slightly from one another, and may also be customized according to the users' interests.
An important difference between the LANL and CCSM tavg_contents files is the ordering in which the elements appear. The CCSM ordering, reported below, is DIJK (the grid descriptor, explained below), name, description, and units; in the LANL ordering, units preceeds description. The CCSM tavg_contents file (see 4.4.2.2 netCDF in CCSM POP) is read by the netCDF-generating routines, and the description, which is delineated by single quotation marks in the tavg_contents files, is assigned to the netCDF variable's 'long-name' attribute.
The grid descriptor, DIJK, consists of four integers. The first indicates the dimensionality ("D") of the field (2-D or 3-D). The three integers which follow identify the i,j,k-grid upon which the field resides, where a value of "1" specifies the tracer grid and a value of "2" specifies the staggered velocity grid.
The following table contains a list of fields and products of fields that can be accumulated for the calculation of means, standard deviations and correlations. It is intended that you use this as a template that you will tailor to your own needs by deleting entries and adding new ones.
| DIJK | Name | Description | Units |
| 2110 | SHF | Total Surface Heat Flux, Including SW | W/m2 |
| 2110 | SHF_QSW | Solar Short-Wave Heat Flux | W/m2 |
| 2110 | SFWF | Virtual Salt Flux in FW Flux formulation | kg/m2/s |
| 2110 | PREC_F * | Precipitation Flux from Coupler | kg/m2/s |
| 2110 | EVAP_F * | Evaporation Flux from Coupler | kg/m2/s |
| 2110 | MELT_F* | Melt Flux from Coupler | kg/m2/s |
| 2110 | ROFF_F * | Runoff Flux from Coupler | kg/m2/s |
| 2110 | SALT_F * | Salt Flux from Coupler (kg of salt/m^2/s) | kg/m2/s |
| 2110 | SENH_F * | Sensible Heat Flux from Coupler | W/m2 |
| 2110 | LWUP_F * | Longwave Heat Flux (up) from Coupler | W/m2 |
| 2110 | LWDN_F * | Longwave Heat Flux (dn) from Coupler | W/m2 |
| 2110 | MELTH_F * | Melt Heat Flux from Coupler | W/m2 |
| 2110 | SSH | Sea Surface Height | cm |
| 2220 | TAUX | Zonal Windstress | dyne/cm2 |
| 2220 | TAUY | Meridional Windstress | dyne/cm2 |
| 2220 | SU | Vertically Integrated Zonal Velocity | cm2/s |
| 2220 | SV | Vertically Integrated Merid Velocity | cm2/s |
| 2110 | HMXL | Mixed-Layer Depth | cm |
| 2110 | HBLT | Boundary-Layer Depth | cm |
| 2110 | XMXL | Maximum Mixed-Layer Depth | cm |
| 2110 | XBLT | Maximum Boundary-Layer Depth | cm |
| 2110 | TMXL | Minimum Mixed-Layer Depth | cm |
| 2110 | TBLT | Minimum Boundary-Layer Depth | cm |
| 2110 | RESID_T | Free-Surface Residual Flux (T) | W/m2 |
| 2110 | RESID_S | Free-Surface Residual Flux (S) | m/year |
| 2110 | FW | Freshwater Flux | cm/s |
| 2110 | TFW_T | T flux due to freshwater flux | W/m2 |
| 2110 | TFW_S | S flux due to freshwater flux | kg of salt/m2/s |
| 2110 | T1_8 | Temperature in Upper 8 Levels | degC |
| 2110 | S1_8 | Salt in Upper 8 Levels | g/g |
| 2220 | U1_8 | Zonal Velocity in Upper 8 Levels | cm/s |
| 2220 | V1_8 | Merid Velocity in Upper 8 Levels | cm/s |
| 2110 | HDIFT | Vertically-Integrated Horz Diff T Tend | degC*cm/s |
| 2110 | ADVT | Vertically-Integrated T Advection Tend | degC*cm/s |
| 2110 | H2 | SSH**2 | cm2 |
| 2110 | H3 | (Dx(SSH))**2 + (Dy(SSH))**2 | ---- |
| 2220 | BSF | Diagnostic barotropic streamfunction | Sverdrups |
| 3221 | UVEL | Zonal Velocity | cm/s |
| 3221 | VVEL | Meridional Velocity | cm/s |
| 3112 | WVEL (CCSM only) |
Vertical Velocity | cm/s |
| 3111 | TEMP | Potential Temperature | degC |
| 3111 | SALT | Salinity | g/g |
| 3111 | PD | Potential Density Ref to Surface | g/cm3 |
| 3211 | UET | East Flux of Heat | degC/s |
| 3121 | VNT | North Flux of Heat | degC/s |
| 3221 | UISOP | Zonal Isopycnal Mixing Velocity | cm/s |
| 3221 | VISOP | Meridional Isopycnal Mixing Velocity | cm/s |
| 3112 | WISOP | Vertical Isopycnal Mixing Velocity (T grid-box top center) | cm/s |
| 3221 | KE | Horizontal Kinetic Energy (U**2+V**2)/2 | cm2/s2 |
| 3111 | TEMP2 | Temperature**2 | degC2 |
| 3111 | SALT2 | Salinity**2 | (g/g)2 |
| 3112 | WTT | Top Flux of Heat | degC/s |
| 3211 | UES | East Flux of Salt | g/g/s |
| 3121 | VNS | North Flux of Salt | g/g/s |
| 3112 | WTS | Top Flux of Salt | g/g/s |
| 3321 | UEU | East Flux of Zonal Momentum | cm/s2 |
| 3231 | VNU | North Flux of Zonal Momentum | cm/s2 |
| 3321 | UEV | East Flux of Meridional Momentum | cm/s2 |
| 3231 | VNV | North Flux of Meridional Momentum | cm/s2 |
| 3111 | PV | Potential Vorticity | 1/cm/s |
| 3111 | Q | z-derivative of potential density | g/cm4 |
| 3221 | UDP | Pressure work | erg |
| 3111 | PEC | Potential energy release convection | g/cm3 |
| 3111 | NCNV | Number of Convective Events | number |
| 3222 | WTU | Top flux of Zonal Momentum | cm/s2 |
| 3222 | WTV | Top flux of Meridional Momentum | cm/s2 |
| 3111 | ST | Temperature*Salinity | degC*g/g |
| 3111 | RHO | In-situ density | g/cm3 |
| 3222 | VUF | Zonal Viscous Stress at Bottom of U Cells | cm2/s2 |
| 3222 | VVF | Merid Viscous Stress at Bottom of U Cells | cm2/s2 |
| 3221 | UV | uvel*vvel | cm2/s2 |
| 3111 | RHOU | rho*uvel | g/cm2/s |
| 3111 | RHOV | rho*vvel | g/cm2/s |
| 3111 | PVWM | Potential Vorticity Flux through Top Face | 1/s2 |
| 3111 | PVWP | Potential Vorticity Flux through Bottom Face | 1/s2 |
| 3211 | UPV | Potential Vorticity Flux through East Face | 1/cm/s2 |
| 3121 | VPV | Potential Vorticity Flux through North Face | 1/cm/s2 |
| 3211 | URHO | Density Flux across East Face | g/cm3/s |
| 3121 | VRHO | Density Flux across North Face | g/cm3/s |
| 3112 | WRHO | Density Flux across Top Face | g/cm3/s |
| 3211 | UQ | uvel*d(rho)/dz | g/cm4/s |
| 3121 | VQ | vvel*d(rho)/dz | g/cm4/s |
*
CCSM POP only
Return to beginning of Chapter 4
If sufficient memory is not available for run-time
accumulation of time-averaged history files, the alternative is to make
snapshot history files are regular intervals.
The interval must be short enough that whatever time-averaging interval
may be desired in the future, there will be three or more samples (snapshots)
per averaging-interval. For monthly
averages, snapshots should be collected at intervals of 10 days or less.
Only one time-level of the prognostic
variables and selected diagnostic variables needs to be saved, since
second-moments and correlations can be computed later from these snapshot
files, at the cost of retrieving a potentially large number of snapshot
files.
In CCSM POP, there exists the option for writing snapshot
history files in netCDF format, instead of binary format.
Note that when the netCDF option is selected
(see 4.4.2.2 netCDF in CCSM POP),
no separate header file is
generated. Instead, all header and data information are combined into
a single netCDF file, which is identifiable by its suffix, '.nc'.
4.3.2 Snapshot history files
| &history_nml | Generation of snapshot history files | |
| history_freq_opt | ['never'],'nstep', 'nyear', 'nmonth', 'nday', 'nhour', 'nsecond' | units of time for 'history_freq' |
| history_freq | [100000] [1] (CCSM) |
number of units between output of snapshot history files |
| history_outfile | ['unknown'] ['OUTPUTHs'] (CCSM) |
root filename with path of history file output (suffixes will be added) |
| history_contents | ['sample_history_contents']
['INPUT/history_contents'] (CCSM) |
input file containing descriptors of fields requested to be output |
| lhistory_use_ncdf (CCSM only) |
.false., [.true.] (CCSM) | if .true., create history output files in netCDF format; if .false., create history output files in binary format |
| / |
The CCSM ocean setup script replaces the following strings:
If binary history files are written, then the first line of the companion history header files contains: num_fields, nsteps_total, tday, yyyymmdd. This line is followed by a list of fields in the same format as the history_contents file:
| DIJK | Name | Units | Description |
| 2110 | SHGT | cm | surface height |
| 2220 | UBTROP | cm/s | barotropic zonal velocity |
| 2220 | VBTROP | cm/s | barotropic meridional velocity |
| 3221 | UVEL | cm/s | zonal velocity |
| 3221 | VVEL | cm/s | meridional velocity |
You can add or delete fields to meet your analysis needs.
Return to beginning of Chapter 4
One of the most exciting aspects of ocean simulation is the opportunity to visualize and animate the evolution of the model variables in time and space. Making movies that progress smoothly requires either output of model variables frequently enough to avoid jerkiness or temporal interpolation of model variables to similarly frequent intervals. Experience has shown that a snapshot every three days (see movie_freq) gives satisfactory results. Any variable can be output, but to reduce archiving cost and retrieval time, movie files typically contain only a few two-dimensional arrays, such as sea-surface temperature, salinity and height, and a few sub-surface variables.
Presently, there is no option in the CCSM POP to generate movie files in netCDF format.
| &movie_nml | generation of snapshot movie files | |
| movie_freq_opt | ['never'], 'nstep', 'nyear','nmonth','nday', 'nhour','nsecond' | units of time for 'movie_freq' |
| movie_freq | [100000] | number of units between output of movie files |
| movie_outfile | ['unknown'] | root filename with path of movie file output(suffixes will be added) |
| movie_contents | ['sample_movie_contents'] | input file containing descriptors of fields requested for movie output |
| / |
The first line of the movie headers contains: num_fields, nsteps_total, tday, yyyymmdd. This is again followed by a list of fields in the same format as the sample_movie_contents (LANL POP) or {gx1v3,gx3v4}_movie_contents (CCSM) file:
| DIJK | Name | Units | Description |
| 2110 | SHGT | cm | surface height |
| 2110 | UTRANS | cm2/s | vertically integrated zonal transport |
| 2110 | VTRANS | cm2/s | vertically integrated meridional transport |
| 2110 | TEMP1_2 | degC | potential temperature average over levels 1,2 |
| 2110 | SALT1_2 | g/g | salinity average over levels 1,2 |
| 2110 | TEMP6 | degC | potential temperature at level 6 |
| 2110 | SALT6 | g/g | salinity at level 6 |
| 2110 | VORT | 1/s | relative vorticity at surface |
As with all sample_*_contents files, you can add or delete fields.
Presently, all CCSM POP movie_contents files only contain a single entry, 'TEMP6', simply because to date, the CCSM control runs have not generated any movie files.
Return to beginning of Chapter 4
Versions of these exist for some machines but these are not yet included in the present version of the code. They will be added soon.
Return to beginning of Chapter 4
In high-resolution applications of POP, the output files described above can be very large, for example, 1-3 GB per history file. Just writing that amount of data to the primary disk system of the computer can take a significant amount of time (minutes), during which the computation is unable to proceed because the processors are busy moving data. It is imperative that this output time be kept to a minimum. On parallel computers, this means that input and output (particularly output) must be done in parallel by as many processors as possible. At present, parallel output is only supported by vendors for files being written in binary format. User-friendly formats like netCDF currently must be written 'serially' by a single processor, while the other processors wait to feed it data. The length of the wait is proportional to the number of processors needing to output data, so the problem of serial output grows worse as the number of processors increases. Therefore, the standard LANL POP uses binary as its primary output format.
The CCSM POP does, however, allow the user to create time-averaged and instantaneous history output files in the netCDF format directly in the CCSM POP code. (See section 4.4.2.2)
Return to beginning of Chapter 4
All standard-LANL POP restart, movie, and both types of history files are written in binary format; as stated earlier, CCSM POP users can elect to generate time-averaged and/or instantaneous history files directly in the netCDF format.
Restart files retain the full 64-bit precision, but 32-bits are sufficient for the analysis and visualization purposes of the other files. Fortran 'direct access' IO is used to write the binary files, so the files have to be written one 'record' at a time and all records must have the same size. The record size is taken to be a complete latitude-longitude slice; this works for 2D horizontal arrays as well as 3D arrays, which are written one level at a time. The records are in Fortran ‘column-major’ order, meaning that if F(I,J,K) is written out, I varies most rapidly, J is next, and K varies most slowly, as in (((F(I,J,K),I=1,IM),J=1,JM),K=1,KM).
Return to beginning of Chapter 4
A utility application bin2nc will be included in the LANL POP source code distribution (tar file) that translates the binary files into netCDF format 'off line', allowing the run to continue with minimal delay. The resulting netCDF file has the same name as the binary file but with '.nc' appended. Thus, bin2nc operating on 'm.21.0672' will produce 'm.21.0672.nc'. The netCDF files can be examined with FERRET (from NOAA PMEL), VCS (from LLNL's PCMDI program) or other utilities having netCDF interfaces.
On Unix systems, the POP job can spawn a separate process to run bin2nc as soon as the binary file has been written. The POP job supplies bin2nc with the name of the binary file and 'metadata' needed to produce a netCDF file. The same process can copy the files to archival storage.
Because the CCSM POP allows the creation of time-averaged and instantaneous history files in netCDF format, CCSM POP users generally will not need this binary-to-netCDF utility; therefore it is not included with the standard CCSM POP release.
Return to beginning of Chapter 4
The CCSM ocean-model community has come to expect output datasets in the netCDF format, and post-processing binary datasets into netCDF format has disadvantages that the CCSM community felt outweighed the overhead associated with writing model output files directly in the netCDF format. Therefore, the CCSM POP has been modified to produce time-averaged and instantaneous ('snapshot') history files in the netCDF format, although binary output can be generated if the user prefers. Timing tests show that for the CCSM resolutions (gx1v3 or gx3v4), relatively infrequent (monthly or annual) history-file generation, and relatively modest numbers of processors (c. 40), the overhead associated with writing files directly into netCDF format is negligible.
The netCDF files generated by the CCSM POP code adhere to the
The CCSM pop_in file contains the namelist scalar_nml which identifies the name of a scalar_contents file containing a list of model constants to be documented in the netCDF history files. The first record of the scalar_contents file is the number of scalars listed in the file; each subsequent record contains the model variable name, a long-name description of the variable, units, the value of the netCDF "dimensions" (0 for scalars), and a dummy value, which is set to -1 in the input file.
| &scalar_nml (CCSM only) |
selection of scalars to be included in netCDF history files | |
| scalar_contents (CCSM) | ['INPUT/scalar_contents'] (CCSM) | filename for scalar contents file |
The CCSM ocean setup script replaces the string 'INPUT' with the string 'input'.
Return to beginning of Chapter 4
Another LANL program, extract, is available to operate on POP binary files. It allows you to specify subsets of variables, geographical subdomains, and time intervals (possibly from multiple input files) that you want to extract and put in a netCDF formatted file. extract is described in Appendix 7.5. At present, it does not work with displaced-pole grids.
The extract program is not available through the CCSM POP distribution.