mom_io module reference¶

This module contains I/O framework code.

Data Types¶

vardesc

Type for describing a variable, typically a tracer.

Functions/Subroutines¶

`create_file()`	Routine creates a new NetCDF file.
`reopen_file()`	This routine opens an existing NetCDF file for output.
`read_axis_data()`	Read the data associated with a named axis in a file.
`num_timelevels()`	This function determines how many time levels a variable has.
`var_desc()`	Returns a vardesc type whose elements have been filled with the provided fields.
`modify_vardesc()`	This routine modifies the named elements of a vardesc type.
`cmor_long_std()`	This function returns the CMOR standard name given a CMOR longname, based on the standard pattern of character conversions.
`query_vardesc()`	This routine queries vardesc.
`safe_string_copy()`	Copies a string.
`ensembler()`	Returns a name with “%#E” or “%E” replaced with the ensemble member number.
`mom_file_exists()`	Returns true if the named file or its domain-decomposed variant exists.
`fms_file_exists()`	Returns true if the named file or its domain-decomposed variant exists.
`mom_read_data_1d()`	This function uses the fms_io function read_data to read 1-D data field named “fieldname” from file “filename”.
`mom_read_data_2d()`	This function uses the fms_io function read_data to read a distributed 2-D data field named “fieldname” from file “filename”.
`mom_read_data_3d()`	This function uses the fms_io function read_data to read a distributed 3-D data field named “fieldname” from file “filename”.
`mom_read_data_4d()`	This function uses the fms_io function read_data to read a distributed 4-D data field named “fieldname” from file “filename”.
`mom_read_vector_2d()`	This function uses the fms_io function read_data to read a pair of distributed 2-D data fields with names given by “[uv]_fieldname” from file “filename”.
`mom_read_vector_3d()`	This function uses the fms_io function read_data to read a pair of distributed 3-D data fields with names given by “[uv]_fieldname” from file “filename”.
`mom_io_init()`	Initialize the MOM_io module.

Detailed Description¶

This file contains a number of subroutines that manipulate NetCDF files and handle input and output of fields. These subroutines, along with their purpose, are:

create_file: create a new file and set up structures that are needed for subsequent output and write out the coordinates.
reopen_file: reopen an existing file for writing and set up structures that are needed for subsequent output.
open_input_file: open the indicated file for reading only.
close_file: close an open file.
synch_file: flush the buffers, completing all pending output.
write_field: write a field to an open file.
write_time: write a value of the time axis to an open file.
read_data: read a variable from an open file.
read_time: read a time from an open file.
name_output_file: provide a name for an output file based on a name root and the time of the output.
find_input_file: find a file that has been previously written by MOM and named by name_output_file and open it for reading.
handle_error: write an error code and quit.

Type Documentation¶

type mom_io/vardesc¶

Type for describing a variable, typically a tracer.

Type fields

% name [character (len=64)] :: Variable name in a NetCDF file.
% units [character (len=48)] :: Physical dimensions of the variable.
% longname [character (len=240)] :: Long name of the variable.
% hor_grid [character (len=8)] :: Horizontal grid: u, v, h, q, Cu, Cv, T, Bu, or 1.
% z_grid [character (len=8)] :: Vertical grid: L, i, or 1.
% t_grid [character (len=8)] :: Time description: s, p, or 1.
% cmor_field_name [character (len=64)] :: CMOR name.
% cmor_units [character (len=64)] :: CMOR physical dimensions of the variable.
% cmor_longname [character (len=240)] :: CMOR long name of the variable.
% conversion [real] :: for unit conversions, such as needed to convert from intensive to extensive

Function/Subroutine Documentation¶

subroutine mom_io/create_file(unit, filename, vars, novars, fields, threading, timeunit, G, dG, GV, checksums)¶

Routine creates a new NetCDF file. It also sets up structures that describe this file and variables that will later be written to this file. Type for describing a variable, typically a tracer.

Parameters

unit :: [out] unit id of an open file or -1 on a nonwriting PE with single file output
filename :: [in] full path to the file to create
vars :: [in] structures describing fields written to filename
novars :: [in] number of fields written to filename
fields :: [inout] array of fieldtypes for each variable
threading :: [in] SINGLE_FILE or MULTIPLE
timeunit :: [in] length of the units for time [s]. The default value is 86400.0, for 1 day.
g :: [in] ocean horizontal grid structure; G or dG is required if the new file uses any horizontal grid axes.
dg :: [in] dynamic horizontal grid structure; G or dG is required if the new file uses any horizontal grid axes.
gv :: [in] ocean vertical grid structure, which is required if the new file uses any vertical grid axes.
checksums :: [in] checksums of vars

Call to

mom_error_handler::mom_error

Called from

mom_ale::ale_writecoordinatefile reopen_file

subroutine mom_io/reopen_file(unit, filename, vars, novars, fields, threading, timeunit, G, dG, GV)¶

This routine opens an existing NetCDF file for output. If it does not find the file, a new file is created. It also sets up structures that describe this file and the variables that will later be written to this file.

Parameters

unit :: [out] unit id of an open file or -1 on a nonwriting PE with single file output
filename :: [in] full path to the file to create
vars :: [in] structures describing fields written to filename
novars :: [in] number of fields written to filename
fields :: [inout] array of fieldtypes for each variable
threading :: [in] SINGLE_FILE or MULTIPLE
timeunit :: [in] length of the units for time [s]. The default value is 86400.0, for 1 day.
g :: [in] ocean horizontal grid structure; G or dG is required if a new file uses any horizontal grid axes.
dg :: [in] dynamic horizontal grid structure; G or dG is required if a new file uses any horizontal grid axes.
gv :: [in] ocean vertical grid structure, which is required if a new file uses any vertical grid axes.

Call to

create_file mom_error_handler::mom_error

subroutine mom_io/read_axis_data(filename, axis_name, var)¶

Read the data associated with a named axis in a file.

Parameters

filename :: [in] Name of the file to read
axis_name :: [in] Name of the axis to read
var :: [out] The axis location data

Call to

mom_error_handler::mom_error

function mom_io/num_timelevels(filename, varname, min_dims) [integer]¶

This function determines how many time levels a variable has.

Parameters

filename :: [in] name of the file to read
varname :: [in] variable whose number of time levels are to be returned
min_dims :: [in] The minimum number of dimensions a variable must have if it has a time dimension. If the variable has 1 less dimension than this, then 0 is returned.

Return

undefined :: number of time levels varname has in filename

Call to

mom_string_functions::lowercase mom_error_handler::mom_error

Called from

mom_surface_forcing::surface_forcing_init

function mom_io/var_desc(name, units, longname, hor_grid, z_grid, t_grid, cmor_field_name, cmor_units, cmor_longname, conversion, caller) [type(vardesc)]¶

Returns a vardesc type whose elements have been filled with the provided fields. The argument name is required, while the others are optional and have default values that are empty strings or are appropriate for a 3-d tracer field at the tracer cell centers.

Parameters

name :: [in] variable name
units :: [in] variable units
longname :: [in] variable long name
hor_grid :: [in] variable horizonal staggering
z_grid :: [in] variable vertical staggering
t_grid :: [in] time description: s, p, or 1
cmor_field_name :: [in] CMOR name
cmor_units :: [in] CMOR physical dimensions of variable
cmor_longname :: [in] CMOR long name
conversion :: [in] for unit conversions, such as needed to convert from intensive to extensive
caller :: [in] calling routine?

Return

undefined :: vardesc type that is created

Call to

modify_vardesc safe_string_copy

Called from

mom_meke::meke_alloc_register_restart mom_open_boundary::open_boundary_register_restarts advection_test_tracer::register_advection_test_tracer mom_barotropic::register_barotropic_restarts boundary_impulse_tracer::register_boundary_impulse_tracer mom_controlled_forcing::register_ctrl_forcing_restarts dome_tracer::register_dome_tracer regional_dyes::register_dye_tracer dyed_obc_tracer::register_dyed_obc_tracer ideal_age_example::register_ideal_age_tracer isomip_tracer::register_isomip_tracer mom_ocmip2_cfc::register_ocmip2_cfc oil_tracer::register_oil_tracer pseudo_salt_tracer::register_pseudo_salt_tracer rgc_tracer::register_rgc_tracer user_tracer_example::user_register_tracer_example mom_shared_initialization::write_ocean_geometry_file mom_coord_initialization::write_vertgrid_file

subroutine mom_io/modify_vardesc(vd, name, units, longname, hor_grid, z_grid, t_grid, cmor_field_name, cmor_units, cmor_longname, conversion, caller)¶

This routine modifies the named elements of a vardesc type. All arguments are optional, except the vardesc type to be modified.

Parameters

vd :: [inout] vardesc type that is modified
name :: [in] name of variable
units :: [in] units of variable
longname :: [in] long name of variable
hor_grid :: [in] horizonal staggering of variable
z_grid :: [in] vertical staggering of variable
t_grid :: [in] time description: s, p, or 1
cmor_field_name :: [in] CMOR name
cmor_units :: [in] CMOR physical dimensions of variable
cmor_longname :: [in] CMOR long name
conversion :: [in] for unit conversions, such as needed to convert from intensive to extensive
caller :: [in] calling routine?

Call to

safe_string_copy

Called from

var_desc

function mom_io/cmor_long_std(longname) [character(len=len(longname))]¶

This function returns the CMOR standard name given a CMOR longname, based on the standard pattern of character conversions.

Parameters: longname :: [in] The CMOR longname being converted
Return: undefined :: The CMOR standard name generated from longname
Call to: mom_string_functions::lowercase
Called from: mom_tracer_registry::register_tracer_diagnostics

subroutine mom_io/query_vardesc(vd, name, units, longname, hor_grid, z_grid, t_grid, cmor_field_name, cmor_units, cmor_longname, conversion, caller)¶

This routine queries vardesc.

Parameters

vd :: [in] vardesc type that is queried
name :: [out] name of variable
units :: [out] units of variable
longname :: [out] long name of variable
hor_grid :: [out] horiz staggering of variable
z_grid :: [out] vert staggering of variable
t_grid :: [out] time description: s, p, or 1
cmor_field_name :: [out] CMOR name
cmor_units :: [out] CMOR physical dimensions of variable
cmor_longname :: [out] CMOR long name
conversion :: [out] for unit conversions, such as needed to convert from intensive to extensive
caller :: [in] calling routine?

Call to

safe_string_copy

Called from

subroutine mom_io/safe_string_copy(str1, str2, fieldnm, caller)¶

Copies a string.

Parameters

str1 :: [in] The string being copied
str2 :: [out] The string being copied into
fieldnm :: [in] The name of the field for error messages
caller :: [in] The calling routine for error messages

Call to

mom_error_handler::mom_error

Called from

modify_vardesc query_vardesc var_desc

function mom_io/ensembler(name, ens_no_in) [character(len=len(name))]¶

Returns a name with “%#E” or “%E” replaced with the ensemble member number.

Parameters

name :: [in] The name to be modified
ens_no_in :: [in] The number of the current ensemble member

Return

undefined :: The name encoded with the ensemble number

Call to

mom_error_handler::mom_error

function mom_io/mom_file_exists(filename, MOM_Domain) [logical]¶

Returns true if the named file or its domain-decomposed variant exists.

Parameters

filename :: [in] The name of the file being inquired about
mom_domain :: [in] The MOM_Domain that describes the decomposition

function mom_io/fms_file_exists(filename, domain, no_domain) [logical]¶

Returns true if the named file or its domain-decomposed variant exists.

Parameters

filename :: [in] The name of the file being inquired about
domain :: [in] The mpp domain2d that describes the decomposition
no_domain :: [in] This file does not use domain decomposition

subroutine mom_io/mom_read_data_1d(filename, fieldname, data, timelevel, scale)¶

This function uses the fms_io function read_data to read 1-D data field named “fieldname” from file “filename”.

Parameters

filename :: [in] The name of the file to read
fieldname :: [in] The variable name of the data in the file
data :: [inout] The 1-dimensional array into which the data
timelevel :: [in] The time level in the file to read
scale :: [in] A scaling factor that the field is multiplied by before they are returned.

subroutine mom_io/mom_read_data_2d(filename, fieldname, data, MOM_Domain, timelevel, position, scale)¶

This function uses the fms_io function read_data to read a distributed 2-D data field named “fieldname” from file “filename”. Valid values for “position” include CORNER, CENTER, EAST_FACE and NORTH_FACE.

Parameters

filename :: [in] The name of the file to read
fieldname :: [in] The variable name of the data in the file
data :: [inout] The 2-dimensional array into which the data should be read
mom_domain :: [in] The MOM_Domain that describes the decomposition
timelevel :: [in] The time level in the file to read
position :: [in] A flag indicating where this data is located
scale :: [in] A scaling factor that the field is multiplied by before they are returned.

Call to

mom_domains::get_simple_array_i_ind mom_domains::get_simple_array_j_ind

subroutine mom_io/mom_read_data_3d(filename, fieldname, data, MOM_Domain, timelevel, position, scale)¶

This function uses the fms_io function read_data to read a distributed 3-D data field named “fieldname” from file “filename”. Valid values for “position” include CORNER, CENTER, EAST_FACE and NORTH_FACE.

Parameters

filename :: [in] The name of the file to read
fieldname :: [in] The variable name of the data in the file
data :: [inout] The 3-dimensional array into which the data should be read
mom_domain :: [in] The MOM_Domain that describes the decomposition
timelevel :: [in] The time level in the file to read
position :: [in] A flag indicating where this data is located
scale :: [in] A scaling factor that the field is multiplied by before they are returned.

Call to

mom_domains::get_simple_array_i_ind mom_domains::get_simple_array_j_ind

subroutine mom_io/mom_read_data_4d(filename, fieldname, data, MOM_Domain, timelevel, position, scale)¶

This function uses the fms_io function read_data to read a distributed 4-D data field named “fieldname” from file “filename”. Valid values for “position” include CORNER, CENTER, EAST_FACE and NORTH_FACE.

Parameters

filename :: [in] The name of the file to read
fieldname :: [in] The variable name of the data in the file
data :: [inout] The 4-dimensional array into which the data should be read
mom_domain :: [in] The MOM_Domain that describes the decomposition
timelevel :: [in] The time level in the file to read
position :: [in] A flag indicating where this data is located
scale :: [in] A scaling factor that the field is multiplied by before they are returned.

Call to

mom_domains::get_simple_array_i_ind mom_domains::get_simple_array_j_ind

subroutine mom_io/mom_read_vector_2d(filename, u_fieldname, v_fieldname, u_data, v_data, MOM_Domain, timelevel, stagger, scalar_pair, scale)¶

This function uses the fms_io function read_data to read a pair of distributed 2-D data fields with names given by “[uv]_fieldname” from file “filename”. Valid values for “stagger” include CGRID_NE, BGRID_NE, and AGRID.

Parameters

filename :: [in] The name of the file to read
u_fieldname :: [in] The variable name of the u data in the file
v_fieldname :: [in] The variable name of the v data in the file
u_data :: [inout] The 2 dimensional array into which the u-component of the data should be read
v_data :: [inout] The 2 dimensional array into which the v-component of the data should be read
mom_domain :: [in] The MOM_Domain that describes the decomposition
timelevel :: [in] The time level in the file to read
stagger :: [in] A flag indicating where this vector is discretized
scalar_pair :: [in] If true, a pair of scalars are to be read.cretized
scale :: [in] A scaling factor that the fields are multiplied by before they are returned.

Call to

mom_domains::get_simple_array_i_ind mom_domains::get_simple_array_j_ind

subroutine mom_io/mom_read_vector_3d(filename, u_fieldname, v_fieldname, u_data, v_data, MOM_Domain, timelevel, stagger, scalar_pair, scale)¶

This function uses the fms_io function read_data to read a pair of distributed 3-D data fields with names given by “[uv]_fieldname” from file “filename”. Valid values for “stagger” include CGRID_NE, BGRID_NE, and AGRID.

Parameters

filename :: [in] The name of the file to read
u_fieldname :: [in] The variable name of the u data in the file
v_fieldname :: [in] The variable name of the v data in the file
u_data :: [inout] The 3 dimensional array into which the u-component of the data should be read
v_data :: [inout] The 3 dimensional array into which the v-component of the data should be read
mom_domain :: [in] The MOM_Domain that describes the decomposition
timelevel :: [in] The time level in the file to read
stagger :: [in] A flag indicating where this vector is discretized
scalar_pair :: [in] If true, a pair of scalars are to be read.cretized
scale :: [in] A scaling factor that the fields are multiplied by before they are returned.

Call to

mom_domains::get_simple_array_i_ind mom_domains::get_simple_array_j_ind

subroutine mom_io/mom_io_init(param_file)¶

Initialize the MOM_io module.

Parameters: param_file :: [in] structure indicating the open file to parse for model parameter values.