mom_sum_output module reference¶

Reports integrated quantities for monitoring the model state.

Data Types¶

`depth_list`	A list of depths and corresponding globally integrated ocean area at each depth and the ocean volume below each depth.
`sum_output_cs`	The control structure for the MOM_sum_output module.

Functions/Subroutines¶

`mom_sum_output_init()`	MOM_sum_output_init initializes the parameters and settings for the MOM_sum_output module.
`mom_sum_output_end()`	MOM_sum_output_end deallocates memory used by the MOM_sum_output module.
`write_energy()`	This subroutine calculates and writes the total model energy, the energy and mass of each layer, and other globally integrated physical quantities.
`accumulate_net_input()`	This subroutine accumulates the net input of volume, salt and heat, through the ocean surface for use in diagnosing conservation.
`depth_list_setup()`	This subroutine sets up an ordered list of depths, along with the cross sectional areas at each depth and the volume of fluid deeper than each depth.
`create_depth_list()`	create_depth_list makes an ordered list of depths, along with the cross sectional areas at each depth and the volume of fluid deeper than each depth.
`write_depth_list()`	This subroutine writes out the depth list to the specified file.
`read_depth_list()`	This subroutine reads in the depth list from the specified file and allocates the memory within and sets up DL.
`get_depth_list_checksums()`	Return the checksums required to verify DEPTH_LIST_FILE contents.

Detailed Description¶

By Robert Hallberg, April 1994 - June 2002.

This file contains the subroutine (write_energy) that writes horizontally integrated quantities, such as energies and layer volumes, and other summary information to an output file. Some of these quantities (APE or resting interface height) are defined relative to the global histogram of topography. The subroutine that compiles that histogram (depth_list_setup) is also included in this file.

In addition, if the number of velocity truncations since the previous call to write_energy exceeds maxtrunc or the total energy exceeds a very large threshold, a fatal termination is triggered.

Type Documentation¶

type mom_sum_output/depth_list¶

A list of depths and corresponding globally integrated ocean area at each depth and the ocean volume below each depth.

Type fields:

% listsize [integer,private] :: length of the list <= niglobal*njglobal + 1
% depth [real(:),allocatable, private] :: A list of depths [Z ~> m].
% area [real(:),allocatable, private] :: The cross-sectional area of the ocean at that depth [L2 ~> m2].
% vol_below [real(:),allocatable, private] :: The ocean volume below that depth [Z L2 ~> m3].

type mom_sum_output/sum_output_cs¶

The control structure for the MOM_sum_output module.

Type fields:

% initialized [logical] :: True if this control structure has been initialized.
% dl [type( depth_list )] :: The sorted depth list.
% lh [integer(:),allocatable] :: This saves the entry in DL with a volume just less than the volume of fluid below the interface.
% do_ape_calc [logical] :: If true, calculate the available potential energy of the interfaces. Disabling this reduces the memory footprint of high-PE-count models dramatically.
% read_depth_list [logical] :: Read the depth list from a file if it exists and write it if it doesn’t.
% depth_list_file [character (len=200)] :: The name of the depth list file.
% d_list_min_inc [real] :: The minimum increment [Z ~> m], between the depths of the entries in the depth-list file, 0 by default.
% require_depth_list_chksum [logical] :: Require matching checksums in Depth_list.nc when reading the file.
% update_depth_list_chksum [logical] :: Automatically update the Depth_list.nc file if the checksums are missing or do not match current values.
% use_temperature [logical] :: If true, temperature and salinity are state variables.
% fresh_water_in_efp [type( efp_type )] :: The total mass of fresh water added by surface fluxes on this PE since the last time that write_energy was called [kg].
% net_salt_in_efp [type( efp_type )] :: The total salt added by surface fluxes on this PE since the last time that write_energy was called [ppt kg].
% net_heat_in_efp [type( efp_type )] :: The total heat added by surface fluxes on this PE since the last time that write_energy was called [J].
% heat_prev_efp [type( efp_type )] :: The total amount of heat in the ocean the last time that write_energy was called [J].
% salt_prev_efp [type( efp_type )] :: The total amount of salt in the ocean the last time that write_energy was called [ppt kg].
% mass_prev_efp [type( efp_type )] :: The total ocean mass the last time that write_energy was called [kg].
% dt_in_t [real] :: The baroclinic dynamics time step [T ~> s].
% energysavedays [type(time_type)] :: The interval between writing the energies and other integral quantities of the run.
% energysavedays_geometric [type(time_type)] :: The starting interval for computing a geometric progression of time deltas between calls to write_energy. This interval will increase by a factor of 2. after each call to write_energy.
% energysave_geometric [logical] :: Logical to control whether calls to write_energy should follow a geometric progression.
% write_energy_time [type(time_type)] :: The next time to write to the energy file.
% geometric_end_time [type(time_type)] :: Time at which to stop the geometric progression of calls to write_energy and revert to the standard energysavedays interval.
% timeunit [real] :: The length of the units for the time axis and certain input parameters including ENERGYSAVEDAYS [s].
% date_stamped_output [logical] :: If true, use dates (not times) in messages to stdout.
% start_time [type(time_type)] :: The start time of the simulation.
% ntrunc [integer,pointer] :: The number of times the velocity has been truncated since the last call to write_energy.
% max_energy [real] :: The maximum permitted energy per unit mass. If there is more energy than this, the model should stop [L2 T-2 ~> m2 s-2].
% maxtrunc [integer] :: The number of truncations per energy save interval at which the run is stopped.
% write_stocks [logical] :: If true, write the integrated tracer amounts to stdout when the energy files are written.
% previous_calls [integer] :: The number of times write_energy has been called.
% prev_n [integer] :: The value of n from the last call.
% fileenergy_nc [type(mom_netcdf_file)] :: The file handle for the netCDF version of the energy file.
% fileenergy_ascii [integer] :: The unit number of the ascii version of the energy file.
% fields [type(mom_field)( num_fields +max_fields_)] :: fieldtype variables for the output fields.
% energyfile [character (len=200)] :: The name of the energy file with path.

Function/Subroutine Documentation¶

subroutine mom_sum_output/mom_sum_output_init(G, GV, US, param_file, directory, ntrnc, Input_start_time, CS)¶

MOM_sum_output_init initializes the parameters and settings for the MOM_sum_output module.

Parameters:

g :: [in] The ocean’s grid structure.
gv :: [in] The ocean’s vertical grid structure.
us :: [in] A dimensional unit scaling type
param_file :: [in] A structure to parse for run-time parameters.
directory :: [in] The directory where the energy file goes.
ntrnc :: [inout] The integer that stores the number of times the velocity has been truncated since the last call to write_energy.
input_start_time :: [in] The start time of the simulation.
cs :: A pointer that is set to point to the control structure for this module.

Call to:

depth_list_setup mom_error_handler::mom_error

subroutine mom_sum_output/mom_sum_output_end(CS)¶

MOM_sum_output_end deallocates memory used by the MOM_sum_output module.

Parameters:: cs :: The control structure returned by a previous call to MOM_sum_output_init.

subroutine mom_sum_output/write_energy(u, v, h, tv, day, n, G, GV, US, CS, tracer_CSp, dt_forcing)¶

This subroutine calculates and writes the total model energy, the energy and mass of each layer, and other globally integrated physical quantities.

Parameters:

g :: [in] The ocean’s grid structure.
gv :: [in] The ocean’s vertical grid structure.
us :: [in] A dimensional unit scaling type
u :: [in] The zonal velocity [L T-1 ~> m s-1].
v :: [in] The meridional velocity [L T-1 ~> m s-1].
h :: [in] Layer thicknesses [H ~> m or kg m-2].
tv :: [in] A structure pointing to various thermodynamic variables.
day :: [in] The current model time.
n :: [in] The time step number of the current execution.
cs :: The control structure returned by a previous call to MOM_sum_output_init.
tracer_csp :: Control structure with the tree of all registered tracer packages
dt_forcing :: [in] The forcing time step

Call to:

mom_tracer_flow_control::call_tracer_stocks mom_error_handler::mom_error

subroutine mom_sum_output/accumulate_net_input(fluxes, sfc_state, tv, dt, G, US, CS)¶

This subroutine accumulates the net input of volume, salt and heat, through the ocean surface for use in diagnosing conservation.

Parameters:

fluxes :: [in] A structure containing pointers to any possible forcing fields. Unused fields are unallocated.
sfc_state :: [in] A structure containing fields that describe the surface state of the ocean.
tv :: [in] A structure pointing to various thermodynamic variables.
dt :: [in] The amount of time over which to average [T ~> s].
g :: [in] The ocean’s grid structure.
us :: [in] A dimensional unit scaling type
cs :: The control structure returned by a previous call to MOM_sum_output_init.

Call to:

mom_error_handler::mom_error

subroutine mom_sum_output/depth_list_setup(G, GV, US, DL, CS)¶

This subroutine sets up an ordered list of depths, along with the cross sectional areas at each depth and the volume of fluid deeper than each depth. This might be read from a previously created file or it might be created anew. (For now only new creation occurs.

Parameters:

g :: [in] The ocean’s grid structure
gv :: [in] The ocean’s vertical grid structure.
us :: [in] A dimensional unit scaling type
dl :: [inout] The list of depths, areas and volumes to set up
cs :: The control structure returned by a previous call to MOM_sum_output_init.

Call to:

create_depth_list mom_error_handler::mom_error read_depth_list write_depth_list

Called from:

mom_sum_output_init

subroutine mom_sum_output/create_depth_list(G, DL, min_depth_inc)¶

create_depth_list makes an ordered list of depths, along with the cross sectional areas at each depth and the volume of fluid deeper than each depth.

Parameters:

g :: [in] The ocean’s grid structure.
dl :: [inout] The list of depths, areas and volumes to create
min_depth_inc :: [in] The minimum increment between depths in the list [Z ~> m]

Called from:

depth_list_setup

subroutine mom_sum_output/write_depth_list(G, US, DL, filename)¶

This subroutine writes out the depth list to the specified file.

Parameters:

g :: [in] The ocean’s grid structure.
us :: [in] A dimensional unit scaling type
dl :: [in] The list of depths, areas and volumes to write
filename :: [in] The path to the depth list file to write.

Call to:

area_chksum_attr depth_chksum_attr get_depth_list_checksums

Called from:

depth_list_setup

subroutine mom_sum_output/read_depth_list(G, US, DL, filename, require_chksum, file_matches)¶

This subroutine reads in the depth list from the specified file and allocates the memory within and sets up DL.

Parameters:

g :: [in] The ocean’s grid structure
us :: [in] A dimensional unit scaling type
dl :: [inout] The list of depths, areas and volumes
filename :: [in] The path to the depth list file to read.
require_chksum :: [in] If true, missing or mismatched depth and area checksums result in a fatal error.
file_matches :: [out] If present, this indicates whether the file has been read with matching depth and area checksums

Call to:

area_chksum_attr depth_chksum_attr get_depth_list_checksums mom_error_handler::mom_error

Called from:

depth_list_setup

subroutine mom_sum_output/get_depth_list_checksums(G, US, depth_chksum, area_chksum)¶

Return the checksums required to verify DEPTH_LIST_FILE contents.

This function computes checksums for the bathymetry (GbathyT) and masked area (mask2dT * areaT) fields of the model grid G, which are used to compute the depth list. A difference in checksum indicates that a different method was used to compute the grid data, and that any results using the depth list, such as APE, will not be reproducible.

Checksums are saved as hexadecimal strings, in order to avoid potential datatype issues with netCDF attributes.

Parameters:

g :: [in] Ocean grid structure
us :: [in] A dimensional unit scaling type
depth_chksum :: [out] Depth checksum hexstring
area_chksum :: [out] Area checksum hexstring

Called from:

read_depth_list write_depth_list