PUBLIC INTERFACE ~ PUBLIC DATA ~ PUBLIC ROUTINES ~ NAMELIST ~ DIAGNOSTIC FIELDS ~ ERROR MESSAGES ~ REFERENCES ~ NOTES

Module ocean_model_mod

Contact:  Stephen M. Griffies ,  Matt Harrison
Reviewers: 
Change History: WebCVS Log

OVERVIEW

Time step the ocean model using either a twolevel staggered scheme (the default) or threelevel leap-frog scheme (the older approach). Threelevel scheme remains only for legacy purposes and is not recommended for normal use.

Top level module for ocean model. Contains routines for initialization, termination, and update of ocean model state.

Design consideration: declarations of top level ocean variables are private to this module and hence are only available to other routines through argument lists. For instance, timestep information is passed to the various modules on the initialization call and stored internally in the respective modules. This is a crucial design consideration sinces it maintains modularity and hence maintainability of the code. (mjh)

OTHER MODULES USED

                     fms_mod
                  fms_io_mod
             mpp_domains_mod
                     mpp_mod
         stock_constants_mod
    time_interp_external_mod
            time_manager_mod
ocean_advection_velocity_mod
        ocean_barotropic_mod
               ocean_bbc_mod
      ocean_bih_friction_mod
           ocean_convect_mod
          ocean_coriolis_mod
           ocean_density_mod
       ocean_diagnostics_mod
           ocean_domains_mod
         ocean_form_drag_mod
             ocean_grids_mod
     ocean_increment_eta_mod
  ocean_increment_tracer_mod
ocean_increment_velocity_mod
        ocean_lap_tracer_mod
        ocean_bih_tracer_mod
      ocean_lap_friction_mod
      ocean_mixdownslope_mod
   ocean_momentum_source_mod
          ocean_nphysics_mod
               ocean_obc_mod
         ocean_operators_mod
      ocean_overexchange_mod
          ocean_overflow_mod
           ocean_passive_mod
      ocean_polar_filter_mod
          ocean_pressure_mod
          ocean_rivermix_mod
       ocean_riverspread_mod
        ocean_parameters_mod
               ocean_sbc_mod
         ocean_shortwave_mod
   ocean_sigma_transport_mod
       ocean_sponges_eta_mod
    ocean_sponges_tracer_mod
  ocean_sponges_velocity_mod
      ocean_submesoscale_mod
          ocean_tempsalt_mod
         ocean_thickness_mod
       ocean_time_filter_mod
             ocean_topog_mod
     ocean_tracer_advect_mod
            ocean_tracer_mod
       ocean_tracer_util_mod
               ocean_tpm_mod
             ocean_types_mod
              ocean_util_mod
   ocean_velocity_advect_mod
     ocean_velocity_diag_mod
          ocean_velocity_mod
          ocean_vert_mix_mod
         ocean_vert_gotm_mod
         ocean_workspace_mod
       ocean_xlandinsert_mod
          ocean_xlandmix_mod
          ocean_drifters_mod
              oda_driver_mod

PUBLIC INTERFACE

ocean_model_init:
update_ocean_model:
get_ocean_grid_size:
get_ocean_domain:
ocean_model_init_sfc:
ocean_model_flux_init:
ocean_model_end:
ocean_model_restart:
ocean_stock_pe:
mom4_get_Tsurf:
mom4_get_Ssurf:
mom4_get_thickness:
mom4_get_density:
mom4_get_prog_tracer:
mom4_get_temperature_index:
mom4_get_salinity_index:
mom4_get_dimensions:
mom4_get_UVsurf:
mom4_get_UV:
mom4_U_to_T_2d:
mom4_get_latlon_UV:
Gets horizontal velocity components (u,v) (in m/s) on T points (A mesh) along geographical (latlon) directions in compute domain.
mom4_get_diag_axes:
mom4_get_num_diag_tracers:
Returns the module variable num_diag_tracers
mom4_get_num_prog_tracers:
Returns the module variable num_prog_tracers
mom4_get_surface_tmask:
Gets the pointer to 2D array Grid%tmask(:,:,1)
mom4_get_ocean_data:
Gets one of the 2D array data of ocean type

PUBLIC DATA

None.

PUBLIC ROUTINES

  1. ocean_model_init

    DESCRIPTION
    Initialize the ocean model. Arguments: Ocean (inout) - A structure containing various publicly visible ocean surface properties after initialization. OS (pointer)- 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. Time_init (in) - The start time for the coupled model's calendar. Time_in (in) - The time at which to initialize the ocean model.


  2. update_ocean_model

    DESCRIPTION
    Update in time the ocean model fields. This subroutine 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.

    Arguments: Ice_ocean_boundary - A structure containing the various forcing fields coming from the ice. It is intent in. Ocean_state - A structure containing the internal ocean state. Ocean_sfc - A structure containing all the publicly visible ocean surface fields after a coupling time step. time_start_update - The time at the beginning of the update step. Ocean_coupling_time_step - The amount of time over which to advance the ocean. Note: although several types are declared intent(inout), this is to allow for the possibility of halo updates and to keep previously allocated memory. In practice, Ice_ocean_boundary is intent in, Ocean_state is private to this module and intent inout, and Ocean_sfc is intent out.


  3. get_ocean_grid_size

    DESCRIPTION
    Obtain the ocean grid size.


  4. get_ocean_domain

    DESCRIPTION
    Obtain the ocean domain size.


  5. ocean_model_init_sfc

    DESCRIPTION
    Call ocean_tpm_init_sfc and pass it the needed arguments, most of which are local to the ocean model.


  6. ocean_model_flux_init

    DESCRIPTION
    Call ocean_tpm_flux_init and pass it the needed arguments, most of which are local to the ocean model.

    Currently, no arguments are passed.


  7. ocean_model_end

    DESCRIPTION
    Close down the ocean model This subroutine terminates the model run, saving the ocean state in a restart file and deallocating any data associated with the ocean.

    NOTE from nnz: This module keeps its own Time and does not need the Time_in argument. Arguments: Ocean_state (type(ocean_state_type), pointer) - A structure containing the internal ocean state. Time_in (type(time_type), intent(in)) - The model time, used for writing restarts. Ocean_sfc (type(ocean_public_type), optional, intent(inout))- An ocean_public_type structure that is to be deallocated upon termination.


  8. ocean_model_restart

    DESCRIPTION
    write out restart file. Arguments: timestamp (optional, intent(in)) : A character string that represents the model time, used for writing restart. timestamp will append to the any restart file name as a prefix.


  9. ocean_stock_pe

    DESCRIPTION
    Returns stocks of total ocean heat and water water for conservation checks. Report here values just on a single PE. Global sums are done in the coupler.

    This routine is part of a group of similar routines in other FMS component models that aims to quantify the conservation of scalar properties between the component models when running coupled models.



  10. mom4_get_Tsurf

    DESCRIPTION
    Return the surface temperature in degrees K


  11. mom4_get_Ssurf

    DESCRIPTION
    Return the surface salinity in psu


  12. mom4_get_thickness

    DESCRIPTION
    Return thickness (in meters) of each layer.


  13. mom4_get_density

    DESCRIPTION
    Return density (in kg/m^3).


  14. mom4_get_prog_tracer

    DESCRIPTION
    Return prognostic tracer data.


  15. mom4_get_temperature_index

    DESCRIPTION
    Return temperature index from prognostic tracer table, which can then be used to extract data.


  16. mom4_get_salinity_index

    DESCRIPTION
    Return salt index from prognostic tracer table, which can then be used to extract data.


  17. mom4_get_dimensions

    DESCRIPTION
    Return dimensions of data in compute domain


  18. mom4_get_UVsurf

    DESCRIPTION
    Return horizontal velocity vector components (u,v) on the A grid (tracer-points).

    Note that these velocity components are oriented according to the grid lines (i-lines and j-lines). They are generally NOT mapped to latitude-longitude lines, unless using a spherical coordinate grid specification.


  19. mom4_get_UV

    DESCRIPTION
    Return horizontal velocity vector (u,v) (in m/s) on T points (A mesh).

    Note that these velocity components are oriented according to the grid lines (i-lines and j-lines). They are generally NOT mapped to latitude-longitude lines, unless using a spherical coordinate grid specification.


  20. mom4_U_to_T_2d

    DESCRIPTION
    Interpolate (u,v) velocity components from U (B-grid) to T points (A-grid).


  21. mom4_get_latlon_UV

    use ocean_model_mod real, dimension(isc:, jsc:, :) :: u,v integer :: ierr call mom4_get_latlon_UV (ua, va, ierr)
    DESCRIPTION
    Note that these velocity components are oriented along the geographical latitude-longitude lines.

    im,j i,j B-------B-------B-------B y | | | | ^ | | i,j| | | /lon |---A---|---A---|---A---| | / | | | | \ | / | |im,jm |i,jm | \|/ rot angle B-------B-------B-------B ---X-------------> x | | | | /|\ | | | | / | \ |---A---|---A---|---A---| | \lat | | | | | \ | | | | B-------B-------B-------B



    OUTPUT
    ua    array will contain velocity component along x direction upon return
       [real, dimension(isc:, jsc:, :)]
    va    array will contain velocity component along y direction upon return
       [real, dimension(isc:, jsc:, :)]
    ierr    error status will be zero for success and nonzero for failure
       [ineger]

  22. mom4_get_diag_axes

    DESCRIPTION
    Return axes indices for diag manager.


  23. mom4_get_num_diag_tracers

    use ocean_model_mod mom4_get_num_diag_tracers ()
    DESCRIPTION
    This function returns the number of ocean diagnostic tracers if not -1. It send a FATAL message if num_diag_tracers is not set (i.e. is -1) before this function call.


    INPUT
        No inputs needed.
       []

    OUTPUT
        This function returns an integer.
       [integer]

  24. mom4_get_num_prog_tracers

    use ocean_model_mod mom4_get_num_prog_tracers ()
    DESCRIPTION
    This function returns the number of ocean prognostic tracers if not -1. It send a FATAL message if num_prog_tracers is not set (i.e. is -1) before this function call.


    INPUT
        No inputs needed.
       []

    OUTPUT
        This function returns an integer.
       [integer]

  25. mom4_get_surface_tmask

    use ocean_model_mod real, dimension(:,:), pointer :: temp call mom4_get_surface_tmask (temp)
    DESCRIPTION
    This subroutine gets the pointer to a 2D array with values of the tmask (land/sea mask for T cells based on s-coordinate) at the ocean surface .


    OUTPUT
    surfaceTmask    pointer to 2 dimensional array of tmask at the ocean surface.
       [real, dimension(:,:),pointer]

  26. mom4_get_ocean_data

    use ocean_model_mod real, dimension(:,:), pointer :: temp call mom4_get_ocean_data (Ocean,'s_surf',temp)
    DESCRIPTION
    This subroutine gets one of the following data arrays of ocean_public_type depending on the passed "name" argument, it sends a FATAL signal otherwise Ocean%t_surf when name='t_surf' Ocean%s_surf when name='s_surf' Ocean%u_surf when name='u_surf' Ocean%v_surf when name='v_surf' Ocean%sea_lev when name='sea_lev' Ocean%frazil when name='frazil'


    INPUT
    Ocean    ocean type
       [type(ocean_public_type)]
    name    one of 't_surf','s_surf','u_surf','v_surf','sea_lev','frazil'
       [character(len=*)]

    OUTPUT
    dataArrayPointer    pointer to 2 dimensional array corresponding to "name" argument, at the ocean surface.
       [real, dimension(:,:), pointer]

NAMELIST

&ocean_model_nml

layout
Processor domain layout for ocean model.
[integer]
io_layout
Processor IO domain layout for ocean model. The default value is (0,0). If either io_layout(1) or (2) is 0, it will default to the number of processors in the computational layout, except restart file will default to single file if fms_io_nml fileset_write is set to 'single'. When both entry of io_layout is positive, io_domain will be defined(a pointer in domain2d) and number of distributed files will be layout(1)*layout(2). For example, assume the restart file is ocean_velocity.res.nc and the diagnostics file is ocean_daily.nc, if the layout = (1,2), the restart files will be ocean_velocity.res.nc.0000 and ocean_veloicity.res.nc.0001, the diagnostics files will be ocean_daily.res.nc.0000 and ocean_daily.res.nc.0001. When the io_domain is defined, restart file and diagnostics file name will be controlled by the io_domain (ignoring fms_io_nml fileset_write).
[integer, dimension(2)]
dt_ocean
Ocean model time step in seconds.
[integer, default: -1]
time_tendency
Possible time stepping schemes are the following.

1. "threelevel" has the following characteristics

leap-frog for the time tendency which means the inviscid/nondissipative processes are at time tau.

forward for lateral mixing processes (dissipation at taum1)

implicit for vertical dissipative (with aidif = 1.0)

semi-implicit for Coriolis (with acor>0)

Because of the need to apply time filters to suppress leap-frog splitting, the threelevel time stepping scheme does not conserve total tracer content in the model.

2. "twolevel" has the following characteristics:

staggered 2nd order forward time tendency, which means that tracer advection, lateral tracer and velocity mixing, are at time tau. Pressure gradients are at taup1.

Adams-Bashforth (either 2nd or 3rd order) for velocity advection Third order is default as it is more stable.

implicit vertical mixing (with aidif = 1.0)

semi-implicit for Coriolis (with acor > 0)

This scheme conserves total volume and tracer in the ocean model.


[character]
impose_init_from_restart
Consider the following situation: We have run the model for many years and generated restarts. Time%init is then .false. Then, we wish to start a series of perturbation experiments from this restart file. The generic situation is for Time%init to then be .true. However, we need it to be .false. in mom4 in order to have a proper reading of the full restart information. Setting impose_init_from_restart=.true. will facilitate this setup. The default is impose_init_from_restart=.false., in which case the model will run through its normal start/stop segments using restarts.
[logical]
baroclinic_split
baroclinic_split = dtts/dtuv = (tracer time step)/(baroclinic time step) = (ocean model time step)/(baroclinic time step) Transients corrupted if baroclinic_split > 1, so it is recommended to use baroclinic_split=1.
[integer]
barotropic_split
Ratio barotropic_split = dtuv/dtbt = (baroclinic time step)/(barotropic time step). Must be large enough to resolve the barotropic gravity waves captured by the barotropic part of the model. Barotropic waves are dissipated when this splitting is greater than unity. Model algorithm is not fully implemented when barotropic_split=1, so user beware if wishing to run an unsplit model simulation.
[integer]
surface_height_split
Ratio surface_height_split = dtts/dteta = (tracer time step)/(surface height time step) = (tracer time step)/(bottom pressure time step) Typically this split is set to unity for models where baroclinic_split=1, but something larger when baroclinic_split is order 10. dteta is the time step used for update of eta_t or pbot_t. If surface_height_split is not equal to unity, then tracer conservation properties are compromised.
[integer]
reinitialize_thickness
When initialized with a nontrivial eta field, it is necessary to reinitialize the thickness arrays.
[logical]
cmip_units
For CMIP output, we need to have temperature in deg K and mass transport in kg/s. The flag cmip_units=.true. will diagnose CMIP5-related fields with the CMIP units for sending to the diagnostic manager. Default cmip_units=.false.
[logical]
debug
For overall model debugging. Set true to print cksums at each timestep for debugging purposes.
[logical]

DATA SETS

None.

ERROR MESSAGES

None.

top