ocean_model_mod module reference¶

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

Data Types¶

`ocean_public_type`	This type is used for communication with other components via the FMS coupler.
`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.

Functions/Subroutines¶

`ocean_model_init()`	ocean_model_init initializes the ocean model, including registering fields for restarts and reading restart files if appropriate.
`update_ocean_model()`	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.
`ocean_model_restart()`	This subroutine writes out the ocean model restart file.
`ocean_model_end()`	ocean_model_end terminates the model run, saving the ocean state in a restart and deallocating any data associated with the ocean.
`ocean_model_save_restart()`	ocean_model_save_restart causes restart files associated with the ocean to be written out.
`initialize_ocean_public_type()`	Initialize the public ocean type.
`convert_state_to_ocean_type()`	This subroutine translates the coupler’s ocean_data_type into MOM’s surface state variable.
`ocean_model_init_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.
`ocean_model_flux_init()`	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 initialized, and it can safely be called multiple times.
`ocean_stock_pe()`	Ocean_stock_pe - returns the integrated stocks of heat, water, etc.
`ocean_model_data2d_get()`	This subroutine extracts a named 2-D field from the ocean surface or public type.
`ocean_model_data1d_get()`	This subroutine extracts a named scalar field from the ocean surface or public type.
`ocean_public_type_chksum()`	Write out checksums for fields from the ocean surface state.
`get_ocean_grid()`	This subroutine gives a handle to the grid from ocean state.
`ocean_model_get_uv_surf()`	This subroutine extracts a named (u- or v-) 2-D surface current from ocean internal state.

Detailed Description¶

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

Type Documentation¶

type ocean_model_mod/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 persistence of things like the cutesy element name “avg_kount”.

Type fields:

% domain [type(domain2d)] :: The domain for the surface fields.
% is_ocean_pe [logical] :: .true. on processors that run the ocean model.
% instance_name [character (len=32)] :: A name that can be used to identify this instance of an ocean model, for example in ensembles when writing messages.
% pelist [integer(:),pointer] :: The list of ocean PEs.
% maskmap [logical(:,:),pointer] :: A pointer to an array indicating which logical processors are actually used for the ocean code. The other logical processors would be all land points and are not assigned to actual processors. This need not be assigned if all logical processors are used.
% stagger [integer] :: The staggering relative to the tracer points points of the two velocity components. Valid entries include AGRID, BGRID_NE, CGRID_NE, BGRID_SW, and CGRID_SW, corresponding to the community-standard Arakawa notation. (These are named integers taken from the MOM_domains module.) Following MOM5, stagger is BGRID_NE by default when the ocean is initialized, but here it is set to -999 so that a global max across ocean and non-ocean processors can be used to determine its value.
% t_surf [real(:,:),pointer] :: SST on t-cell [degrees Kelvin].
% s_surf [real(:,:),pointer] :: SSS on t-cell [ppt].
% u_surf [real(:,:),pointer] :: i-velocity at the locations indicated by stagger [m s-1].
% v_surf [real(:,:),pointer] :: j-velocity at the locations indicated by stagger [m s-1].
% sea_lev [real(:,:),pointer] :: Sea level in m after correction for surface pressure,.
% frazil [real(:,:),pointer] :: Accumulated heating [J m-2] from frazil.
% melt_potential [real(:,:),pointer] :: Instantaneous heat used to melt sea ice [J m-2].
% obld [real(:,:),pointer] :: Ocean boundary layer depth [m].
% area [real(:,:),pointer] :: cell area of the ocean surface [m2].
% fields [type(coupler_2d_bc_type)] :: A structure that may contain named arrays of tracer-related surface fields.
% avg_kount [integer] :: A count of contributions to running sums, used externally by the FMS coupler for accumulating averages of this type.
% axes [integer(2)] :: Axis numbers that are available for I/O using this surface data.

type ocean_model_mod/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. 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.

Type fields:

% is_ocean_pe [logical] :: True if this is an ocean PE.
% time [type(time_type)] :: The ocean model’s time and master clock.
% time_dyn [type(time_type)] :: The ocean model’s time for the dynamics. Time and Time_dyn should be the same after a full time step.
% restart_control [integer] :: An integer that is bit-tested to determine whether incremental restart files are saved and whether they have a time stamped name. +1 (bit 0) for generic files and +2 (bit 1) for time-stamped files. A restart file is saved at the end of a run segment unless Restart_control is negative.
% nstep [integer] :: The number of calls to update_ocean that update the dynamics.
% nstep_thermo [integer] :: The number of calls to update_ocean that update the thermodynamics.
% use_ice_shelf [logical] :: If true, the ice shelf model is enabled.
% use_waves [logical] :: If true use wave coupling.
% icebergs_alter_ocean [logical] :: If true, the icebergs can change ocean the ocean dynamics and forcing fluxes.
% press_to_z [real] :: A conversion factor between pressure and ocean depth, usually 1/(rho_0*g) [Z T2 R-1 L-2 ~> m Pa-1].
% c_p [real] :: The heat capacity of seawater [J degC-1 kg-1].
% offline_tracer_mode [logical] :: If false, use the model in prognostic mode with the barotropic and baroclinic dynamics, thermodynamics, etc. stepped forward integrated in time. If true, all of the above are bypassed with all fields necessary to integrate only the tracer advection and diffusion equation read in from files stored from a previous integration of the prognostic model.
% single_step_call [logical] :: 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. The default is true.
% dt [real] :: (baroclinic) dynamics time step [T ~> s]
% dt_therm [real] :: thermodynamics time step [T ~> s]
% thermo_spans_coupling [logical] :: If true, thermodynamic and tracer time steps can span multiple coupled time steps.
% diabatic_first [logical] :: If true, apply diabatic and thermodynamic processes before time stepping the dynamics.
% dirs [type( directories )] :: A structure containing several relevant directory paths.
% forces [type( mech_forcing )] :: A structure with the driving mechanical surface forces.
% fluxes [type( forcing )] :: A structure containing pointers to the thermodynamic ocean forcing fields.
% flux_tmp [type( forcing )] :: A secondary structure containing pointers to the ocean forcing fields for when multiple coupled timesteps are taken per thermodynamic step.
% sfc_state [type( surface )] :: A structure containing pointers to the ocean surface state fields.
% grid [type( ocean_grid_type ),pointer] :: A pointer to a grid structure containing metrics.
% gv [type( verticalgrid_type ),pointer] :: A pointer to a structure containing information.
% us [type( unit_scale_type ),pointer] :: A pointer to a structure containing dimensional.
% mom_csp [type( mom_control_struct )] :: MOM control structure.
% ice_shelf_csp [type( ice_shelf_cs ),pointer] :: A pointer to the control structure for the.
% marine_ice_csp [type( marine_ice_cs ),pointer] :: A pointer to the control structure for the.
% waves [type( wave_parameters_cs ),pointer] :: A pointer to the surface wave control structure.
% forcing_csp [type( surface_forcing_cs ),pointer] :: A pointer to the MOM forcing control structure.
% diag [type( diag_ctrl ),pointer] :: A pointer to the diagnostic regulatory structure.

Function/Subroutine Documentation¶

subroutine ocean_model_mod/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.

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

Parameters:

ocean_sfc :: [inout] 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. 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.
wind_stagger :: [in] If present, the staggering of the winds that are being provided in calls to update_ocean_model
gas_fields_ocn :: [in] If present, this type describes the

Call to:

mom_error_handler::calltree_enter mom_error_handler::calltree_leave mom_file_parser::close_param_file convert_state_to_ocean_type mom_coupler_types::coupler_type_set_diags mom_diag_mediator::diag_mediator_close_registration initialize_ocean_public_type mom_marine_ice::marine_ice_init mom_string_functions::uppercase

subroutine ocean_model_mod/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.

Parameters:

ice_ocean_boundary :: [in] A structure containing the various
os :: A pointer to a private structure containing the
ocean_sfc :: [inout] A structure containing all the publicly visible
time_start_update :: [in] The time at the beginning of the update step.
ocean_coupling_time_step :: [in] The amount of time over which to advance the ocean.
update_dyn :: [in] If present and false, do not do updates due to the ocean dynamics.
update_thermo :: [in] If present and false, do not do updates due to the ocean thermodynamics or remapping.
ocn_fluxes_used :: [in] If present, this indicates whether the cumulative thermodynamic fluxes from the ocean, like frazil, have been used and should be reset.
start_cycle :: [in] 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.
end_cycle :: [in] 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.
cycle_length :: [in] The duration of a coupled time stepping cycle [s].

Call to:

mom_ice_shelf::add_shelf_forces mom_error_handler::calltree_enter mom_error_handler::calltree_leave convert_state_to_ocean_type mom_coupler_types::coupler_type_send_data mom_forcing_type::forcing_diagnostics mom_marine_ice::iceberg_fluxes mom_marine_ice::iceberg_forces mom_forcing_type::mech_forcing_diags mom_generic_tracer::mom_generic_tracer_fluxes_accumulate mom_wave_interface::update_surface_waves

subroutine ocean_model_mod/ocean_model_restart(OS, 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
timestamp :: [in] An optional timestamp string that should be prepended to the file name. (Currently this is unused.)

Call to:

mom_surface_forcing_gfdl::forcing_save_restart mom_ice_shelf::ice_shelf_save_restart mom::save_mom_restart

subroutine ocean_model_mod/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.

Parameters:

ocean_sfc :: [inout] An ocean_public_type() structure that is to be deallocated upon termination. 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.
time :: [in] The model time, used for writing restarts.

Call to:

mom_diag_mediator::diag_mediator_end mom_ice_shelf::ice_shelf_end ocean_model_save_restart

subroutine ocean_model_mod/ocean_model_save_restart(OS, Time, directory, 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).
time :: [in] The model time at this call, needed for writing files.
directory :: [in] An optional directory into which to write these restart files.
filename_suffix :: [in] An optional suffix (e.g., a time-stamp) to append to the restart file names.

Call to:

mom_surface_forcing_gfdl::forcing_save_restart mom_ice_shelf::ice_shelf_save_restart mom::save_mom_restart

Called from:

ocean_model_end

subroutine ocean_model_mod/initialize_ocean_public_type(input_domain, Ocean_sfc, diag, gas_fields_ocn)¶

Initialize the public ocean type.

Parameters:

input_domain :: [in] The ocean model domain description
ocean_sfc :: [inout] A structure containing various publicly visible ocean surface properties after initialization, whose elements are allocated here.
diag :: [in] A structure that regulates diagnostic output
gas_fields_ocn :: [in] If present, this type describes the

Called from:

ocean_model_init

subroutine ocean_model_mod/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 indices.

Parameters:

sfc_state :: [inout] A structure containing fields that describe the surface state of the ocean.
ocean_sfc :: [inout] A structure containing various publicly
g :: [inout] The ocean’s grid structure
us :: [in] A dimensional unit scaling type
patm :: [in] The pressure at the ocean surface [R L2 T-2 ~> Pa]
press_to_z :: [in] A conversion factor between pressure and ocean depth, usually 1/(rho_0*g) [Z T2 R-1 L-2 ~> m Pa-1]

Called from:

ocean_model_init ocean_model_init_sfc update_ocean_model

subroutine ocean_model_mod/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.

Parameters:

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

Call to:

convert_state_to_ocean_type

subroutine ocean_model_mod/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 initialized, 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.
verbosity :: [in] A 0-9 integer indicating a level of verbosity.

Call to:

mom_tracer_flow_control::call_tracer_flux_init

subroutine ocean_model_mod/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.

Parameters:

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

subroutine ocean_model_mod/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.

Parameters:

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

subroutine ocean_model_mod/ocean_model_data1d_get(OS, Ocean, name, 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).
ocean :: [in] A structure containing various publicly visible ocean surface fields.
name :: [in] The name of the field to extract
value :: [out] The value of the named field [various]

subroutine ocean_model_mod/ocean_public_type_chksum(id, timestep, ocn)¶

Write out checksums for fields from the ocean surface state.

Parameters:

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

Call to:

mom_io::stdout_if_root

subroutine ocean_model_mod/get_ocean_grid(OS, 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

subroutine ocean_model_mod/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.

Parameters:

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