MOM_restart.F90

! This file is part of MOM6, the Modular Ocean Model version 6.

! See the LICENSE file for licensing information.

! SPDX-License-Identifier: Apache-2.0

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

module mom_restart

use, intrinsic :: iso_fortran_env, only : int64

use mom_array_transform, only : rotate_array, rotate_vector, rotate_array_pair

use mom_checksums, only : chksum => field_checksum

use mom_domains, only : pe_here, num_pes, agrid, bgrid_ne, cgrid_ne

use mom_error_handler, only : mom_error, mom_mesg, fatal, warning, note, is_root_pe, mom_get_verbosity

use mom_file_parser, only : get_param, log_param, log_version, param_file_type

use mom_grid, only : ocean_grid_type

use mom_io, only : create_mom_file, file_exists

use mom_io, only : mom_infra_file, mom_field

use mom_io, only : mom_read_data, read_data, mom_write_field, field_exists

use mom_io, only : vardesc, var_desc, query_vardesc, modify_vardesc, get_filename_appendix

use mom_io, only : multiple, readonly_file, single_file

use mom_io, only : center, corner, north_face, east_face

use mom_io, only : axis_info, get_axis_info

use mom_string_functions, only : lowercase

use mom_time_manager,  only : time_type, time_type_to_real, real_to_time

use mom_time_manager,  only : days_in_month, get_date, set_date

use mom_verticalgrid,  only : verticalgrid_type

implicit none ; private

public restart_init, restart_end, restore_state, register_restart_field

public copy_restart_var, copy_restart_vector

public save_restart, query_initialized, set_initialized, only_read_from_restarts

public restart_registry_lock, restart_init_end, vardesc

public restart_files_exist, determine_is_new_run, is_new_run

public register_restart_field_as_obsolete, register_restart_pair

public lock_check

! A note on unit descriptions in comments: MOM6 uses units that can be rescaled for dimensional

! consistency testing. These are noted in comments with units like Z, H, L, and T, along with

! their mks counterparts with notation like "a velocity [Z T-1 ~> m s-1]".  If the units

! vary with the Boussinesq approximation, the Boussinesq variant is given first.

! The functions in this module work with variables with arbitrary units, in which case the

! arbitrary rescaled units are indicated with [A ~> a], while the unscaled units are just [a].

!> A type for making arrays of pointers to 4-d arrays

type p4d

  real, dimension(:,:,:,:), pointer :: p => null() !< A pointer to a 4d array in arbitrary rescaled units [A ~> a]

end type p4d

!> A type for making arrays of pointers to 3-d arrays

type p3d

  real, dimension(:,:,:), pointer :: p => null() !< A pointer to a 3d array in arbitrary rescaled units [A ~> a]

end type p3d

!> A type for making arrays of pointers to 2-d arrays

type p2d

  real, dimension(:,:), pointer :: p => null() !< A pointer to a 2d array in arbitrary rescaled units [A ~> a]

end type p2d

!> A type for making arrays of pointers to 1-d arrays

type p1d

  real, dimension(:), pointer :: p => null() !< A pointer to a 1d array in arbitrary rescaled units [A ~> a]

end type p1d

!> A type for making arrays of pointers to scalars

type p0d

  real, pointer :: p => null() !< A pointer to a scalar in arbitrary rescaled units [A ~> a]

end type p0d

!> A structure with information about a single restart field

type field_restart

  type(vardesc) :: vars         !< Description of a field that is to be read from or written

                                !! to the restart file.

  logical :: mand_var           !< If .true. the run will abort if this field is not successfully

                                !! read from the restart file.

  logical :: initialized        !< .true. if this field has been read from the restart file.

  character(len=32) :: var_name !< A name by which a variable may be queried.

  real    :: conv = 1.0         !< 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.

end type field_restart

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

type obsolete_restart

  character(len=32) :: field_name       !< Name of restart field that is no longer in use

  character(len=32) :: replacement_name !< Name of replacement restart field, if applicable

end type obsolete_restart

!> A restart registry and the control structure for restarts

type, public :: mom_restart_cs ; private

  logical :: initialized = .false. !< True if this control structure has been initialized.

  logical :: restart    !< restart is set to .true. if the run has been started from a full restart

                        !! file.  Otherwise some fields must be initialized approximately.

  integer :: novars = 0 !< The number of restart fields that have been registered.

  integer :: num_obsolete_vars = 0  !< The number of obsolete restart fields that have been registered.

  logical :: parallel_restartfiles  !< 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.

  logical :: new_run                !< If true, the input filenames and restart file existence will

                                    !! result in a new run that is not initialized from restart files.

  logical :: new_run_set = .false.  !< If true, new_run has been determined for this restart_CS.

  logical :: checksum_required      !< 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.

  logical :: symmetric_checksums    !< 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.

  logical :: unsigned_zeros         !< 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.

  logical :: reentrant_x            !< If true, the domain is reentrant in the x-direction.  This is only

                                    !! used here to determine the extent of the restart checksums.

  logical :: reentrant_y            !< If true, the domain is reentrant in the y-direction.  This is only

                                    !! used here to determine the extent of the restart checksums.

  character(len=240) :: restartfile !< The name or name root for MOM restart files.

  integer :: turns                  !< Number of quarter turns from input to model domain

  logical :: locked = .false.       !< If true this registry has been locked and no further restart

                                    !! fields can be added without explicitly unlocking the registry.

  !> An array of descriptions of the registered fields

  type(field_restart), pointer :: restart_field(:) => null()

  !> An array of obsolete restart fields

  type(obsolete_restart), pointer :: restart_obsolete(:) => null()

  !>@{ Pointers to the fields that have been registered for restarts

  type(p0d), pointer :: var_ptr0d(:) => null()

  type(p1d), pointer :: var_ptr1d(:) => null()

  type(p2d), pointer :: var_ptr2d(:) => null()

  type(p3d), pointer :: var_ptr3d(:) => null()

  type(p4d), pointer :: var_ptr4d(:) => null()

  !>@}

  integer :: max_fields !< The maximum number of restart fields

end type mom_restart_cs

!> Register fields for restarts

interface register_restart_field

  module procedure register_restart_field_ptr4d, register_restart_field_4d

  module procedure register_restart_field_ptr3d, register_restart_field_3d

  module procedure register_restart_field_ptr2d, register_restart_field_2d

  module procedure register_restart_field_ptr1d, register_restart_field_1d

  module procedure register_restart_field_ptr0d, register_restart_field_0d

end interface

!> Register a pair of restart fields whose rotations map onto each other

interface register_restart_pair

  module procedure register_restart_pair_ptr2d

  module procedure register_restart_pair_ptr3d

  module procedure register_restart_pair_ptr4d

end interface register_restart_pair

!> Indicate whether a field has been read from a restart file

interface query_initialized

  module procedure query_initialized_name

  module procedure query_initialized_0d, query_initialized_0d_name

  module procedure query_initialized_1d, query_initialized_1d_name

  module procedure query_initialized_2d, query_initialized_2d_name

  module procedure query_initialized_3d, query_initialized_3d_name

  module procedure query_initialized_4d, query_initialized_4d_name

end interface

!> Specify that a field has been initialized, even if it was not read from a restart file

interface set_initialized

  module procedure set_initialized_name, set_initialized_0d_name

  module procedure set_initialized_1d_name, set_initialized_2d_name

  module procedure set_initialized_3d_name, set_initialized_4d_name

end interface

!> Copy the restart variable with the specified name into an array, perhaps after rotation

interface copy_restart_var

  module procedure copy_restart_var_3d

end interface copy_restart_var

!> Copy the restart vector component variables with the specified names into a pair of arrays,

!! perhaps after rotation

interface copy_restart_vector

  module procedure copy_restart_vector_3d

end interface copy_restart_vector

!> Read optional variables from restart files.

interface only_read_from_restarts

  module procedure only_read_restart_field_4d

  module procedure only_read_restart_field_3d

  module procedure only_read_restart_field_2d

!  module procedure only_read_restart_field_1d

!  module procedure only_read_restart_field_0d

  module procedure only_read_restart_pair_3d

end interface

contains

!> Register a restart field as obsolete

subroutine register_restart_field_as_obsolete(field_name, replacement_name, CS)

  character(*), intent(in) :: field_name       !< Name of restart field that is no longer in use

  character(*), intent(in) :: replacement_name !< Name of replacement restart field, if applicable

  type(mom_restart_cs), intent(inout) :: cs    !< MOM restart control struct

  cs%num_obsolete_vars = cs%num_obsolete_vars+1

  cs%restart_obsolete(cs%num_obsolete_vars)%field_name = field_name

  cs%restart_obsolete(cs%num_obsolete_vars)%replacement_name = replacement_name

end subroutine register_restart_field_as_obsolete

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

subroutine register_restart_field_ptr3d(f_ptr, var_desc, mandatory, CS, conversion)

  real, dimension(:,:,:), &

                      target, intent(in) :: f_ptr     !< A pointer to the field to be read or written

                                                      !! in arbitrary rescaled units [A ~> a]

  type(vardesc),              intent(in) :: var_desc  !< A structure with metadata about this variable

  logical,                    intent(in) :: mandatory !< If true, the run will abort if this field is not

                                                      !! successfully read from the restart file.

  type(mom_restart_cs),       intent(inout) :: CS     !< MOM restart control struct

  real,             optional, intent(in) :: conversion !< A factor to multiply a restart field by

                                                      !! before it is written [a A-1 ~> 1], 1 by default.

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "register_restart_field: Module must be initialized before it is used.")

  call lock_check(cs, var_desc)

  cs%novars = cs%novars+1

  if (cs%novars > cs%max_fields) return ! This is an error that will be reported

                                     ! once the total number of fields is known.

  cs%restart_field(cs%novars)%vars = var_desc

  cs%restart_field(cs%novars)%mand_var = mandatory

  cs%restart_field(cs%novars)%initialized = .false.

  cs%restart_field(cs%novars)%conv = 1.0

  if (present(conversion)) cs%restart_field(cs%novars)%conv = conversion

  call query_vardesc(cs%restart_field(cs%novars)%vars, &

                     name=cs%restart_field(cs%novars)%var_name, &

                     caller="register_restart_field_ptr3d")

  cs%var_ptr3d(cs%novars)%p => f_ptr

  cs%var_ptr4d(cs%novars)%p => null()

  cs%var_ptr2d(cs%novars)%p => null()

  cs%var_ptr1d(cs%novars)%p => null()

  cs%var_ptr0d(cs%novars)%p => null()

end subroutine register_restart_field_ptr3d

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

subroutine register_restart_field_ptr4d(f_ptr, var_desc, mandatory, CS, conversion)

  real, dimension(:,:,:,:), &

                      target, intent(in) :: f_ptr     !< A pointer to the field to be read or written

                                                      !! in arbitrary rescaled units [A ~> a]

  type(vardesc),              intent(in) :: var_desc  !< A structure with metadata about this variable

  logical,                    intent(in) :: mandatory !< If true, the run will abort if this field is not

                                                      !! successfully read from the restart file.

  type(mom_restart_cs),       intent(inout) :: CS     !< MOM restart control struct

  real,             optional, intent(in) :: conversion !< A factor to multiply a restart field by

                                                      !! before it is written [a A-1 ~> 1], 1 by default.

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "register_restart_field: Module must be initialized before it is used.")

  call lock_check(cs, var_desc)

  cs%novars = cs%novars+1

  if (cs%novars > cs%max_fields) return ! This is an error that will be reported

                                     ! once the total number of fields is known.

  cs%restart_field(cs%novars)%vars = var_desc

  cs%restart_field(cs%novars)%mand_var = mandatory

  cs%restart_field(cs%novars)%initialized = .false.

  cs%restart_field(cs%novars)%conv = 1.0

  if (present(conversion)) cs%restart_field(cs%novars)%conv = conversion

  call query_vardesc(cs%restart_field(cs%novars)%vars, &

                     name=cs%restart_field(cs%novars)%var_name, &

                     caller="register_restart_field_ptr4d")

  cs%var_ptr4d(cs%novars)%p => f_ptr

  cs%var_ptr3d(cs%novars)%p => null()

  cs%var_ptr2d(cs%novars)%p => null()

  cs%var_ptr1d(cs%novars)%p => null()

  cs%var_ptr0d(cs%novars)%p => null()

end subroutine register_restart_field_ptr4d

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

subroutine register_restart_field_ptr2d(f_ptr, var_desc, mandatory, CS, conversion)

  real, dimension(:,:), &

                      target, intent(in) :: f_ptr     !< A pointer to the field to be read or written

                                                      !! in arbitrary rescaled units [A ~> a]

  type(vardesc),              intent(in) :: var_desc  !< A structure with metadata about this variable

  logical,                    intent(in) :: mandatory !< If true, the run will abort if this field is not

                                                      !! successfully read from the restart file.

  type(mom_restart_cs),       intent(inout) :: CS     !< MOM restart control struct

  real,             optional, intent(in) :: conversion !< A factor to multiply a restart field by

                                                      !! before it is written [a A-1 ~> 1], 1 by default.

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "register_restart_field: Module must be initialized before it is used.")

  call lock_check(cs, var_desc)

  cs%novars = cs%novars+1

  if (cs%novars > cs%max_fields) return ! This is an error that will be reported

                                     ! once the total number of fields is known.

  cs%restart_field(cs%novars)%vars = var_desc

  cs%restart_field(cs%novars)%mand_var = mandatory

  cs%restart_field(cs%novars)%initialized = .false.

  cs%restart_field(cs%novars)%conv = 1.0

  if (present(conversion)) cs%restart_field(cs%novars)%conv = conversion

  call query_vardesc(cs%restart_field(cs%novars)%vars, &

                     name=cs%restart_field(cs%novars)%var_name, &

                     caller="register_restart_field_ptr2d")

  cs%var_ptr2d(cs%novars)%p => f_ptr

  cs%var_ptr4d(cs%novars)%p => null()

  cs%var_ptr3d(cs%novars)%p => null()

  cs%var_ptr1d(cs%novars)%p => null()

  cs%var_ptr0d(cs%novars)%p => null()

end subroutine register_restart_field_ptr2d

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

subroutine register_restart_field_ptr1d(f_ptr, var_desc, mandatory, CS, conversion)

  real, dimension(:), target, intent(in) :: f_ptr     !< A pointer to the field to be read or written

                                                      !! in arbitrary rescaled units [A ~> a]

  type(vardesc),              intent(in) :: var_desc  !< A structure with metadata about this variable

  logical,                    intent(in) :: mandatory !< If true, the run will abort if this field is not

                                                      !! successfully read from the restart file.

  type(mom_restart_cs),       intent(inout) :: CS     !< MOM restart control struct

  real,             optional, intent(in) :: conversion !< A factor to multiply a restart field by

                                                      !! before it is written [a A-1 ~> 1], 1 by default.

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "register_restart_field: Module must be initialized before it is used.")

  call lock_check(cs, var_desc)

  cs%novars = cs%novars+1

  if (cs%novars > cs%max_fields) return ! This is an error that will be reported

                                     ! once the total number of fields is known.

  cs%restart_field(cs%novars)%vars = var_desc

  cs%restart_field(cs%novars)%mand_var = mandatory

  cs%restart_field(cs%novars)%initialized = .false.

  cs%restart_field(cs%novars)%conv = 1.0

  if (present(conversion)) cs%restart_field(cs%novars)%conv = conversion

  call query_vardesc(cs%restart_field(cs%novars)%vars, &

                     name=cs%restart_field(cs%novars)%var_name, &

                     caller="register_restart_field_ptr1d")

  cs%var_ptr1d(cs%novars)%p => f_ptr

  cs%var_ptr4d(cs%novars)%p => null()

  cs%var_ptr3d(cs%novars)%p => null()

  cs%var_ptr2d(cs%novars)%p => null()

  cs%var_ptr0d(cs%novars)%p => null()

end subroutine register_restart_field_ptr1d

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

subroutine register_restart_field_ptr0d(f_ptr, var_desc, mandatory, CS, conversion)

  real,               target, intent(in) :: f_ptr     !< A pointer to the field to be read or written

                                                      !! in arbitrary rescaled units [A ~> a]

  type(vardesc),              intent(in) :: var_desc  !< A structure with metadata about this variable

  logical,                    intent(in) :: mandatory !< If true, the run will abort if this field is not

                                                      !! successfully read from the restart file.

  type(mom_restart_cs),       intent(inout) :: CS     !< MOM restart control struct

  real,             optional, intent(in) :: conversion !< A factor to multiply a restart field by

                                                      !! before it is written [a A-1 ~> 1], 1 by default.

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "register_restart_field: Module must be initialized before it is used.")

  call lock_check(cs, var_desc)

  cs%novars = cs%novars+1

  if (cs%novars > cs%max_fields) return ! This is an error that will be reported

                                     ! once the total number of fields is known.

  cs%restart_field(cs%novars)%vars = var_desc

  cs%restart_field(cs%novars)%mand_var = mandatory

  cs%restart_field(cs%novars)%initialized = .false.

  cs%restart_field(cs%novars)%conv = 1.0

  if (present(conversion)) cs%restart_field(cs%novars)%conv = conversion

  call query_vardesc(cs%restart_field(cs%novars)%vars, &

                     name=cs%restart_field(cs%novars)%var_name, &

                     caller="register_restart_field_ptr0d")

  cs%var_ptr0d(cs%novars)%p => f_ptr

  cs%var_ptr4d(cs%novars)%p => null()

  cs%var_ptr3d(cs%novars)%p => null()

  cs%var_ptr2d(cs%novars)%p => null()

  cs%var_ptr1d(cs%novars)%p => null()

end subroutine register_restart_field_ptr0d

!> Register a pair of rotationally equivalent 2d restart fields

subroutine register_restart_pair_ptr2d(a_ptr, b_ptr, a_desc, b_desc, &

                mandatory, CS, conversion, scalar_pair)

  real, dimension(:,:), target, intent(in) :: a_ptr   !< First field pointer

                                                      !! in arbitrary rescaled units [A ~> a]

  real, dimension(:,:), target, intent(in) :: b_ptr   !< Second field pointer

                                                      !! in arbitrary rescaled units [A ~> a]

  type(vardesc),                intent(in) :: a_desc  !< First field descriptor

  type(vardesc),                intent(in) :: b_desc  !< Second field descriptor

  logical,                      intent(in) :: mandatory !< If true, abort if field is missing

  type(mom_restart_cs),      intent(inout) :: CS      !< MOM restart control structure

  real,               optional, intent(in) :: conversion !< A factor to multiply a restart field by

                                                      !! before it is written [a A-1 ~> 1], 1 by default.

  logical,            optional, intent(in) :: scalar_pair !< If true, the arrays describe a pair of

                                                      !! scalars, instead of vector components

                                                      !! whose signs change when rotated

  ! Local variables

  real :: a_conv, b_conv  ! Factors to multipy the a- and b-components by before they are written,

                          ! including sign changes to account for grid rotation [a A-1 ~> 1]

  call lock_check(cs, a_desc)

  call set_conversion_pair(a_conv, b_conv, cs%turns, conversion, scalar_pair)

  if (modulo(cs%turns, 2) == 0) then  ! This is the usual case.

    call register_restart_field(a_ptr, a_desc, mandatory, cs, conversion=a_conv)

    call register_restart_field(b_ptr, b_desc, mandatory, cs, conversion=b_conv)

  else

    call register_restart_field(b_ptr, a_desc, mandatory, cs, conversion=a_conv)

    call register_restart_field(a_ptr, b_desc, mandatory, cs, conversion=b_conv)

  endif

end subroutine register_restart_pair_ptr2d

!> Register a pair of rotationally equivalent 3d restart fields

subroutine register_restart_pair_ptr3d(a_ptr, b_ptr, a_desc, b_desc, &

                mandatory, CS, conversion, scalar_pair)

  real, dimension(:,:,:), target, intent(in) :: a_ptr !< First field pointer

                                                      !! in arbitrary rescaled units [A ~> a]

  real, dimension(:,:,:), target, intent(in) :: b_ptr !< Second field pointer

                                                      !! in arbitrary rescaled units [A ~> a]

  type(vardesc),                intent(in) :: a_desc  !< First field descriptor

  type(vardesc),                intent(in) :: b_desc  !< Second field descriptor

  logical,                      intent(in) :: mandatory !< If true, abort if field is missing

  type(mom_restart_cs),      intent(inout) :: CS      !< MOM restart control structure

  real,               optional, intent(in) :: conversion !< A factor to multiply a restart field by

                                                      !! before it is written [a A-1 ~> 1], 1 by default.

  logical,            optional, intent(in) :: scalar_pair !< If true, the arrays describe a pair of

                                                      !! scalars, instead of vector components

                                                      !! whose signs change when rotated

  ! Local variables

  real :: a_conv, b_conv  ! Factors to multipy the a- and b-components by before they are written,

                          ! including sign changes to account for grid rotation [a A-1 ~> 1]

  call lock_check(cs, a_desc)

  call set_conversion_pair(a_conv, b_conv, cs%turns, conversion, scalar_pair)

  if (modulo(cs%turns, 2) == 0) then  ! This is the usual case.

    call register_restart_field(a_ptr, a_desc, mandatory, cs, conversion=a_conv)

    call register_restart_field(b_ptr, b_desc, mandatory, cs, conversion=b_conv)

  else

    call register_restart_field(b_ptr, a_desc, mandatory, cs, conversion=a_conv)

    call register_restart_field(a_ptr, b_desc, mandatory, cs, conversion=b_conv)

  endif

end subroutine register_restart_pair_ptr3d

!> Register a pair of rotationally equivalent 2d restart fields

subroutine register_restart_pair_ptr4d(a_ptr, b_ptr, a_desc, b_desc, &

                mandatory, CS, conversion, scalar_pair)

  real, dimension(:,:,:,:), target, intent(in) :: a_ptr !< First field pointer

                                                      !! in arbitrary rescaled units [A ~> a]

  real, dimension(:,:,:,:), target, intent(in) :: b_ptr !< Second field pointer

                                                      !! in arbitrary rescaled units [A ~> a]

  type(vardesc),                intent(in) :: a_desc  !< First field descriptor

  type(vardesc),                intent(in) :: b_desc  !< Second field descriptor

  logical,                      intent(in) :: mandatory !< If true, abort if field is missing

  type(mom_restart_cs),      intent(inout) :: CS      !< MOM restart control structure

  real,               optional, intent(in) :: conversion !< A factor to multiply a restart field by

                                                      !! before it is written [a A-1 ~> 1], 1 by default.

  logical,            optional, intent(in) :: scalar_pair !< If true, the arrays describe a pair of

                                                      !! scalars, instead of vector components

                                                      !! whose signs change when rotated

  ! Local variables

  real :: a_conv, b_conv  ! Factors to multipy the a- and b-components by before they are written,

                          ! including sign changes to account for grid rotation [a A-1 ~> 1]

  call lock_check(cs, a_desc)

  call set_conversion_pair(a_conv, b_conv, cs%turns, conversion, scalar_pair)

  if (modulo(cs%turns, 2) == 0) then  ! This is the usual case.

    call register_restart_field(a_ptr, a_desc, mandatory, cs, conversion=a_conv)

    call register_restart_field(b_ptr, b_desc, mandatory, cs, conversion=b_conv)

  else

    call register_restart_field(b_ptr, a_desc, mandatory, cs, conversion=a_conv)

    call register_restart_field(a_ptr, b_desc, mandatory, cs, conversion=b_conv)

  endif

end subroutine register_restart_pair_ptr4d

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

subroutine set_conversion_pair(u_conv, v_conv, turns, conversion, scalar_pair)

  real,   intent(out) :: u_conv !< 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]

  real,   intent(out) :: v_conv !< 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]

  integer, intent(in) :: turns  !< Number of quarter turns from input to model domain

  real,    optional, intent(in) :: conversion !< A factor to multiply a restart field by

                                !! before it is written [a A-1 ~> 1], 1 by default.

  logical, optional, intent(in) :: scalar_pair !< If true, the arrays describe a pair of scalars,

                                 !! instead of vector components whose signs change when rotated

  ! Local variables

  integer :: q_turns

  logical :: scalars

  u_conv = 1.0 ; v_conv = 1.0

  if (present(conversion)) then

    u_conv = conversion ; v_conv = conversion

  endif

  scalars = .false. ; if (present(scalar_pair)) scalars = scalar_pair

  if (scalars) return

  q_turns = modulo(turns, 4)

  if (q_turns == 1) then

    v_conv = -1.0*v_conv

  elseif (q_turns == 2) then

    u_conv = -1.0*u_conv ; v_conv = -1.0*v_conv

  elseif (q_turns == 3) then

    u_conv = -1.0*u_conv

  endif

end subroutine set_conversion_pair

! The following provide alternate interfaces to register restarts.

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

subroutine register_restart_field_4d(f_ptr, name, mandatory, CS, longname, units, conversion, &

                                     hor_grid, z_grid, t_grid, extra_axes)

  real, dimension(:,:,:,:), &

                      target, intent(in) :: f_ptr     !< A pointer to the field to be read or written

                                                      !! in arbitrary rescaled units [A ~> a]

  character(len=*),           intent(in) :: name      !< variable name to be used in the restart file

  logical,                    intent(in) :: mandatory !< If true, the run will abort if this field is not

                                                      !! successfully read from the restart file.

  type(mom_restart_cs),       intent(inout) :: CS     !< MOM restart control struct

  character(len=*), optional, intent(in) :: longname  !< variable long name

  character(len=*), optional, intent(in) :: units     !< variable units

  real,             optional, intent(in) :: conversion !< A factor to multiply a restart field by

                                                      !! before it is written [a A-1 ~> 1], 1 by default.

  character(len=*), optional, intent(in) :: hor_grid  !< variable horizontal staggering, 'h' if absent

  character(len=*), optional, intent(in) :: z_grid    !< variable vertical staggering, 'L' if absent

  character(len=*), optional, intent(in) :: t_grid    !< time description: s, p, or 1, 's' if absent

  type(axis_info),  dimension(:), &

                    optional, intent(in) :: extra_axes !< dimensions other than space-time

  type(vardesc) :: vd

  character(len=32), dimension(:), allocatable :: dim_names

  integer :: n, n_extradims

  ! first 2 dimensions in dim_names are reserved for i,j

  ! so extra_dimensions are shifted to index 3.

  ! this is designed not to break the behavior in SIS2

  ! (see register_restart_field_4d in SIS_restart.F90)

  if (present(extra_axes)) then

    n_extradims = size(extra_axes)

    allocate(dim_names(n_extradims+2))

    dim_names(1) = ""

    dim_names(2) = ""

    do n=3,n_extradims+2

      dim_names(n) = extra_axes(n-2)%name

    enddo

  endif

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart: " // &

      "register_restart_field_4d: Module must be initialized before "//&

      "it is used to register "//trim(name))

  call lock_check(cs, name=name)

  if (present(extra_axes)) then

    vd = var_desc(name, units=units, longname=longname, hor_grid=hor_grid, &

                  z_grid=z_grid, t_grid=t_grid, dim_names=dim_names, extra_axes=extra_axes)

  else

    vd = var_desc(name, units=units, longname=longname, hor_grid=hor_grid, &

                  z_grid=z_grid, t_grid=t_grid)

  endif

  call register_restart_field_ptr4d(f_ptr, vd, mandatory, cs, conversion)

end subroutine register_restart_field_4d

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

subroutine register_restart_field_3d(f_ptr, name, mandatory, CS, longname, units, conversion, &

                                     hor_grid, z_grid, t_grid, extra_axes)

  real, dimension(:,:,:), &

                      target, intent(in) :: f_ptr     !< A pointer to the field to be read or written

                                                      !! in arbitrary rescaled units [A ~> a]

  character(len=*),           intent(in) :: name      !< variable name to be used in the restart file

  logical,                    intent(in) :: mandatory !< If true, the run will abort if this field is not

                                                      !! successfully read from the restart file.

  type(mom_restart_cs),       intent(inout) :: CS     !< MOM restart control struct

  character(len=*), optional, intent(in) :: longname  !< variable long name

  character(len=*), optional, intent(in) :: units     !< variable units

  real,             optional, intent(in) :: conversion !< A factor to multiply a restart field by

                                                      !! before it is written [a A-1 ~> 1], 1 by default.

  character(len=*), optional, intent(in) :: hor_grid  !< variable horizontal staggering, 'h' if absent

  character(len=*), optional, intent(in) :: z_grid    !< variable vertical staggering, 'L' if absent

  character(len=*), optional, intent(in) :: t_grid    !< time description: s, p, or 1, 's' if absent

  type(axis_info),  dimension(:), &

                    optional, intent(in) :: extra_axes !< dimensions other than space-time

  type(vardesc) :: vd

  character(len=32), dimension(:), allocatable :: dim_names

  integer :: n, n_extradims

  ! first 2 dimensions in dim_names are reserved for i,j

  ! so extra_dimensions are shifted to index 3.

  ! this is designed not to break the behavior in SIS2

  ! (see register_restart_field_4d in SIS_restart.F90)

  if (present(extra_axes)) then

    n_extradims = size(extra_axes)

    allocate(dim_names(n_extradims+2))

    dim_names(1) = ""

    dim_names(2) = ""

    do n=3,n_extradims+2

      dim_names(n) = extra_axes(n-2)%name

    enddo

  endif

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart: " // &

      "register_restart_field_3d: Module must be initialized before "//&

      "it is used to register "//trim(name))

  call lock_check(cs, name=name)

  if (present(extra_axes)) then

    vd = var_desc(name, units=units, longname=longname, hor_grid=hor_grid, &

                  z_grid=z_grid, t_grid=t_grid, dim_names=dim_names, extra_axes=extra_axes)

  else

    vd = var_desc(name, units=units, longname=longname, hor_grid=hor_grid, &

                  z_grid=z_grid, t_grid=t_grid)

  endif

  call register_restart_field_ptr3d(f_ptr, vd, mandatory, cs, conversion)

end subroutine register_restart_field_3d

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

subroutine register_restart_field_2d(f_ptr, name, mandatory, CS, longname, units, conversion, &

                                     hor_grid, z_grid, t_grid)

  real, dimension(:,:), &

                      target, intent(in) :: f_ptr     !< A pointer to the field to be read or written

                                                      !! in arbitrary rescaled units [A ~> a]

  character(len=*),           intent(in) :: name      !< variable name to be used in the restart file

  logical,                    intent(in) :: mandatory !< If true, the run will abort if this field is not

                                                      !! successfully read from the restart file.

  type(mom_restart_cs),       intent(inout) :: CS     !< MOM restart control struct

  character(len=*), optional, intent(in) :: longname  !< variable long name

  character(len=*), optional, intent(in) :: units     !< variable units

  real,             optional, intent(in) :: conversion !< A factor to multiply a restart field by

                                                      !! before it is written [a A-1 ~> 1], 1 by default.

  character(len=*), optional, intent(in) :: hor_grid  !< variable horizontal staggering, 'h' if absent

  character(len=*), optional, intent(in) :: z_grid    !< variable vertical staggering, '1' if absent

  character(len=*), optional, intent(in) :: t_grid    !< time description: s, p, or 1, 's' if absent

  type(vardesc) :: vd

  character(len=8) :: Zgrid

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart: " // &

      "register_restart_field_2d: Module must be initialized before "//&

      "it is used to register "//trim(name))

  zgrid = '1' ; if (present(z_grid)) zgrid = z_grid

  call lock_check(cs, name=name)

  vd = var_desc(name, units=units, longname=longname, hor_grid=hor_grid, &

                z_grid=zgrid, t_grid=t_grid)

  call register_restart_field_ptr2d(f_ptr, vd, mandatory, cs, conversion)

end subroutine register_restart_field_2d

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

subroutine register_restart_field_1d(f_ptr, name, mandatory, CS, longname, units, conversion, &

                                     hor_grid, z_grid, t_grid)

  real, dimension(:), target, intent(in) :: f_ptr     !< A pointer to the field to be read or written

                                                      !! in arbitrary rescaled units [A ~> a]

  character(len=*),           intent(in) :: name      !< variable name to be used in the restart file

  logical,                    intent(in) :: mandatory !< If true, the run will abort if this field is not

                                                      !! successfully read from the restart file.

  type(mom_restart_cs),       intent(inout) :: CS     !< MOM restart control struct

  character(len=*), optional, intent(in) :: longname  !< variable long name

  character(len=*), optional, intent(in) :: units     !< variable units

  real,             optional, intent(in) :: conversion !< A factor to multiply a restart field by

                                                      !! before it is written [a A-1 ~> 1], 1 by default.

  character(len=*), optional, intent(in) :: hor_grid  !< variable horizontal staggering, '1' if absent

  character(len=*), optional, intent(in) :: z_grid    !< variable vertical staggering, 'L' if absent

  character(len=*), optional, intent(in) :: t_grid    !< time description: s, p, or 1, 's' if absent

  type(vardesc) :: vd

  character(len=8) :: hgrid

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart: " // &

      "register_restart_field_3d: Module must be initialized before "//&

      "it is used to register "//trim(name))

  hgrid = '1' ; if (present(hor_grid)) hgrid = hor_grid

  call lock_check(cs, name=name)

  vd = var_desc(name, units=units, longname=longname, hor_grid=hgrid, &

                z_grid=z_grid, t_grid=t_grid)

  call register_restart_field_ptr1d(f_ptr, vd, mandatory, cs, conversion)

end subroutine register_restart_field_1d

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

subroutine register_restart_field_0d(f_ptr, name, mandatory, CS, longname, units, conversion, &

                                     t_grid)

  real,               target, intent(in) :: f_ptr     !< A pointer to the field to be read or written

                                                      !! in arbitrary rescaled units [A ~> a]

  character(len=*),           intent(in) :: name      !< variable name to be used in the restart file

  logical,                    intent(in) :: mandatory !< If true, the run will abort if this field is not

                                                      !! successfully read from the restart file.

  type(mom_restart_cs),       intent(inout) :: CS     !< MOM restart control struct

  character(len=*), optional, intent(in) :: longname  !< variable long name

  character(len=*), optional, intent(in) :: units     !< variable units

  real,             optional, intent(in) :: conversion !< A factor to multiply a restart field by

                                                      !! before it is written [a A-1 ~> 1], 1 by default.

  character(len=*), optional, intent(in) :: t_grid    !< time description: s, p, or 1, 's' if absent

  type(vardesc) :: vd

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart: " // &

      "register_restart_field_0d: Module must be initialized before "//&

      "it is used to register "//trim(name))

  call lock_check(cs, name=name)

  vd = var_desc(name, units=units, longname=longname, hor_grid='1', &

                z_grid='1', t_grid=t_grid)

  call register_restart_field_ptr0d(f_ptr, vd, mandatory, cs, conversion)

end subroutine register_restart_field_0d

!> query_initialized_name determines whether a named field has been successfully

!! read from a restart file or has otherwise been recorded as being initialized.

function query_initialized_name(name, CS) result(query_initialized)

  character(len=*),     intent(in) :: name  !< The name of the field that is being queried

  type(mom_restart_cs), intent(in) :: cs    !< MOM restart control struct

  logical :: query_initialized

  integer :: m, n

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "query_initialized: Module must be initialized before it is used.")

  if (cs%novars > cs%max_fields) call restart_error(cs)

  query_initialized = .false.

  n = cs%novars+1

  do m=1,cs%novars

    if (trim(name) == cs%restart_field(m)%var_name) then

      if (cs%restart_field(m)%initialized) query_initialized = .true.

      n = m ; exit

    endif

  enddo

  if ((n==cs%novars+1) .and. (is_root_pe())) &

    call mom_error(note,"MOM_restart: Unknown restart variable "//name// &

                        " queried for initialization.")

  if ((is_root_pe()) .and. query_initialized) &

    call mom_error(note,"MOM_restart: "//name// &

                         " initialization confirmed by name.")

end function query_initialized_name

!> Indicate whether the field pointed to by f_ptr has been initialized from a restart file.

function query_initialized_0d(f_ptr, CS) result(query_initialized)

  real,         target, intent(in) :: f_ptr !< A pointer to the field that is being queried [arbitrary]

  type(mom_restart_cs), intent(in) :: cs    !< MOM restart control struct

  logical :: query_initialized

  integer :: m, n

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "query_initialized: Module must be initialized before it is used.")

  if (cs%novars > cs%max_fields) call restart_error(cs)

  query_initialized = .false.

  n = cs%novars+1

  do m=1,cs%novars

    if (associated(cs%var_ptr0d(m)%p,f_ptr)) then

      if (cs%restart_field(m)%initialized) query_initialized = .true.

      n = m ; exit

    endif

  enddo

end function query_initialized_0d

!> Indicate whether the field pointed to by f_ptr has been initialized from a restart file.

function query_initialized_1d(f_ptr, CS) result(query_initialized)

  real, dimension(:), target, intent(in) :: f_ptr !< A pointer to the field that is being queried [arbitrary]

  type(mom_restart_cs),       intent(in) :: cs    !< MOM restart control struct

  logical :: query_initialized

  integer :: m, n

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "query_initialized: Module must be initialized before it is used.")

  if (cs%novars > cs%max_fields) call restart_error(cs)

  query_initialized = .false.

  n = cs%novars+1

  do m=1,cs%novars

    if (associated(cs%var_ptr1d(m)%p,f_ptr)) then

      if (cs%restart_field(m)%initialized) query_initialized = .true.

      n = m ; exit

    endif

  enddo

end function query_initialized_1d

!> Indicate whether the field pointed to by f_ptr has been initialized from a restart file.

function query_initialized_2d(f_ptr, CS) result(query_initialized)

  real, dimension(:,:), &

                target, intent(in) :: f_ptr !< A pointer to the field that is being queried [arbitrary]

  type(mom_restart_cs), intent(in) :: cs    !< MOM restart control struct

  logical :: query_initialized

  integer :: m, n

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "query_initialized: Module must be initialized before it is used.")

  if (cs%novars > cs%max_fields) call restart_error(cs)

  query_initialized = .false.

  n = cs%novars+1

  do m=1,cs%novars

    if (associated(cs%var_ptr2d(m)%p,f_ptr)) then

      if (cs%restart_field(m)%initialized) query_initialized = .true.

      n = m ; exit

    endif

  enddo

end function query_initialized_2d

!> Indicate whether the field pointed to by f_ptr has been initialized from a restart file.

function query_initialized_3d(f_ptr, CS) result(query_initialized)

  real, dimension(:,:,:), &

                target, intent(in) :: f_ptr !< A pointer to the field that is being queried [arbitrary]

  type(mom_restart_cs), intent(in) :: cs    !< MOM restart control struct

  logical :: query_initialized

  integer :: m, n

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "query_initialized: Module must be initialized before it is used.")

  if (cs%novars > cs%max_fields) call restart_error(cs)

  query_initialized = .false.

  n = cs%novars+1

  do m=1,cs%novars

    if (associated(cs%var_ptr3d(m)%p,f_ptr)) then

      if (cs%restart_field(m)%initialized) query_initialized = .true.

      n = m ; exit

    endif

  enddo

end function query_initialized_3d

!> Indicate whether the field pointed to by f_ptr has been initialized from a restart file.

function query_initialized_4d(f_ptr, CS) result(query_initialized)

  real, dimension(:,:,:,:),  &

                target, intent(in) :: f_ptr !< A pointer to the field that is being queried [arbitrary]

  type(mom_restart_cs), intent(in) :: cs    !< MOM restart control struct

  logical :: query_initialized

  integer :: m, n

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "query_initialized: Module must be initialized before it is used.")

  if (cs%novars > cs%max_fields) call restart_error(cs)

  query_initialized = .false.

  n = cs%novars+1

  do m=1,cs%novars

    if (associated(cs%var_ptr4d(m)%p,f_ptr)) then

      if (cs%restart_field(m)%initialized) query_initialized = .true.

      n = m ; exit

    endif

  enddo

end function query_initialized_4d

!> Indicate whether the field stored in f_ptr or with the specified variable

!! name has been initialized from a restart file.

function query_initialized_0d_name(f_ptr, name, CS) result(query_initialized)

  real,         target, intent(in) :: f_ptr !< The field that is being queried [arbitrary]

  character(len=*),     intent(in) :: name  !< The name of the field that is being queried

  type(mom_restart_cs), intent(in) :: cs    !< MOM restart control struct

  logical :: query_initialized

  integer :: m, n

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "query_initialized: Module must be initialized before it is used.")

  if (cs%novars > cs%max_fields) call restart_error(cs)

  query_initialized = .false.

  n = cs%novars+1

  do m=1,cs%novars

    if (associated(cs%var_ptr0d(m)%p,f_ptr)) then

      if (cs%restart_field(m)%initialized) query_initialized = .true.

      n = m ; exit

    endif

  enddo

  if (n==cs%novars+1) then

    if (is_root_pe()) &

      call mom_error(note,"MOM_restart: Unable to find "//name//" queried by pointer, "//&

        "probably because of the suspect comparison of pointers by ASSOCIATED.")

    query_initialized = query_initialized_name(name, cs)

  endif

end function 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.

function query_initialized_1d_name(f_ptr, name, CS) result(query_initialized)

  real, dimension(:),  &

                target, intent(in) :: f_ptr !< The field that is being queried [arbitrary]

  character(len=*),     intent(in) :: name  !< The name of the field that is being queried

  type(mom_restart_cs), intent(in) :: cs    !< MOM restart control struct

  logical :: query_initialized

  integer :: m, n

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "query_initialized: Module must be initialized before it is used.")

  if (cs%novars > cs%max_fields) call restart_error(cs)

  query_initialized = .false.

  n = cs%novars+1

  do m=1,cs%novars

    if (associated(cs%var_ptr1d(m)%p,f_ptr)) then

      if (cs%restart_field(m)%initialized) query_initialized = .true.

      n = m ; exit

    endif

  enddo

  if (n==cs%novars+1) then

    if (is_root_pe()) &

      call mom_error(note,"MOM_restart: Unable to find "//name//" queried by pointer, "//&

        "probably because of the suspect comparison of pointers by ASSOCIATED.")

    query_initialized = query_initialized_name(name, cs)

  endif

end function 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.

function query_initialized_2d_name(f_ptr, name, CS) result(query_initialized)

  real, dimension(:,:),  &

                target, intent(in) :: f_ptr !< The field that is being queried [arbitrary]

  character(len=*),     intent(in) :: name  !< The name of the field that is being queried

  type(mom_restart_cs), intent(in) :: cs    !< MOM restart control struct

  logical :: query_initialized

  integer :: m, n

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "query_initialized: Module must be initialized before it is used.")

  if (cs%novars > cs%max_fields) call restart_error(cs)

  query_initialized = .false.

  n = cs%novars+1

  do m=1,cs%novars

    if (associated(cs%var_ptr2d(m)%p,f_ptr)) then

      if (cs%restart_field(m)%initialized) query_initialized = .true.

      n = m ; exit

    endif

  enddo

  if (n==cs%novars+1) then

    if (is_root_pe()) &

      call mom_error(note,"MOM_restart: Unable to find "//name//" queried by pointer, "//&

        "probably because of the suspect comparison of pointers by ASSOCIATED.")

    query_initialized = query_initialized_name(name, cs)

  endif

end function 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.

function query_initialized_3d_name(f_ptr, name, CS) result(query_initialized)

  real, dimension(:,:,:),  &

                target, intent(in) :: f_ptr !< The field that is being queried [arbitrary]

  character(len=*),     intent(in) :: name  !< The name of the field that is being queried

  type(mom_restart_cs), intent(in) :: cs    !< MOM restart control struct

  logical :: query_initialized

  integer :: m, n

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "query_initialized: Module must be initialized before it is used.")

  if (cs%novars > cs%max_fields) call restart_error(cs)

  query_initialized = .false.

  n = cs%novars+1

  do m=1,cs%novars

    if (associated(cs%var_ptr3d(m)%p,f_ptr)) then

      if (cs%restart_field(m)%initialized) query_initialized = .true.

      n = m ; exit

    endif

  enddo

  if (n==cs%novars+1) then

    if (is_root_pe()) &

      call mom_error(note, "MOM_restart: Unable to find "//name//" queried by pointer, "//&

        "possibly because of the suspect comparison of pointers by ASSOCIATED.")

    query_initialized = query_initialized_name(name, cs)

  endif

end function 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.

function query_initialized_4d_name(f_ptr, name, CS) result(query_initialized)

  real, dimension(:,:,:,:),  &

                target, intent(in) :: f_ptr !< The field that is being queried [arbitrary]

  character(len=*),     intent(in) :: name  !< The name of the field that is being queried

  type(mom_restart_cs), intent(in) :: cs    !< MOM restart control struct

  logical :: query_initialized

  integer :: m, n

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "query_initialized: Module must be initialized before it is used.")

  if (cs%novars > cs%max_fields) call restart_error(cs)

  query_initialized = .false.

  n = cs%novars+1

  do m=1,cs%novars

    if (associated(cs%var_ptr4d(m)%p,f_ptr)) then

      if (cs%restart_field(m)%initialized) query_initialized = .true.

      n = m ; exit

    endif

  enddo

  if (n==cs%novars+1) then

    if (is_root_pe()) &

      call mom_error(note, "MOM_restart: Unable to find "//name//" queried by pointer, "//&

        "possibly because of the suspect comparison of pointers by ASSOCIATED.")

    query_initialized = query_initialized_name(name, cs)

  endif

end function query_initialized_4d_name

!> set_initialized_name records that a named field has been initialized.

subroutine set_initialized_name(name, CS)

  character(len=*),     intent(in)    :: name  !< The name of the field that is being set

  type(mom_restart_cs), intent(inout) :: CS    !< MOM restart control struct

  integer :: m

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "set_initialized: Module must be initialized before it is used.")

  do m=1,cs%novars ; if (trim(name) == trim(cs%restart_field(m)%var_name)) then

    cs%restart_field(m)%initialized = .true. ; exit

  endif ; enddo

  if ((m==cs%novars+1) .and. (is_root_pe())) &

    call mom_error(note,"MOM_restart: Unknown restart variable "//name// &

                        " used in set_initialized call.")

end subroutine set_initialized_name

!> Record that the array in f_ptr with the given name has been initialized.

subroutine set_initialized_0d_name(f_ptr, name, CS)

  real,         target, intent(in)    :: f_ptr !< The variable that has been initialized [arbitrary]

  character(len=*),     intent(in)    :: name  !< The name of the field that has been initialized

  type(mom_restart_cs), intent(inout) :: CS    !< MOM restart control struct

  integer :: m

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "set_initialized: Module must be initialized before it is used.")

  do m=1,cs%novars ; if (associated(cs%var_ptr0d(m)%p,f_ptr)) then

    cs%restart_field(m)%initialized = .true. ; exit

  endif ; enddo

  if (m==cs%novars+1) then

    if (is_root_pe()) &

      call mom_error(note,"MOM_restart: Unable to find "//name//" queried by pointer, "//&

        "probably because of the suspect comparison of pointers by ASSOCIATED.")

    call set_initialized_name(name, cs)

  endif

end subroutine set_initialized_0d_name

!> Record that the array in f_ptr with the given name has been initialized.

subroutine set_initialized_1d_name(f_ptr, name, CS)

  real, dimension(:),  &

                target, intent(in)    :: f_ptr !< The array that has been initialized [arbitrary]

  character(len=*),     intent(in)    :: name  !< The name of the field that has been initialized

  type(mom_restart_cs), intent(inout) :: CS    !< MOM restart control struct

  integer :: m

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "set_initialized: Module must be initialized before it is used.")

  do m=1,cs%novars ; if (associated(cs%var_ptr1d(m)%p,f_ptr)) then

    cs%restart_field(m)%initialized = .true. ; exit

  endif ; enddo

  if (m==cs%novars+1) then

    if (is_root_pe()) &

      call mom_error(note,"MOM_restart: Unable to find "//name//" queried by pointer, "//&

        "probably because of the suspect comparison of pointers by ASSOCIATED.")

    call set_initialized_name(name, cs)

  endif

end subroutine set_initialized_1d_name

!> Record that the array in f_ptr with the given name has been initialized.

subroutine set_initialized_2d_name(f_ptr, name, CS)

  real, dimension(:,:),  &

                target, intent(in)    :: f_ptr !< The array that has been initialized [arbitrary]

  character(len=*),     intent(in)    :: name  !< The name of the field that has been initialized

  type(mom_restart_cs), intent(inout) :: CS    !< MOM restart control struct

  integer :: m

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "set_initialized: Module must be initialized before it is used.")

  do m=1,cs%novars ; if (associated(cs%var_ptr2d(m)%p,f_ptr)) then

    cs%restart_field(m)%initialized = .true. ; exit

  endif ; enddo

  if (m==cs%novars+1) then

    if (is_root_pe()) &

      call mom_error(note,"MOM_restart: Unable to find "//name//" queried by pointer, "//&

        "probably because of the suspect comparison of pointers by ASSOCIATED.")

    call set_initialized_name(name, cs)

  endif

end subroutine set_initialized_2d_name

!> Record that the array in f_ptr with the given name has been initialized.

subroutine set_initialized_3d_name(f_ptr, name, CS)

  real, dimension(:,:,:),  &

                target, intent(in)    :: f_ptr !< The array that has been initialized [arbitrary]

  character(len=*),     intent(in)    :: name  !< The name of the field that has been initialized

  type(mom_restart_cs), intent(inout) :: CS    !< MOM restart control struct

  integer :: m

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "set_initialized: Module must be initialized before it is used.")

  do m=1,cs%novars ; if (associated(cs%var_ptr3d(m)%p,f_ptr)) then

    cs%restart_field(m)%initialized = .true. ; exit

  endif ; enddo

  if (m==cs%novars+1) then

    if (is_root_pe()) &

      call mom_error(note,"MOM_restart: Unable to find "//name//" queried by pointer, "//&

        "probably because of the suspect comparison of pointers by ASSOCIATED.")

    call set_initialized_name(name, cs)

  endif

end subroutine set_initialized_3d_name

!> Record that the array in f_ptr with the given name has been initialized.

subroutine set_initialized_4d_name(f_ptr, name, CS)

  real, dimension(:,:,:,:),  &

                target, intent(in)    :: f_ptr !< The array that has been initialized [arbitrary]

  character(len=*),     intent(in)    :: name  !< The name of the field that has been initialized

  type(mom_restart_cs), intent(inout) :: CS    !< MOM restart control struct

  integer :: m

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "set_initialized: Module must be initialized before it is used.")

  do m=1,cs%novars ; if (associated(cs%var_ptr4d(m)%p,f_ptr)) then

    cs%restart_field(m)%initialized = .true. ; exit

  endif ; enddo

  if (m==cs%novars+1) then

    if (is_root_pe()) &

      call mom_error(note,"MOM_restart: Unable to find "//name//" queried by pointer, "//&

        "probably because of the suspect comparison of pointers by ASSOCIATED.")

    call set_initialized_name(name, cs)

  endif

end subroutine set_initialized_4d_name

!====================== only_read_from_restarts variants =======================

!> Try to read a named 4-d field from the restart files

subroutine only_read_restart_field_4d(varname, f_ptr, G, CS, position, filename, directory, success, scale)

  character(len=*),                intent(in)    :: varname   !< The variable name to be used in the restart file

  real, dimension(:,:,:,:),        intent(inout) :: f_ptr     !< The array for the field to be read

                                                              !! in arbitrary rescaled units [A ~> a]

  type(ocean_grid_type),           intent(in)    :: G         !< The ocean's grid structure

  type(mom_restart_cs),            intent(in)    :: CS        !< MOM restart control struct

  integer,               optional, intent(in)    :: position  !< A coded integer indicating the horizontal

                                                              !! position of this variable

  character(len=*),      optional, intent(in)    :: filename  !< The list of restart file names or a single

                                                              !! character 'r' to read automatically named files

  character(len=*),      optional, intent(in)    :: directory !< The directory in which to seek restart files.

  logical,               optional, intent(out)   :: success   !< True if the field was read successfully

  real,                  optional, intent(in)    :: scale     !< A factor by which the field will be scaled

                                                              !! [A a-1 ~> 1] to convert from the units in

                                                              !! the file to the internal units of this field

  ! Local variables

  character(len=:), allocatable :: file_path ! The full path to the file with the variable

  logical :: found     ! True if the variable was found.

  logical :: is_global ! True if the variable is in a global file.

  found = find_var_in_restart_files(varname, g, cs, file_path, filename, directory, is_global)

  if (found) then

    call mom_read_data(file_path, varname, f_ptr, g%domain, timelevel=1, position=position, &

                       scale=scale, global_file=is_global)

  endif

  if (present(success)) success = found

end subroutine only_read_restart_field_4d

!> Try to read a named 3-d field from the restart files

subroutine only_read_restart_field_3d(varname, f_ptr, G, CS, position, filename, directory, success, scale)

  character(len=*),                intent(in)    :: varname   !< The variable name to be used in the restart file

  real, dimension(:,:,:),          intent(inout) :: f_ptr     !< The array for the field to be read

                                                              !! in arbitrary rescaled units [A ~> a]

  type(ocean_grid_type),           intent(in)    :: G         !< The ocean's grid structure

  type(mom_restart_cs),            intent(in)    :: CS        !< MOM restart control struct

  integer,               optional, intent(in)    :: position  !< A coded integer indicating the horizontal

                                                              !! position of this variable

  character(len=*),      optional, intent(in)    :: filename  !< The list of restart file names or a single

                                                              !! character 'r' to read automatically named files

  character(len=*),      optional, intent(in)    :: directory !< The directory in which to seek restart files.

  logical,               optional, intent(out)   :: success   !< True if the field was read successfully

  real,                  optional, intent(in)    :: scale     !< A factor by which the field will be scaled

                                                              !! [A a-1 ~> 1] to convert from the units in

                                                              !! the file to the internal units of this field

  ! Local variables

  character(len=:), allocatable :: file_path ! The full path to the file with the variable

  logical :: found     ! True if the variable was found.

  logical :: is_global ! True if the variable is in a global file.

  found = find_var_in_restart_files(varname, g, cs, file_path, filename, directory, is_global)

  if (found) then

    call mom_read_data(file_path, varname, f_ptr, g%domain, timelevel=1, position=position, &

                       scale=scale, global_file=is_global)

  endif

  if (present(success)) success = found

end subroutine only_read_restart_field_3d

!> Try to read a named 2-d field from the restart files

subroutine only_read_restart_field_2d(varname, f_ptr, G, CS, position, filename, directory, success, scale)

  character(len=*),                intent(in)    :: varname   !< The variable name to be used in the restart file

  real, dimension(:,:),            intent(inout) :: f_ptr     !< The array for the field to be read

                                                              !! in arbitrary rescaled units [A ~> a]

  type(ocean_grid_type),           intent(in)    :: G         !< The ocean's grid structure

  type(mom_restart_cs),            intent(in)    :: CS        !< MOM restart control struct

  integer,               optional, intent(in)    :: position  !< A coded integer indicating the horizontal

                                                              !! position of this variable

  character(len=*),      optional, intent(in)    :: filename  !< The list of restart file names or a single

                                                              !! character 'r' to read automatically named files

  character(len=*),      optional, intent(in)    :: directory !< The directory in which to seek restart files.

  logical,               optional, intent(out)   :: success   !< True if the field was read successfully

  real,                  optional, intent(in)    :: scale     !< A factor by which the field will be scaled

                                                              !! [A a-1 ~> 1] to convert from the units in

                                                              !! the file to the internal units of this field

  ! Local variables

  character(len=:), allocatable :: file_path ! The full path to the file with the variable

  logical :: found     ! True if the variable was found.

  logical :: is_global ! True if the variable is in a global file.

  found = find_var_in_restart_files(varname, g, cs, file_path, filename, directory, is_global)

  if (found) then

    call mom_read_data(file_path, varname, f_ptr, g%domain, timelevel=1, position=position, &

                       scale=scale, global_file=is_global)

  endif

  if (present(success)) success = found

end subroutine only_read_restart_field_2d

!> Try to read a named 3-d field from the restart files

subroutine only_read_restart_pair_3d(a_ptr, b_ptr, a_name, b_name, G, CS, &

                                     stagger, filename, directory, success, scale)

  real, dimension(:,:,:),          intent(inout) :: a_ptr     !< The array for the first field to be read

                                                              !! in arbitrary rescaled units [A ~> a]

  real, dimension(:,:,:),          intent(inout) :: b_ptr     !< The array for the second field to be read

                                                              !! in arbitrary rescaled units [A ~> a]

  character(len=*),                intent(in)    :: a_name    !< The first variable name to be used in the restart file

  character(len=*),                intent(in)    :: b_name    !< The second variable name to be used in the restart file

  type(ocean_grid_type),           intent(in)    :: G         !< The ocean's grid structure

  type(mom_restart_cs),            intent(in)    :: CS        !< MOM restart control struct

  integer,               optional, intent(in)    :: stagger   !< A coded integer indicating the horizontal

                                                              !! position of this pair of variables

  character(len=*),      optional, intent(in)    :: filename  !< The list of restart file names or a single

                                                              !! character 'r' to read automatically named files

  character(len=*),      optional, intent(in)    :: directory !< The directory in which to seek restart files.

  logical,               optional, intent(out)   :: success   !< True if the field was read successfully

  real,                  optional, intent(in)    :: scale     !< A factor by which the fields will be scaled

                                                              !! [A a-1 ~> 1] to convert from the units in

                                                              !! the file to the internal units of this field

  ! Local variables

  character(len=:), allocatable :: file_path_a ! The full path to the file with the first variable

  character(len=:), allocatable :: file_path_b ! The full path to the file with the second variable

  integer :: a_pos, b_pos       ! A coded position for the two variables.

  logical :: a_found, b_found   ! True if the variables were found.

  logical :: global_a, global_b ! True if the variables are in global files.

  a_found = find_var_in_restart_files(a_name, g, cs, file_path_a, filename, directory, global_a)

  b_found = find_var_in_restart_files(b_name, g, cs, file_path_b, filename, directory, global_b)

  a_pos = east_face ; b_pos = north_face

  if (present(stagger)) then ; select case (stagger)

    case (agrid)    ; a_pos = center ; b_pos = center

    case (bgrid_ne) ; a_pos = corner ; b_pos = corner

    case (cgrid_ne) ; a_pos = east_face ; b_pos = north_face

    case default    ; a_pos = east_face ; b_pos = north_face

  end select ; endif

  if (a_found .and. b_found) then

    call mom_read_data(file_path_a, a_name, a_ptr, g%domain, timelevel=1, position=a_pos, &

                       scale=scale, global_file=global_b, file_may_be_4d=.true.)

    call mom_read_data(file_path_b, b_name, b_ptr, g%domain, timelevel=1, position=b_pos, &

                       scale=scale, global_file=global_b, file_may_be_4d=.true.)

  endif

  if (present(success)) success = (a_found .and. b_found)

end subroutine only_read_restart_pair_3d

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

function find_var_in_restart_files(varname, G, CS, file_path, filename, directory, is_global) result (found)

  character(len=*),                intent(in)    :: varname   !< The variable name to be used in the restart file

  type(ocean_grid_type),           intent(in)    :: g         !< The ocean's grid structure

  type(mom_restart_cs),            intent(in)    :: cs        !< MOM restart control struct

  character(len=:),   allocatable, intent(out)   :: file_path !< The full path to the file in which the

                                                              !! variable is found

  character(len=*),      optional, intent(in)    :: filename  !< The list of restart file names or a single

                                                              !! character 'r' to read automatically named files

  character(len=*),      optional, intent(in)    :: directory !< The directory in which to seek restart files.

  logical,               optional, intent(out)   :: is_global !< True if the file is global.

  logical :: found !< True if the named variable was found in the restart files.

  ! Local variables

  character(len=240), allocatable, dimension(:) :: file_paths ! The possible file names.

  character(len=:), allocatable :: dir ! The directory to read from.

  character(len=:), allocatable :: fname ! The list of file names.

  logical, allocatable, dimension(:) :: global_file  ! True if the file is global

  integer :: n, num_files

  dir = "./INPUT/" ; if (present(directory)) dir = trim(directory)

  ! Set the default return values.

  found = .false.

  file_path = ""

  if (present(is_global)) is_global = .false.

  fname = 'r'

  if (present(filename)) then

    if (.not.((len_trim(filename) == 1) .and. (filename(1:1) == 'F'))) fname = filename

  endif

  num_files = get_num_restart_files(fname, dir, g, cs)

  if (num_files == 0) return

  allocate(file_paths(num_files), global_file(num_files))

  num_files = open_restart_units(fname, dir, g, cs, file_paths=file_paths, global_files=global_file)

  do n=1,num_files ; if (field_exists(file_paths(n), varname, mom_domain=g%domain)) then

    found = .true.

    file_path = file_paths(n)

    if (present(is_global)) is_global = global_file(n)

    exit

  endif ; enddo

  deallocate(file_paths, global_file)

end function find_var_in_restart_files

!====================== end of the only_read_from_restarts variants =======================

!> Copy the restart variable with the specified name into a 3-d array, perhaps after rotation

subroutine copy_restart_var_3d(var, name, CS, unrotate)

  real, dimension(:,:,:), intent(inout) :: var   !< The field that is being copied [arbitrary]

  character(len=*),       intent(in)    :: name  !< The name of the field that is being copied

  type(mom_restart_cs),   intent(in)    :: CS    !< MOM restart control struct

  logical, optional,      intent(in)    :: unrotate !< If present and true, the output is on an unrotated grid.

  logical :: keep_rotation

  character(len=256) :: size_msg  !< The array sizes

  integer :: m, n

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "query_initialized: Module must be initialized before it is used.")

  if (cs%novars > cs%max_fields) call restart_error(cs)

  keep_rotation = .true. ; if (present(unrotate)) keep_rotation = .not.unrotate

  n = cs%novars+1

  do m=1,cs%novars

    if (trim(name) == cs%restart_field(m)%var_name) then

      if (.not.associated(cs%var_ptr3d(m)%p)) then

        call mom_error(fatal, "MOM_restart: copy_restart_var(_3d) "//&

                      "attempted to copy restart variable "//name//" with the wrong rank.")

      elseif (cs%restart_field(m)%initialized) then

        if (cs%turns == 0 .or. keep_rotation) then

          if ( size_mismatch_3d(var, cs%var_ptr3d(m)%p, cs%turns, size_msg) ) &

            call mom_error(fatal, "MOM_restart: copy_restart_var(_3d) "//&

                      "attempted to copy restart variable "//name//" with the wrong sizes, "//trim(size_msg))

          var(:,:,:) = cs%var_ptr3d(m)%p(:,:,:)

        else

          call rotate_array(cs%var_ptr3d(m)%p, -cs%turns, var)

        endif

      else

        call mom_error(note, "MOM_restart: copy_restart_var(_3d) "//&

                      "attempted to copy uninitialized restart variable "//name//".")

      endif

      n = m ; exit

    endif

  enddo

  if ((n==cs%novars+1) .and. (is_root_pe())) &

    call mom_error(note, "MOM_restart: copy_restart_var(_3d) "//&

                  "attempted to copy unknown restart variable "//name//".")

end subroutine copy_restart_var_3d

!> Copy the restart vector component variables with the specified names into a pair

!! of 3-d arrays, perhaps after rotation

subroutine copy_restart_vector_3d(u_var, v_var, u_name, v_name, CS, unrotate, scalar_pair)

  real, dimension(:,:,:), intent(inout) :: u_var !< The u-component of the field that is being copied [arbitrary]

  real, dimension(:,:,:), intent(inout) :: v_var !< The u-component of the field that is being copied [arbitrary]

  character(len=*),       intent(in)    :: u_name !< The name of the u-component of the field that is being copied

  character(len=*),       intent(in)    :: v_name !< The name of the v-component of the field that is being copied

  type(mom_restart_cs),   intent(in)    :: CS    !< MOM restart control struct

  logical, optional,      intent(in)    :: unrotate !< If present and true, the output is on an unrotated grid.

  logical,      optional, intent(in)    :: scalar_pair !< If true, the arrays describe a pair of

                                                 !! scalars, instead of vector components

                                                 !! whose signs change when rotated

  logical :: keep_rotation, scalars

  character(len=256) :: size_msg  !< The array sizes

  integer :: m, n_u, n_v

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "query_initialized: Module must be initialized before it is used.")

  if (cs%novars > cs%max_fields) call restart_error(cs)

  keep_rotation = .true. ; if (present(unrotate)) keep_rotation = .not.unrotate

  n_u = cs%novars+1 ; n_v = cs%novars+1

  do m=1,cs%novars

    if (trim(u_name) == cs%restart_field(m)%var_name) then

      if (.not.associated(cs%var_ptr3d(m)%p)) then

        call mom_error(fatal, "MOM_restart: copy_restart_vector(_3d) "//&

                      "attempted to copy restart variable "//trim(u_name)//" with the wrong rank.")

      elseif (cs%restart_field(m)%initialized) then

        n_u = m

      else

        call mom_error(note, "MOM_restart: copy_restart_vector(_3d) "//&

                      "attempted to copy uninitialized restart variable "//trim(u_name)//".")

        n_u = -1

      endif

    endif

    if (trim(v_name) == cs%restart_field(m)%var_name) then

      if (.not.associated(cs%var_ptr3d(m)%p)) then

        call mom_error(fatal, "MOM_restart: copy_restart_vector(_3d) "//&

                      "attempted to copy restart variable "//trim(v_name)//" with the wrong rank.")

      elseif (cs%restart_field(m)%initialized) then

        n_v = m

      else

        call mom_error(note, "MOM_restart: copy_restart_vector(_3d) "//&

                      "attempted to copy uninitialized restart variable "//trim(v_name)//".")

        n_v = -1

      endif

    endif

  enddo

  if ((n_u==cs%novars+1) .and. (is_root_pe())) &

    call mom_error(note, "MOM_restart: copy_restart_vector(_3d) "//&

                  "attempted to copy unknown restart variable "//trim(u_name)//".")

  if ((n_v==cs%novars+1) .and. (is_root_pe())) &

    call mom_error(note, "MOM_restart: copy_restart_vector(_3d) "//&

                  "attempted to copy unknown restart variable "//trim(v_name)//".")

  if ((n_u>0) .and. (n_u<=cs%novars) .and. (n_v>0) .and. (n_v<=cs%novars)) then

    ! Now actually update the vector.

    if ( size_mismatch_3d(u_var, cs%var_ptr3d(n_u)%p, cs%turns, size_msg) ) &

      call mom_error(fatal, "MOM_restart: copy_restart_vector(_3d) "//&

                "attempted to copy restart variable "//trim(u_name)//" with the wrong sizes, "//trim(size_msg))

    if ( size_mismatch_3d(v_var, cs%var_ptr3d(n_v)%p, cs%turns, size_msg) ) &

      call mom_error(fatal, "MOM_restart: copy_restart_vector(_3d) "//&

                "attempted to copy restart variable "//trim(v_name)//" with the wrong sizes, "//trim(size_msg))

    if (cs%turns == 0 .or. keep_rotation) then

      u_var(:,:,:) = cs%var_ptr3d(n_u)%p(:,:,:)

      v_var(:,:,:) = cs%var_ptr3d(n_v)%p(:,:,:)

    else

      scalars = .false. ; if (present(scalar_pair)) scalars = scalar_pair

      if ((modulo(cs%turns, 2) == 0) .and. scalars) then

        call rotate_array_pair(cs%var_ptr3d(n_u)%p, cs%var_ptr3d(n_v)%p, -cs%turns, u_var, v_var)

      elseif (modulo(cs%turns, 2) == 0) then

        call rotate_vector(cs%var_ptr3d(n_u)%p, cs%var_ptr3d(n_v)%p, -cs%turns, u_var, v_var)

      elseif (scalars) then  ! This is less common

        call rotate_array_pair(cs%var_ptr3d(n_v)%p, cs%var_ptr3d(n_u)%p, -cs%turns, u_var, v_var)

      else

        call rotate_vector(cs%var_ptr3d(n_v)%p, cs%var_ptr3d(n_u)%p, -cs%turns, u_var, v_var)

      endif

    endif

  endif

end subroutine copy_restart_vector_3d

!> Indicate if two 3-d arrays are not of the same size after rotation is considered.

logical function size_mismatch_3d(var_a, var_b, turns, size_msg)

  real,    intent(in) :: var_a(:,:,:)   !< The first field being compared

  real,    intent(in) :: var_b(:,:,:)   !< The second field being compared

  integer, intent(in) :: turns          !< Number of quarter turns from input to model domain

  character(len=256), intent(out) :: size_msg  !< The array sizes

  if (modulo(turns, 2) == 0) then

    size_mismatch_3d = ( (size(var_a,1) /= size(var_b,1)) .or. &

                         (size(var_a,2) /= size(var_b,2)) .or. &

                         (size(var_a,3) /= size(var_b,3)) )

  else

    size_mismatch_3d = ( (size(var_a,1) /= size(var_b,2)) .or. &

                         (size(var_a,2) /= size(var_b,1)) .or. &

                         (size(var_a,3) /= size(var_b,3)) )

  endif

  write(size_msg, '(3(1x,I0), " vs ", 3(1x,I0))') size(var_a,1), size(var_a,2), size(var_a,3), &

                                                  size(var_b,1), size(var_b,2), size(var_b,3)

end function size_mismatch_3d

!> save_restart saves all registered variables to restart files.

subroutine save_restart(directory, time, G, CS, time_stamped, filename, GV, num_rest_files, write_IC)

  character(len=*),        intent(in)    :: directory !< The directory where the restart files

                                                  !! are to be written

  type(time_type),         intent(in)    :: time  !< The current model time

  type(ocean_grid_type),   intent(inout) :: g     !< The ocean's grid structure as seen from the driver.

  type(mom_restart_cs),    intent(inout) :: cs    !< MOM restart control struct

  logical,       optional, intent(in)    :: time_stamped !< If present and true, add time-stamp

                                                  !! to the restart file names

  character(len=*), optional, intent(in) :: filename !< A filename that overrides the name in CS%restartfile

  type(verticalgrid_type), &

                 optional, intent(in)    :: gv    !< The ocean's vertical grid structure

  integer,       optional, intent(out)   :: num_rest_files !< number of restart files written

  logical,       optional, intent(in)    :: write_ic !< If present and true, initial conditions

                                                  !! are being written

  ! Local variables

  type(vardesc) :: vars(cs%max_fields)  ! Descriptions of the fields that

                                        ! are to be read from the restart file.

  type(mom_field) :: fields(cs%max_fields) ! Opaque types containing metadata describing

                                        ! each variable that will be written.

  character(len=512) :: restartpath     ! The restart file path (dir/file).

  character(len=256) :: restartname     ! The restart file name (no dir).

  character(len=8)   :: suffix          ! A suffix (like _2) that is appended

                                        ! to the name of files after the first.

  integer(kind=int64) :: var_sz, size_in_file ! The size in bytes of each variable

                                        ! and the variables already in a file.

  integer(kind=int64), parameter :: max_file_size = 4294967292_int64 ! The maximum size in bytes for the

                                        ! starting position of each variable in a file's record,

                                        ! based on the use of NetCDF 3.6 or later.  For earlier

                                        ! versions of NetCDF, the value was 2147483647_int64.

  integer :: start_var, next_var        ! The starting variables of the

                                        ! current and next files.

  type(mom_infra_file) :: io_handle     ! The I/O handle of the open fileset

  integer :: m, nz, na

  integer :: num_files                  ! The number of restart files that will be used.

  integer :: seconds, days, year, month, hour, minute

  character(len=8) :: z_grid, t_grid    ! Variable grid info.

  integer :: pos                        ! A coded integer indicating the horizontal staggering of a variable

  real :: conv                          ! Shorthand for the conversion factor [a A-1 ~> 1]

  real :: restart_time                  ! The model time at whic the restart file is being written [days]

  character(len=32) :: filename_appendix = '' ! Appendix to filename for ensemble runs

  integer :: length                     ! The length of a text string.

  character(len=256) :: mesg, var_name

  integer(kind=int64) :: check_val(cs%max_fields,1)

  logical :: verbose

  integer :: isl, iel, jsl, jel

  integer :: turns                      ! Number of quarter turns from input to model domain

  integer, parameter :: nmax_extradims = 5

  type(axis_info), dimension(:), allocatable :: extra_axes

  turns = cs%turns

  allocate (extra_axes(nmax_extradims))

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "save_restart: Module must be initialized before it is used.")

  if (cs%novars > cs%max_fields) call restart_error(cs)

  verbose = (is_root_pe() .and. (mom_get_verbosity() >= 7))

  ! With parallel read & write, it is possible to disable the following...

  num_files = 0

  next_var = 0

  nz = 1 ; if (present(gv)) nz = gv%ke

  restart_time = time_type_to_real(time) / 86400.0

  restartname = trim(cs%restartfile)

  if (present(filename)) restartname = trim(filename)

  if (PRESENT(time_stamped)) then ; if (time_stamped) then

    call get_date(time, year, month, days, hour, minute, seconds)

    ! Compute the year-day, because I don't like months. - RWH

    do m=1,month-1

      days = days + days_in_month(set_date(year, m, 2, 0, 0, 0))

    enddo

    seconds = seconds + 60*minute + 3600*hour

    if (year <= 9999) then

      write(restartname,'("_Y",I4.4,"_D",I3.3,"_S",I5.5)') year, days, seconds

    elseif (year <= 99999) then

      write(restartname,'("_Y",I5.5,"_D",I3.3,"_S",I5.5)') year, days, seconds

    else

      write(restartname,'("_Y",I10.10,"_D",I3.3,"_S",I5.5)') year, days, seconds

    endif

    restartname = trim(cs%restartfile)//trim(restartname)

  endif ; endif

  ! Determine if there is a filename_appendix (used for ensemble runs).

  call get_filename_appendix(filename_appendix)

  if (len_trim(filename_appendix) > 0) then

    length = len_trim(restartname)

    if (restartname(length-2:length) == '.nc') then

      restartname = restartname(1:length-3)//'.'//trim(filename_appendix)//'.nc'

    else

      restartname = restartname(1:length)  //'.'//trim(filename_appendix)

    endif

  endif

  next_var = 1

  do while (next_var <= cs%novars )

    start_var = next_var

    size_in_file = 8*(2*g%Domain%niglobal+2*g%Domain%njglobal+2*nz+1000)

    do m=start_var,cs%novars

      call query_vardesc(cs%restart_field(m)%vars, position=pos, &

                         z_grid=z_grid, t_grid=t_grid, caller="save_restart", &

                         extra_axes=extra_axes)

      var_sz = get_variable_byte_size(pos, z_grid, t_grid, g, nz)

      ! factor in size of extra axes, or multiply by 1

      do na=1,nmax_extradims

        var_sz = var_sz*extra_axes(na)%ax_size

      enddo

      if ((m==start_var) .OR. (size_in_file < max_file_size-var_sz)) then

        size_in_file = size_in_file + var_sz

      else ; exit

      endif

    enddo

    next_var = m

    restartpath = trim(directory) // trim(restartname)

    write(suffix,'("_",I0)') num_files

    length = len_trim(restartpath)

    if (length < 3) then  ! This case is very uncommon but this test avoids segmentation-faults.

      if (num_files > 0) restartpath = trim(restartpath) // suffix

      restartpath = trim(restartpath)//".nc"

    elseif (restartpath(length-2:length) == ".nc") then

      if (num_files > 0) restartpath = restartpath(1:length-3)//trim(suffix)//".nc"

    else

      if (num_files > 0) restartpath = trim(restartpath) // suffix

      restartpath = trim(restartpath)//".nc"

    endif

    do m=start_var,next_var-1

      vars(m-start_var+1) = cs%restart_field(m)%vars

    enddo

    call query_vardesc(vars(1), t_grid=t_grid, position=pos, caller="save_restart")

    t_grid = adjustl(t_grid)

    if (t_grid(1:1) /= 'p') &

      call modify_vardesc(vars(1), t_grid='s', caller="save_restart")

    !Prepare the checksum of the restart fields to be written to restart files

    do m=start_var,next_var-1

      call query_vardesc(vars(m), position=pos, name=var_name, caller="save_restart")

      if (modulo(turns, 2) == 0) then

        call get_checksum_loop_ranges(g, cs, pos, isl, iel, jsl, jel)

      else   ! Note that G is always the unrotated grid as it is seen by the driver level.

        call get_checksum_loop_ranges(g, cs, pos, jsl, jel, isl, iel)

      endif

      if (verbose) then

        if (pos == center) then

          write(mesg, '(" is in CENTER position, checksum range",4(1x,I0))') isl, iel, jsl, jel

        elseif (pos == corner) then

          write(mesg, '(" is in CORNER position, checksum range",4(1x,I0))') isl, iel, jsl, jel

        elseif (pos == north_face) then

          write(mesg, '(" is in NORTH_FACE position, checksum range",4(1x,I0))') isl, iel, jsl, jel

        elseif (pos == east_face) then

          write(mesg, '(" is in EAST_FACE position, checksum range",4(1x,I0))') isl, iel, jsl, jel

        else

          write(mesg, '(" is in another position, ",I0,", checksum range",4(1x,I0))') pos, isl, iel, jsl, jel

        endif

        call mom_mesg(trim(var_name)//mesg)

      endif

      conv = cs%restart_field(m)%conv

      if (associated(cs%var_ptr3d(m)%p)) then

        check_val(m-start_var+1,1) = chksum(cs%var_ptr3d(m)%p(isl:iel,jsl:jel,:), turns=-turns, unscale=conv)

      elseif (associated(cs%var_ptr2d(m)%p)) then

        check_val(m-start_var+1,1) = chksum(cs%var_ptr2d(m)%p(isl:iel,jsl:jel), turns=-turns, unscale=conv)

      elseif (associated(cs%var_ptr4d(m)%p)) then

        check_val(m-start_var+1,1) = chksum(cs%var_ptr4d(m)%p(isl:iel,jsl:jel,:,:), turns=-turns, unscale=conv)

      elseif (associated(cs%var_ptr1d(m)%p)) then

        check_val(m-start_var+1,1) = chksum(cs%var_ptr1d(m)%p(:), unscale=conv)

      elseif (associated(cs%var_ptr0d(m)%p)) then

        check_val(m-start_var+1,1) = chksum(cs%var_ptr0d(m)%p, pelist=(/pe_here()/), unscale=conv)

      endif

    enddo

    if (cs%parallel_restartfiles) then

      call create_mom_file(io_handle, trim(restartpath), vars, next_var-start_var, &

          fields, multiple, g=g, gv=gv, checksums=check_val, extra_axes=extra_axes)

    else

      call create_mom_file(io_handle, trim(restartpath), vars, next_var-start_var, &

          fields, single_file, g=g, gv=gv, checksums=check_val, extra_axes=extra_axes)

    endif

    do m=start_var,next_var-1

      if (associated(cs%var_ptr3d(m)%p)) then

        call mom_write_field(io_handle, fields(m-start_var+1), g%Domain, cs%var_ptr3d(m)%p, &

                             restart_time, unscale=cs%restart_field(m)%conv, turns=-turns, &

                             zero_zeros=cs%unsigned_zeros)

      elseif (associated(cs%var_ptr2d(m)%p)) then

        call mom_write_field(io_handle, fields(m-start_var+1), g%Domain, cs%var_ptr2d(m)%p, &

                             restart_time, unscale=cs%restart_field(m)%conv, turns=-turns, &

                             zero_zeros=cs%unsigned_zeros)

      elseif (associated(cs%var_ptr4d(m)%p)) then

        call mom_write_field(io_handle, fields(m-start_var+1), g%Domain, cs%var_ptr4d(m)%p, &

                             restart_time, unscale=cs%restart_field(m)%conv, turns=-turns, &

                             zero_zeros=cs%unsigned_zeros)

      elseif (associated(cs%var_ptr1d(m)%p)) then

        call mom_write_field(io_handle, fields(m-start_var+1), cs%var_ptr1d(m)%p, &

                             restart_time, unscale=cs%restart_field(m)%conv, &

                             zero_zeros=cs%unsigned_zeros)

      elseif (associated(cs%var_ptr0d(m)%p)) then

        call mom_write_field(io_handle, fields(m-start_var+1), cs%var_ptr0d(m)%p, &

                             restart_time, unscale=cs%restart_field(m)%conv, &

                             zero_zeros=cs%unsigned_zeros)

      endif

    enddo

    call io_handle%close()

    num_files = num_files+1

  enddo

  if (present(num_rest_files)) num_rest_files = num_files

end subroutine save_restart

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

subroutine restore_state(filename, directory, day, G, CS)

  character(len=*),      intent(in)  :: filename  !< The list of restart file names or a single

                                                  !! character 'r' to read automatically named files

  character(len=*),      intent(in)  :: directory !< The directory in which to find restart files

  type(time_type),       intent(out) :: day       !< The time of the restarted run

  type(ocean_grid_type), intent(in)  :: g         !< The ocean's grid structure

  type(mom_restart_cs),  intent(inout) :: cs      !< MOM restart control struct

  ! Local variables

  real :: scale  ! A scaling factor for reading a field [A a-1 ~> 1] to convert

                 ! from the units in the file to the internal units of this field

  real :: conv   ! The output conversion factor for writing a field [a A-1 ~> 1]

  character(len=512) :: mesg      ! A message for warnings.

  character(len=80) :: varname    ! A variable's name.

  integer :: num_file        ! The number of files (restart files and others

                             ! explicitly in filename) that are open.

  integer :: i, n, m, missing_fields

  integer :: isl, iel, jsl, jel

  integer :: nvar, ntime, pos

  type(mom_infra_file) :: io_handles(cs%max_fields) ! The I/O units of all open files.

  character(len=200) :: unit_path(cs%max_fields) ! The file names.

  logical :: unit_is_global(cs%max_fields) ! True if the file is global.

  real    :: t1, t2 ! Two times from the start of different files [days].

  real, allocatable :: time_vals(:)  ! Times from a file extracted with getl_file_times [days]

  type(mom_field), allocatable :: fields(:)

  logical            :: is_there_a_checksum ! Is there a valid checksum that should be checked.

  integer(kind=int64) :: checksum_file  ! The checksum value recorded in the input file.

  integer(kind=int64) :: checksum_data  ! The checksum value for the data that was read in.

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "restore_state: Module must be initialized before it is used.")

  if (cs%novars > cs%max_fields) call restart_error(cs)

  ! Get NetCDF ids for all of the restart files.

  if ((len_trim(filename) == 1) .and. (filename(1:1) == 'F')) then

    num_file = open_restart_units('r', directory, g, cs, io_handles=io_handles, &

                     file_paths=unit_path, global_files=unit_is_global)

  else

    num_file = open_restart_units(filename, directory, g, cs, io_handles=io_handles, &

                     file_paths=unit_path, global_files=unit_is_global)

  endif

  if (num_file == 0) then

    write(mesg,'("Unable to find any restart files specified by  ",A,"  in directory ",A,".")') &

                  trim(filename), trim(directory)

    call mom_error(fatal,"MOM_restart: "//mesg)

  endif

  ! Get the time from the first file in the list that has one.

  do n=1,num_file

    call io_handles(n)%get_file_times(time_vals, ntime)

    if (ntime < 1) cycle

    t1 = time_vals(1)

    deallocate(time_vals)

    day = real_to_time(t1*86400.0)

    exit

  enddo

  if (n>num_file) call mom_error(warning, "MOM_restart: No times found in restart files.")

  ! Check the remaining files for different times and issue a warning

  ! if they differ from the first time.

    do m = n+1,num_file

      call io_handles(n)%get_file_times(time_vals, ntime)

      if (ntime < 1) cycle

      t2 = time_vals(1)

      deallocate(time_vals)

      if (t1 /= t2 .and. is_root_pe()) then

        write(mesg,'("WARNING: Restart file ",I0," has time ",F10.4,"whereas &

              &simulation is restarted at ",F10.4," (differing by ",F10.4,").")') &

              m, t1, t2, t1-t2

        call mom_error(warning, "MOM_restart: "//mesg)

      endif

    enddo

  ! Read each variable from the first file in which it is found.

  do n=1,num_file

    call io_handles(n)%get_file_info(nvar=nvar)

    allocate(fields(nvar))

    call io_handles(n)%get_file_fields(fields(1:nvar))

    do m=1, nvar

      call io_handles(n)%get_field_atts(fields(m), name=varname)

      do i=1,cs%num_obsolete_vars

        if (adjustl(lowercase(trim(varname))) == adjustl(lowercase(trim(cs%restart_obsolete(i)%field_name)))) then

            call mom_error(fatal, "MOM_restart restore_state: Attempting to use obsolete restart field "//&

                           trim(varname)//" - the new corresponding restart field is "//&

                           trim(cs%restart_obsolete(i)%replacement_name))

        endif

      enddo

    enddo

    missing_fields = 0

    do m=1,cs%novars

      if (cs%restart_field(m)%initialized) cycle

      call query_vardesc(cs%restart_field(m)%vars, position=pos, caller="restore_state")

      conv = cs%restart_field(m)%conv

      if (conv == 0.0) then ; scale = 1.0 ; else ; scale = 1.0 / conv ; endif

      if (modulo(cs%turns, 2) == 0) then

        call get_checksum_loop_ranges(g, cs, pos, isl, iel, jsl, jel)

      else   ! Note that G is always the unrotated grid as it is used during initialization.

        call get_checksum_loop_ranges(g, cs, pos, jsl, jel, isl, iel)

      endif

      do i=1, nvar

        call io_handles(n)%get_field_atts(fields(i), name=varname)

        if (lowercase(trim(varname)) == lowercase(trim(cs%restart_field(m)%var_name))) then

          checksum_data = -1

          if (cs%checksum_required) then

            call io_handles(n)%read_field_chksum(fields(i), checksum_file, is_there_a_checksum)

          else

            checksum_file = -1

            is_there_a_checksum = .false. ! Do not need to do data checksumming.

          endif

          if (associated(cs%var_ptr1d(m)%p))  then

            ! Read a 1d array, which should be invariant to domain decomposition.

            call mom_read_data(unit_path(n), varname, cs%var_ptr1d(m)%p, &

                               timelevel=1, scale=scale, mom_domain=g%Domain)

            if (is_there_a_checksum) checksum_data = chksum(cs%var_ptr1d(m)%p(:), unscale=conv)

          elseif (associated(cs%var_ptr0d(m)%p)) then ! Read a scalar...

            call mom_read_data(unit_path(n), varname, cs%var_ptr0d(m)%p, &

                               timelevel=1, scale=scale, mom_domain=g%Domain)

            if (is_there_a_checksum) checksum_data = chksum(cs%var_ptr0d(m)%p, pelist=(/pe_here()/), unscale=conv)

          elseif (associated(cs%var_ptr2d(m)%p)) then  ! Read a 2d array.

            if (pos /= 0) then

              call mom_read_data(unit_path(n), varname, cs%var_ptr2d(m)%p, &

                                 g%Domain, timelevel=1, position=pos, scale=scale, turns=cs%turns)

            else ! This array is not domain-decomposed.  This variant may be under-tested.

              call mom_error(fatal, &

                        "MOM_restart does not support 2-d arrays without domain decomposition.")

              ! call read_data(unit_path(n), varname, CS%var_ptr2d(m)%p,no_domain=.true., timelevel=1)

            endif

            if (is_there_a_checksum) checksum_data = chksum(cs%var_ptr2d(m)%p(isl:iel,jsl:jel), unscale=conv)

          elseif (associated(cs%var_ptr3d(m)%p)) then  ! Read a 3d array.

            if (pos /= 0) then

              call mom_read_data(unit_path(n), varname, cs%var_ptr3d(m)%p, &

                                 g%Domain, timelevel=1, position=pos, scale=scale, turns=cs%turns)

            else ! This array is not domain-decomposed.  This variant may be under-tested.

              call mom_error(fatal, &

                        "MOM_restart does not support 3-d arrays without domain decomposition.")

              ! call read_data(unit_path(n), varname, CS%var_ptr3d(m)%p, no_domain=.true., timelevel=1)

            endif

            if (is_there_a_checksum) checksum_data = chksum(cs%var_ptr3d(m)%p(isl:iel,jsl:jel,:), unscale=conv)

          elseif (associated(cs%var_ptr4d(m)%p)) then  ! Read a 4d array.

            if (pos /= 0) then

              call mom_read_data(unit_path(n), varname, cs%var_ptr4d(m)%p, &

                                 g%Domain, timelevel=1, position=pos, scale=scale, &

                                 global_file=unit_is_global(n), turns=cs%turns)

            else ! This array is not domain-decomposed.  This variant may be under-tested.

              call mom_error(fatal, &

                        "MOM_restart does not support 4-d arrays without domain decomposition.")

              ! call read_data(unit_path(n), varname, CS%var_ptr4d(m)%p, no_domain=.true., timelevel=1)

            endif

            if (is_there_a_checksum) checksum_data = chksum(cs%var_ptr4d(m)%p(isl:iel,jsl:jel,:,:), unscale=conv)

          else

            call mom_error(fatal, "MOM_restart restore_state: No pointers set for "//trim(varname))

          endif

          if (is_root_pe() .and. is_there_a_checksum .and. (checksum_file /= checksum_data)) then

             write (mesg,'(a,Z16,a,Z16,a)') "Checksum of input field "// trim(varname)//" ",checksum_data,&

                                          " does not match value ", checksum_file, &

                                          " stored in "//trim(unit_path(n)//"." )

             call mom_error(fatal, "MOM_restart(restore_state): "//trim(mesg) )

          endif

          cs%restart_field(m)%initialized = .true.

          exit ! Start search for next restart variable.

        endif

      enddo

      if (i>nvar) missing_fields = missing_fields+1

    enddo

    deallocate(fields)

    if (missing_fields == 0) exit

  enddo

  do n=1,num_file

    call io_handles(n)%close()

  enddo

  ! Check whether any mandatory fields have not been found.

  cs%restart = .true.

  do m=1,cs%novars

    if (.not.(cs%restart_field(m)%initialized)) then

      cs%restart = .false.

      if (cs%restart_field(m)%mand_var) then

        call mom_error(fatal,"MOM_restart: Unable to find mandatory variable " &

                       //trim(cs%restart_field(m)%var_name)//" in restart files.")

      endif

    endif

  enddo

  ! Lock the restart registry so that no further variables can be registered.

  cs%locked = .true.

end subroutine restore_state

!> restart_files_exist determines whether any restart files exist.

function restart_files_exist(filename, directory, G, CS)

  character(len=*),      intent(in)  :: filename  !< The list of restart file names or a single

                                                  !! character 'r' to read automatically named files

  character(len=*),      intent(in)  :: directory !< The directory in which to find restart files

  type(ocean_grid_type), intent(in)  :: g         !< The ocean's grid structure

  type(mom_restart_cs),  intent(in)  :: cs        !< MOM restart control struct

  logical :: restart_files_exist                  !< The function result, which indicates whether

                                                  !! any of the explicitly or automatically named

                                                  !! restart files exist in directory

  integer :: num_files

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "restart_files_exist: Module must be initialized before it is used.")

  if ((len_trim(filename) == 1) .and. (filename(1:1) == 'F')) then

    num_files = get_num_restart_files('r', directory, g, cs)

  else

    num_files = get_num_restart_files(filename, directory, g, cs)

  endif

  restart_files_exist = (num_files > 0)

end function restart_files_exist

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

function determine_is_new_run(filename, directory, G, CS) result(is_new_run)

  character(len=*),      intent(in)  :: filename  !< The list of restart file names or a single

                                                  !! character 'r' to read automatically named files

  character(len=*),      intent(in)  :: directory !< The directory in which to find restart files

  type(ocean_grid_type), intent(in)  :: g         !< The ocean's grid structure

  type(mom_restart_cs),  intent(inout) :: cs      !< MOM restart control struct

  logical :: is_new_run                           !< The function result, which indicates whether

                                                  !! this is a new run, based on the value of

                                                  !! filename and whether restart files exist

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "determine_is_new_run: Module must be initialized before it is used.")

  if (len_trim(filename) > 1) then

    cs%new_run = .false.

  elseif (len_trim(filename) == 0) then

    cs%new_run = .true.

  elseif (filename(1:1) == 'n') then

    cs%new_run = .true.

  elseif (filename(1:1) == 'F') then

    cs%new_run = (get_num_restart_files('r', directory, g, cs) == 0)

  else

    cs%new_run = .false.

  endif

  cs%new_run_set = .true.

  is_new_run = cs%new_run

end function determine_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.

function is_new_run(CS)

  type(mom_restart_cs), intent(in) :: cs  !< MOM restart control struct

  logical :: is_new_run                !< The function result, which had been stored in CS during

                                       !! a previous call to determine_is_new_run

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "is_new_run: Module must be initialized before it is used.")

  if (.not.cs%new_run_set) call mom_error(fatal, "MOM_restart " // &

      "determine_is_new_run must be called for a restart file before is_new_run.")

  is_new_run = cs%new_run

end function is_new_run

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

function open_restart_units(filename, directory, G, CS, IO_handles, file_paths, &

                            global_files) result(num_files)

  character(len=*),      intent(in)  :: filename  !< The list of restart file names or a single

                                                  !! character 'r' to read automatically named files

  character(len=*),      intent(in)  :: directory !< The directory in which to find restart files

  type(ocean_grid_type), intent(in)  :: g         !< The ocean's grid structure

  type(mom_restart_cs),  intent(in)  :: cs        !< MOM restart control struct

  type(mom_infra_file), dimension(:), &

               optional, intent(out) :: io_handles !< The I/O handles of all opened files

  character(len=*), dimension(:), &

               optional, intent(out) :: file_paths   !< The full paths to open files

  logical, dimension(:), &

               optional, intent(out) :: global_files !< True if a file is global

  integer :: num_files  !< The number of files (both automatically named restart

                        !! files and others explicitly in filename) that have been opened.

  ! Local variables

  character(len=256) :: filepath  ! The path (dir/file) to the file being opened.

  character(len=256) :: fname     ! The name of the current file.

  character(len=8)   :: suffix    ! A suffix (like "_2") that is added to any

                                  ! additional restart files.

  integer :: num_restart     ! The number of restart files that have already

                             ! been opened using their numbered suffix.

  integer :: start_char      ! The location of the starting character in the

                             ! current file name.

  integer :: nf              ! The number of files that have been found so far

  integer :: m, length

  logical :: still_looking   ! If true, the code is still looking for automatically named files

  logical :: fexists         ! True if a file has been found

  character(len=32) :: filename_appendix = '' ! Filename appendix for ensemble runs

  character(len=80) :: restartname

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "open_restart_units: Module must be initialized before it is used.")

  ! Get NetCDF ids for all of the restart files.

  num_restart = 0 ; nf = 0 ; start_char = 1

  do while (start_char <= len_trim(filename) )

    do m=start_char,len_trim(filename)

      if (filename(m:m) == ' ') exit

    enddo

    fname = filename(start_char:m-1)

    start_char = m

    do while (start_char <= len_trim(filename))

      if (filename(start_char:start_char) == ' ') then

        start_char = start_char + 1

      else

        exit

      endif

    enddo

    if ((fname(1:1)=='r') .and. ( len_trim(fname) == 1)) then

      still_looking = (num_restart <= 0) ! Avoid going through the file list twice.

      do while (still_looking)

        restartname = trim(cs%restartfile)

        ! Determine if there is a filename_appendix (used for ensemble runs).

        call get_filename_appendix(filename_appendix)

        if (len_trim(filename_appendix) > 0) then

          length = len_trim(restartname)

          if (restartname(length-2:length) == '.nc') then

            restartname = restartname(1:length-3)//'.'//trim(filename_appendix)//'.nc'

          else

            restartname = restartname(1:length)  //'.'//trim(filename_appendix)

          endif

        endif

        filepath = trim(directory) // trim(restartname)

        write(suffix,'("_",I0)') num_restart

        if (num_restart > 0) filepath = trim(filepath) // suffix

        filepath = trim(filepath)//".nc"

        num_restart = num_restart + 1

        ! Look for a global netCDF file.

        inquire(file=filepath, exist=fexists)

        if (fexists) then

          nf = nf + 1

          if (present(io_handles)) &

            call io_handles(nf)%open(trim(filepath), readonly_file, &

                mom_domain=g%Domain, threading=multiple, fileset=single_file)

          if (present(global_files)) global_files(nf) = .true.

          if (present(file_paths)) file_paths(nf) = filepath

        elseif (cs%parallel_restartfiles) then

          ! Look for decomposed files using the I/O Layout.

          fexists = file_exists(filepath, g%Domain)

          if (fexists) then

            nf = nf + 1

            if (present(io_handles)) &

              call io_handles(nf)%open(trim(filepath), readonly_file, mom_domain=g%Domain)

            if (present(global_files)) global_files(nf) = .false.

            if (present(file_paths)) file_paths(nf) = filepath

          endif

        endif

        if (fexists) then

          if (is_root_pe() .and. (present(io_handles))) &

            call mom_error(note, "MOM_restart: MOM run restarted using : "//trim(filepath))

        else

          still_looking = .false. ; exit

        endif

      enddo ! while (still_looking) loop

    else

      filepath = trim(directory)//trim(fname)

      inquire(file=filepath, exist=fexists)

      if (.not. fexists) filepath = trim(filepath)//".nc"

      inquire(file=filepath, exist=fexists)

      if (fexists) then

        nf = nf + 1

        if (present(io_handles)) &

          call io_handles(nf)%open(trim(filepath), readonly_file, &

              mom_domain=g%Domain, threading=multiple, fileset=single_file)

        if (present(global_files)) global_files(nf) = .true.

        if (present(file_paths)) file_paths(nf) = filepath

        if (is_root_pe() .and. (present(io_handles))) &

          call mom_error(note, "MOM_restart: MOM run restarted using : "//trim(filepath))

      else

        if (present(io_handles)) &

          call mom_error(warning, "MOM_restart: Unable to find restart file : "//trim(filepath))

      endif

    endif

  enddo ! while (start_char < len_trim(filename)) loop

  num_files = nf

end function open_restart_units

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

function get_num_restart_files(filenames, directory, G, CS, file_paths) result(num_files)

  character(len=*),      intent(in)  :: filenames !< The list of restart file names or a single

                                                  !! character 'r' to read automatically named files

  character(len=*),      intent(in)  :: directory !< The directory in which to find restart files

  type(ocean_grid_type), intent(in)  :: g         !< The ocean's grid structure

  type(mom_restart_cs),  intent(in)  :: cs        !< MOM restart control struct

  character(len=*), dimension(:), &

               optional, intent(out) :: file_paths !< The full paths to the restart files.

  integer :: num_files  !< The function result, the number of files (both automatically named

                        !! restart files and others explicitly in filename) that have been opened

  if (.not.cs%initialized) call mom_error(fatal, "MOM_restart " // &

      "get_num_restart_files: Module must be initialized before it is used.")

  ! This call uses open_restart_units without the optional arguments needed to actually

  ! open the files to determine the number of restart files.

  num_files = open_restart_units(filenames, directory, g, cs, file_paths=file_paths)

end function get_num_restart_files

!> Initialize this module and set up a restart control structure.

subroutine restart_init(param_file, CS, restart_root)

  type(param_file_type), intent(in) :: param_file !< A structure to parse for run-time parameters

  type(mom_restart_cs),  pointer    :: cs !< A pointer to a MOM_restart_CS object that is allocated here

  character(len=*), optional, &

                         intent(in) :: restart_root !< A filename root that overrides the value

                                          !! set by RESTARTFILE to enable the use of this module by

                                          !! other components than MOM.

  logical :: rotate_index

  ! This include declares and sets the variable "version".

# include "version_variable.h"

  character(len=40)  :: mdl = "MOM_restart"   ! This module's name.

  logical :: all_default   ! If true, all parameters are using their default values.

  if (associated(cs)) then

    call mom_error(warning, "restart_init called with an associated control structure.")

    return

  endif

  allocate(cs)

  cs%initialized = .true.

  ! Determine whether all paramters are set to their default values.

  call get_param(param_file, mdl, "PARALLEL_RESTARTFILES", cs%parallel_restartfiles, &

                 default=.false., do_not_log=.true.)

  call get_param(param_file, mdl, "MAX_FIELDS", cs%max_fields, default=100, do_not_log=.true.)

  call get_param(param_file, mdl, "RESTART_CHECKSUMS_REQUIRED", cs%checksum_required, &

                 default=.true., do_not_log=.true.)

  call get_param(param_file, mdl, "RESTART_SYMMETRIC_CHECKSUMS", cs%symmetric_checksums, &

                 default=.false., do_not_log=.true.)

  call get_param(param_file, mdl, "RESTART_UNSIGNED_ZEROS", cs%unsigned_zeros, &

                 default=.false., do_not_log=.true.)

  all_default = ((.not.cs%parallel_restartfiles) .and. (cs%max_fields == 100) .and. &

                 (cs%checksum_required) .and. (.not.cs%symmetric_checksums) .and. (.not.cs%unsigned_zeros))

  if (.not.present(restart_root)) then

    call get_param(param_file, mdl, "RESTARTFILE", cs%restartfile, &

                   default="MOM.res", do_not_log=.true.)

    all_default = (all_default .and. (trim(cs%restartfile) == trim("MOM.res")))

  endif

  ! Read all relevant parameters and write them to the model log.

  call log_version(param_file, mdl, version, "", all_default=all_default)

  call get_param(param_file, mdl, "PARALLEL_RESTARTFILES", cs%parallel_restartfiles, &

                 "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 combining output from all PEs.", &

                 default=.false.)

  if (present(restart_root)) then

    cs%restartfile = restart_root

    call log_param(param_file, mdl, "RESTARTFILE from argument", cs%restartfile)

  else

    call get_param(param_file, mdl, "RESTARTFILE", cs%restartfile, &

                 "The name-root of the restart file.", default="MOM.res")

  endif

  call get_param(param_file, mdl, "MAX_FIELDS", cs%max_fields, &

                 "The maximum number of restart fields that can be used.", &

                 default=100)

  call get_param(param_file, mdl, "RESTART_CHECKSUMS_REQUIRED", cs%checksum_required, &

                 "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.",&

                 default=.true.)

  call get_param(param_file, mdl, "RESTART_SYMMETRIC_CHECKSUMS", cs%symmetric_checksums, &

                 "If true, do the restart checksums on all the edge points for a non-reentrant "//&

                 "grid.  This requires that SYMMETRIC_MEMORY_ is defined at compile time.", &

                 default=.false.)

  call get_param(param_file, mdl, "RESTART_UNSIGNED_ZEROS", cs%unsigned_zeros, &

                 "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.", &

                 default=.false.)

  call get_param(param_file, mdl, "REENTRANT_X", cs%reentrant_x, &

                 "If true, the domain is zonally reentrant.", default=.true., do_not_log=.true.)

  call get_param(param_file, mdl, "REENTRANT_Y", cs%reentrant_y, &

                 "If true, the domain is meridionally reentrant.", default=.false., do_not_log=.true.)

  ! Maybe not the best place to do this?

  call get_param(param_file, mdl, "ROTATE_INDEX", rotate_index, &

      default=.false., do_not_log=.true.)

  cs%turns = 0

  if (rotate_index) then

    call get_param(param_file, mdl, "INDEX_TURNS", cs%turns, &

        default=1, do_not_log=.true.)

  endif

  allocate(cs%restart_field(cs%max_fields))

  allocate(cs%restart_obsolete(cs%max_fields))

  allocate(cs%var_ptr0d(cs%max_fields))

  allocate(cs%var_ptr1d(cs%max_fields))

  allocate(cs%var_ptr2d(cs%max_fields))

  allocate(cs%var_ptr3d(cs%max_fields))

  allocate(cs%var_ptr4d(cs%max_fields))

  cs%locked = .false.

end subroutine restart_init

!> Issue an error message if the restart_registry is locked.

subroutine lock_check(CS, var_desc, name)

  type(mom_restart_cs),       intent(in) :: cs        !< A MOM_restart_CS object (intent in)

  type(vardesc),    optional, intent(in) :: var_desc  !< A structure with metadata about this variable

  character(len=*), optional, intent(in) :: name      !< variable name to be used in the restart file

  character(len=256) :: var_name  ! A variable name.

  if (cs%locked) then

    if (present(var_desc)) then

      call query_vardesc(var_desc, name=var_name)

      call mom_error(fatal, "Attempted to register "//trim(var_name)//" but the restart registry is locked.")

    elseif (present(name)) then

      call mom_error(fatal, "Attempted to register "//trim(name)//" but the restart registry is locked.")

    else

      call mom_error(fatal, "Attempted to register a variable but the restart registry is locked.")

    endif

  endif

end subroutine lock_check

!> Lock the restart registry so that an error is issued if any further restart variables are registered.

subroutine restart_registry_lock(CS, unlocked)

  type(mom_restart_cs), intent(inout) :: cs        !< A MOM_restart_CS object (intent inout)

  logical, optional,    intent(in)    :: unlocked  !< If present and true, unlock the registry

  cs%locked = .true.

  if (present(unlocked)) cs%locked = .not.unlocked

end subroutine restart_registry_lock

!> Indicate that all variables have now been registered and lock the registry.

subroutine restart_init_end(CS)

  type(mom_restart_cs),  pointer    :: cs !< A pointer to a MOM_restart_CS object

  if (associated(cs)) then

    cs%locked = .true.

    if (cs%novars == 0) call restart_end(cs)

  endif

end subroutine restart_init_end

!> Deallocate memory associated with a MOM_restart_CS variable.

subroutine restart_end(CS)

  type(mom_restart_cs),  pointer    :: cs !< A pointer to a MOM_restart_CS object

  if (associated(cs%restart_field)) deallocate(cs%restart_field)

  if (associated(cs%restart_obsolete)) deallocate(cs%restart_obsolete)

  if (associated(cs%var_ptr0d)) deallocate(cs%var_ptr0d)

  if (associated(cs%var_ptr1d)) deallocate(cs%var_ptr1d)

  if (associated(cs%var_ptr2d)) deallocate(cs%var_ptr2d)

  if (associated(cs%var_ptr3d)) deallocate(cs%var_ptr3d)

  if (associated(cs%var_ptr4d)) deallocate(cs%var_ptr4d)

  deallocate(cs)

end subroutine restart_end

subroutine restart_error(CS)

  type(mom_restart_cs),  intent(in) :: CS   !< MOM restart control struct

  character(len=16)  :: num  ! String for error messages

  if (cs%novars > cs%max_fields) then

    write(num,'(I0)') cs%novars

    call mom_error(fatal,"MOM_restart: Too many fields registered for " // &

           "restart.  Set MAX_FIELDS to be at least "//trim(num)//" in the MOM input file.")

  else

    call mom_error(fatal,"MOM_restart: Unspecified fatal error.")

  endif

end subroutine restart_error

!> Return bounds for computing checksums to store in restart files

subroutine get_checksum_loop_ranges(G, CS, pos, isL, ieL, jsL, jeL)

  type(ocean_grid_type), intent(in)  :: G   !< The ocean's grid structure

  type(mom_restart_cs),  intent(in)  :: CS  !< MOM restart control structure

  integer,               intent(in)  :: pos !< A coded integer indicating the horizontal staggering

                                            !! of a variable

  integer,               intent(out) :: isL !< i-start for checksum

  integer,               intent(out) :: ieL !< i-end for checksum

  integer,               intent(out) :: jsL !< j-start for checksum

  integer,               intent(out) :: jeL !< j-end for checksum

  ! Regular non-symmetric compute domain

  isl = g%isc-g%isd+1

  iel = g%iec-g%isd+1

  jsl = g%jsc-g%jsd+1

  jel = g%jec-g%jsd+1

  ! Expand range east or south for symmetric arrays

  if (cs%symmetric_checksums) then

    if (.not.g%symmetric) call mom_error(fatal, &

        "Setting SYMMETRIC_RESTART_CHECKSUMS to true only works with symmetric memory allocation, "//&

        "which is specified at compile time by defining the cpp macro SYMMETRIC_MEMORY_.")

    if (((pos == east_face) .or. (pos == corner)) .and. (.not.cs%reentrant_x)) then ! For u-, q-points only

      if (g%isc+g%idg_offset == 1) isl = isl - 1 ! Include western edge in checksums only for western PEs

    endif

    if (((pos == north_face) .or. (pos == corner)) .and. (.not.cs%reentrant_y)) then ! For v-, q-points only

      if (g%jsc+g%jdg_offset == 1) jsl = jsl - 1 ! Include southern edge in checksums only for southern PEs

    endif

  endif

end subroutine get_checksum_loop_ranges

!> get the size of a variable in bytes

function get_variable_byte_size(pos, z_grid, t_grid, G, num_z) result(var_sz)

  integer,               intent(in) :: pos      !< An integer indicating the horizontal staggering position

  character(len=8),      intent(in) :: z_grid   !< The vertical grid string to interpret

  character(len=8),      intent(in) :: t_grid   !< A time string to interpret

  type(ocean_grid_type), intent(in) :: g        !< The ocean's grid structure

  integer,               intent(in) :: num_z    !< The number of vertical layers in the grid

  integer(kind=int64) :: var_sz !< The function result, the size in bytes of a variable

  ! Local variables

  integer :: var_periods  ! The number of entries in a time-periodic axis

  character(len=8) :: t_grid_read, t_grid_tmp ! Modified versions of t_grid

  if (pos == 0) then

    var_sz = 8

  else ! This may be an overestimate, as it is based on symmetric-memory corner points.

    var_sz = 8*(g%Domain%niglobal+1)*(g%Domain%njglobal+1)

  endif

  select case (trim(z_grid))

    case ('L') ; var_sz = var_sz * num_z

    case ('i') ; var_sz = var_sz * (num_z+1)

  end select

  t_grid_tmp = adjustl(t_grid)

  if (t_grid_tmp(1:1) == 'p') then

    if (len_trim(t_grid_tmp(2:8)) > 0) then

      var_periods = -1

      t_grid_read = adjustl(t_grid_tmp(2:8))

      read(t_grid_read,*) var_periods

      if (var_periods > 1) var_sz = var_sz * var_periods

    endif

  endif

end function get_variable_byte_size

end module mom_restart