Because of additional requirements placed upon POP2 time-averaged output files by CESM1 and because of the extended capability of the CESM1 POP2 time-averaged history fields, the two versions are documented separately in the following two subsections.
The namelist tavg_nml 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 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.
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. Note that the fields in the output files are normalized by the accumulated time since the start of the time average. The time interval used for this normalization is output as the file attribute tavg_sum. When the model restarts from a restart file, the sums are de-normalized before continuing the accumulated sum.
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 | Valid Values [default] |
generation of time-average history files |
| tavg_freq_opt | ['never'], 'nyear', 'nmonth', 'nday', 'nhour', 'nsecond', 'nstep' | units of time for 'tavg_freq' |
| tavg_freq | [100000] | interval in above units for computation and output of time-average history files |
| tavg_start_opt | ['nstep'], 'nyear', 'nmonth', 'nday', 'date' | units for tavg_start ('date' implies yyyymmdd) |
| tavg_start | [100000] | time in above units after which to start accumulating time average |
| tavg_infile | ['unknown'] | restart file for partial tavg sums if starting from restart (ignored if luse_pointer_files is enabled) |
| tavg_fmt_in | ['bin'],'nc' | format for tavg restart file (binary or netCDF) |
| tavg_outfile | ['unknown'] | root filename (with path) for tavg output files (suffixes will be added) |
| tavg_fmt_out | ['bin'],'nc' | format for tavg output files (binary or netCDF) |
| tavg_contents | 'sample_tavg_contents' | file name for input file containing names of fields requested for tavg output |
| / |
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.
For time-averaged output, a tavg_contents file is required containing a simple list (one field per line) of accepted short names for all the fields desired for the output file. A sample_tavg_contents file is supplied containing a large list of fields available for tavg output. It is meant for the user to use as a template, modifying it for their own needs by deleting entries or adding new ones. If a user wishes to add a field that is currently not available, the user must modify the code to add that field using other available fields as a template.
In CESM1 POP2, the time-averaged history-file ("tavg") module has been modified to provide additional features and options to the user:
Presently, CESM1 POP2 supports the creation of a maximum of four concurrent tavg output streams, with a hard limit of nine streams possible if the tavg module is appropriately modified. Options for each of the streams is set individually, using array syntax in the namelist.
In order to support these additional features, the CESM1 POP2 tavg_contents files and the tavg_nml namelist have necessarily become more complex than the basic LANL POP2.
There are two main differences between the CESM1 POP2 tavg_contents file and the LANL counterpart, but they are small:
The first character of each line in the CESM1 POP2 tavg_contents file is either a comment character or an integer in the interval [1,4]. The next two characters must be blank; the remaining characters on the line spell out the short name of a requested variable.
If the leading character is a comment character -- either the pound sign (#) or the exclamation point (!) -- then the entire line is treated as a comment. If the leading character on the line is an integer, it identifies the number of the output stream in which the requested field will appear. Each requested tavg output field may be assigned to only one stream; assigning the same field to more than one stream will result in the model ignoring it and all subsequent requests. Similarly, duplicate requests of the same field within the same stream will be eliminated. In all cases, a summary of field and stream assignments is printed in the output log file, which allows the user to confirm which fields will be written to which stream.
Output filenames for the each stream are determined from within the CESM1 tavg module, incorporating the stream number into the output filename in all but the first stream. This seemingly inconsistent treatment of tavg output filenames was chosen based on the requirement for backwards-compatability in filenames. For example, a one-stream case would generate tavg output files of the form $CASE.pop.h.*; an N-stream case would generate tavg output files of the form $CASE.pop.h.*, $CASE.pop.h2.*, ..., $CASE.pop.hN.*
Most of the CESM1 tavg namelist variables are now arrays of length (max_avail_tavg_streams), which allows the user to set controls for each tavg history-file stream on a stream-by-stream basis.
In the table below, any array element that is undefined in the CESM1 pop2 namelist file is set to the default value identified in curly braces.
| &tavg_nml | CESM1 dipole-grid default | CESM1 tripole-grid default | Valid values | generation of time-average history files for stream-dimensioned variable, specify one value per stream |
| n_tavg_streams | 3 | 2 | (1,9) | number of tavg output files ("streams") |
| tavg_freq_opt | ('nmonth' 'nday' 'once') | ('nmonth' 'nday') | 'never', 'nyear', 'nmonth', 'nday', 'nhour', 'nsecond', 'nstep', 'once' | units of time for 'tavg_freq' |
| tavg_freq | (1,1,1) | (1,1) | integers > 0 | interval in above units for computation and output of time-average history fields |
| tavg_file_freq_opt | ('nmonth','nmonth','once') | ('nmonth','nmonth') | 'never', 'nyear', 'nmonth', 'nday', 'nhour', 'nsecond', 'nstep', 'once' | units of time for 'tavg_file_freq' (file-writing frequency) |
| tavg_file_freq | (1,1,1) | (1,1) | integers > 0 | units of time for 'tavg_file_freq' |
| tavg_start_opt | ('nstep','nstep','nstep') | ('nstep','nstep') | 'nstep', 'nyear', 'nmonth', 'nday', 'date' | units for tavg_start ('date' implies yyyymmdd) |
| tavg_start | (1,1,1) | (1,1) | integers > 0 | time in above units after which to start accumulating time average |
| tavg_infile | auto-filled by CESM1 scripts | auto-filled by CESM1 scripts | string ≤ 256 chars | restart file for partial tavg sums if starting from restart (ignored if luse_pointer_files is enabled) |
| tavg_fmt_in | ('nc','nc','nc') | ('nc','nc') | 'bin','nc' | format for tavg restart file (binary or netCDF) |
| tavg_outfile | auto-filled by CESM1 scripts to $CASE.pop.h | auto-filled by CESM1 scripts to $CASE.pop.h | string ≤ 256 characters | root filename (with path) for tavg output files (suffixes will be added automatically in the code) |
| tavg_fmt_out | ('nc','nc','nc') | ('nc','nc') | 'bin','nc' | format for tavg output files (binary or netCDF) |
| tavg_contents | auto-filled by CESM1 scripts to '${resolution}_tavg_contents' | auto-filled by CESM1 scripts to '${resolution}_tavg_contents' | string ≤ 256 characters | file name for input file containing names of fields requested for tavg output |
| ltavg_has_offset_date | (.false. .false. .false.) | (.false. .false.) | true., .false. | if .true., sets the time from which counting begins for tavg_freq |
| tavg_offset_years | (1 1 1) | (1 1) | integer > 0 | the reference year number in the time-management time_to_do function |
| tavg_offset_months | (1 1 1) | (1 1) | integer > 0 | the reference month number in the time-management time_to_do function |
| tavg_offset_days | (1 1 1) | (1 1) | integer > 0 | the reference day number in the time-management time_to_do function |
| ltavg_one_time_header | (.false. .false. .false.) | (.false. .false. ) | .true., .false. | write time-invariant information only into the first file of each stream in each model run segment |
| ltavg_nino_diags_requested | .true. | .false. | .true.,.false. | if .true., compute NINO diagnostics. If n_tavg_streams > 1, the code will determine which stream contains the necessary fields from which to compute the diagnostics. |
| / |
| Name | Units | Description |
| SHF | W/m2 | Surface Heat Flux |
| SFWF | mm/day | Surface Freshwater Flux (p-e) |
| SSH | cm | Sea Surface Height |
| H2 (SSH2 in CESM1) |
cm2 | SSH2 |
| H3 | unitless | (Δx(SSH))2 + (Δy(SSH))2 |
| TAUX | dyne/cm2 | Zonal windstress |
| TAUY | dyne/cm2 | Meridional windstress |
| UVEL | cm/s | Zonal Velocity |
| VVEL | cm/s | Meridional Velocity |
| KE | cm2/s2 | Horizontal Kinetic Energy (U2 + V2)/2 |
| TEMP | oC | Potential Temperature |
| SALT | g/g | Salinity |
| TEMP2 | oC2 | Temperature2 |
| SALT2 | (g/g)2 | Salt2 |
| UET | oC/s | East Flux of Heat |
| VNT | oC/s | North Flux of Heat |
| WTT | oC/s | Top Flux of Heat |
| UES | g/g/s | East Flux of Salt |
| VNS | g/g/s | North Flux of Salt |
| WTS | g/g/s | Top Flux of Salt |
| UEU | cm/s2 | East Flux of Zonal Momentum |
| VNU | cm/s2 | North Flux of Zonal Momentum |
| UEV | cm/s2 | East Flux of Meridional Momentum |
| VNV | cm/s2 | North Flux of Meridional Momentum |
| PV | 1/s | Potential Vorticity |
| Q | g/cm4 | z-derivative of potential density |
| PD | g/cm3 | Potential density referenced to surface |
| UDP | erg | Pressure work |
| PEC | g/cm3 | Potential energy release due to convection |
| NCNV | adjustments/s | Convective adjustments per second |
| WTU | cm/s2 | Top flux of Zonal Momentum |
| WTV | cm/s2 | Top flux of Meridional Momentum |
| ST | oCg/g | Temperature*Salinity |
| RHO | g/cm3 | In-situ density |
| Name | Units | Description |
| QFLUX | Watts/m2 | Internal Ocean Heat Flux Due to Ice Formation; heat of fusion > 0 or ice-melting potential < 0 |
| BSF | Sv | Barotropic Stream Function |
| TFW_T | Watts/m2 | T flux due to freshwater flux |
| TFW_S | kg/m2/s | S flux due to freshwater flux (kg of salt/m^2/s) |
| RESID_T | Watts/m2 | Free-Surface Residual Flux (T) |
| RESID_S | kg/m2/s | Free-Surface Residual Flux (S) |
| QSW_HTP | Watts/m2 | Solar Short-Wave Heat Flux in top layer |
| QSW_HBL | Watts/m2 | Solar Short-Wave Heat Flux in boundary layer |
| SHF_QSW | Watts/m2 | Solar Short-Wave Heat Flux |
| PREC_F | kg/m2/s | Precipitation Flux from Coupler (rain+snow) |
| SNOW_F | kg/m2/s | Snow Flux from Coupler |
| EVAP_F | kg/m2/s | Evaporation Flux from Coupler |
| MELT_F | kg/m2/s | Melt Flux from Coupler |
| ROFF_F | kg/m2/s | Runoff Flux from Coupler |
| IOFF_F | kg/m2/s | Ice Flux from Coupler due to Land-Model Snow Capping |
| SALT_F | kg/m2/s | Salt Flux from Coupler (kg of salt/m^2/s) |
| SENH_F | kg/m2/s | Sensible Heat Flux from Coupler |
| LWUP_F | Watts/m2 | Longwave Heat Flux (up) from Coupler |
| LWDN_F | Watts/m2 | Longwave Heat Flux (down) from Coupler |
| MELTH_F | Watts/m2 | Melt Heat Flux from Coupler |
| IFRAC | unitless fraction | Ice Fraction from Coupler |
| HMXL and HMXL_2 |
cm | Mixed-Layer Depth |
| XMXL and XMXL_2 |
cm | Maximum Mixed-Layer Depth |
| TMXL | cm | Minimum Mixed-Layer Depth |
| HBLT | cm | Boundary-Layer Depth |
| XBLT | cm | Maximum Boundary-Layer Depth |
| TBLT | cm | Minimum Boundary-Layer Depth |
| FW | cm/s | Freshwater Flux |
| ADVT | cm/oC/s | Vertically-Integrated T Advection Tendency |
| ADVS | cm g/km/s | Vertically-Integrated S Advection Tendency |
| dTEMP_POS_2D | oC | max positive column temperature timestep diff |
| dTEMP_NEG_2D | oC | max negative column temperature timestep diff |
| KAPPA_ISOP | cm2/s | Isopycnal diffusion coefficient |
| KAPPA_THIC | cm2/s | Thickness diffusion coefficient |
| HOR_DIFF | cm2/s | Horizontal diffusion coefficient |
| DIA_DEPTH | cm | Depth of the Diabatic Region at the Surface |
| TLT | cm | Transition Layer Thickness |
| INT_DEPTH | cm | Depth at which the Interior Region Starts |
| UISOP | cm/s | Bolus Velocity in grid-x direction (diagnostic) |
| VISOP | cm/s | Bolus Velocity in grid-y direction (diagnostic) |
| WISOP | cm/s | Vertical Bolus Velocity (diagnostic) |
| ADVT_ISOP | cm/oC/s | Vertically-Integrated T Eddy-Induced Advection Tendency (diagnostic) |
| ADVS_ISOP | cm g/km/s | Vertically-Integrated S Eddy-Induced Advection Tendency (diagnostic) |
| VNT_ISOP | oC/s | Heat Flux Tendency in grid-y Dir due to Eddy-Induced Vel (diagnostic) |
| VNS_ISOP | g/km/s | Salt Flux Tendency in grid-y Dir due to Eddy-Induced Vel (diagnostic) |
| KVMIX | cm2/s | Vertical diabatic diffusivity due to background or Tidal Mixing + background |
| KVMIX_M | cm2/s | Vertical viscosity due to background or Tidal Mixing + background |
| TPOWER | erg/s | Energy Used by Vertical Mixing |
| VVC_BCK | cm2/s | Vertical viscosity due to background |
| USUBM | cm/s | Submeso velocity in grid-x direction (diagnostic) |
| VSUBM | cm/s | Submeso velocity in grid-y direction (diagnostic) |
| WSUBM | cm/s | Vertical submeso velocity (diagnostic) |
| ADVT_SUBM | cm/oC/s | Vertically-Integrated T submeso Advection Tendency (diagnostic) |
| ADVS_SUBM | cm g/km/s | Vertically-Integrated S submeso Advection Tendency (diagnostic) |
| VNT_SUBM | oC/s | Heat Flux Tendency in grid-y Dir due to submeso Vel (diagnostic) |
| VNS_SUBM | oC/s | Salt Flux Tendency in grid-y Dir due to submeso Vel (diagnostic) |
| HLS_SUBM | cm | Horizontal length scale used in submeso |
| VDC_T | cm2/s | total diabatic vertical TEMP diffusivity |
| VDC_S | cm2/s | total diabatic vertical SALT diffusivity |
| UVEL2 | cm2/s2 | Velocity in grid-x direction |
| VVEL2 | cm2/s2 | Velocity in grid-y direction |
| WVEL2 | cm2/s2 | Vertical Velocity2 |
| RHO_VINT | g/cm2 | Vertical Integral of In-Situ Density |
| SFWF_WRST | kg/m2/s | Virtual Salt Flux due to weak restoring |
| TAUX2 | dyne2/cm4 | Windstress2 in grid-x direction |
| TAUY2 | dyne2/cm4 | Windstress2 in grid-y direction |
| SSH2 (H2 in LANL POP) |
cm2 | SSH2 |
| VVC | cm2/s | total vertical momentum viscosity |
| VDC_BCK | cm2/s | Vertical diabatic diffusivity due to background |
To customize tavg output in your CESM1 run: