ocean_model_mod Module Reference

Detailed Description

Top-level module for the MOM6 ocean model in coupled mode.

Data Types
interface	ocean_model_data_get
	This interface extracts a named scalar field or array from the ocean surface or public type. More...
type	ocean_public_type
	This type is used for communication with other components via the FMS coupler. The element names and types can be changed only with great deliberation, hence the persistnce of things like the cutsy element name "avg_kount". More...
type	ocean_state_type
	The ocean_state_type contains all information about the state of the ocean, with a format that is private so it can be readily changed without disrupting other coupled components. More...

Functions/Subroutines
subroutine, public	ocean_model_init (Ocean_sfc, OS, Time_init, Time_in, wind_stagger, gas_fields_ocn)
	ocean_model_init initializes the ocean model, including registering fields for restarts and reading restart files if appropriate. More...
subroutine, public	update_ocean_model (Ice_ocean_boundary, OS, Ocean_sfc, time_start_update, Ocean_coupling_time_step, update_dyn, update_thermo, Ocn_fluxes_used, start_cycle, end_cycle, cycle_length)
	update_ocean_model uses the forcing in Ice_ocean_boundary to advance the ocean model's state from the input value of Ocean_state (which must be for time time_start_update) for a time interval of Ocean_coupling_time_step, returning the publicly visible ocean surface properties in Ocean_sfc and storing the new ocean properties in Ocean_state. More...
subroutine, public	ocean_model_restart (OS, timestamp)
	This subroutine writes out the ocean model restart file. More...
subroutine, public	ocean_model_end (Ocean_sfc, Ocean_state, Time)
	ocean_model_end terminates the model run, saving the ocean state in a restart and deallocating any data associated with the ocean. More...
subroutine, public	ocean_model_save_restart (OS, Time, directory, filename_suffix)
	ocean_model_save_restart causes restart files associated with the ocean to be written out. More...
subroutine	initialize_ocean_public_type (input_domain, Ocean_sfc, diag, maskmap, gas_fields_ocn)
	Initialize the public ocean type. More...
subroutine	convert_state_to_ocean_type (sfc_state, Ocean_sfc, G, US, patm, press_to_z)
	This subroutine translates the coupler's ocean_data_type into MOM's surface state variable. This may eventually be folded into the MOM code that calculates the surface state in the first place. Note the offset in the arrays because the ocean_data_type has no halo points in its arrays and always uses absolute indicies. More...
subroutine, public	ocean_model_init_sfc (OS, Ocean_sfc)
	This subroutine extracts the surface properties from the ocean's internal state and stores them in the ocean type returned to the calling ice model. It has to be separate from the ocean_initialization call because the coupler module allocates the space for some of these variables. More...
subroutine, public	ocean_model_flux_init (OS, verbosity)
	ocean_model_flux_init is used to initialize properties of the air-sea fluxes as determined by various run-time parameters. It can be called from non-ocean PEs, or PEs that have not yet been initialzed, and it can safely be called multiple times. More...
subroutine, public	ocean_stock_pe (OS, index, value, time_index)
	Ocean_stock_pe - returns the integrated stocks of heat, water, etc. for conservation checks. Because of the way FMS is coded, only the root PE has the integrated amount, while all other PEs get 0. More...
subroutine	ocean_model_data2d_get (OS, Ocean, name, array2D, isc, jsc)
	This subroutine extracts a named 2-D field from the ocean surface or public type. More...
subroutine	ocean_model_data1d_get (OS, Ocean, name, value)
	This subroutine extracts a named scalar field from the ocean surface or public type. More...
subroutine, public	ocean_public_type_chksum (id, timestep, ocn)
	Write out FMS-format checsums on fields from the ocean surface state. More...
subroutine, public	get_ocean_grid (OS, Gridp)
	This subroutine gives a handle to the grid from ocean state. More...
subroutine, public	ocean_model_get_uv_surf (OS, Ocean, name, array2D, isc, jsc)
	This subroutine extracts a named (u- or v-) 2-D surface current from ocean internal state. More...

Function/Subroutine Documentation

convert_state_to_ocean_type()

subroutine ocean_model_mod::convert_state_to_ocean_type ( type(surface), intent(inout)  sfc_state, type(ocean_public_type), intent(inout), target  Ocean_sfc, type(ocean_grid_type), intent(inout)  G, type(unit_scale_type), intent(in)  US, real, dimension(:,:), intent(in), optional  patm, real, intent(in), optional  press_to_z  )

private

This subroutine translates the coupler's ocean_data_type into MOM's surface state variable. This may eventually be folded into the MOM code that calculates the surface state in the first place. Note the offset in the arrays because the ocean_data_type has no halo points in its arrays and always uses absolute indicies.

Parameters

[in,out]	sfc_state	A structure containing fields that describe the surface state of the ocean.
[in,out]	ocean_sfc	A structure containing various publicly
[in,out]	g	The ocean's grid structure
[in]	us	A dimensional unit scaling type
[in]	patm	The pressure at the ocean surface [Pa].
[in]	press_to_z	A conversion factor between pressure and ocean depth in m, usually 1/(rho_0*g) [m Pa-1].

Definition at line 821 of file ocean_model_MOM.F90.

  type(surface),         intent(inout) :: sfc_state !< A structure containing fields that
                                               !! describe the surface state of the ocean.
  type(ocean_public_type), &
                 target, intent(inout) :: Ocean_sfc !< A structure containing various publicly
                                               !! visible ocean surface fields, whose elements
                                               !! have their data set here.
  type(ocean_grid_type), intent(inout) :: G    !< The ocean's grid structure
  type(unit_scale_type), intent(in)    :: US   !< A dimensional unit scaling type
  real,        optional, intent(in)    :: patm(:,:)  !< The pressure at the ocean surface [Pa].
  real,        optional, intent(in)    :: press_to_z !< A conversion factor between pressure and
                                               !! ocean depth in m, usually 1/(rho_0*g) [m Pa-1].
  ! Local variables
  real :: IgR0
  character(len=48)  :: val_str
  integer :: isc_bnd, iec_bnd, jsc_bnd, jec_bnd
  integer :: i, j, i0, j0, is, ie, js, je

  is = g%isc ; ie = g%iec ; js = g%jsc ; je = g%jec
  call pass_vector(sfc_state%u, sfc_state%v, g%Domain)

  call mpp_get_compute_domain(ocean_sfc%Domain, isc_bnd, iec_bnd, &
                              jsc_bnd, jec_bnd)
  if (present(patm)) then
    ! Check that the inidicies in patm are (isc_bnd:iec_bnd,jsc_bnd:jec_bnd).
    if (.not.present(press_to_z)) call mom_error(fatal, &
        'convert_state_to_ocean_type: press_to_z must be present if patm is.')
  endif

  i0 = is - isc_bnd ; j0 = js - jsc_bnd
  if (sfc_state%T_is_conT) then
    ! Convert the surface T from conservative T to potential T.
    do j=jsc_bnd,jec_bnd ; do i=isc_bnd,iec_bnd
      ocean_sfc%t_surf(i,j) = gsw_pt_from_ct(sfc_state%SSS(i+i0,j+j0), &
                               sfc_state%SST(i+i0,j+j0)) + celsius_kelvin_offset
    enddo ; enddo
  else
    do j=jsc_bnd,jec_bnd ; do i=isc_bnd,iec_bnd
      ocean_sfc%t_surf(i,j) = sfc_state%SST(i+i0,j+j0) + celsius_kelvin_offset
    enddo ; enddo
  endif
  if (sfc_state%S_is_absS) then
    ! Convert the surface S from absolute salinity to practical salinity.
    do j=jsc_bnd,jec_bnd ; do i=isc_bnd,iec_bnd
      ocean_sfc%s_surf(i,j) = gsw_sp_from_sr(sfc_state%SSS(i+i0,j+j0))
    enddo ; enddo
  else
    do j=jsc_bnd,jec_bnd ; do i=isc_bnd,iec_bnd
      ocean_sfc%s_surf(i,j) = sfc_state%SSS(i+i0,j+j0)
    enddo ; enddo
  endif

  if (present(patm)) then
    do j=jsc_bnd,jec_bnd ; do i=isc_bnd,iec_bnd
      ocean_sfc%sea_lev(i,j) = us%Z_to_m * sfc_state%sea_lev(i+i0,j+j0) + patm(i,j) * press_to_z
      ocean_sfc%area(i,j) = us%L_to_m**2 * g%areaT(i+i0,j+j0)
    enddo ; enddo
  else
    do j=jsc_bnd,jec_bnd ; do i=isc_bnd,iec_bnd
      ocean_sfc%sea_lev(i,j) = us%Z_to_m * sfc_state%sea_lev(i+i0,j+j0)
      ocean_sfc%area(i,j) = us%L_to_m**2 * g%areaT(i+i0,j+j0)
    enddo ; enddo
  endif

  if (allocated(sfc_state%frazil)) then
    do j=jsc_bnd,jec_bnd ; do i=isc_bnd,iec_bnd
      ocean_sfc%frazil(i,j) = us%Q_to_J_kg*us%RZ_to_kg_m2 * sfc_state%frazil(i+i0,j+j0)
    enddo ; enddo
  endif

  if (ocean_sfc%stagger == agrid) then
    do j=jsc_bnd,jec_bnd ; do i=isc_bnd,iec_bnd
      ocean_sfc%u_surf(i,j) = g%mask2dT(i+i0,j+j0) * us%L_T_to_m_s * &
                0.5*(sfc_state%u(i+i0,j+j0)+sfc_state%u(i-1+i0,j+j0))
      ocean_sfc%v_surf(i,j) = g%mask2dT(i+i0,j+j0) * us%L_T_to_m_s * &
                0.5*(sfc_state%v(i+i0,j+j0)+sfc_state%v(i+i0,j-1+j0))
    enddo ; enddo
  elseif (ocean_sfc%stagger == bgrid_ne) then
    do j=jsc_bnd,jec_bnd ; do i=isc_bnd,iec_bnd
      ocean_sfc%u_surf(i,j) = g%mask2dBu(i+i0,j+j0) * us%L_T_to_m_s * &
                0.5*(sfc_state%u(i+i0,j+j0)+sfc_state%u(i+i0,j+j0+1))
      ocean_sfc%v_surf(i,j) = g%mask2dBu(i+i0,j+j0) * us%L_T_to_m_s * &
                0.5*(sfc_state%v(i+i0,j+j0)+sfc_state%v(i+i0+1,j+j0))
    enddo ; enddo
  elseif (ocean_sfc%stagger == cgrid_ne) then
    do j=jsc_bnd,jec_bnd ; do i=isc_bnd,iec_bnd
      ocean_sfc%u_surf(i,j) = g%mask2dCu(i+i0,j+j0)*us%L_T_to_m_s * sfc_state%u(i+i0,j+j0)
      ocean_sfc%v_surf(i,j) = g%mask2dCv(i+i0,j+j0)*us%L_T_to_m_s * sfc_state%v(i+i0,j+j0)
    enddo ; enddo
  else
    write(val_str, '(I8)') ocean_sfc%stagger
    call mom_error(fatal, "convert_state_to_ocean_type: "//&
      "Ocean_sfc%stagger has the unrecognized value of "//trim(val_str))
  endif

  if (coupler_type_initialized(sfc_state%tr_fields)) then
    if (.not.coupler_type_initialized(ocean_sfc%fields)) then
      call mom_error(fatal, "convert_state_to_ocean_type: "//&
               "Ocean_sfc%fields has not been initialized.")
    endif
    call coupler_type_copy_data(sfc_state%tr_fields, ocean_sfc%fields)
  endif

get_ocean_grid()

subroutine, public ocean_model_mod::get_ocean_grid	(	type(ocean_state_type)	OS,
		type(ocean_grid_type), pointer	Gridp
	)

This subroutine gives a handle to the grid from ocean state.

Parameters

os	A structure containing the internal ocean state
gridp	The ocean's grid structure

Definition at line 1120 of file ocean_model_MOM.F90.

  ! Obtain the ocean grid.
  type(ocean_state_type) :: OS              !< A structure containing the
                                            !! internal ocean state
  type(ocean_grid_type) , pointer :: Gridp  !< The ocean's grid structure

  gridp => os%grid
  return

initialize_ocean_public_type()

subroutine ocean_model_mod::initialize_ocean_public_type ( type(domain2d), intent(in)  input_domain, type(ocean_public_type), intent(inout)  Ocean_sfc, type(diag_ctrl), intent(in)  diag, logical, dimension(:,:), intent(in), optional  maskmap, type(coupler_1d_bc_type), intent(in), optional  gas_fields_ocn  )

private

Initialize the public ocean type.

Parameters

[in]	input_domain	The ocean model domain description
[in,out]	ocean_sfc	A structure containing various publicly visible ocean surface properties after initialization, whose elements are allocated here.
[in]	diag	A structure that regulates diagnsotic output
[in]	maskmap	A mask indicating which virtual processors
[in]	gas_fields_ocn	If present, this type describes the

Definition at line 763 of file ocean_model_MOM.F90.

  type(domain2D),          intent(in)    :: input_domain !< The ocean model domain description
  type(ocean_public_type), intent(inout) :: Ocean_sfc !< A structure containing various publicly
                                !! visible ocean surface properties after initialization, whose
                                !! elements are allocated here.
  type(diag_ctrl),         intent(in)    :: diag  !< A structure that regulates diagnsotic output
  logical, dimension(:,:), &
                 optional, intent(in)    :: maskmap !< A mask indicating which virtual processors
                                              !! are actually in use.  If missing, all are used.
  type(coupler_1d_bc_type), &
                 optional, intent(in)    :: gas_fields_ocn !< If present, this type describes the
                                              !! ocean and surface-ice fields that will participate
                                              !! in the calculation of additional gas or other
                                              !! tracer fluxes.

  integer :: xsz, ysz, layout(2)
  ! ice-ocean-boundary fields are always allocated using absolute indicies
  ! and have no halos.
  integer :: isc, iec, jsc, jec

  call mpp_get_layout(input_domain,layout)
  call mpp_get_global_domain(input_domain, xsize=xsz, ysize=ysz)
  if (PRESENT(maskmap)) then
     call mpp_define_domains((/1,xsz,1,ysz/),layout,ocean_sfc%Domain, maskmap=maskmap)
  else
     call mpp_define_domains((/1,xsz,1,ysz/),layout,ocean_sfc%Domain)
  endif
  call mpp_get_compute_domain(ocean_sfc%Domain, isc, iec, jsc, jec)

  allocate ( ocean_sfc%t_surf (isc:iec,jsc:jec), &
             ocean_sfc%s_surf (isc:iec,jsc:jec), &
             ocean_sfc%u_surf (isc:iec,jsc:jec), &
             ocean_sfc%v_surf (isc:iec,jsc:jec), &
             ocean_sfc%sea_lev(isc:iec,jsc:jec), &
             ocean_sfc%area   (isc:iec,jsc:jec), &
             ocean_sfc%frazil (isc:iec,jsc:jec))

  ocean_sfc%t_surf(:,:)  = 0.0  ! time averaged sst (Kelvin) passed to atmosphere/ice model
  ocean_sfc%s_surf(:,:)  = 0.0  ! time averaged sss (psu) passed to atmosphere/ice models
  ocean_sfc%u_surf(:,:)  = 0.0  ! time averaged u-current (m/sec) passed to atmosphere/ice models
  ocean_sfc%v_surf(:,:)  = 0.0  ! time averaged v-current (m/sec)  passed to atmosphere/ice models
  ocean_sfc%sea_lev(:,:) = 0.0  ! time averaged thickness of top model grid cell (m) plus patm/rho0/grav
  ocean_sfc%frazil(:,:)  = 0.0  ! time accumulated frazil (J/m^2) passed to ice model
  ocean_sfc%area(:,:)    = 0.0
  ocean_sfc%axes    = diag%axesT1%handles !diag axes to be used by coupler tracer flux diagnostics

  if (present(gas_fields_ocn)) then
    call coupler_type_spawn(gas_fields_ocn, ocean_sfc%fields, (/isc,isc,iec,iec/), &
                              (/jsc,jsc,jec,jec/), suffix = '_ocn', as_needed=.true.)
  endif

ocean_model_data1d_get()

subroutine ocean_model_mod::ocean_model_data1d_get	(	type(ocean_state_type), pointer	OS,
		type(ocean_public_type), intent(in)	Ocean,
		character(len=*), intent(in)	name,
		real, intent(out)	value
	)

This subroutine extracts a named scalar field from the ocean surface or public type.

Parameters

	os	A pointer to the structure containing the internal ocean state (intent in).
[in]	ocean	A structure containing various publicly visible ocean surface fields.
[in]	name	The name of the field to extract
[out]	value	The value of the named field

Definition at line 1075 of file ocean_model_MOM.F90.

  type(ocean_state_type),     pointer    :: OS    !< A pointer to the structure containing the
                                                  !! internal ocean state (intent in).
  type(ocean_public_type),    intent(in) :: Ocean !< A structure containing various publicly
                                                  !! visible ocean surface fields.
  character(len=*)          , intent(in) :: name  !< The name of the field to extract
  real                      , intent(out):: value !< The value of the named field

  if (.not.associated(os)) return
  if (.not.os%is_ocean_pe) return

  select case(name)
  case('c_p')
    value = os%C_p
  case default
    call mom_error(fatal,'get_ocean_grid_data1D: unknown argument name='//name)
  end select

ocean_model_data2d_get()

subroutine ocean_model_mod::ocean_model_data2d_get	(	type(ocean_state_type), pointer	OS,
		type(ocean_public_type), intent(in)	Ocean,
		character(len=*), intent(in)	name,
		real, dimension(isc:,jsc:), intent(out)	array2D,
		integer, intent(in)	isc,
		integer, intent(in)	jsc
	)

This subroutine extracts a named 2-D field from the ocean surface or public type.

Parameters

	os	A pointer to the structure containing the internal ocean state (intent in).
[in]	ocean	A structure containing various publicly visible ocean surface fields.
[in]	name	The name of the field to extract
[out]	array2d	The values of the named field, it must cover only the computational domain
[in]	isc	The starting i-index of array2D
[in]	jsc	The starting j-index of array2D

Definition at line 1013 of file ocean_model_MOM.F90.

  use mom_constants, only : celsius_kelvin_offset
  type(ocean_state_type),     pointer    :: OS    !< A pointer to the structure containing the
                                                  !! internal ocean state (intent in).
  type(ocean_public_type),    intent(in) :: Ocean !< A structure containing various publicly
                                                  !! visible ocean surface fields.
  character(len=*)          , intent(in) :: name  !< The name of the field to extract
  real, dimension(isc:,jsc:), intent(out):: array2D !< The values of the named field, it must
                                                  !! cover only the computational domain
  integer                   , intent(in) :: isc   !< The starting i-index of array2D
  integer                   , intent(in) :: jsc   !< The starting j-index of array2D

  integer :: g_isc, g_iec, g_jsc, g_jec,g_isd, g_ied, g_jsd, g_jed, i, j

  if (.not.associated(os)) return
  if (.not.os%is_ocean_pe) return

! The problem is %areaT is on MOM domain but Ice_Ocean_Boundary%... is on mpp domain.
! We want to return the MOM data on the mpp (compute) domain
! Get MOM domain extents
  call mpp_get_compute_domain(os%grid%Domain%mpp_domain, g_isc, g_iec, g_jsc, g_jec)
  call mpp_get_data_domain   (os%grid%Domain%mpp_domain, g_isd, g_ied, g_jsd, g_jed)

  g_isc = g_isc-g_isd+1 ; g_iec = g_iec-g_isd+1 ; g_jsc = g_jsc-g_jsd+1 ; g_jec = g_jec-g_jsd+1


  select case(name)
  case('area')
     array2d(isc:,jsc:) = os%US%L_to_m**2*os%grid%areaT(g_isc:g_iec,g_jsc:g_jec)
  case('mask')
     array2d(isc:,jsc:) = os%grid%mask2dT(g_isc:g_iec,g_jsc:g_jec)
!OR same result
!     do j=g_jsc,g_jec ; do i=g_isc,g_iec
!        array2D(isc+i-g_isc,jsc+j-g_jsc) = OS%grid%mask2dT(i,j)
!     enddo ; enddo
  case('t_surf')
     array2d(isc:,jsc:) = ocean%t_surf(isc:,jsc:)-celsius_kelvin_offset
  case('t_pme')
     array2d(isc:,jsc:) = ocean%t_surf(isc:,jsc:)-celsius_kelvin_offset
  case('t_runoff')
     array2d(isc:,jsc:) = ocean%t_surf(isc:,jsc:)-celsius_kelvin_offset
  case('t_calving')
     array2d(isc:,jsc:) = ocean%t_surf(isc:,jsc:)-celsius_kelvin_offset
  case('btfHeat')
     array2d(isc:,jsc:) = 0
  case('cos_rot')
     array2d(isc:,jsc:) = os%grid%cos_rot(g_isc:g_iec,g_jsc:g_jec) ! =1
  case('sin_rot')
     array2d(isc:,jsc:) = os%grid%sin_rot(g_isc:g_iec,g_jsc:g_jec) ! =0
  case('s_surf')
     array2d(isc:,jsc:) = ocean%s_surf(isc:,jsc:)
  case('sea_lev')
     array2d(isc:,jsc:) = ocean%sea_lev(isc:,jsc:)
  case('frazil')
     array2d(isc:,jsc:) = ocean%frazil(isc:,jsc:)
  case default
     call mom_error(fatal,'get_ocean_grid_data2D: unknown argument name='//name)
  end select

ocean_model_end()

subroutine, public ocean_model_mod::ocean_model_end	(	type(ocean_public_type), intent(inout)	Ocean_sfc,
		type(ocean_state_type), pointer	Ocean_state,
		type(time_type), intent(in)	Time
	)

ocean_model_end terminates the model run, saving the ocean state in a restart and deallocating any data associated with the ocean.

Parameters

[in,out]	ocean_sfc	An ocean_public_type structure that is to be deallocated upon termination.
	ocean_state	A pointer to the structure containing the internal ocean state to be deallocated upon termination.
[in]	time	The model time, used for writing restarts.

Definition at line 711 of file ocean_model_MOM.F90.

  type(ocean_public_type), intent(inout) :: Ocean_sfc   !< An ocean_public_type structure that is
                                                        !! to be deallocated upon termination.
  type(ocean_state_type),  pointer       :: Ocean_state !< A pointer to the structure containing
                                                        !! the internal ocean state to be deallocated
                                                        !! upon termination.
  type(time_type),         intent(in)    :: Time        !< The model time, used for writing restarts.

  call ocean_model_save_restart(ocean_state, time)
  call diag_mediator_end(time, ocean_state%diag)
  call mom_end(ocean_state%MOM_CSp)
  if (ocean_state%use_ice_shelf) call ice_shelf_end(ocean_state%Ice_shelf_CSp)

ocean_model_flux_init()

subroutine, public ocean_model_mod::ocean_model_flux_init	(	type(ocean_state_type), optional, pointer	OS,
		integer, intent(in), optional	verbosity
	)

ocean_model_flux_init is used to initialize properties of the air-sea fluxes as determined by various run-time parameters. It can be called from non-ocean PEs, or PEs that have not yet been initialzed, and it can safely be called multiple times.

Parameters

	os	An optional pointer to the ocean state, used to figure out if this is an ocean PE that has already been initialized.
[in]	verbosity	A 0-9 integer indicating a level of verbosity.

Definition at line 951 of file ocean_model_MOM.F90.

  type(ocean_state_type), optional, pointer :: OS  !< An optional pointer to the ocean state,
                                             !! used to figure out if this is an ocean PE that
                                             !! has already been initialized.
  integer, optional, intent(in) :: verbosity !< A 0-9 integer indicating a level of verbosity.

  logical :: OS_is_set
  integer :: verbose

  os_is_set = .false. ; if (present(os)) os_is_set = associated(os)

  ! Use this to control the verbosity of output; consider rethinking this logic later.
  verbose = 5 ; if (os_is_set) verbose = 3
  if (present(verbosity)) verbose = verbosity

  call call_tracer_flux_init(verbosity=verbose)

ocean_model_get_uv_surf()

subroutine, public ocean_model_mod::ocean_model_get_uv_surf	(	type(ocean_state_type), pointer	OS,
		type(ocean_public_type), intent(in)	Ocean,
		character(len=*), intent(in)	name,
		real, dimension(isc:,jsc:), intent(out)	array2D,
		integer, intent(in)	isc,
		integer, intent(in)	jsc
	)

This subroutine extracts a named (u- or v-) 2-D surface current from ocean internal state.

Parameters

	os	A pointer to the structure containing the internal ocean state (intent in).
[in]	ocean	A structure containing various publicly visible ocean surface fields.
[in]	name	The name of the current (ua or va) to extract
[out]	array2d	The values of the named field, it must cover only the computational domain
[in]	isc	The starting i-index of array2D
[in]	jsc	The starting j-index of array2D

Definition at line 1131 of file ocean_model_MOM.F90.

  type(ocean_state_type),     pointer    :: OS    !< A pointer to the structure containing the
                                                  !! internal ocean state (intent in).
  type(ocean_public_type),    intent(in) :: Ocean !< A structure containing various publicly
                                                  !! visible ocean surface fields.
  character(len=*)          , intent(in) :: name  !< The name of the current (ua or va) to extract
  real, dimension(isc:,jsc:), intent(out):: array2D !< The values of the named field, it must
                                                  !! cover only the computational domain
  integer                   , intent(in) :: isc   !< The starting i-index of array2D
  integer                   , intent(in) :: jsc   !< The starting j-index of array2D

  type(ocean_grid_type) , pointer :: G            !< The ocean's grid structure
  type(surface),          pointer :: sfc_state    !< A structure containing fields that
                                                  !! describe the surface state of the ocean.

  integer :: isc_bnd, iec_bnd, jsc_bnd, jec_bnd
  integer :: i, j, i0, j0
  integer :: is, ie, js, je

  if (.not.associated(os)) return
  if (.not.os%is_ocean_pe) return

  g => os%grid
  is = g%isc ; ie = g%iec ; js = g%jsc ; je = g%jec

  call mpp_get_compute_domain(ocean%Domain, isc_bnd, iec_bnd, &
                              jsc_bnd, jec_bnd)

  i0 = is - isc_bnd ; j0 = js - jsc_bnd

  sfc_state => os%sfc_state

  select case(name)
  case('ua')
    do j=jsc_bnd,jec_bnd ; do i=isc_bnd,iec_bnd
      array2d(i,j) = g%mask2dT(i+i0,j+j0) * &
                0.5*(sfc_state%u(i+i0,j+j0)+sfc_state%u(i-1+i0,j+j0))
    enddo ; enddo
  case('va')
    do j=jsc_bnd,jec_bnd ; do i=isc_bnd,iec_bnd
      array2d(i,j) = g%mask2dT(i+i0,j+j0) * &
                0.5*(sfc_state%v(i+i0,j+j0)+sfc_state%v(i+i0,j-1+j0))
    enddo ; enddo
  case('ub')
    do j=jsc_bnd,jec_bnd ; do i=isc_bnd,iec_bnd
      array2d(i,j) = g%mask2dBu(i+i0,j+j0) * &
                0.5*(sfc_state%u(i+i0,j+j0)+sfc_state%u(i+i0,j+j0+1))
    enddo ; enddo
  case('vb')
    do j=jsc_bnd,jec_bnd ; do i=isc_bnd,iec_bnd
      array2d(i,j) = g%mask2dBu(i+i0,j+j0) * &
                0.5*(sfc_state%v(i+i0,j+j0)+sfc_state%v(i+i0+1,j+j0))
    enddo ; enddo
  case default
     call mom_error(fatal,'ocean_model_get_UV_surf: unknown argument name='//name)
  end select

ocean_model_init()

subroutine, public ocean_model_mod::ocean_model_init	(	type(ocean_public_type), intent(inout), target	Ocean_sfc,
		type(ocean_state_type), pointer	OS,
		type(time_type), intent(in)	Time_init,
		type(time_type), intent(in)	Time_in,
		integer, intent(in), optional	wind_stagger,
		type(coupler_1d_bc_type), intent(in), optional	gas_fields_ocn
	)

ocean_model_init initializes the ocean model, including registering fields for restarts and reading restart files if appropriate.

This subroutine initializes both the ocean state and the ocean surface type. Because of the way that indicies and domains are handled, Ocean_sfc must have been used in a previous call to initialize_ocean_type.

Parameters

[in,out]	ocean_sfc	A structure containing various publicly
	os	A structure whose internal contents are private to ocean_model_mod that may be used to contain all information about the ocean's interior state.
[in]	time_init	The start time for the coupled model's calendar
[in]	time_in	The time at which to initialize the ocean model.
[in]	wind_stagger	If present, the staggering of the winds that are being provided in calls to update_ocean_model
[in]	gas_fields_ocn	If present, this type describes the

Definition at line 228 of file ocean_model_MOM.F90.

  type(ocean_public_type), target, &
                       intent(inout) :: Ocean_sfc !< A structure containing various publicly
                                !! visible ocean surface properties after initialization,
                                !! the data in this type is intent out.
  type(ocean_state_type), pointer    :: OS        !< A structure whose internal
                                !! contents are private to ocean_model_mod that may be used to
                                !! contain all information about the ocean's interior state.
  type(time_type),     intent(in)    :: Time_init !< The start time for the coupled model's calendar
  type(time_type),     intent(in)    :: Time_in   !< The time at which to initialize the ocean model.
  integer, optional,   intent(in)    :: wind_stagger !< If present, the staggering of the winds that are
                                                     !! being provided in calls to update_ocean_model
  type(coupler_1d_bc_type), &
             optional, intent(in)    :: gas_fields_ocn !< If present, this type describes the
                                              !! ocean and surface-ice fields that will participate
                                              !! in the calculation of additional gas or other
                                              !! tracer fluxes, and can be used to spawn related
                                              !! internal variables in the ice model.
  ! Local variables
  real :: Rho0        ! The Boussinesq ocean density [kg m-3].
  real :: G_Earth     ! The gravitational acceleration [m s-2].
  real :: HFrz        !< If HFrz > 0 (m), melt potential will be computed.
                      !! The actual depth over which melt potential is computed will
                      !! min(HFrz, OBLD), where OBLD is the boundary layer depth.
                      !! If HFrz <= 0 (default), melt potential will not be computed.
  logical :: use_melt_pot!< If true, allocate melt_potential array

! This include declares and sets the variable "version".
#include "version_variable.h"
  character(len=40)  :: mdl = "ocean_model_init"  ! This module's name.
  character(len=48)  :: stagger ! A string indicating the staggering locations for the
                                ! surface velocities returned to the coupler.
  type(param_file_type) :: param_file !< A structure to parse for run-time parameters
  logical :: use_temperature ! If true, temperature and salinity are state variables.

  call calltree_enter("ocean_model_init(), ocean_model_MOM.F90")
  if (associated(os)) then
    call mom_error(warning, "ocean_model_init called with an associated "// &
                   "ocean_state_type structure. Model is already initialized.")
    return
  endif
  allocate(os)

  os%is_ocean_pe = ocean_sfc%is_ocean_pe
  if (.not.os%is_ocean_pe) return

  os%Time = time_in ; os%Time_dyn = time_in
  call initialize_mom(os%Time, time_init, param_file, os%dirs, os%MOM_CSp, &
                      os%restart_CSp, time_in, offline_tracer_mode=os%offline_tracer_mode, &
                      diag_ptr=os%diag, count_calls=.true.)
  call get_mom_state_elements(os%MOM_CSp, g=os%grid, gv=os%GV, us=os%US, c_p=os%C_p, &
                              c_p_scaled=os%fluxes%C_p, use_temp=use_temperature)

  ! Read all relevant parameters and write them to the model log.
  call log_version(param_file, mdl, version, "")

  call get_param(param_file, mdl, "SINGLE_STEPPING_CALL", os%single_step_call, &
                 "If true, advance the state of MOM with a single step "//&
                 "including both dynamics and thermodynamics.  If false, "//&
                 "the two phases are advanced with separate calls.", default=.true.)
  call get_param(param_file, mdl, "DT", os%dt, &
                 "The (baroclinic) dynamics time step.  The time-step that "//&
                 "is actually used will be an integer fraction of the "//&
                 "forcing time-step.", units="s", fail_if_missing=.true.)
  call get_param(param_file, mdl, "DT_THERM", os%dt_therm, &
                 "The thermodynamic and tracer advection time step. "//&
                 "Ideally DT_THERM should be an integer multiple of DT "//&
                 "and less than the forcing or coupling time-step, unless "//&
                 "THERMO_SPANS_COUPLING is true, in which case DT_THERM "//&
                 "can be an integer multiple of the coupling timestep.  By "//&
                 "default DT_THERM is set to DT.", units="s", default=os%dt)
  call get_param(param_file, "MOM", "THERMO_SPANS_COUPLING", os%thermo_spans_coupling, &
                 "If true, the MOM will take thermodynamic and tracer "//&
                 "timesteps that can be longer than the coupling timestep. "//&
                 "The actual thermodynamic timestep that is used in this "//&
                 "case is the largest integer multiple of the coupling "//&
                 "timestep that is less than or equal to DT_THERM.", default=.false.)
  call get_param(param_file, mdl, "DIABATIC_FIRST", os%diabatic_first, &
                 "If true, apply diabatic and thermodynamic processes, "//&
                 "including buoyancy forcing and mass gain or loss, "//&
                 "before stepping the dynamics forward.", default=.false.)

  call get_param(param_file, mdl, "RESTART_CONTROL", os%Restart_control, &
                 "An integer whose bits encode which restart files are "//&
                 "written. Add 2 (bit 1) for a time-stamped file, and odd "//&
                 "(bit 0) for a non-time-stamped file.  A restart file "//&
                 "will be saved at the end of the run segment for any "//&
                 "non-negative value.", default=1)
  call get_param(param_file, mdl, "OCEAN_SURFACE_STAGGER", stagger, &
                 "A case-insensitive character string to indicate the "//&
                 "staggering of the surface velocity field that is "//&
                 "returned to the coupler.  Valid values include "//&
                 "'A', 'B', or 'C'.", default="C")
  if (uppercase(stagger(1:1)) == 'A') then ; ocean_sfc%stagger = agrid
  elseif (uppercase(stagger(1:1)) == 'B') then ; ocean_sfc%stagger = bgrid_ne
  elseif (uppercase(stagger(1:1)) == 'C') then ; ocean_sfc%stagger = cgrid_ne
  else ; call mom_error(fatal,"ocean_model_init: OCEAN_SURFACE_STAGGER = "// &
                        trim(stagger)//" is invalid.") ; endif

  call get_param(param_file, mdl, "RHO_0", rho0, &
                 "The mean ocean density used with BOUSSINESQ true to "//&
                 "calculate accelerations and the mass for conservation "//&
                 "properties, or with BOUSSINSEQ false to convert some "//&
                 "parameters from vertical units of m to kg m-2.", &
                 units="kg m-3", default=1035.0)
  call get_param(param_file, mdl, "G_EARTH", g_earth, &
                 "The gravitational acceleration of the Earth.", &
                 units="m s-2", default = 9.80)

  call get_param(param_file, mdl, "ICE_SHELF",  os%use_ice_shelf, &
                 "If true, enables the ice shelf model.", default=.false.)

  call get_param(param_file, mdl, "ICEBERGS_APPLY_RIGID_BOUNDARY",  os%icebergs_alter_ocean, &
                 "If true, allows icebergs to change boundary condition felt by ocean", default=.false.)

  os%press_to_z = 1.0/(rho0*g_earth)

  !   Consider using a run-time flag to determine whether to do the diagnostic
  ! vertical integrals, since the related 3-d sums are not negligible in cost.
  call get_param(param_file, mdl, "HFREEZE", hfrz, &
                 "If HFREEZE > 0, melt potential will be computed. The actual depth "//&
                 "over which melt potential is computed will be min(HFREEZE, OBLD), "//&
                 "where OBLD is the boundary layer depth. If HFREEZE <= 0 (default), "//&
                 "melt potential will not be computed.", units="m", default=-1.0, do_not_log=.true.)

  if (hfrz .gt. 0.0) then
    use_melt_pot=.true.
  else
    use_melt_pot=.false.
  endif

  call allocate_surface_state(os%sfc_state, os%grid, use_temperature, do_integrals=.true., &
                              gas_fields_ocn=gas_fields_ocn, use_meltpot=use_melt_pot)

  if (present(wind_stagger)) then
    call surface_forcing_init(time_in, os%grid, os%US, param_file, os%diag, &
                              os%forcing_CSp, wind_stagger)
  else
    call surface_forcing_init(time_in, os%grid, os%US, param_file, os%diag, &
                              os%forcing_CSp)
  endif

  if (os%use_ice_shelf)  then
    call initialize_ice_shelf(param_file, os%grid, os%Time, os%ice_shelf_CSp, &
                              os%diag, os%forces, os%fluxes)
  endif
  if (os%icebergs_alter_ocean)  then
    call marine_ice_init(os%Time, os%grid, param_file, os%diag, os%marine_ice_CSp)
    if (.not. os%use_ice_shelf) &
      call allocate_forcing_type(os%grid, os%fluxes, shelf=.true.)
  endif

  call get_param(param_file, mdl, "USE_WAVES", os%Use_Waves, &
       "If true, enables surface wave modules.", default=.false.)
  if (os%use_waves) then
    call mom_wave_interface_init(os%Time, os%grid, os%GV, os%US, param_file, os%Waves, os%diag)
  else
    call mom_wave_interface_init_lite(param_file)
  endif

  if (associated(os%grid%Domain%maskmap)) then
    call initialize_ocean_public_type(os%grid%Domain%mpp_domain, ocean_sfc, &
                                      os%diag, maskmap=os%grid%Domain%maskmap, &
                                      gas_fields_ocn=gas_fields_ocn)
  else
    call initialize_ocean_public_type(os%grid%Domain%mpp_domain, ocean_sfc, &
                                      os%diag, gas_fields_ocn=gas_fields_ocn)
  endif

  ! This call can only occur here if the coupler_bc_type variables have been
  ! initialized already using the information from gas_fields_ocn.
  if (present(gas_fields_ocn)) then
    call coupler_type_set_diags(ocean_sfc%fields, "ocean_sfc", &
                                ocean_sfc%axes(1:2), time_in)

    call extract_surface_state(os%MOM_CSp, os%sfc_state)

    call convert_state_to_ocean_type(os%sfc_state, ocean_sfc, os%grid, os%US)

  endif

  call close_param_file(param_file)
  call diag_mediator_close_registration(os%diag)

  call mom_mesg('==== Completed MOM6 Coupled Initialization ====', 2)

  call calltree_leave("ocean_model_init(")

ocean_model_init_sfc()

subroutine, public ocean_model_mod::ocean_model_init_sfc	(	type(ocean_state_type), pointer	OS,
		type(ocean_public_type), intent(inout)	Ocean_sfc
	)

This subroutine extracts the surface properties from the ocean's internal state and stores them in the ocean type returned to the calling ice model. It has to be separate from the ocean_initialization call because the coupler module allocates the space for some of these variables.

Parameters

	os	The structure with the complete ocean state
[in,out]	ocean_sfc	A structure containing various publicly visible ocean surface properties after initialization, whose elements have their data set here.

Definition at line 930 of file ocean_model_MOM.F90.

  type(ocean_state_type),  pointer       :: OS  !< The structure with the complete ocean state
  type(ocean_public_type), intent(inout) :: Ocean_sfc !< A structure containing various publicly
                                !! visible ocean surface properties after initialization, whose
                                !! elements have their data set here.
  integer :: is, ie, js, je

  is = os%grid%isc ; ie = os%grid%iec ; js = os%grid%jsc ; je = os%grid%jec
  call coupler_type_spawn(ocean_sfc%fields, os%sfc_state%tr_fields, &
                          (/is,is,ie,ie/), (/js,js,je,je/), as_needed=.true.)

  call extract_surface_state(os%MOM_CSp, os%sfc_state)

  call convert_state_to_ocean_type(os%sfc_state, ocean_sfc, os%grid, os%US)

ocean_model_restart()

subroutine, public ocean_model_mod::ocean_model_restart	(	type(ocean_state_type), pointer	OS,
		character(len=*), intent(in), optional	timestamp
	)

This subroutine writes out the ocean model restart file.

Parameters

	os	A pointer to the structure containing the internal ocean state being saved to a restart file
[in]	timestamp	An optional timestamp string that should be prepended to the file name. (Currently this is unused.)

Definition at line 673 of file ocean_model_MOM.F90.

  type(ocean_state_type),     pointer    :: OS !< A pointer to the structure containing the
                                               !! internal ocean state being saved to a restart file
  character(len=*), optional, intent(in) :: timestamp !< An optional timestamp string that should be
                                               !! prepended to the file name. (Currently this is unused.)

  if (.not.mom_state_is_synchronized(os%MOM_CSp)) &
      call mom_error(warning, "End of MOM_main reached with inconsistent "//&
         "dynamics and advective times.  Additional restart fields "//&
         "that have not been coded yet would be required for reproducibility.")
  if (.not.os%fluxes%fluxes_used) call mom_error(fatal, "ocean_model_restart "//&
      "was called with unused buoyancy fluxes.  For conservation, the ocean "//&
      "restart files can only be created after the buoyancy forcing is applied.")

  if (btest(os%Restart_control,1)) then
    call save_restart(os%dirs%restart_output_dir, os%Time, os%grid, &
                      os%restart_CSp, .true., gv=os%GV)
    call forcing_save_restart(os%forcing_CSp, os%grid, os%Time, &
                              os%dirs%restart_output_dir, .true.)
    if (os%use_ice_shelf) then
      call ice_shelf_save_restart(os%Ice_shelf_CSp, os%Time, os%dirs%restart_output_dir, .true.)
    endif
  endif
  if (btest(os%Restart_control,0)) then
    call save_restart(os%dirs%restart_output_dir, os%Time, os%grid, &
                      os%restart_CSp, gv=os%GV)
    call forcing_save_restart(os%forcing_CSp, os%grid, os%Time, &
                              os%dirs%restart_output_dir)
    if (os%use_ice_shelf) then
      call ice_shelf_save_restart(os%Ice_shelf_CSp, os%Time, os%dirs%restart_output_dir)
    endif
  endif

ocean_model_save_restart()

subroutine, public ocean_model_mod::ocean_model_save_restart	(	type(ocean_state_type), pointer	OS,
		type(time_type), intent(in)	Time,
		character(len=*), intent(in), optional	directory,
		character(len=*), intent(in), optional	filename_suffix
	)

ocean_model_save_restart causes restart files associated with the ocean to be written out.

Parameters

	os	A pointer to the structure containing the internal ocean state (in).
[in]	time	The model time at this call, needed for mpp_write calls.
[in]	directory	An optional directory into which to write these restart files.
[in]	filename_suffix	An optional suffix (e.g., a time-stamp) to append to the restart file names.

Definition at line 727 of file ocean_model_MOM.F90.

  type(ocean_state_type),     pointer    :: OS  !< A pointer to the structure containing the
                                                !! internal ocean state (in).
  type(time_type),            intent(in) :: Time !< The model time at this call, needed for mpp_write calls.
  character(len=*), optional, intent(in) :: directory  !<  An optional directory into which to
                                                !! write these restart files.
  character(len=*), optional, intent(in) :: filename_suffix !< An optional suffix (e.g., a time-stamp)
                                                !! to append to the restart file names.
! Note: This is a new routine - it will need to exist for the new incremental
!   checkpointing.  It will also be called by ocean_model_end, giving the same
!   restart behavior as now in FMS.
  character(len=200) :: restart_dir

  if (.not.mom_state_is_synchronized(os%MOM_CSp)) &
    call mom_error(warning, "ocean_model_save_restart called with inconsistent "//&
         "dynamics and advective times.  Additional restart fields "//&
         "that have not been coded yet would be required for reproducibility.")
  if (.not.os%fluxes%fluxes_used) call mom_error(fatal, "ocean_model_save_restart "//&
       "was called with unused buoyancy fluxes.  For conservation, the ocean "//&
       "restart files can only be created after the buoyancy forcing is applied.")

  if (present(directory)) then ; restart_dir = directory
  else ; restart_dir = os%dirs%restart_output_dir ; endif

  call save_restart(restart_dir, time, os%grid, os%restart_CSp, gv=os%GV)

  call forcing_save_restart(os%forcing_CSp, os%grid, time, restart_dir)

  if (os%use_ice_shelf) then
    call ice_shelf_save_restart(os%Ice_shelf_CSp, os%Time, os%dirs%restart_output_dir)
  endif

ocean_public_type_chksum()

subroutine, public ocean_model_mod::ocean_public_type_chksum	(	character(len=*), intent(in)	id,
		integer, intent(in)	timestep,
		type(ocean_public_type), intent(in)	ocn
	)

Write out FMS-format checsums on fields from the ocean surface state.

Parameters

[in]	id	An identifying string for this call
[in]	timestep	The number of elapsed timesteps
[in]	ocn	A structure containing various publicly visible ocean surface fields.

Definition at line 1096 of file ocean_model_MOM.F90.

  character(len=*),        intent(in) :: id  !< An identifying string for this call
  integer,                 intent(in) :: timestep !< The number of elapsed timesteps
  type(ocean_public_type), intent(in) :: ocn !< A structure containing various publicly
                                             !! visible ocean surface fields.
  integer :: n, m, outunit

  outunit = stdout()

  write(outunit,*) "BEGIN CHECKSUM(ocean_type):: ", id, timestep
  write(outunit,100) 'ocean%t_surf   ',mpp_chksum(ocn%t_surf )
  write(outunit,100) 'ocean%s_surf   ',mpp_chksum(ocn%s_surf )
  write(outunit,100) 'ocean%u_surf   ',mpp_chksum(ocn%u_surf )
  write(outunit,100) 'ocean%v_surf   ',mpp_chksum(ocn%v_surf )
  write(outunit,100) 'ocean%sea_lev  ',mpp_chksum(ocn%sea_lev)
  write(outunit,100) 'ocean%frazil   ',mpp_chksum(ocn%frazil )

  call coupler_type_write_chksums(ocn%fields, outunit, 'ocean%')
100 FORMAT("   CHECKSUM::",a20," = ",z20)

ocean_stock_pe()

subroutine, public ocean_model_mod::ocean_stock_pe	(	type(ocean_state_type), pointer	OS,
		integer, intent(in)	index,
		real, intent(out)	value,
		integer, intent(in), optional	time_index
	)

Ocean_stock_pe - returns the integrated stocks of heat, water, etc. for conservation checks. Because of the way FMS is coded, only the root PE has the integrated amount, while all other PEs get 0.

Parameters

	os	A structure containing the internal ocean state. The data in OS is intent in.
[in]	index	The stock index for the quantity of interest.
[out]	value	Sum returned for the conservation quantity of interest.
[in]	time_index	An unused optional argument, present only for interfacial compatibility with other models.

Definition at line 973 of file ocean_model_MOM.F90.

  use stock_constants_mod, only : istock_water, istock_heat,istock_salt
  type(ocean_state_type), pointer     :: OS         !< A structure containing the internal ocean state.
                                                    !! The data in OS is intent in.
  integer,                intent(in)  :: index      !< The stock index for the quantity of interest.
  real,                   intent(out) :: value      !< Sum returned for the conservation quantity of interest.
  integer,      optional, intent(in)  :: time_index !< An unused optional argument, present only for
                                                    !! interfacial compatibility with other models.
! Arguments: OS - A structure containing the internal ocean state.
!  (in)      index - Index of conservation quantity of interest.
!  (in)      value -  Sum returned for the conservation quantity of interest.
!  (in,opt)  time_index - Index for time level to use if this is necessary.

  real :: salt

  value = 0.0
  if (.not.associated(os)) return
  if (.not.os%is_ocean_pe) return

  select case (index)
    case (istock_water)  ! Return the mass of fresh water in the ocean in kg.
      if (os%GV%Boussinesq) then
        call get_ocean_stocks(os%MOM_CSp, mass=value, on_pe_only=.true.)
      else  ! In non-Boussinesq mode, the mass of salt needs to be subtracted.
        call get_ocean_stocks(os%MOM_CSp, mass=value, salt=salt, on_pe_only=.true.)
        value = value - salt
      endif
    case (istock_heat)  ! Return the heat content of the ocean in J.
      call get_ocean_stocks(os%MOM_CSp, heat=value, on_pe_only=.true.)
    case (istock_salt)  ! Return the mass of the salt in the ocean in kg.
       call get_ocean_stocks(os%MOM_CSp, salt=value, on_pe_only=.true.)
    case default ; value = 0.0
  end select
  ! If the FMS coupler is changed so that Ocean_stock_PE is only called on
  ! ocean PEs, uncomment the following and eliminate the on_PE_only flags above.
  !  if (.not.is_root_pe()) value = 0.0

update_ocean_model()

subroutine, public ocean_model_mod::update_ocean_model	(	type(ice_ocean_boundary_type), intent(in)	Ice_ocean_boundary,
		type(ocean_state_type), pointer	OS,
		type(ocean_public_type), intent(inout)	Ocean_sfc,
		type(time_type), intent(in)	time_start_update,
		type(time_type), intent(in)	Ocean_coupling_time_step,
		logical, intent(in), optional	update_dyn,
		logical, intent(in), optional	update_thermo,
		logical, intent(in), optional	Ocn_fluxes_used,
		logical, intent(in), optional	start_cycle,
		logical, intent(in), optional	end_cycle,
		real, intent(in), optional	cycle_length
	)

update_ocean_model uses the forcing in Ice_ocean_boundary to advance the ocean model's state from the input value of Ocean_state (which must be for time time_start_update) for a time interval of Ocean_coupling_time_step, returning the publicly visible ocean surface properties in Ocean_sfc and storing the new ocean properties in Ocean_state.

Parameters

[in]	ice_ocean_boundary	A structure containing the various
	os	A pointer to a private structure containing the
[in,out]	ocean_sfc	A structure containing all the publicly visible
[in]	time_start_update	The time at the beginning of the update step.
[in]	ocean_coupling_time_step	The amount of time over which to advance the ocean.
[in]	update_dyn	If present and false, do not do updates due to the ocean dynamics.
[in]	update_thermo	If present and false, do not do updates due to the ocean thermodynamics or remapping.
[in]	ocn_fluxes_used	If present, this indicates whether the cumulative thermodynamic fluxes from the ocean, like frazil, have been used and should be reset.
[in]	start_cycle	This indicates whether this call is to be treated as the first call to step_MOM in a time-stepping cycle; missing is like true.
[in]	end_cycle	This indicates whether this call is to be treated as the last call to step_MOM in a time-stepping cycle; missing is like true.
[in]	cycle_length	The duration of a coupled time stepping cycle [s].

Definition at line 424 of file ocean_model_MOM.F90.

  type(ice_ocean_boundary_type), &
                     intent(in)    :: Ice_ocean_boundary !< A structure containing the various
                                              !! forcing fields coming from the ice and atmosphere.
  type(ocean_state_type), &
                     pointer       :: OS      !< A pointer to a private structure containing the
                                              !! internal ocean state.
  type(ocean_public_type), &
                     intent(inout) :: Ocean_sfc !< A structure containing all the publicly visible
                                              !! ocean surface fields after a coupling time step.
                                              !! The data in this type is intent out.
  type(time_type),   intent(in)    :: time_start_update  !< The time at the beginning of the update step.
  type(time_type),   intent(in)    :: Ocean_coupling_time_step !< The amount of time over which to
                                              !! advance the ocean.
  logical, optional, intent(in)    :: update_dyn !< If present and false, do not do updates
                                              !! due to the ocean dynamics.
  logical, optional, intent(in)    :: update_thermo !< If present and false, do not do updates
                                              !! due to the ocean thermodynamics or remapping.
  logical, optional, intent(in)    :: Ocn_fluxes_used !< If present, this indicates whether the
                                              !! cumulative thermodynamic fluxes from the ocean,
                                              !! like frazil, have been used and should be reset.
  logical, optional, intent(in)    :: start_cycle !< This indicates whether this call is to be
                                              !! treated as the first call to step_MOM in a
                                              !! time-stepping cycle; missing is like true.
  logical, optional, intent(in)    :: end_cycle   !< This indicates whether this call is to be
                                              !! treated as the last call to step_MOM in a
                                              !! time-stepping cycle; missing is like true.
  real,    optional, intent(in)    :: cycle_length !< The duration of a coupled time stepping cycle [s].

  ! Local variables
  type(time_type) :: Time_seg_start ! Stores the dynamic or thermodynamic ocean model time at the
                            ! start of this call to allow step_MOM to temporarily change the time
                            ! as seen by internal modules.
  type(time_type) :: Time_thermo_start ! Stores the ocean model thermodynamics time at the start of
                            ! this call to allow step_MOM to temporarily change the time as seen by
                            ! internal modules.
  type(time_type) :: Time1  ! The value of the ocean model's time at the start of a call to step_MOM.
  integer :: index_bnds(4)  ! The computational domain index bounds in the ice-ocean boundary type.
  real :: weight            ! Flux accumulation weight of the current fluxes.
  real :: dt_coupling       ! The coupling time step [s].
  real :: dt_therm          ! A limited and quantized version of OS%dt_therm [s].
  real :: dt_dyn            ! The dynamics time step [s].
  real :: dtdia             ! The diabatic time step [s].
  real :: t_elapsed_seg     ! The elapsed time in this update segment [s].
  integer :: n              ! The internal iteration counter.
  integer :: nts            ! The number of baroclinic dynamics time steps in a thermodynamic step.
  integer :: n_max          ! The number of calls to step_MOM dynamics in this call to update_ocean_model.
  integer :: n_last_thermo  ! The iteration number the last time thermodynamics were updated.
  logical :: thermo_does_span_coupling ! If true, thermodynamic forcing spans multiple dynamic timesteps.
  logical :: do_dyn         ! If true, step the ocean dynamics and transport.
  logical :: do_thermo      ! If true, step the ocean thermodynamics.
  logical :: step_thermo    ! If true, take a thermodynamic step.
  integer :: is, ie, js, je

  call calltree_enter("update_ocean_model(), ocean_model_MOM.F90")
  dt_coupling = time_type_to_real(ocean_coupling_time_step)

  if (.not.associated(os)) then
    call mom_error(fatal, "update_ocean_model called with an unassociated "// &
                    "ocean_state_type structure. ocean_model_init must be "//  &
                    "called first to allocate this structure.")
    return
  endif

  do_dyn = .true. ; if (present(update_dyn)) do_dyn = update_dyn
  do_thermo = .true. ; if (present(update_thermo)) do_thermo = update_thermo

  if (do_thermo .and. (time_start_update /= os%Time)) &
    call mom_error(warning, "update_ocean_model: internal clock does not "//&
                            "agree with time_start_update argument.")
  if (do_dyn .and. (time_start_update /= os%Time_dyn)) &
    call mom_error(warning, "update_ocean_model: internal dynamics clock does not "//&
                            "agree with time_start_update argument.")

  if (.not.(do_dyn .or. do_thermo)) call mom_error(fatal, &
      "update_ocean_model called without updating either dynamics or thermodynamics.")
  if (do_dyn .and. do_thermo .and. (os%Time /= os%Time_dyn)) call mom_error(fatal, &
      "update_ocean_model called to update both dynamics and thermodynamics with inconsistent clocks.")

  ! This is benign but not necessary if ocean_model_init_sfc was called or if
  ! OS%sfc_state%tr_fields was spawned in ocean_model_init.  Consider removing it.
  is = os%grid%isc ; ie = os%grid%iec ; js = os%grid%jsc ; je = os%grid%jec
  call coupler_type_spawn(ocean_sfc%fields, os%sfc_state%tr_fields, &
                          (/is,is,ie,ie/), (/js,js,je,je/), as_needed=.true.)

  ! Translate Ice_ocean_boundary into fluxes and forces.
  call mpp_get_compute_domain(ocean_sfc%Domain, index_bnds(1), index_bnds(2), &
                              index_bnds(3), index_bnds(4))

  if (do_dyn) then
    call convert_iob_to_forces(ice_ocean_boundary, os%forces, index_bnds, os%Time_dyn, os%grid, os%US, &
                               os%forcing_CSp, dt_forcing=dt_coupling, reset_avg=os%fluxes%fluxes_used)
    if (os%use_ice_shelf) &
      call add_shelf_forces(os%grid, os%US, os%Ice_shelf_CSp, os%forces)
    if (os%icebergs_alter_ocean) &
      call iceberg_forces(os%grid, os%forces, os%use_ice_shelf, &
                          os%sfc_state, dt_coupling, os%marine_ice_CSp)
  endif

  if (do_thermo) then
    if (os%fluxes%fluxes_used) then
      call convert_iob_to_fluxes(ice_ocean_boundary, os%fluxes, index_bnds, os%Time, dt_coupling, &
                                 os%grid, os%US, os%forcing_CSp, os%sfc_state)

      ! Add ice shelf fluxes
      if (os%use_ice_shelf) &
        call shelf_calc_flux(os%sfc_state, os%fluxes, os%Time, dt_coupling, os%Ice_shelf_CSp)
      if (os%icebergs_alter_ocean) &
        call iceberg_fluxes(os%grid, os%US, os%fluxes, os%use_ice_shelf, &
                            os%sfc_state, dt_coupling, os%marine_ice_CSp)

#ifdef _USE_GENERIC_TRACER
      call enable_averaging(dt_coupling, os%Time + ocean_coupling_time_step, os%diag) !Is this needed?
      call mom_generic_tracer_fluxes_accumulate(os%fluxes, 1.0) ! Here weight=1, so just store the current fluxes
      call disable_averaging(os%diag)
#endif
    else
      ! The previous fluxes have not been used yet, so translate the input fluxes
      ! into a temporary type and then accumulate them in about 20 lines.
      os%flux_tmp%C_p = os%fluxes%C_p
      call convert_iob_to_fluxes(ice_ocean_boundary, os%flux_tmp, index_bnds, os%Time, dt_coupling, &
                                 os%grid, os%US, os%forcing_CSp, os%sfc_state)

      if (os%use_ice_shelf) &
        call shelf_calc_flux(os%sfc_state, os%flux_tmp, os%Time, dt_coupling, os%Ice_shelf_CSp)
      if (os%icebergs_alter_ocean) &
        call iceberg_fluxes(os%grid, os%US, os%flux_tmp, os%use_ice_shelf, &
                            os%sfc_state, dt_coupling, os%marine_ice_CSp)

      call fluxes_accumulate(os%flux_tmp, os%fluxes, os%grid, weight)
#ifdef _USE_GENERIC_TRACER
       ! Incorporate the current tracer fluxes into the running averages
      call mom_generic_tracer_fluxes_accumulate(os%flux_tmp, weight)
#endif
    endif
  endif

  ! The net mass forcing is not currently used in the MOM6 dynamics solvers, so this is may be unnecessary.
  if (do_dyn .and. associated(os%forces%net_mass_src) .and. .not.os%forces%net_mass_src_set) &
    call get_net_mass_forcing(os%fluxes, os%grid, os%US, os%forces%net_mass_src)

  if (os%use_waves .and. do_thermo) then
    ! For now, the waves are only updated on the thermodynamics steps, because that is where
    ! the wave intensities are actually used to drive mixing.  At some point, the wave updates
    ! might also need to become a part of the ocean dynamics, according to B. Reichl.
    call update_surface_waves(os%grid, os%GV, os%US, os%time, ocean_coupling_time_step, os%waves)
  endif

  if ((os%nstep==0) .and. (os%nstep_thermo==0)) then ! This is the first call to update_ocean_model.
    call finish_mom_initialization(os%Time, os%dirs, os%MOM_CSp, os%restart_CSp)
  endif

  time_thermo_start = os%Time
  time_seg_start = os%Time ; if (do_dyn) time_seg_start = os%Time_dyn
  time1 = time_seg_start

  if (os%offline_tracer_mode .and. do_thermo) then
    call step_offline(os%forces, os%fluxes, os%sfc_state, time1, dt_coupling, os%MOM_CSp)
  elseif ((.not.do_thermo) .or. (.not.do_dyn)) then
    ! The call sequence is being orchestrated from outside of update_ocean_model.
    call step_mom(os%forces, os%fluxes, os%sfc_state, time1, dt_coupling, os%MOM_CSp, &
                  waves=os%Waves, do_dynamics=do_dyn, do_thermodynamics=do_thermo, &
                  start_cycle=start_cycle, end_cycle=end_cycle, cycle_length=cycle_length, &
                  reset_therm=ocn_fluxes_used)
  elseif (os%single_step_call) then
    call step_mom(os%forces, os%fluxes, os%sfc_state, time1, dt_coupling, os%MOM_CSp, waves=os%Waves)
  else  ! Step both the dynamics and thermodynamics with separate calls.
    n_max = 1 ; if (dt_coupling > os%dt) n_max = ceiling(dt_coupling/os%dt - 0.001)
    dt_dyn = dt_coupling / real(n_max)
    thermo_does_span_coupling = (os%thermo_spans_coupling .and. (os%dt_therm > 1.5*dt_coupling))

    if (thermo_does_span_coupling) then
      dt_therm = dt_coupling * floor(os%dt_therm / dt_coupling + 0.001)
      nts = floor(dt_therm/dt_dyn + 0.001)
    else
      nts = max(1,min(n_max,floor(os%dt_therm/dt_dyn + 0.001)))
      n_last_thermo = 0
    endif

    time1 = time_seg_start ; t_elapsed_seg = 0.0
    do n=1,n_max
      if (os%diabatic_first) then
        if (thermo_does_span_coupling) call mom_error(fatal, &
            "MOM is not yet set up to have restarts that work with "//&
            "THERMO_SPANS_COUPLING and DIABATIC_FIRST.")
        if (modulo(n-1,nts)==0) then
          dtdia = dt_dyn*min(nts,n_max-(n-1))
          call step_mom(os%forces, os%fluxes, os%sfc_state, time1, dtdia, os%MOM_CSp, &
                        waves=os%Waves, do_dynamics=.false., do_thermodynamics=.true., &
                        start_cycle=(n==1), end_cycle=.false., cycle_length=dt_coupling)
        endif

        call step_mom(os%forces, os%fluxes, os%sfc_state, time1, dt_dyn, os%MOM_CSp, &
                      waves=os%Waves, do_dynamics=.true., do_thermodynamics=.false., &
                      start_cycle=.false., end_cycle=(n==n_max), cycle_length=dt_coupling)
      else
        call step_mom(os%forces, os%fluxes, os%sfc_state, time1, dt_dyn, os%MOM_CSp, &
                      waves=os%Waves, do_dynamics=.true., do_thermodynamics=.false., &
                      start_cycle=(n==1), end_cycle=.false., cycle_length=dt_coupling)

        step_thermo = .false.
        if (thermo_does_span_coupling) then
          dtdia = dt_therm
          step_thermo = mom_state_is_synchronized(os%MOM_CSp, adv_dyn=.true.)
        elseif ((modulo(n,nts)==0) .or. (n==n_max)) then
          dtdia = dt_dyn*(n - n_last_thermo)
          n_last_thermo = n
          step_thermo = .true.
        endif

        if (step_thermo) then
          ! Back up Time1 to the start of the thermodynamic segment.
          time1 = time1 - real_to_time(dtdia - dt_dyn)
          call step_mom(os%forces, os%fluxes, os%sfc_state, time1, dtdia, os%MOM_CSp, &
                        waves=os%Waves, do_dynamics=.false., do_thermodynamics=.true., &
                        start_cycle=.false., end_cycle=(n==n_max), cycle_length=dt_coupling)
        endif
      endif

      t_elapsed_seg = t_elapsed_seg + dt_dyn
      time1 = time_seg_start + real_to_time(t_elapsed_seg)
    enddo
  endif

  if (do_dyn) os%Time_dyn = time_seg_start + ocean_coupling_time_step
  if (do_dyn) os%nstep = os%nstep + 1
  os%Time = time_thermo_start  ! Reset the clock to compensate for shared pointers.
  if (do_thermo) os%Time = os%Time + ocean_coupling_time_step
  if (do_thermo) os%nstep_thermo = os%nstep_thermo + 1

  if (do_dyn) then
    call mech_forcing_diags(os%forces, dt_coupling, os%grid, os%Time_dyn, os%diag, os%forcing_CSp%handles)
  endif

  if (os%fluxes%fluxes_used .and. do_thermo) then
    call forcing_diagnostics(os%fluxes, os%sfc_state, os%grid, os%US, os%Time, os%diag, os%forcing_CSp%handles)
  endif

! Translate state into Ocean.
!  call convert_state_to_ocean_type(OS%sfc_state, Ocean_sfc, OS%grid, OS%US, &
!                                   Ice_ocean_boundary%p, OS%press_to_z)
  call convert_state_to_ocean_type(os%sfc_state, ocean_sfc, os%grid, os%US)
  time1 = os%Time ; if (do_dyn) time1 = os%Time_dyn
  call coupler_type_send_data(ocean_sfc%fields, time1)

  call calltree_leave("update_ocean_model()")