mom_restart module reference

The MOM6 facility for reading and writing restart files, and querying what has been read.

Data Types

`p4d`	A type for making arrays of pointers to 4-d arrays.
`p3d`	A type for making arrays of pointers to 3-d arrays.
`p2d`	A type for making arrays of pointers to 2-d arrays.
`p1d`	A type for making arrays of pointers to 1-d arrays.
`p0d`	A type for making arrays of pointers to scalars.
`field_restart`	A structure with information about a single restart field.
`obsolete_restart`	A structure to store information about restart fields that are no longer used.
`mom_restart_cs`	A restart registry and the control structure for restarts.

Functions/Subroutines

`register_restart_field_as_obsolete()`	Register a restart field as obsolete.
`register_restart_field_ptr3d()`	Register a 3-d field for restarts, providing the metadata in a structure.
`register_restart_field_ptr4d()`	Register a 4-d field for restarts, providing the metadata in a structure.
`register_restart_field_ptr2d()`	Register a 2-d field for restarts, providing the metadata in a structure.
`register_restart_field_ptr1d()`	Register a 1-d field for restarts, providing the metadata in a structure.
`register_restart_field_ptr0d()`	Register a 0-d field for restarts, providing the metadata in a structure.
`register_restart_pair_ptr2d()`	Register a pair of rotationally equivalent 2d restart fields.
`register_restart_pair_ptr3d()`	Register a pair of rotationally equivalent 3d restart fields.
`register_restart_pair_ptr4d()`	Register a pair of rotationally equivalent 2d restart fields.
`set_conversion_pair()`	Set a pair of factors to multiply by the components of a vector when writing that include any sign changes needed to account for grid rotation.
`register_restart_field_4d()`	Register a 4-d field for restarts, providing the metadata as individual arguments.
`register_restart_field_3d()`	Register a 3-d field for restarts, providing the metadata as individual arguments.
`register_restart_field_2d()`	Register a 2-d field for restarts, providing the metadata as individual arguments.
`register_restart_field_1d()`	Register a 1-d field for restarts, providing the metadata as individual arguments.
`register_restart_field_0d()`	Register a 0-d field for restarts, providing the metadata as individual arguments.
`query_initialized_name()`	query_initialized_name determines whether a named field has been successfully read from a restart file or has otherwise been recorded as being initialized.
`query_initialized_0d()`	Indicate whether the field pointed to by f_ptr has been initialized from a restart file.
`query_initialized_1d()`	Indicate whether the field pointed to by f_ptr has been initialized from a restart file.
`query_initialized_2d()`	Indicate whether the field pointed to by f_ptr has been initialized from a restart file.
`query_initialized_3d()`	Indicate whether the field pointed to by f_ptr has been initialized from a restart file.
`query_initialized_4d()`	Indicate whether the field pointed to by f_ptr has been initialized from a restart file.
`query_initialized_0d_name()`	Indicate whether the field stored in f_ptr or with the specified variable name has been initialized from a restart file.
`query_initialized_1d_name()`	Indicate whether the field stored in f_ptr or with the specified variable name has been initialized from a restart file.
`query_initialized_2d_name()`	Indicate whether the field stored in f_ptr or with the specified variable name has been initialized from a restart file.
`query_initialized_3d_name()`	Indicate whether the field stored in f_ptr or with the specified variable name has been initialized from a restart file.
`query_initialized_4d_name()`	Indicate whether the field stored in f_ptr or with the specified variable name has been initialized from a restart file.
`set_initialized_name()`	set_initialized_name records that a named field has been initialized.
`set_initialized_0d_name()`	Record that the array in f_ptr with the given name has been initialized.
`set_initialized_1d_name()`	Record that the array in f_ptr with the given name has been initialized.
`set_initialized_2d_name()`	Record that the array in f_ptr with the given name has been initialized.
`set_initialized_3d_name()`	Record that the array in f_ptr with the given name has been initialized.
`set_initialized_4d_name()`	Record that the array in f_ptr with the given name has been initialized.
`only_read_restart_field_4d()`	Try to read a named 4-d field from the restart files.
`only_read_restart_field_3d()`	Try to read a named 3-d field from the restart files.
`only_read_restart_field_2d()`	Try to read a named 2-d field from the restart files.
`only_read_restart_pair_3d()`	Try to read a named 3-d field from the restart files.
`find_var_in_restart_files()`	Return an indication of whether the named variable is in the restart files, and provide the full path to the restart file in which a variable is found.
`copy_restart_var_3d()`	Copy the restart variable with the specified name into a 3-d array, perhaps after rotation.
`copy_restart_vector_3d()`	Copy the restart vector component variables with the specified names into a pair of 3-d arrays, perhaps after rotation.
`size_mismatch_3d()`	Indicate if two 3-d arrays are not of the same size after rotation is considered.
`save_restart()`	save_restart saves all registered variables to restart files.
`restore_state()`	restore_state reads the model state from previously generated files. All restart variables are read from the first file in the input filename list in which they are found.
`restart_files_exist()`	restart_files_exist determines whether any restart files exist.
`determine_is_new_run()`	determine_is_new_run determines from the value of filename and the existence automatically named restart files in directory whether this would be a new, and as a side effect stores this information in CS.
`is_new_run()`	is_new_run returns whether this is going to be a new run based on the information stored in CS by a previous call to determine_is_new_run.
`open_restart_units()`	open_restart_units determines the number of existing restart files and optionally opens them and returns unit ids, paths and whether the files are global or spatially decomposed.
`get_num_restart_files()`	get_num_restart_files returns the number of existing restart files that match the provided directory structure and other information stored in the control structure and optionally also provides the full paths to these files.
`restart_init()`	Initialize this module and set up a restart control structure.
`lock_check()`	Issue an error message if the restart_registry is locked.
`restart_registry_lock()`	Lock the restart registry so that an error is issued if any further restart variables are registered.
`restart_init_end()`	Indicate that all variables have now been registered and lock the registry.
`restart_end()`	Deallocate memory associated with a MOM_restart_CS variable.
`restart_error()`
`get_checksum_loop_ranges()`	Return bounds for computing checksums to store in restart files.
`get_variable_byte_size()`	get the size of a variable in bytes

Detailed Description

The MOM6 facility for reading and writing restart files, and querying what has been read.

Type Documentation

type mom_restart/p4d

A type for making arrays of pointers to 4-d arrays.

Type fields:

% p :: real, dimension(:,:,:,:), pointer, private A pointer to a 4d array in arbitrary rescaled units [A ~> a].

[source]

type mom_restart/p3d

A type for making arrays of pointers to 3-d arrays.

Type fields:

% p :: real, dimension(:,:,:), pointer, private A pointer to a 3d array in arbitrary rescaled units [A ~> a].

[source]

type mom_restart/p2d

A type for making arrays of pointers to 2-d arrays.

Type fields:

% p :: real, dimension(:,:), pointer, private A pointer to a 2d array in arbitrary rescaled units [A ~> a].

[source]

type mom_restart/p1d

A type for making arrays of pointers to 1-d arrays.

Type fields:

% p :: real, dimension(:), pointer, private A pointer to a 1d array in arbitrary rescaled units [A ~> a].

[source]

type mom_restart/p0d

A type for making arrays of pointers to scalars.

Type fields:

% p :: real, pointer, private A pointer to a scalar in arbitrary rescaled units [A ~> a].

[source]

type mom_restart/field_restart

A structure with information about a single restart field.

Type fields:

% vars :: type(vardesc), private Description of a field that is to be read from or written to the restart file.
% mand_var :: logical, private If .true. the run will abort if this field is not successfully read from the restart file.
% initialized :: logical, private .true. if this field has been read from the restart file.
% var_name :: character(len=32), private A name by which a variable may be queried.
% conv :: real, private A factor by which a restart field should be multiplied before it is written to a restart file, usually to convert it to MKS or other standard units [a A-1 ~> 1]. When read, the restart field is multiplied by the reciprocal of this factor.

[source]

type mom_restart/obsolete_restart

A structure to store information about restart fields that are no longer used.

Type fields:

% field_name :: character(len=32), private Name of restart field that is no longer in use.
% replacement_name :: character(len=32), private Name of replacement restart field, if applicable.

[source]

type mom_restart/mom_restart_cs

A restart registry and the control structure for restarts.

Type fields:

% var_ptr0d :: type(p0d), dimension(:), pointer Pointers to the fields that have been registered for restarts.
% var_ptr1d :: type(p1d), dimension(:), pointer Pointers to the fields that have been registered for restarts.
% var_ptr2d :: type(p2d), dimension(:), pointer Pointers to the fields that have been registered for restarts.
% var_ptr3d :: type(p3d), dimension(:), pointer Pointers to the fields that have been registered for restarts.
% var_ptr4d :: type(p4d), dimension(:), pointer Pointers to the fields that have been registered for restarts.
% initialized :: logical True if this control structure has been initialized.
% restart :: logical restart is set to .true. if the run has been started from a full restart file. Otherwise some fields must be initialized approximately.
% novars :: integer The number of restart fields that have been registered.
% num_obsolete_vars :: integer The number of obsolete restart fields that have been registered.
% parallel_restartfiles :: logical If true, the IO layout is used to group processors that write to the same restart file or each processor writes its own (numbered) restart file. If false, a single restart file is generated after internally combining output from all PEs.
% new_run :: logical If true, the input filenames and restart file existence will result in a new run that is not initialized from restart files.
% new_run_set :: logical If true, new_run has been determined for this restart_CS.
% checksum_required :: logical If true, require the restart checksums to match and error out otherwise. Users may want to avoid this comparison if for example the restarts are made from a run with a different mask_table than the current run, in which case the checksums will not match and cause crash.
% symmetric_checksums :: logical If true, do the restart checksums on all the edge points for a non-reentrant grid. Setting this to true requires that SYMMETRIC_MEMORY_ is defined at compile time.
% unsigned_zeros :: logical If true, convert any negative zeros that would be written to the restart file into ordinary unsigned zeros. This does not change answers, but it can be helpful in comparing restart files after grid rotation, for example.
% reentrant_x :: logical If true, the domain is reentrant in the x-direction. This is only used here to determine the extent of the restart checksums.
% reentrant_y :: logical If true, the domain is reentrant in the y-direction. This is only used here to determine the extent of the restart checksums.
% restartfile :: character(len=240) The name or name root for MOM restart files.
% turns :: integer Number of quarter turns from input to model domain.
% locked :: logical If true this registry has been locked and no further restart fields can be added without explicitly unlocking the registry.
% restart_field :: type(field_restart), dimension(:), pointer An array of descriptions of the registered fields.
% restart_obsolete :: type(obsolete_restart), dimension(:), pointer An array of obsolete restart fields.
% max_fields :: integer The maximum number of restart fields.

[source]

Function/Subroutine Documentation

subroutine mom_restart/register_restart_field_as_obsolete(field_name, replacement_name, CS)

Register a restart field as obsolete.

Parameters:

field_name :: field_name [in] Name of restart field that is no longer in use
replacement_name :: replacement_name [in] Name of replacement restart field, if applicable
cs :: [inout] MOM restart control struct

Called from:

mom_set_visc::set_visc_init

[source]

subroutine mom_restart/register_restart_field_ptr3d(f_ptr, var_desc, mandatory, CS, conversion)

Register a 3-d field for restarts, providing the metadata in a structure.

Parameters:

f_ptr :: f_ptr [in] A pointer to the field to be read or written
var_desc :: var_desc [in] A structure with metadata about this variable
mandatory :: mandatory [in] If true, the run will abort if this field is not successfully read from the restart file.
cs :: [inout] MOM restart control struct
conversion :: conversion [in] A factor to multiply a restart field by before it is written [a A-1 ~> 1], 1 by default.

Called from:

mom_restart::register_restart_field::register_restart_field_3d

[source]

subroutine mom_restart/register_restart_field_ptr4d(f_ptr, var_desc, mandatory, CS, conversion)

Register a 4-d field for restarts, providing the metadata in a structure.

Parameters:

f_ptr :: f_ptr [in] A pointer to the field to be read or written
var_desc :: var_desc [in] A structure with metadata about this variable
mandatory :: mandatory [in] If true, the run will abort if this field is not successfully read from the restart file.
cs :: [inout] MOM restart control struct
conversion :: conversion [in] A factor to multiply a restart field by before it is written [a A-1 ~> 1], 1 by default.

Called from:

mom_restart::register_restart_field::register_restart_field_4d

[source]

subroutine mom_restart/register_restart_field_ptr2d(f_ptr, var_desc, mandatory, CS, conversion)

Register a 2-d field for restarts, providing the metadata in a structure.

Parameters:

f_ptr :: f_ptr [in] A pointer to the field to be read or written
var_desc :: var_desc [in] A structure with metadata about this variable
mandatory :: mandatory [in] If true, the run will abort if this field is not successfully read from the restart file.
cs :: [inout] MOM restart control struct
conversion :: conversion [in] A factor to multiply a restart field by before it is written [a A-1 ~> 1], 1 by default.

Called from:

mom_restart::register_restart_field::register_restart_field_2d

[source]

subroutine mom_restart/register_restart_field_ptr1d(f_ptr, var_desc, mandatory, CS, conversion)

Register a 1-d field for restarts, providing the metadata in a structure.

Parameters:

f_ptr :: f_ptr [in] A pointer to the field to be read or written in arbitrary rescaled units [A ~> a]
var_desc :: var_desc [in] A structure with metadata about this variable
mandatory :: mandatory [in] If true, the run will abort if this field is not successfully read from the restart file.
cs :: [inout] MOM restart control struct
conversion :: conversion [in] A factor to multiply a restart field by before it is written [a A-1 ~> 1], 1 by default.

Called from:

mom_restart::register_restart_field::register_restart_field_1d

[source]

subroutine mom_restart/register_restart_field_ptr0d(f_ptr, var_desc, mandatory, CS, conversion)

Register a 0-d field for restarts, providing the metadata in a structure.

Parameters:

f_ptr :: f_ptr [in] A pointer to the field to be read or written in arbitrary rescaled units [A ~> a]
var_desc :: var_desc [in] A structure with metadata about this variable
mandatory :: mandatory [in] If true, the run will abort if this field is not successfully read from the restart file.
cs :: [inout] MOM restart control struct
conversion :: conversion [in] A factor to multiply a restart field by before it is written [a A-1 ~> 1], 1 by default.

Called from:

mom_restart::register_restart_field::register_restart_field_0d

[source]

subroutine mom_restart/register_restart_pair_ptr2d(a_ptr, b_ptr, a_desc, b_desc, mandatory, CS, conversion, scalar_pair)

Register a pair of rotationally equivalent 2d restart fields.

Parameters:

a_ptr :: a_ptr [in] First field pointer in arbitrary rescaled units [A ~> a]
b_ptr :: b_ptr [in] Second field pointer in arbitrary rescaled units [A ~> a]
a_desc :: a_desc [in] First field descriptor
b_desc :: b_desc [in] Second field descriptor
mandatory :: mandatory [in] If true, abort if field is missing
cs :: [inout] MOM restart control structure
conversion :: conversion [in] A factor to multiply a restart field by before it is written [a A-1 ~> 1], 1 by default.
scalar_pair :: scalar_pair [in] If true, the arrays describe a pair of scalars, instead of vector components whose signs change when rotated

[source]

subroutine mom_restart/register_restart_pair_ptr3d(a_ptr, b_ptr, a_desc, b_desc, mandatory, CS, conversion, scalar_pair)

Register a pair of rotationally equivalent 3d restart fields.

Parameters:

a_ptr :: a_ptr [in] First field pointer in arbitrary rescaled units [A ~> a]
b_ptr :: b_ptr [in] Second field pointer in arbitrary rescaled units [A ~> a]
a_desc :: a_desc [in] First field descriptor
b_desc :: b_desc [in] Second field descriptor
mandatory :: mandatory [in] If true, abort if field is missing
cs :: [inout] MOM restart control structure
conversion :: conversion [in] A factor to multiply a restart field by before it is written [a A-1 ~> 1], 1 by default.
scalar_pair :: scalar_pair [in] If true, the arrays describe a pair of scalars, instead of vector components whose signs change when rotated

[source]

subroutine mom_restart/register_restart_pair_ptr4d(a_ptr, b_ptr, a_desc, b_desc, mandatory, CS, conversion, scalar_pair)

Register a pair of rotationally equivalent 2d restart fields.

Parameters:

a_ptr :: a_ptr [in] First field pointer in arbitrary rescaled units [A ~> a]
b_ptr :: b_ptr [in] Second field pointer in arbitrary rescaled units [A ~> a]
a_desc :: a_desc [in] First field descriptor
b_desc :: b_desc [in] Second field descriptor
mandatory :: mandatory [in] If true, abort if field is missing
cs :: [inout] MOM restart control structure
conversion :: conversion [in] A factor to multiply a restart field by before it is written [a A-1 ~> 1], 1 by default.
scalar_pair :: scalar_pair [in] If true, the arrays describe a pair of scalars, instead of vector components whose signs change when rotated

[source]

subroutine mom_restart/set_conversion_pair(u_conv, v_conv, turns, conversion, scalar_pair)

Set a pair of factors to multiply by the components of a vector when writing that include any sign changes needed to account for grid rotation.

Parameters:

u_conv :: u_conv [out] A factor to multiply the u-component of a vector by before it is written, including sign changes due to grid rotation [a A-1 ~> 1]
v_conv :: v_conv [out] A factor to multiply the u-component of a vector by before it is written, including sign changes due to grid rotation [a A-1 ~> 1]
turns :: turns [in] Number of quarter turns from input to model domain
conversion :: conversion [in] A factor to multiply a restart field by before it is written [a A-1 ~> 1], 1 by default.
scalar_pair :: scalar_pair [in] If true, the arrays describe a pair of scalars, instead of vector components whose signs change when rotated

Called from:

mom_restart::register_restart_pair::register_restart_pair_ptr2d mom_restart::register_restart_pair::register_restart_pair_ptr3d mom_restart::register_restart_pair::register_restart_pair_ptr4d

[source]

subroutine mom_restart/register_restart_field_4d(f_ptr, name, mandatory, CS, longname, units, conversion, hor_grid, z_grid, t_grid, extra_axes)

Register a 4-d field for restarts, providing the metadata as individual arguments.

Parameters:

f_ptr :: f_ptr [in] A pointer to the field to be read or written
name :: name [in] variable name to be used in the restart file
mandatory :: mandatory [in] If true, the run will abort if this field is not successfully read from the restart file.
cs :: [inout] MOM restart control struct
longname :: longname [in] variable long name
units :: units [in] variable units
conversion :: conversion [in] A factor to multiply a restart field by before it is written [a A-1 ~> 1], 1 by default.
hor_grid :: hor_grid [in] variable horizontal staggering, ‘h’ if absent
z_grid :: z_grid [in] variable vertical staggering, ‘L’ if absent
t_grid :: t_grid [in] time description: s, p, or 1, ‘s’ if absent
extra_axes :: extra_axes [in] dimensions other than space-time

[source]

subroutine mom_restart/register_restart_field_3d(f_ptr, name, mandatory, CS, longname, units, conversion, hor_grid, z_grid, t_grid, extra_axes)

Register a 3-d field for restarts, providing the metadata as individual arguments.

Parameters:

f_ptr :: f_ptr [in] A pointer to the field to be read or written
name :: name [in] variable name to be used in the restart file
mandatory :: mandatory [in] If true, the run will abort if this field is not successfully read from the restart file.
cs :: [inout] MOM restart control struct
longname :: longname [in] variable long name
units :: units [in] variable units
conversion :: conversion [in] A factor to multiply a restart field by before it is written [a A-1 ~> 1], 1 by default.
hor_grid :: hor_grid [in] variable horizontal staggering, ‘h’ if absent
z_grid :: z_grid [in] variable vertical staggering, ‘L’ if absent
t_grid :: t_grid [in] time description: s, p, or 1, ‘s’ if absent
extra_axes :: extra_axes [in] dimensions other than space-time

[source]

subroutine mom_restart/register_restart_field_2d(f_ptr, name, mandatory, CS, longname, units, conversion, hor_grid, z_grid, t_grid)

Register a 2-d field for restarts, providing the metadata as individual arguments.

Parameters:

f_ptr :: f_ptr [in] A pointer to the field to be read or written
name :: name [in] variable name to be used in the restart file
mandatory :: mandatory [in] If true, the run will abort if this field is not successfully read from the restart file.
cs :: [inout] MOM restart control struct
longname :: longname [in] variable long name
units :: units [in] variable units
conversion :: conversion [in] A factor to multiply a restart field by before it is written [a A-1 ~> 1], 1 by default.
hor_grid :: hor_grid [in] variable horizontal staggering, ‘h’ if absent
z_grid :: z_grid [in] variable vertical staggering, ‘1’ if absent
t_grid :: t_grid [in] time description: s, p, or 1, ‘s’ if absent

[source]

subroutine mom_restart/register_restart_field_1d(f_ptr, name, mandatory, CS, longname, units, conversion, hor_grid, z_grid, t_grid)

Register a 1-d field for restarts, providing the metadata as individual arguments.

Parameters:

f_ptr :: f_ptr [in] A pointer to the field to be read or written in arbitrary rescaled units [A ~> a]
name :: name [in] variable name to be used in the restart file
mandatory :: mandatory [in] If true, the run will abort if this field is not successfully read from the restart file.
cs :: [inout] MOM restart control struct
longname :: longname [in] variable long name
units :: units [in] variable units
conversion :: conversion [in] A factor to multiply a restart field by before it is written [a A-1 ~> 1], 1 by default.
hor_grid :: hor_grid [in] variable horizontal staggering, ‘1’ if absent
z_grid :: z_grid [in] variable vertical staggering, ‘L’ if absent
t_grid :: t_grid [in] time description: s, p, or 1, ‘s’ if absent

[source]

subroutine mom_restart/register_restart_field_0d(f_ptr, name, mandatory, CS, longname, units, conversion, t_grid)

Register a 0-d field for restarts, providing the metadata as individual arguments.

Parameters:

f_ptr :: f_ptr [in] A pointer to the field to be read or written in arbitrary rescaled units [A ~> a]
name :: name [in] variable name to be used in the restart file
mandatory :: mandatory [in] If true, the run will abort if this field is not successfully read from the restart file.
cs :: [inout] MOM restart control struct
longname :: longname [in] variable long name
units :: units [in] variable units
conversion :: conversion [in] A factor to multiply a restart field by before it is written [a A-1 ~> 1], 1 by default.
t_grid :: t_grid [in] time description: s, p, or 1, ‘s’ if absent

[source]

function mom_restart/query_initialized_name(name, CS)

query_initialized_name determines whether a named field has been successfully read from a restart file or has otherwise been recorded as being initialized.

Parameters:

name :: name [in] The name of the field that is being queried
cs :: [in] MOM restart control struct

Called from:

mom_restart::query_initialized::query_initialized_0d_name mom_restart::query_initialized::query_initialized_1d_name mom_restart::query_initialized::query_initialized_2d_name mom_restart::query_initialized::query_initialized_3d_name mom_restart::query_initialized::query_initialized_4d_name

[source]

function mom_restart/query_initialized_0d(f_ptr, CS)