namespace mom_io¶

Overview¶

This module contains I/O framework code. More…

namespace mom_io {

// interfaces

interface file_exists;
interface mom_read_data;
interface mom_read_vector;

// global functions

subroutine, public create_file(
    unit unit,
    filename filename,
    vars vars,
    novars novars,
    fields fields,
    threading threading,
    timeunit timeunit,
    G G,
    dG dG,
    GV GV,
    checksums checksums
    );

subroutine, public reopen_file(
    unit unit,
    filename filename,
    vars vars,
    novars novars,
    fields fields,
    threading threading,
    timeunit timeunit,
    G G,
    dG dG,
    GV GV
    );

subroutine, public read_axis_data(filename filename, axis_name axis_name, var var);
integer function, public num_timelevels(filename filename, varname varname, min_dims min_dims);

type(vardesc) function, public var_desc(
    name name,
    units units,
    longname longname,
    hor_grid hor_grid,
    z_grid z_grid,
    t_grid t_grid,
    cmor_field_name cmor_field_name,
    cmor_units cmor_units,
    cmor_longname cmor_longname,
    conversion conversion,
    caller caller
    );

subroutine, public modify_vardesc(
    vd vd,
    name name,
    units units,
    longname longname,
    hor_grid hor_grid,
    z_grid z_grid,
    t_grid t_grid,
    cmor_field_name cmor_field_name,
    cmor_units cmor_units,
    cmor_longname cmor_longname,
    conversion conversion,
    caller caller
    );

character(len=len(longname)) function, public cmor_long_std(longname longname);

subroutine, public query_vardesc(
    vd vd,
    name name,
    units units,
    longname longname,
    hor_grid hor_grid,
    z_grid z_grid,
    t_grid t_grid,
    cmor_field_name cmor_field_name,
    cmor_units cmor_units,
    cmor_longname cmor_longname,
    conversion conversion,
    caller caller
    );

character(len=len(name)) function, public ensembler(name name, ens_no_in ens_no_in);
subroutine, public mom_io_init(param_file param_file);

} // namespace mom_io

Detailed Documentation¶

This module contains I/O framework code.

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.

Global Functions¶

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

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

subroutine, public read_axis_data(
    filename filename,
    axis_name axis_name,
    var var
    )

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

Parameters:

filename	Name of the file to read
axis_name	Name of the axis to read
var	The axis location data

integer function, public num_timelevels(
    filename filename,
    varname varname,
    min_dims min_dims
    )

This function determines how many time levels a variable has.

Parameters:

filename	name of the file to read
varname	variable whose number of time levels are to be returned
min_dims	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.

Returns:

number of time levels varname has in filename

type(vardesc) function, public var_desc(
    name name,
    units units,
    longname longname,
    hor_grid hor_grid,
    z_grid z_grid,
    t_grid t_grid,
    cmor_field_name cmor_field_name,
    cmor_units cmor_units,
    cmor_longname cmor_longname,
    conversion conversion,
    caller caller
    )

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	variable name
units	variable units
longname	variable long name
hor_grid	variable horizonal staggering
z_grid	variable vertical staggering
t_grid	time description: s, p, or 1
cmor_field_name	CMOR name
cmor_units	CMOR physical dimensions of variable
cmor_longname	CMOR long name
conversion	for unit conversions, such as needed to convert from intensive to extensive
caller	calling routine?

Returns:

vardesc type that is created

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

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

Parameters:

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

character(len=len(longname)) function, public cmor_long_std(longname longname)

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

Parameters:

longname

The CMOR longname being converted

Returns:

The CMOR standard name generated from longname

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

This routine queries vardesc.

Parameters:

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

character(len=len(name)) function, public ensembler(name name, ens_no_in ens_no_in)

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

Parameters:

name	The name to be modified
ens_no_in	The number of the current ensemble member

Returns:

The name encoded with the ensemble number

subroutine, public mom_io_init(param_file param_file)

Initialize the MOM_io module.

Parameters:

param_file

structure indicating the open file to parse for model parameter values.