• • 7.1.4.0.1 MITgcm Kernel Diagnostic Menu:

7.1.4 Usage Notes

To use the diagnostics package, other than enabling it in packages.conf and turning the usediagnostics flag in data.pkg to .TRUE., there are two further steps the user must take to enable the diagnostics package for output of quantities that are already defined in the GCM under an experiment's configuration of packages. A namelist must be supplied in the run directory called data.diagnostics, and the file DIAGNOSTICS_SIZE.h must be included in the code directory. The steps for defining a new (permanent or experiment-specific temporary) diagnostic quantity will be outlined later.

The namelist will activate a user-defined list of diagnostics quantities to be computed, specify the frequency and type of output, the number of levels, and the name of all the separate output files. A sample data.diagnostics namelist file:

# Diagnostic Package Choices
 &diagnostics\_list
  frequency(1) = 86400., 
   levels(1,1) = 1., 
   fields(1,1) = 'RSURF   ', 
   filename(1) = 'surface', 
  frequency(2) = 86400., 
   levels(1,2) = 1.,2.,3.,4.,5., 
   fields(1,2) = 'UVEL    ','VVEL    ', 
   filename(2) = 'diagout1', 
  frequency(3) = 3600., 
   fields(1,3) = 'UVEL    ','VVEL    ','PRESSURE', 
   filename(3) = 'diagout2', 
  fileflags(3) = ' P1     ', 
 &end

In this example, there are two output files that will be generated for each tile and for each output time. The first set of output files has the prefix diagout1, does time averaging every 86400. seconds, (frequency is 86400.), and will write fields which are multiple-level fields at output levels 1-5. The names of diagnostics quantities are UVEL and VVEL. The second set of output files has the prefix diagout2, does time averaging every 3600. seconds, includes fields which are multiple-level fields, levels output are 1-5, and the names of diagnostics quantities are THETA and SALT.

The user must assure that enough computer memory is allocated for the diagnostics and the output streams selected for a particular experiment. This is acomplished by modifying the file DIAGNOSTICS_SIZE.h and including it in the experiment code directory. The parameters that should be checked are called numdiags, numlists, numperlist, and diagSt_size.

numdiags (and diagSt_size):
All GCM diagnostic quantities are stored in the single diagnostic array QDIAG which is located in the file
pkg/diagnostics/DIAGNOSTICS.h.
and has the form:

      common /diagnostics/
     &     qdiag(1-Olx,sNx+Olx,1-Olx,sNx+Olx,numdiags,Nsx,Nsy)

numlists and numperlist:
The parameter numlists must be set greater than or equal to the number of separate output streams that the user specifies in the namelist file data.diagnostics. The parameter numperlist corresponds to the number of diagnostics requested in each output stream.

In order to define and include as part of the diagnostic output any field that is desired for a particular experiment, two steps must be taken. The first is to enable the ``User Diagnostic'' in data.diagnostics. This is accomplished by adding one of the ``User Diagnostic'' field names (UDIAG1 through UDIAG10, for multi-level fields, or SDIAG1 through SDIAG10 for single level fields) to the data.diagnostics namelist in one of the output streams. These fields are listed in the diagnostics menu. The second step is to add a call to diagnostics_fill from the subroutine in which the quantity desired for diagnostic output is computed.

In order to add a new diagnostic to the permanent set of diagnostics that the main model or any package contains as part of its diagnostics menu, the subroutine diagnostics_add2list should be called during the initialization phase of the main model or package. For the main model, the call should be made from subroutine diagnostics_main_init, and for a package, the call should probably be made from somewhere in the packages_init_fixed sequence (probaby from inside the particular package's init_fixed routine). A typical code sequence to set the input arguments to diagnostics_add2list would look like:

      diagName  = 'THETA   '
      diagTitle = 'Potential Temperature (degC,K)'
      diagUnits = 'Degrees K       '
      diagCode  = 'SM      MR      '
      CALL DIAGNOSTICS\_ADD2LIST( diagNum,
     I          diagName, diagCode, diagUnits, diagTitle, myThid )

If the new diagnostic quantity is associated with either a vector pair or a diagnostic counter, the diagCode argument must be filled with the proper index for the ``mate''. The output argument from diagnostics_add2list that is called diagNum here contains a running total of the number of diagnostics defined in the code up to any point during the run. The sequence number for the next two diagnostics defined (the two components of the vector pair, for instance) will be diagNum+1 and diagNum+2. The definition of the first component of the vector pair must fill the ``mate'' segment of the diagCode as diagnostic number diagNum+2. Since the subroutine increments diagNum, the definition of the second component of the vector fills the ``mate'' part of diagCode with diagNum. A code sequence for this case would look like:

      diagName  = 'UVEL    ' 
      diagTitle = 'Zonal Velocity                ' 
      diagUnits = 'm / sec         ' 
      diagCode  = 'SM      MR      ' 
      write(diagCode,'(A,I3.3,A)') 'VV   ', diagNum+2 ,'MR      ' 
      call diagnostics\_add2list( diagNum, 
     I          diagName, diagCode, diagUnits, diagTitle, myThid ) 
      diagName  = 'VVEL    ' 
      diagTitle = 'Meridional Velocity           ' 
      diagUnits = 'm / sec         ' 
      diagCode  = 'SM      MR      ' 
      write(diagCode,'(A,I3.3,A)') 'VV   ', diagNum ,'MR      ' 
      call diagnostics\_add2list( diagNum, 
     I          diagName, diagCode, diagUnits, diagTitle, myThid )

7.1.4.0.1 MITgcm Kernel Diagnostic Menu:

NAME	UNITS	LEVELS	DESCRIPTION
UVEL		Nr	U-Velocity
VVEL		Nr	V-Velocity
UVEL_k2		1	U-Velocity
VVEL_k2		1	V-Velocity
WVEL		Nr	Vertical-Velocity
THETASQ		Nr	Square of Potential Temperature
SALTSQ		Nr	Square of Salt (or Water Vapor Mixing Ratio)
SALTSQan		Nr	Square of Salt anomaly (=SALT-35)
UVELSQ		Nr	Square of U-Velocity
VVELSQ		Nr	Square of V-Velocity
WVELSQ		Nr	Square of Vertical-Velocity
UV_VEL_C		Nr	Meridional Transport of Zonal Momentum (cell center)
UV_VEL_Z		Nr	Meridional Transport of Zonal Momentum (corner)
WU_VEL		Nr	Vertical Transport of Zonal Momentum (cell center)
WV_VEL		Nr	Vertical Transport of Meridional Momentum (cell center)
UVELMASS		Nr	Zonal Mass-Weighted Component of Velocity
VVELMASS		Nr	Meridional Mass-Weighted Component of Velocity
WVELMASS		Nr	Vertical Mass-Weighted Component of Velocity
UTHMASS		Nr	Zonal Mass-Weight Transp of Pot Temp
VTHMASS		Nr	Meridional Mass-Weight Transp of Pot Temp
WTHMASS		Nr	Vertical Mass-Weight Transp of Pot Temp
ETAN		1	Perturbation of Surface (pressure, height)
ETANSQ		1	Square of Perturbation of Surface (pressure, height)
DETADT2		1	Square of Eta (Surf.P,SSH) Tendency
THETA		Nr	Potential Temperature
SST		1	Sea Surface Temperature
SALT		Nr	Salt (or Water Vapor Mixing Ratio)
SSS		1	Sea Surface Salinity
SALTanom		Nr	Salt anomaly (=SALT-35)

NAME	UNITS	LEVELS	DESCRIPTION
USLTMASS		Nr	Zonal Mass-Weight Transp of Salt (or W.Vap Mix Rat.)
VSLTMASS		Nr	Meridional Mass-Weight Transp of Salt (or W.Vap Mix Rat.)
WSLTMASS		Nr	Vertical Mass-Weight Transp of Salt (or W.Vap Mix Rat.)
UVELTH		Nr	Zonal Transp of Pot Temp
VVELTH		Nr	Meridional Transp of Pot Temp
WVELTH		Nr	Vertical Transp of Pot Temp
UVELSLT		Nr	Zonal Transp of Salt (or W.Vap Mix Rat.)
VVELSLT		Nr	Meridional Transp of Salt (or W.Vap Mix Rat.)
WVELSLT		Nr	Vertical Transp of Salt (or W.Vap Mix Rat.)
RHOAnoma		Nr	Density Anomaly (=Rho-rhoConst)
RHOANOSQ		Nr	Square of Density Anomaly (=(Rho-rhoConst))
URHOMASS		Nr	Zonal Transport of Density
VRHOMASS		Nr	Meridional Transport of Density
WRHOMASS		Nr	Vertical Transport of Potential Density
PHIHYD		Nr	Hydrostatic (ocean) pressure / (atmos) geo-Potential
PHIHYDSQ		Nr	Square of Hyd. (ocean) press / (atmos) geoPotential
PHIBOT		Nr	ocean bottom pressure / top. atmos geo-Potential
PHIBOTSQ		Nr	Square of ocean bottom pressure / top. geo-Potential
DRHODR		Nr	Stratification: d.Sigma/dr
VISCA4		1	Biharmonic Viscosity Coefficient
VISCAH		1	Harmonic Viscosity Coefficient
TAUX		1	zonal surface wind stress, >0 increases uVel
TAUY		1	meridional surf. wind stress, >0 increases vVel
TFLUX		1	net surface heat flux, >0 increases theta
TRELAX		1	surface temperature relaxation, >0 increases theta
TICE		1	heat from melt/freeze of sea-ice, >0 increases theta
SFLUX		1	net surface salt flux, >0 increases salt
SRELAX		1	surface salinity relaxation, >0 increases salt
PRESSURE		Nr	Atmospheric Pressure (Pa)

NAME	UNITS	LEVELS	DESCRIPTION
ADVr_TH		Nr	Vertical Advective Flux of Pot.Temperature
ADVx_TH		Nr	Zonal Advective Flux of Pot.Temperature
ADVy_TH		Nr	Meridional Advective Flux of Pot.Temperature
DFrE_TH		Nr	Vertical Diffusive Flux of Pot.Temperature (Explicit part)
DIFx_TH		Nr	Zonal Diffusive Flux of Pot.Temperature
DIFy_TH		Nr	Meridional Diffusive Flux of Pot.Temperature
DFrI_TH		Nr	Vertical Diffusive Flux of Pot.Temperature (Implicit part)
ADVr_SLT		Nr	Vertical Advective Flux of Water-Vapor
ADVx_SLT		Nr	Zonal Advective Flux of Water-Vapor
ADVy_SLT		Nr	Meridional Advective Flux of Water-Vapor
DFrE_SLT		Nr	Vertical Diffusive Flux of Water-Vapor (Explicit part)
DIFx_SLT		Nr	Zonal Diffusive Flux of Water-Vapor
DIFy_SLT		Nr	Meridional Diffusive Flux of Water-Vapor
DFrI_SLT		Nr	Vertical Diffusive Flux of Water-Vapor (Implicit part)

For a list of the diagnostic fields available in the different MITgcm packages, follow the link to the diagnostics menu in the manual section describing the package:

• aim: 6.5.1.2
• exf: 6.4.6.7
• gchem: 6.8.1.3
• generic_advdiff: 6.2.1.3
• gridalt: 6.2.5.6
• gmredi: 6.4.1.8
• fizhi: 6.5.3.3
• kpp: 6.4.2.6
• land: 6.5.2.3
• mom_common: 2.14.8
• obcs: 6.3.1.7
• thsice: 6.6.1.3
• shap_filt: 2.20.1
• ptracers: 6.3.3.4

Copyright © 2006 Massachusetts Institute of Technology

Last update 2011-01-09