mom_io module reference

This module contains I/O framework code.

More…

Data Types

attribute_info

Type that stores for a global file attribute.

axis_info

Type that stores information that can be used to create a non-decomposed axis.

vardesc

Type for describing a 3-d variable for output.

Functions/Subroutines

create_file()

Routine creates a new NetCDF file.

reopen_file()

This routine opens an existing NetCDF file for output.

num_timelevels()

This function determines how many time levels a variable has in a file.

get_var_sizes()

get_var_sizes returns the number and size of dimensions associate with a variable in a file. Usually only the root PE does the read, and then the information is broadcast

read_var_sizes()

read_var_sizes returns the number and size of dimensions associated with a variable in a file. If the variable is not in the file the returned sizes are all 0 and ndims is -1. Every processor for which this is called does the reading.

read_variable_0d()

Read a real scalar variable from a netCDF file with the root PE, and broadcast the results to all the other PEs.

read_variable_1d()

Read a 1-d real variable from a netCDF file with the root PE, and broadcast the results to all the other PEs.

read_variable_0d_int()

Read a integer scalar variable from a netCDF file with the root PE, and broadcast the results to all the other PEs.

read_variable_1d_int()

Read a 1-d integer variable from a netCDF file with the root PE, and broadcast the results to all the other PEs.

read_attribute_str()

Read a character-string global or variable attribute.

read_attribute_int32()

Read a 32-bit integer global or variable attribute.

read_attribute_int64()

Read a 64-bit integer global or variable attribute.

read_attribute_real()

Read a real global or variable attribute.

open_file_to_read()

Open a netcdf file for reading, with error handling.

close_file_to_read()

Close a netcdf file that had been opened for reading, with error handling.

get_varid()

get_varid finds the netcdf handle for the potentially case-insensitive variable name in a file

verify_variable_units()

Verify that a file contains a named variable with the expected units.

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.

position_from_horgrid()

set_axis_info()

Store information that can be used to create an axis in a subsequent call to create_file.

delete_axis_info()

Delete the information in an array of axis_info() types and deallocate memory in them.

set_attribute_info()

Store information that can be used to create an attribute in a subsequent call to create_file.

delete_attribute_info()

Delete the information in an array of attribute_info() types and deallocate memory in them.

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.

mom_read_data_0d()

Read a scalar from file using infrastructure I/O.

mom_read_data_0d_int()

Read a scalar integer from file using infrastructure I/O.

mom_read_data_1d()

Read a 1d array from file using infrastructure I/O.

mom_read_data_1d_int()

Read a 1d integer array from file using infrastructure I/O.

mom_read_data_2d()

Read a 2d array from file using infrastructure I/O.

mom_read_data_2d_region()

Read a 2d region array from file using infrastructure I/O.

mom_read_data_3d()

Read a 3d array from file using infrastructure I/O.

mom_read_data_4d()

Read a 4d array from file using infrastructure I/O.

mom_read_vector_2d()

Read a 2d vector tuple from file using infrastructure I/O.

mom_read_vector_3d()

Read a 3d vector tuple from file using infrastructure I/O.

mom_write_field_4d()

Write a 4d field to an output file, potentially with rotation.

mom_write_field_3d()

Write a 3d field to an output file, potentially with rotation.

mom_write_field_2d()

Write a 2d field to an output file, potentially with rotation.

mom_write_field_1d()

Write a 1d field to an output file.

mom_write_field_0d()

Write a 0d field to an output file.

field_size()

Given filename and fieldname, this subroutine returns the size of the field in the file.

safe_string_copy()

Copies a string.

ensembler()

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

get_filename_appendix()

Provide a string to append to filenames, to differentiate ensemble members, for example.

write_version_number()

Write a file version number to the log file or other output file.

open_namelist_file()

Open a single namelist file that is potentially readable by all PEs.

check_nml_error()

Checks the iostat argument that is returned after reading a namelist variable and writes a message if there is an error.

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/attribute_info

Type that stores for a global file attribute.

Type fields
  • % name [character (len=:),allocatable, private] :: The name of this attribute.

  • % att_val [character (len=:),allocatable, private] :: The values of this attribute.

type mom_io/axis_info

Type that stores information that can be used to create a non-decomposed axis.

Type fields
  • % name [character (len=32),private] :: The name of this axis for use in files.

  • % longname [character (len=256),private] :: A longer name describing this axis.

  • % units [character (len=48),private] :: The units of the axis labels.

  • % cartesian [character (len=8),private] :: A variable indicating which direction this axis corresponds with. Valid values include ‘X’, ‘Y’, ‘Z’, ‘T’, and ‘N’ for none.

  • % sense [integer,private] :: This is 1 for axes whose values increase upward, or -1 if they increase downward. The default, 0, is ignored.

  • % ax_size [integer,private] :: The number of elements in this axis.

  • % ax_data [real(:),allocatable, private] :: The values of the data on the axis.

type mom_io/vardesc

Type for describing a 3-d variable for output.

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

  • % dim_names [character (len=32)(5)] :: The names in the file of the axes for this variable.

  • % position [integer] :: An integer encoding the horizontal position, it may CENTER, CORNER, EAST_FACE, NORTH_FACE, or 0.

Function/Subroutine Documentation

subroutine mom_io/create_file(IO_handle, filename, vars, novars, fields, threading, timeunit, G, dG, GV, checksums, extra_axes, global_atts)

Routine creates a new NetCDF file. It also sets up fieldtype structures that describe this file and variables that will later be written to this file.

Parameters
  • io_handle :: [inout] Handle for a files or fileset that is to be opened or reopened for writing

  • 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

  • extra_axes :: [in] Types with information about some axes that might be used in this file

  • global_atts :: [in] Global attributes to write to this file

Call to

mom_string_functions::lowercase mom_error_handler::mom_error position_from_horgrid

Called from

mom_ale::ale_writecoordinatefile reopen_file

subroutine mom_io/reopen_file(IO_handle, filename, vars, novars, fields, threading, timeunit, G, dG, GV, extra_axes, global_atts)

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
  • io_handle :: [inout] Handle for a file or fileset that is to be opened or reopened for writing

  • 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.

  • extra_axes :: [in] Types with information about some axes that might be used in this file

  • global_atts :: [in] Global attributes to write to this file

Call to

create_file 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 in a file.

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

get_var_sizes mom_error_handler::mom_error

Called from

mom_surface_forcing::surface_forcing_init

subroutine mom_io/get_var_sizes(filename, varname, ndims, sizes, match_case, caller, all_read, dim_names, ncid_in)

get_var_sizes returns the number and size of dimensions associate with a variable in a file. Usually only the root PE does the read, and then the information is broadcast

Parameters
  • filename :: [in] Name of the file to read, used here in messages

  • varname :: [in] The variable name, used here for messages

  • ndims :: [out] The number of dimensions to the variable

  • sizes :: [out] The dimension sizes, or 0 for extra values

  • match_case :: [in] If false, allow for variables name matches to be case insensitive, but take a perfect match if found. The default is true.

  • caller :: [in] The name of a calling routine for use in error messages

  • all_read :: [in] If present and true, all PEs that call this routine actually do the read, otherwise only root PE reads and then it broadcasts the results.

  • dim_names :: [out] The names of the dimensions for this variable

  • ncid_in :: [in] The netCDF ID of an open file. If absent, the file is opened and closed within this routine.

Call to

read_var_sizes

Called from

field_size num_timelevels mom_wave_interface::surface_bands_by_data_override

subroutine mom_io/read_var_sizes(filename, varname, ndims, sizes, match_case, caller, dim_names, ncid_in)

read_var_sizes returns the number and size of dimensions associated with a variable in a file. If the variable is not in the file the returned sizes are all 0 and ndims is -1. Every processor for which this is called does the reading.

Parameters
  • filename :: [in] Name of the file to read, used here in messages

  • varname :: [in] The variable name, used here for messages

  • ndims :: [out] The number of dimensions to the variable

  • sizes :: [out] The dimension sizes, or 0 for extra values

  • match_case :: [in] If false, allow for variables name matches to be case insensitive, but take a perfect match if found. The default is true.

  • caller :: [in] The name of a calling routine for use in error messages

  • dim_names :: [out] The names of the dimensions for this variable

  • ncid_in :: [in] The netCDF ID of an open file. If absent, the file is opened and closed within this routine.

Call to

close_file_to_read get_varid mom_error_handler::mom_error open_file_to_read

Called from

get_var_sizes

subroutine mom_io/read_variable_0d(filename, varname, var, ncid_in, scale)

Read a real scalar variable from a netCDF file with the root PE, and broadcast the results to all the other PEs.

Parameters
  • filename :: [in] The name of the file to read

  • varname :: [in] The variable name of the data in the file

  • var :: [inout] The scalar into which to read the data

  • ncid_in :: [in] The netCDF ID of an open file. If absent, the file is opened and closed within this routine

  • scale :: [in] A scaling factor that the variable is multiplied by before it is returned

Call to

close_file_to_read get_varid mom_error_handler::mom_error open_file_to_read

subroutine mom_io/read_variable_1d(filename, varname, var, ncid_in, scale)

Read a 1-d real variable from a netCDF file with the root PE, and broadcast the results to all the other PEs.

Parameters
  • filename :: [in] The name of the file to read

  • varname :: [in] The variable name of the data in the file

  • var :: [inout] The 1-d array into which to read the data

  • ncid_in :: [in] The netCDF ID of an open file. If absent, the file is opened and closed within this routine

  • scale :: [in] A scaling factor that the variable is multiplied by before it is returned

Call to

close_file_to_read get_varid mom_error_handler::mom_error open_file_to_read

subroutine mom_io/read_variable_0d_int(filename, varname, var, ncid_in)

Read a integer scalar variable from a netCDF file with the root PE, and broadcast the results to all the other PEs.

Parameters
  • filename :: [in] The name of the file to read

  • varname :: [in] The variable name of the data in the file

  • var :: [inout] The scalar into which to read the data

  • ncid_in :: [in] The netCDF ID of an open file. If absent, the file is opened and closed within this routine.

Call to

close_file_to_read get_varid mom_error_handler::mom_error open_file_to_read

subroutine mom_io/read_variable_1d_int(filename, varname, var, ncid_in)

Read a 1-d integer variable from a netCDF file with the root PE, and broadcast the results to all the other PEs.

Parameters
  • filename :: [in] The name of the file to read

  • varname :: [in] The variable name of the data in the file

  • var :: [inout] The 1-d array into which to read the data

  • ncid_in :: [in] The netCDF ID of an open file. If absent, the file is opened and closed within this routine.

Call to

close_file_to_read get_varid mom_error_handler::mom_error open_file_to_read

subroutine mom_io/read_attribute_str(filename, attname, att_val, varname, found, all_read, ncid_in)

Read a character-string global or variable attribute.

Parameters
  • filename :: [in] Name of the file to read

  • attname :: [in] Name of the attribute to read

  • att_val :: [out] The value of the attribute

  • varname :: [in] The name of the variable whose attribute will be read. If missing, read a global attribute.

  • found :: [out] Returns true if the attribute is found

  • all_read :: [in] If present and true, all PEs that call this routine actually do the read, otherwise only root PE reads and then broadcasts the results.

  • ncid_in :: [in] The netCDF ID of an open file. If absent, the file is opened and closed within this routine.

Call to

close_file_to_read get_varid mom_error_handler::mom_error open_file_to_read

subroutine mom_io/read_attribute_int32(filename, attname, att_val, varname, found, all_read, ncid_in)

Read a 32-bit integer global or variable attribute.

Parameters
  • filename :: [in] Name of the file to read

  • attname :: [in] Name of the attribute to read

  • att_val :: [out] The value of the attribute

  • varname :: [in] The name of the variable whose attribute will be read. If missing, read a global attribute.

  • found :: [out] Returns true if the attribute is found

  • all_read :: [in] If present and true, all PEs that call this routine actually do the read, otherwise only root PE reads and then broadcasts the results.

  • ncid_in :: [in] The netCDF ID of an open file. If absent, the file is opened and closed within this routine.

Call to

close_file_to_read get_varid mom_error_handler::mom_error open_file_to_read

subroutine mom_io/read_attribute_int64(filename, attname, att_val, varname, found, all_read, ncid_in)

Read a 64-bit integer global or variable attribute.

Parameters
  • filename :: [in] Name of the file to read

  • attname :: [in] Name of the attribute to read

  • att_val :: [out] The value of the attribute

  • varname :: [in] The name of the variable whose attribute will be read. If missing, read a global attribute.

  • found :: [out] Returns true if the attribute is found

  • all_read :: [in] If present and true, all PEs that call this routine actually do the read, otherwise only root PE reads and then broadcasts the results.

  • ncid_in :: [in] The netCDF ID of an open file. If absent, the file is opened and closed within this routine.

Call to

get_varid mom_error_handler::mom_error open_file_to_read

subroutine mom_io/read_attribute_real(filename, attname, att_val, varname, found, all_read, ncid_in)

Read a real global or variable attribute.

Parameters
  • filename :: [in] Name of the file to read

  • attname :: [in] Name of the attribute to read

  • att_val :: [out] The value of the attribute

  • varname :: [in] The name of the variable whose attribute will be read. If missing, read a global attribute.

  • found :: [out] Returns true if the attribute is found

  • all_read :: [in] If present and true, all PEs that call this routine actually do the read, otherwise only root PE reads and then broadcasts the results.

  • ncid_in :: [in] The netCDF ID of an open file. If absent, the file is opened and closed within this routine.

Call to

close_file_to_read get_varid mom_error_handler::mom_error open_file_to_read

subroutine mom_io/open_file_to_read(filename, ncid, success)

Open a netcdf file for reading, with error handling.

Parameters
  • filename :: [in] path and name of the file to open for reading

  • ncid :: [out] The netcdf handle for the file

  • success :: [out] Returns true if the file was opened, or if this argument is not present, failure is fatal error.

Call to

mom_error_handler::mom_error

Called from

read_attribute_int32 read_attribute_int64 read_attribute_real read_attribute_str read_var_sizes read_variable_0d read_variable_0d_int read_variable_1d read_variable_1d_int mom_tracer_z_init::read_z_edges verify_variable_units

subroutine mom_io/close_file_to_read(ncid, filename)

Close a netcdf file that had been opened for reading, with error handling.

Parameters
  • ncid :: [inout] The netcdf handle for the file to close

  • filename :: [in] path and name of the file to close

Call to

mom_error_handler::mom_error

Called from

read_attribute_int32 read_attribute_real read_attribute_str read_var_sizes read_variable_0d read_variable_0d_int read_variable_1d read_variable_1d_int mom_tracer_z_init::read_z_edges

subroutine mom_io/get_varid(varname, ncid, filename, varid, match_case, found)

get_varid finds the netcdf handle for the potentially case-insensitive variable name in a file

Parameters
  • varname :: [in] The name of the variable that is being sought

  • ncid :: [in] The open netcdf handle for the file

  • filename :: [in] name of the file to read, used here in messages

  • varid :: [out] The netcdf handle for the variable

  • match_case :: [in] If false, allow for variables name matches to be case insensitive, but take a perfect match if found. The default is true.

  • found :: [out] Returns true if the attribute is found

Call to

mom_string_functions::lowercase mom_error_handler::mom_error

Called from

read_attribute_int32 read_attribute_int64 read_attribute_real read_attribute_str read_var_sizes read_variable_0d read_variable_0d_int read_variable_1d read_variable_1d_int

subroutine mom_io/verify_variable_units(filename, varname, expected_units, msg, ierr, alt_units)

Verify that a file contains a named variable with the expected units.

Parameters
  • filename :: [in] File name

  • varname :: [in] Variable name

  • expected_units :: [in] Expected units of variable

  • msg :: [inout] Message to use for errors

  • ierr :: [out] True if an error occurs

  • alt_units :: [in] Alterate acceptable units of variable

Call to

open_file_to_read

Called from

mom_regridding::initialize_regridding

function mom_io/var_desc(name, units, longname, hor_grid, z_grid, t_grid, cmor_field_name, cmor_units, cmor_longname, conversion, caller, position, dim_names, fixed) [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] A character string indicating the horizontal position of this variable

  • 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] The calling routine for error messages

  • position :: [in] A coded integer indicating the horizontal position of this variable if it has such dimensions. Valid values include CORNER, CENTER, EAST_FACE NORTH_FACE, and 0 for no horizontal dimensions.

  • dim_names :: [in] The names of the dimensions of this variable

  • fixed :: [in] If true, this does not evolve with time

Return

undefined :: vardesc type that is created

Call to

modify_vardesc safe_string_copy

Called from

mom_meke::meke_alloc_register_restart mom_mixed_layer_restrat::mixedlayer_restrat_register_restarts 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_cfc_cap::register_cfc_cap 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 nw2_tracers::register_nw2_tracers mom_ocmip2_cfc::register_ocmip2_cfc oil_tracer::register_oil_tracer pseudo_salt_tracer::register_pseudo_salt_tracer mom_dynamics_split_rk2::register_restarts_dyn_split_rk2 rgc_tracer::register_rgc_tracer user_tracer_example::user_register_tracer_example mom_shared_initialization::write_ocean_geometry_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, position, dim_names)

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] horizontal 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] A multiplicative factor for unit conversions, such as needed to convert from intensive to extensive or dimensional consistency testing

  • caller :: [in] The calling routine for error messages

  • position :: [in] A coded integer indicating the horizontal position of this variable if it has such dimensions. Valid values include CORNER, CENTER, EAST_FACE NORTH_FACE, and 0 for no horizontal dimensions.

  • dim_names :: [in] The names of the dimensions of this variable

Call to

mom_error_handler::mom_error position_from_horgrid safe_string_copy

Called from

var_desc

function mom_io/position_from_horgrid(hor_grid) [integer]
Parameters

hor_grid :: [in] horizontal staggering of variable

Called from

create_file modify_vardesc query_vardesc

subroutine mom_io/set_axis_info(axis, name, units, longname, ax_size, ax_data, cartesian, sense)

Store information that can be used to create an axis in a subsequent call to create_file.

Parameters
  • axis :: [inout] A type with information about a named axis

  • name :: [in] The name of this axis for use in files

  • units :: [in] The units of the axis labels

  • longname :: [in] Long name of the axis variable

  • ax_size :: [in] The number of elements in this axis

  • ax_data :: [in] The values of the data on the axis

  • cartesian :: [in] A variable indicating which direction this axis axis corresponds with. Valid values include ‘X’, ‘Y’, ‘Z’, ‘T’, and ‘N’ (the default) for none.

  • sense :: [in] This is 1 for axes whose values increase upward, or -1 if they increase downward. The default, 0, is ignored.

Call to

mom_error_handler::mom_error safe_string_copy

subroutine mom_io/delete_axis_info(axes)

Delete the information in an array of axis_info() types and deallocate memory in them. types and deallocate memory in them.

Parameters

axes :: [inout] An array with information about named axes

subroutine mom_io/set_attribute_info(attribute, name, str_value)

Store information that can be used to create an attribute in a subsequent call to create_file.

Parameters
  • attribute :: [inout] A type with information about a named attribute

  • name :: [in] The name of this attribute for use in files

  • str_value :: [in] The value of this attribute

subroutine mom_io/delete_attribute_info(atts)

Delete the information in an array of attribute_info() types and deallocate memory in them. types and deallocate memory in them.

Parameters

atts :: [inout] An array of global attributes

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, position, dim_names)

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] horizontal staggering of variable

  • z_grid :: [out] verticle 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?

  • position :: [out] A coded integer indicating the horizontal position of this variable if it has such dimensions. Valid values include CORNER, CENTER, EAST_FACE NORTH_FACE, and 0 for no horizontal dimensions.

  • dim_names :: [out] The names of the dimensions of this variable

Call to

position_from_horgrid safe_string_copy

Called from

advection_test_tracer::advection_test_stock boundary_impulse_tracer::boundary_impulse_stock mom_cfc_cap::cfc_cap_stock regional_dyes::dye_stock ideal_age_example::ideal_age_stock advection_test_tracer::initialize_advection_test_tracer boundary_impulse_tracer::initialize_boundary_impulse_tracer dome_tracer::initialize_dome_tracer dyed_obc_tracer::initialize_dyed_obc_tracer ideal_age_example::initialize_ideal_age_tracer isomip_tracer::initialize_isomip_tracer oil_tracer::initialize_oil_tracer pseudo_salt_tracer::initialize_pseudo_salt_tracer rgc_tracer::initialize_rgc_tracer mom_ocmip2_cfc::ocmip2_cfc_stock oil_tracer::oil_stock pseudo_salt_tracer::pseudo_salt_stock boundary_impulse_tracer::register_boundary_impulse_tracer regional_dyes::register_dye_tracer ideal_age_example::register_ideal_age_tracer oil_tracer::register_oil_tracer pseudo_salt_tracer::register_pseudo_salt_tracer mom_tracer_registry::register_tracer user_tracer_example::user_initialize_tracer user_tracer_example::user_tracer_stock

subroutine mom_io/mom_read_data_0d(filename, fieldname, data, timelevel, scale, MOM_Domain, global_file, file_may_be_4d)

Read a scalar from file using infrastructure I/O.

Parameters
  • filename :: [in] Input filename

  • fieldname :: [in] Field variable name

  • data :: [inout] Field value

  • timelevel :: [in] Time level to read in file

  • scale :: [in] Rescale factor

  • mom_domain :: [in] Model domain decomposition

  • global_file :: [in] If true, read from a single file

  • file_may_be_4d :: [in] If true, fields may be stored as 4d arrays in the file.

subroutine mom_io/mom_read_data_0d_int(filename, fieldname, data, timelevel)

Read a scalar integer from file using infrastructure I/O.

Parameters
  • filename :: [in] Input filename

  • fieldname :: [in] Field variable name

  • data :: [inout] Field value

  • timelevel :: [in] Time level to read in file

subroutine mom_io/mom_read_data_1d(filename, fieldname, data, timelevel, scale, MOM_Domain, global_file, file_may_be_4d)

Read a 1d array from file using infrastructure I/O.

Parameters
  • filename :: [in] Input filename

  • fieldname :: [in] Field variable name

  • data :: [inout] Field value

  • timelevel :: [in] Time level to read in file

  • scale :: [in] Rescale factor

  • mom_domain :: [in] Model domain decomposition

  • global_file :: [in] If true, read from a single file

  • file_may_be_4d :: [in] If true, fields may be stored as 4d arrays in the file.

subroutine mom_io/mom_read_data_1d_int(filename, fieldname, data, timelevel)

Read a 1d integer array from file using infrastructure I/O.

Parameters
  • filename :: [in] Input filename

  • fieldname :: [in] Field variable name

  • data :: [inout] Field value

  • timelevel :: [in] Time level to read in file

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

Read a 2d array from file using infrastructure I/O.

Parameters
  • filename :: [in] Input filename

  • fieldname :: [in] Field variable name

  • data :: [inout] Field value

  • mom_domain :: [in] Model domain decomposition

  • timelevel :: [in] Time level to read in file

  • position :: [in] Grid positioning flag

  • scale :: [in] Rescale factor

  • global_file :: [in] If true, read from a single file

  • file_may_be_4d :: [in] If true, fields may be stored as 4d arrays in the file.

subroutine mom_io/mom_read_data_2d_region(filename, fieldname, data, start, nread, MOM_domain, no_domain, scale, turns)

Read a 2d region array from file using infrastructure I/O.

Parameters
  • filename :: [in] Input filename

  • fieldname :: [in] Field variable name

  • data :: [inout] Field value

  • start :: [in] Starting index for each axis. In 2d, start(3:4) must be 1.

  • nread :: [in] Number of values to read along each axis. In 2d, nread(3:4) must be 1.

  • mom_domain :: [in] Model domain decomposition

  • no_domain :: [in] If true, field does not use domain decomposion.

  • scale :: [in] Rescale factor

  • turns :: [in] Number of quarter turns from input to model grid

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

Read a 3d array from file using infrastructure I/O.

Parameters
  • filename :: [in] Input filename

  • fieldname :: [in] Field variable name

  • data :: [inout] Field value

  • mom_domain :: [in] Model domain decomposition

  • timelevel :: [in] Time level to read in file

  • position :: [in] Grid positioning flag

  • scale :: [in] Rescale factor

  • global_file :: [in] If true, read from a single file

  • file_may_be_4d :: [in] If true, fields may be stored as 4d arrays in the file.

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

Read a 4d array from file using infrastructure I/O.

Parameters
  • filename :: [in] Input filename

  • fieldname :: [in] Field variable name

  • data :: [inout] Field value

  • mom_domain :: [in] Model domain decomposition

  • timelevel :: [in] Time level to read in file

  • position :: [in] Grid positioning flag

  • scale :: [in] Rescale factor

  • global_file :: [in] If true, read from a single file

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

Read a 2d vector tuple from file using infrastructure I/O.

Parameters
  • filename :: [in] Input filename

  • u_fieldname :: [in] Field variable name in u

  • v_fieldname :: [in] Field variable name in v

  • u_data :: [inout] Field value in u

  • v_data :: [inout] Field value in v

  • mom_domain :: [in] Model domain decomposition

  • timelevel :: [in] Time level to read in file

  • stagger :: [in] Grid staggering flag

  • scalar_pair :: [in] True if tuple is not a vector

  • scale :: [in] Rescale factor

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

Read a 3d vector tuple from file using infrastructure I/O.

Parameters
  • filename :: [in] Input filename

  • u_fieldname :: [in] Field variable name in u

  • v_fieldname :: [in] Field variable name in v

  • u_data :: [inout] Field value in u

  • v_data :: [inout] Field value in v

  • mom_domain :: [in] Model domain decomposition

  • timelevel :: [in] Time level to read in file

  • stagger :: [in] Grid staggering flag

  • scalar_pair :: [in] True if tuple is not a vector

  • scale :: [in] Rescale factor

subroutine mom_io/mom_write_field_4d(IO_handle, field_md, MOM_domain, field, tstamp, tile_count, fill_value, turns, scale)

Write a 4d field to an output file, potentially with rotation.

Parameters
  • io_handle :: [inout] Handle for a file that is open for writing

  • field_md :: [in] Field type with metadata

  • mom_domain :: [in] The MOM_Domain that describes the decomposition

  • field :: [inout] Unrotated field to write

  • tstamp :: [in] Model timestamp

  • tile_count :: [in] PEs per tile (default: 1)

  • fill_value :: [in] Missing data fill value

  • turns :: [in] Number of quarter-turns to rotate the data

  • scale :: [in] A scaling factor that the field is multiplied by before it is written

subroutine mom_io/mom_write_field_3d(IO_handle, field_md, MOM_domain, field, tstamp, tile_count, fill_value, turns, scale)

Write a 3d field to an output file, potentially with rotation.

Parameters
  • io_handle :: [inout] Handle for a file that is open for writing

  • field_md :: [in] Field type with metadata

  • mom_domain :: [in] The MOM_Domain that describes the decomposition

  • field :: [inout] Unrotated field to write

  • tstamp :: [in] Model timestamp

  • tile_count :: [in] PEs per tile (default: 1)

  • fill_value :: [in] Missing data fill value

  • turns :: [in] Number of quarter-turns to rotate the data

  • scale :: [in] A scaling factor that the field is multiplied by before it is written

subroutine mom_io/mom_write_field_2d(IO_handle, field_md, MOM_domain, field, tstamp, tile_count, fill_value, turns, scale)

Write a 2d field to an output file, potentially with rotation.

Parameters
  • io_handle :: [inout] Handle for a file that is open for writing

  • field_md :: [in] Field type with metadata

  • mom_domain :: [in] The MOM_Domain that describes the decomposition

  • field :: [inout] Unrotated field to write

  • tstamp :: [in] Model timestamp

  • tile_count :: [in] PEs per tile (default: 1)

  • fill_value :: [in] Missing data fill value

  • turns :: [in] Number of quarter-turns to rotate the data

  • scale :: [in] A scaling factor that the field is multiplied by before it is written

subroutine mom_io/mom_write_field_1d(IO_handle, field_md, field, tstamp, fill_value, scale)

Write a 1d field to an output file.

Parameters
  • io_handle :: [inout] Handle for a file that is open for writing

  • field_md :: [in] Field type with metadata

  • field :: [in] Field to write

  • tstamp :: [in] Model timestamp

  • fill_value :: [in] Missing data fill value

  • scale :: [in] A scaling factor that the field is multiplied by before it is written

subroutine mom_io/mom_write_field_0d(IO_handle, field_md, field, tstamp, fill_value, scale)

Write a 0d field to an output file.

Parameters
  • io_handle :: [inout] Handle for a file that is open for writing

  • field_md :: [in] Field type with metadata

  • field :: [in] Field to write

  • tstamp :: [in] Model timestamp

  • fill_value :: [in] Missing data fill value

  • scale :: [in] A scaling factor that the field is multiplied by before it is written

subroutine mom_io/field_size(filename, fieldname, sizes, field_found, no_domain, ndims, ncid_in)

Given filename and fieldname, this subroutine returns the size of the field in the file.

Parameters
  • filename :: [in] The name of the file to read

  • fieldname :: [in] The name of the variable whose sizes are returned

  • sizes :: [inout] The sizes of the variable in each dimension

  • field_found :: [out] This indicates whether the field was found in the input file. Without this argument, there is a fatal error if the field is not found.

  • no_domain :: [in] If present and true, do not check for file names with an appended tile number. If ndims is present, the default changes to true.

  • ndims :: [out] The number of dimensions to the variable

  • ncid_in :: [in] The netCDF ID of an open file. If absent, the file is opened and closed within this routine.

Call to

get_var_sizes mom_error_handler::mom_error

Called from

mom_state_initialization::initialize_sponges_file mom_tidal_mixing::read_tidal_constituents

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 set_axis_info 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

subroutine mom_io/get_filename_appendix(suffix)

Provide a string to append to filenames, to differentiate ensemble members, for example.

Parameters

suffix :: [out] A string to append to filenames

Called from

mom_diag_mediator::diag_mediator_init

subroutine mom_io/write_version_number(version, tag, unit)

Write a file version number to the log file or other output file.

Parameters
  • version :: [in] A string that contains the routine name and version

  • tag :: [in] A tag name to add to the message

  • unit :: [in] An alternate unit number for output

function mom_io/open_namelist_file(file) [integer]

Open a single namelist file that is potentially readable by all PEs.

Parameters

file :: [in] The file to open, by default “input.nml”

Return

undefined :: The opened unit number of the namelist file

Called from

mom_get_input::get_mom_input

function mom_io/check_nml_error(IOstat, nml_name) [integer]

Checks the iostat argument that is returned after reading a namelist variable and writes a message if there is an error.

Parameters
  • iostat :: [in] An I/O status field from a namelist read call

  • nml_name :: [in] The name of the namelist

Return

undefined :: A copy of IOstat that is returned to preserve legacy function behavior

Called from

mom_get_input::get_mom_input mom_main

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.