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.
`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.
`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(:,:,:,:),pointer, private] :: A pointer to a 4d array in arbitrary rescaled units [A ~> a].

type mom_restart/p3d¶

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

Type fields:

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

type mom_restart/p2d¶

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

Type fields:

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

type mom_restart/p1d¶

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

Type fields:

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

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

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 Adcroft reciprocal of this factor.

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.

type mom_restart/mom_restart_cs¶

A restart registry and the control structure for restarts.

Type fields:

% var_ptr0d [type( p0d )(:),pointer] :: Pointers to the fields that have been registered for restarts.
% var_ptr1d [type( p1d )(:),pointer] :: Pointers to the fields that have been registered for restarts.
% var_ptr2d [type( p2d )(:),pointer] :: Pointers to the fields that have been registered for restarts.
% var_ptr3d [type( p3d )(:),pointer] :: Pointers to the fields that have been registered for restarts.
% var_ptr4d [type( p4d )(:),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.
% 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 )(:),pointer] :: An array of descriptions of the registered fields.
% restart_obsolete [type( obsolete_restart )(:),pointer] :: An array of obsolete restart fields.
% max_fields [integer] :: The maximum number of restart fields.

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 :: [in] Name of restart field that is no longer in use
replacement_name :: [in] Name of replacement restart field, if applicable
cs :: [inout] MOM restart control struct

Called from:

mom_set_visc::set_visc_init

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 :: [in] A pointer to the field to be read or written
var_desc :: [in] A structure with metadata about this variable
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 :: [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

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 :: [in] A pointer to the field to be read or written
var_desc :: [in] A structure with metadata about this variable
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 :: [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

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 :: [in] A pointer to the field to be read or written
var_desc :: [in] A structure with metadata about this variable
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 :: [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

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 :: [in] A pointer to the field to be read or written in arbitrary rescaled units [A ~> a]
var_desc :: [in] A structure with metadata about this variable
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 :: [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

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 :: [in] A pointer to the field to be read or written in arbitrary rescaled units [A ~> a]
var_desc :: [in] A structure with metadata about this variable
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 :: [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

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

Register a pair of rotationally equivalent 2d restart fields.

Parameters:

a_ptr :: [in] First field pointer in arbitrary rescaled units [A ~> a]
b_ptr :: [in] Second field pointer in arbitrary rescaled units [A ~> a]
a_desc :: [in] First field descriptor
b_desc :: [in] Second field descriptor
mandatory :: [in] If true, abort if field is missing
cs :: [inout] MOM restart control structure
conversion :: [in] A factor to multiply a restart field by before it is written [a A-1 ~> 1], 1 by default.

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

Register a pair of rotationally equivalent 3d restart fields.

Parameters:

a_ptr :: [in] First field pointer in arbitrary rescaled units [A ~> a]
b_ptr :: [in] Second field pointer in arbitrary rescaled units [A ~> a]
a_desc :: [in] First field descriptor
b_desc :: [in] Second field descriptor
mandatory :: [in] If true, abort if field is missing
cs :: [inout] MOM restart control structure
conversion :: [in] A factor to multiply a restart field by before it is written [a A-1 ~> 1], 1 by default.

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

Register a pair of rotationally equivalent 2d restart fields.

Parameters:

a_ptr :: [in] First field pointer in arbitrary rescaled units [A ~> a]
b_ptr :: [in] Second field pointer in arbitrary rescaled units [A ~> a]
a_desc :: [in] First field descriptor
b_desc :: [in] Second field descriptor
mandatory :: [in] If true, abort if field is missing
cs :: [inout] MOM restart control structure
conversion :: [in] A factor to multiply a restart field by before it is written [a A-1 ~> 1], 1 by default.

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 :: [in] A pointer to the field to be read or written
name :: [in] variable name to be used in the restart file
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 :: [in] variable long name
units :: [in] variable units
conversion :: [in] A factor to multiply a restart field by before it is written [a A-1 ~> 1], 1 by default.
hor_grid :: [in] variable horizontal staggering, ‘h’ if absent
z_grid :: [in] variable vertical staggering, ‘L’ if absent
t_grid :: [in] time description: s, p, or 1, ‘s’ if absent
extra_axes :: [in] dimensions other than space-time

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 :: [in] A pointer to the field to be read or written
name :: [in] variable name to be used in the restart file
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 :: [in] variable long name
units :: [in] variable units
conversion :: [in] A factor to multiply a restart field by before it is written [a A-1 ~> 1], 1 by default.
hor_grid :: [in] variable horizontal staggering, ‘h’ if absent
z_grid :: [in] variable vertical staggering, ‘L’ if absent
t_grid :: [in] time description: s, p, or 1, ‘s’ if absent
extra_axes :: [in] dimensions other than space-time

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 :: [in] A pointer to the field to be read or written
name :: [in] variable name to be used in the restart file
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 :: [in] variable long name
units :: [in] variable units
conversion :: [in] A factor to multiply a restart field by before it is written [a A-1 ~> 1], 1 by default.
hor_grid :: [in] variable horizontal staggering, ‘h’ if absent
z_grid :: [in] variable vertical staggering, ‘1’ if absent
t_grid :: [in] time description: s, p, or 1, ‘s’ if absent

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 :: [in] A pointer to the field to be read or written in arbitrary rescaled units [A ~> a]
name :: [in] variable name to be used in the restart file
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 :: [in] variable long name
units :: [in] variable units
conversion :: [in] A factor to multiply a restart field by before it is written [a A-1 ~> 1], 1 by default.
hor_grid :: [in] variable horizontal staggering, ‘1’ if absent
z_grid :: [in] variable vertical staggering, ‘L’ if absent
t_grid :: [in] time description: s, p, or 1, ‘s’ if absent

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 :: [in] A pointer to the field to be read or written in arbitrary rescaled units [A ~> a]
name :: [in] variable name to be used in the restart file
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 :: [in] variable long name
units :: [in] variable units
conversion :: [in] A factor to multiply a restart field by before it is written [a A-1 ~> 1], 1 by default.
t_grid :: [in] time description: s, p, or 1, ‘s’ if absent

function mom_restart/query_initialized_name(name, CS) [logical]¶

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 :: [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

function mom_restart/query_initialized_0d(f_ptr, CS) [logical]¶