MOM_tracer_flow_control.F90

Go to the documentation of this file.

module mom_tracer_flow_control
!***********************************************************************
!*                   GNU General Public License                        *
!* This file is a part of MOM.                                         *
!*                                                                     *
!* MOM is free software; you can redistribute it and/or modify it and  *
!* are expected to follow the terms of the GNU General Public License  *
!* as published by the Free Software Foundation; either version 2 of   *
!* the License, or (at your option) any later version.                 *
!*                                                                     *
!* MOM is distributed in the hope that it will be useful, but WITHOUT  *
!* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY  *
!* or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public    *
!* License for more details.                                           *
!*                                                                     *
!* For the full text of the GNU General Public License,                *
!* write to: Free Software Foundation, Inc.,                           *
!*           675 Mass Ave, Cambridge, MA 02139, USA.                   *
!* or see:   http://www.gnu.org/licenses/gpl.html                      *
!***********************************************************************

!********+*********+*********+*********+*********+*********+*********+**
!*                                                                     *
!*  By Will Cooke, April 2003                                          *
!*                                                                     *
!*    This module contains two subroutines into which calls to other   *
!*  tracer initialization (call_tracer_init_fns) and column physics    *
!*  routines (call_tracer_column_fns) can be inserted.                 *
!*                                                                     *
!********+*********+*********+*********+*********+*********+*********+**

use mom_diag_mediator, only : time_type, diag_ctrl
use mom_diag_to_z, only : diag_to_z_cs
use mom_error_handler, only : mom_error, fatal, warning
use mom_file_parser, only : get_param, log_version, param_file_type
use mom_forcing_type, only : forcing, optics_type
use mom_grid, only : ocean_grid_type
use mom_hor_index, only : hor_index_type
use mom_open_boundary, only : ocean_obc_type
use mom_restart, only : mom_restart_cs
use mom_sponge, only : sponge_cs
use mom_ale_sponge, only : ale_sponge_cs
use mom_tracer_registry, only : tracer_registry_type
use mom_variables, only : surface, thermo_var_ptrs
use mom_verticalgrid, only : verticalgrid_type
#include <MOM_memory.h>

! Add references to other user-provide tracer modules here.
use user_tracer_example, only : tracer_column_physics, user_initialize_tracer, user_tracer_stock
use user_tracer_example, only : user_register_tracer_example, user_tracer_surface_state
use user_tracer_example, only : user_tracer_example_end, user_tracer_example_cs
use dome_tracer, only : register_dome_tracer, initialize_dome_tracer
use dome_tracer, only : dome_tracer_column_physics, dome_tracer_surface_state
use dome_tracer, only : dome_tracer_end, dome_tracer_cs
use isomip_tracer, only : register_isomip_tracer, initialize_isomip_tracer
use isomip_tracer, only : isomip_tracer_column_physics, isomip_tracer_surface_state
use isomip_tracer, only : isomip_tracer_end, isomip_tracer_cs
use ideal_age_example, only : register_ideal_age_tracer, initialize_ideal_age_tracer
use ideal_age_example, only : ideal_age_tracer_column_physics, ideal_age_tracer_surface_state
use ideal_age_example, only : ideal_age_stock, ideal_age_example_end, ideal_age_tracer_cs
use regional_dyes, only : register_dye_tracer, initialize_dye_tracer
use regional_dyes, only : dye_tracer_column_physics, dye_tracer_surface_state
use regional_dyes, only : dye_stock, regional_dyes_end, dye_tracer_cs
use mom_ocmip2_cfc, only : register_ocmip2_cfc, initialize_ocmip2_cfc
use mom_ocmip2_cfc, only : ocmip2_cfc_column_physics, ocmip2_cfc_surface_state
use mom_ocmip2_cfc, only : ocmip2_cfc_stock, ocmip2_cfc_end, ocmip2_cfc_cs
use oil_tracer, only : register_oil_tracer, initialize_oil_tracer
use oil_tracer, only : oil_tracer_column_physics, oil_tracer_surface_state
use oil_tracer, only : oil_stock, oil_tracer_end, oil_tracer_cs
use advection_test_tracer, only : register_advection_test_tracer, initialize_advection_test_tracer
use advection_test_tracer, only : advection_test_tracer_column_physics, advection_test_tracer_surface_state
use advection_test_tracer, only : advection_test_stock, advection_test_tracer_end, advection_test_tracer_cs
#ifdef _USE_GENERIC_TRACER
use mom_generic_tracer, only : register_mom_generic_tracer, initialize_mom_generic_tracer
use mom_generic_tracer, only : mom_generic_tracer_column_physics, mom_generic_tracer_surface_state
use mom_generic_tracer, only : end_mom_generic_tracer, mom_generic_tracer_get
use mom_generic_tracer, only : mom_generic_tracer_stock, mom_generic_tracer_min_max, mom_generic_tracer_cs
#endif
use pseudo_salt_tracer, only : register_pseudo_salt_tracer, initialize_pseudo_salt_tracer
use pseudo_salt_tracer, only : pseudo_salt_tracer_column_physics, pseudo_salt_tracer_surface_state
use pseudo_salt_tracer, only : pseudo_salt_stock, pseudo_salt_tracer_end, pseudo_salt_tracer_cs
use boundary_impulse_tracer, only : register_boundary_impulse_tracer, initialize_boundary_impulse_tracer
use boundary_impulse_tracer, only : boundary_impulse_tracer_column_physics, boundary_impulse_tracer_surface_state
use boundary_impulse_tracer, only : boundary_impulse_stock, boundary_impulse_tracer_end
use boundary_impulse_tracer, only : boundary_impulse_tracer_cs

implicit none ; private

public call_tracer_register, tracer_flow_control_init, call_tracer_set_forcing
public call_tracer_column_fns, call_tracer_surface_state, call_tracer_stocks
public get_chl_from_model, tracer_flow_control_end

type, public :: tracer_flow_control_cs ; private
  logical :: use_user_tracer_example = .false.
  logical :: use_dome_tracer = .false.
  logical :: use_isomip_tracer = .false.
  logical :: use_ideal_age = .false.
  logical :: use_regional_dyes = .false.
  logical :: use_oil = .false.
  logical :: use_advection_test_tracer = .false.
  logical :: use_ocmip2_cfc = .false.
  logical :: use_mom_generic_tracer = .false.
  logical :: use_pseudo_salt_tracer = .false.
  logical :: use_boundary_impulse_tracer = .false.
  type(user_tracer_example_cs), pointer :: user_tracer_example_csp => null()
  type(dome_tracer_cs), pointer :: dome_tracer_csp => null()
  type(isomip_tracer_cs), pointer :: isomip_tracer_csp => null()
  type(ideal_age_tracer_cs), pointer :: ideal_age_tracer_csp => null()
  type(dye_tracer_cs), pointer :: dye_tracer_csp => null()
  type(oil_tracer_cs), pointer :: oil_tracer_csp => null()
  type(advection_test_tracer_cs), pointer :: advection_test_tracer_csp => null()
  type(ocmip2_cfc_cs), pointer :: ocmip2_cfc_csp => null()
#ifdef _USE_GENERIC_TRACER
  type(mom_generic_tracer_cs), pointer :: mom_generic_tracer_csp => null()
#endif
  type(pseudo_salt_tracer_cs), pointer :: pseudo_salt_tracer_csp => null()
  type(boundary_impulse_tracer_cs), pointer :: boundary_impulse_tracer_csp => null()
end type tracer_flow_control_cs

contains

!> The following 5 subroutines and associated definitions provide the
!! machinery to register and call the subroutines that initialize
!! tracers and apply vertical column processes to tracers.
subroutine call_tracer_register(HI, GV, param_file, CS, tr_Reg, restart_CS)
  type(hor_index_type),         intent(in) :: HI         !< A horizontal index type structure.
  type(verticalgrid_type),      intent(in) :: GV         !< The ocean's vertical grid structure.
  type(param_file_type),        intent(in) :: param_file !< A structure to parse for run-time
                                                         !! parameters.
  type(tracer_flow_control_cs), pointer    :: CS         !< A pointer that is set to point to the
                                                         !! control structure for this module.
  type(tracer_registry_type),   pointer    :: tr_Reg     !< A pointer that is set to point to the
                                                         !! control structure for the tracer
                                                         !! advection and diffusion module.
  type(mom_restart_cs),         pointer    :: restart_CS !< A pointer to the restart control
                                                         !! structure.
! Arguments: HI - A horizontal index type structure.
!  (in)      GV - The ocean's vertical grid structure.
!  (in)      param_file - A structure indicating the open file to parse for
!                         model parameter values.
!  (in/out)  CS - A pointer that is set to point to the control structure
!                 for this module
!  (in/out)  tr_Reg - A pointer that is set to point to the control structure
!                  for the tracer advection and diffusion module.
!  (in)      restart_CS - A pointer to the restart control structure.

! This include declares and sets the variable "version".
#include "version_variable.h"
  character(len=40)  :: mdl = "MOM_tracer_flow_control" ! This module's name.

  if (associated(cs)) then
    call mom_error(warning, "call_tracer_register called with an associated "// &
                            "control structure.")
    return
  else ; allocate(cs) ; endif

  ! Read all relevant parameters and write them to the model log.
  call log_version(param_file, mdl, version, "")
  call get_param(param_file, mdl, "USE_USER_TRACER_EXAMPLE", &
                                cs%use_USER_tracer_example, &
                 "If true, use the USER_tracer_example tracer package.", &
                 default=.false.)
  call get_param(param_file, mdl, "USE_DOME_TRACER", cs%use_DOME_tracer, &
                 "If true, use the DOME_tracer tracer package.", &
                 default=.false.)
  call get_param(param_file, mdl, "USE_ISOMIP_TRACER", cs%use_ISOMIP_tracer, &
                 "If true, use the ISOMIP_tracer tracer package.", &
                 default=.false.)
  call get_param(param_file, mdl, "USE_IDEAL_AGE_TRACER", cs%use_ideal_age, &
                 "If true, use the ideal_age_example tracer package.", &
                 default=.false.)
  call get_param(param_file, mdl, "USE_REGIONAL_DYES", cs%use_regional_dyes, &
                 "If true, use the regional_dyes tracer package.", &
                 default=.false.)
  call get_param(param_file, mdl, "USE_OIL_TRACER", cs%use_oil, &
                 "If true, use the oil_tracer tracer package.", &
                 default=.false.)
  call get_param(param_file, mdl, "USE_ADVECTION_TEST_TRACER", cs%use_advection_test_tracer, &
                 "If true, use the advection_test_tracer tracer package.", &
                 default=.false.)
  call get_param(param_file, mdl, "USE_OCMIP2_CFC", cs%use_OCMIP2_CFC, &
                 "If true, use the MOM_OCMIP2_CFC tracer package.", &
                 default=.false.)
  call get_param(param_file, mdl, "USE_generic_tracer", &
                                cs%use_MOM_generic_tracer, &
                 "If true and _USE_GENERIC_TRACER is defined as a \n"//&
                 "preprocessor macro, use the MOM_generic_tracer packages.", &
                 default=.false.)
  call get_param(param_file, mdl, "USE_PSEUDO_SALT_TRACER", cs%use_pseudo_salt_tracer, &
                 "If true, use the pseudo salt tracer, typically run as a diagnostic.", &
                 default=.false.)
  call get_param(param_file, mdl, "USE_BOUNDARY_IMPULSE_TRACER", cs%use_boundary_impulse_tracer, &
                 "If true, use the boundary impulse tracer.", &
                 default=.false.)

#ifndef _USE_GENERIC_TRACER
  if (cs%use_MOM_generic_tracer) call mom_error(fatal, &
       "call_tracer_register: use_MOM_generic_tracer=.true. BUT not compiled")
#endif

!    Add other user-provided calls to register tracers for restarting here. Each
!  tracer package registration call returns a logical false if it cannot be run
!  for some reason.  This then overrides the run-time selection from above.
  if (cs%use_USER_tracer_example) cs%use_USER_tracer_example = &
    user_register_tracer_example(hi, gv, param_file, cs%USER_tracer_example_CSp, &
                                 tr_reg, restart_cs)
  if (cs%use_DOME_tracer) cs%use_DOME_tracer = &
    register_dome_tracer(hi, gv, param_file, cs%DOME_tracer_CSp, &
                         tr_reg, restart_cs)
  if (cs%use_ISOMIP_tracer) cs%use_ISOMIP_tracer = &
    register_isomip_tracer(hi, gv, param_file, cs%ISOMIP_tracer_CSp, &
                           tr_reg, restart_cs)
  if (cs%use_ideal_age) cs%use_ideal_age = &
    register_ideal_age_tracer(hi, gv, param_file,  cs%ideal_age_tracer_CSp, &
                              tr_reg, restart_cs)
  if (cs%use_regional_dyes) cs%use_regional_dyes = &
    register_dye_tracer(hi, gv, param_file,  cs%dye_tracer_CSp, &
                        tr_reg, restart_cs)
  if (cs%use_oil) cs%use_oil = &
    register_oil_tracer(hi, gv, param_file,  cs%oil_tracer_CSp, &
                        tr_reg, restart_cs)
  if (cs%use_advection_test_tracer) cs%use_advection_test_tracer = &
    register_advection_test_tracer(hi, gv, param_file, cs%advection_test_tracer_CSp, &
                                   tr_reg, restart_cs)
  if (cs%use_OCMIP2_CFC) cs%use_OCMIP2_CFC = &
    register_ocmip2_cfc(hi, gv, param_file,  cs%OCMIP2_CFC_CSp, &
                        tr_reg, restart_cs)
#ifdef _USE_GENERIC_TRACER
  if (cs%use_MOM_generic_tracer) cs%use_MOM_generic_tracer = &
    register_mom_generic_tracer(hi, gv, param_file,  cs%MOM_generic_tracer_CSp, &
                                tr_reg, restart_cs)
#endif
  if (cs%use_pseudo_salt_tracer) cs%use_pseudo_salt_tracer = &
    register_pseudo_salt_tracer(hi, gv, param_file,  cs%pseudo_salt_tracer_CSp, &
                        tr_reg, restart_cs)
  if (cs%use_boundary_impulse_tracer) cs%use_boundary_impulse_tracer = &
    register_boundary_impulse_tracer(hi, gv, param_file,  cs%boundary_impulse_tracer_CSp, &
                        tr_reg, restart_cs)


end subroutine call_tracer_register

!> This subroutine calls all registered tracer initialization
!! subroutines.
subroutine tracer_flow_control_init(restart, day, G, GV, h, param_file, diag, OBC, &
                                CS, sponge_CSp, ALE_sponge_CSp, diag_to_Z_CSp, tv)
  logical,                               intent(in)    :: restart !< 1 if the fields have already
                                                                  !! been read from a restart file.
  type(time_type), target,               intent(in)    :: day     !< Time of the start of the run.
  type(ocean_grid_type),                 intent(inout) :: G       !< The ocean's grid structure.
  type(verticalgrid_type),               intent(in)    :: GV      !< The ocean's vertical grid
                                                                  !! structure.
  real, dimension(NIMEM_,NJMEM_,NKMEM_), intent(in)    :: h       !< Layer thicknesses, in H
                                                                  !! (usually m or kg m-2)
  type(param_file_type),                 intent(in)    :: param_file !< A structure to parse for
                                                                  !! run-time parameters
  type(diag_ctrl), target,               intent(in)    :: diag    !< A structure that is used to
                                                                  !! regulate diagnostic output.
  type(ocean_obc_type),                  pointer       :: OBC     !< This open boundary condition
                                                                  !! type specifies whether, where,
                                                                  !! and what open boundary
                                                                  !! conditions are used.
  type(tracer_flow_control_cs),          pointer       :: CS      !< The control structure returned
                                                                  !! by a previous call to
                                                                  !! call_tracer_register.
  type(sponge_cs),                       pointer       :: sponge_CSp     !< A pointer to the control
                                               !! structure for the sponges, if they are in use.
                                               !! Otherwise this may be unassociated.
  type(ale_sponge_cs),                   pointer       :: ALE_sponge_CSp !< A pointer to the control
                                               !! structure for the ALE sponges, if they are in use.
                                               !! Otherwise this may be unassociated.
  type(diag_to_z_cs),                    pointer       :: diag_to_Z_CSp  !< A pointer to the control
                                               !! structure for diagnostics in depth space.
  type(thermo_var_ptrs),                 intent(in)    :: tv      !< A structure pointing to various
                                                                  !! thermodynamic variables
!   This subroutine calls all registered tracer initialization
! subroutines.

! Arguments: restart - 1 if the fields have already been read from
!                     a restart file.
!  (in)      day - Time of the start of the run.
!  (in)      G - The ocean's grid structure.
!  (in)      GV - The ocean's vertical grid structure.
!  (in)      h - Layer thickness, in m (Boussinesq) or kg m-2 (non-Boussinesq).
!  (in)      diag - A structure that is used to regulate diagnostic output.
!  (in)      OBC - This open boundary condition type specifies whether, where,
!                  and what open boundary conditions are used.
!  (in)      CS - The control structure returned by a previous call to
!                 call_tracer_register.
!  (in/out)  sponge_CSp - A pointer to the control structure for the sponges, if
!                         they are in use.  Otherwise this may be unassociated.
!  (in/out)  ALE_sponge_CSp - A pointer to the control structure for the ALE sponges, if they are
!                             in use.  Otherwise this may be unassociated.
!  (in/out)  diag_to_Z_Csp - A pointer to the control structure for diagnostics
!                            in depth space.
  if (.not. associated(cs)) call mom_error(fatal, "tracer_flow_control_init: "// &
         "Module must be initialized via call_tracer_register before it is used.")

!  Add other user-provided calls here.
  if (cs%use_USER_tracer_example) &
    call user_initialize_tracer(restart, day, g, gv, h, diag, obc, cs%USER_tracer_example_CSp, &
                                sponge_csp, diag_to_z_csp)
  if (cs%use_DOME_tracer) &
    call initialize_dome_tracer(restart, day, g, gv, h, diag, obc, cs%DOME_tracer_CSp, &
                                sponge_csp, diag_to_z_csp)
  if (cs%use_ISOMIP_tracer) &
    call initialize_isomip_tracer(restart, day, g, gv, h, diag, obc, cs%ISOMIP_tracer_CSp, &
                                ale_sponge_csp, diag_to_z_csp)
  if (cs%use_ideal_age) &
    call initialize_ideal_age_tracer(restart, day, g, gv, h, diag, obc, cs%ideal_age_tracer_CSp, &
                                     sponge_csp, diag_to_z_csp)
  if (cs%use_regional_dyes) &
    call initialize_dye_tracer(restart, day, g, gv, h, diag, obc, cs%dye_tracer_CSp, &
                                     sponge_csp, diag_to_z_csp)
  if (cs%use_oil) &
    call initialize_oil_tracer(restart, day, g, gv, h, diag, obc, cs%oil_tracer_CSp, &
                                     sponge_csp, diag_to_z_csp)
  if (cs%use_advection_test_tracer) &
    call initialize_advection_test_tracer(restart, day, g, gv, h, diag, obc, cs%advection_test_tracer_CSp, &
                                sponge_csp, diag_to_z_csp)
  if (cs%use_OCMIP2_CFC) &
    call initialize_ocmip2_cfc(restart, day, g, gv, h, diag, obc, cs%OCMIP2_CFC_CSp, &
                                sponge_csp, diag_to_z_csp)
#ifdef _USE_GENERIC_TRACER
  if (cs%use_MOM_generic_tracer) &
    call initialize_mom_generic_tracer(restart, day, g, gv, h, param_file, diag, obc, &
        cs%MOM_generic_tracer_CSp, sponge_csp, ale_sponge_csp, diag_to_z_csp)
#endif
  if (cs%use_pseudo_salt_tracer) &
    call initialize_pseudo_salt_tracer(restart, day, g, gv, h, diag, obc, cs%pseudo_salt_tracer_CSp, &
                                sponge_csp, diag_to_z_csp, tv)
  if (cs%use_boundary_impulse_tracer) &
    call initialize_boundary_impulse_tracer(restart, day, g, gv, h, diag, obc, cs%boundary_impulse_tracer_CSp, &
                                sponge_csp, diag_to_z_csp, tv)

end subroutine tracer_flow_control_init

! #@# This subroutine needs a doxygen description
subroutine get_chl_from_model(Chl_array, G, CS)
  real, dimension(NIMEM_,NJMEM_,NKMEM_), intent(out) :: Chl_array !< The array into which the
                                                                  !! model's Chlorophyll-A
                                                                  !! concentrations in mg m-3 are
                                                                  !! to be read.
  type(ocean_grid_type),                 intent(in)  :: G         !< The ocean's grid structure.
  type(tracer_flow_control_cs),          pointer     :: CS        !< The control structure returned
                                                                  !! by a previous call to
                                                                  !! call_tracer_register.
! Arguments: Chl_array - The array into which the model's Chlorophyll-A
!                        concentrations in mg m-3 are to be read.
!  (in)      G - The ocean's grid structure.
!  (in)      CS - The control structure returned by a previous call to
!                 call_tracer_register.

#ifdef _USE_GENERIC_TRACER
  if (cs%use_MOM_generic_tracer) then
    call mom_generic_tracer_get('chl','field',chl_array, cs%MOM_generic_tracer_CSp)
  else
    call mom_error(fatal, "get_chl_from_model was called in a configuration "// &
             "that is unable to provide a sensible model-based value.\n"// &
             "CS%use_MOM_generic_tracer is false and no other viable options are on.")
  endif
#else
  call mom_error(fatal, "get_chl_from_model was called in a configuration "// &
           "that is unable to provide a sensible model-based value.\n"// &
           "_USE_GENERIC_TRACER is undefined and no other options "//&
           "are currently viable.")
#endif

end subroutine get_chl_from_model

!> This subroutine calls the individual tracer modules' subroutines to
!! specify or read quantities related to their surface forcing.
subroutine call_tracer_set_forcing(state, fluxes, day_start, day_interval, G, CS)

  type(surface),                intent(inout) :: state     !< A structure containing fields that
                                                           !! describe the surface state of the
                                                           !! ocean.
  type(forcing),                intent(inout) :: fluxes    !< A structure containing pointers to any
                                                           !! possible forcing fields. Unused fields
                                                           !! have NULL ptrs.
  type(time_type),              intent(in)    :: day_start !< Start time of the fluxes.
  type(time_type),              intent(in)    :: day_interval !< Length of time over which these
                                                           !! fluxes will be applied.
  type(ocean_grid_type),        intent(in)    :: G         !< The ocean's grid structure.
  type(tracer_flow_control_cs), pointer       :: CS        !< The control structure returned by a
                                                           !! previous call to call_tracer_register.

!   This subroutine calls the individual tracer modules' subroutines to
! specify or read quantities related to their surface forcing.
! Arguments: state - A structure containing fields that describe the
!                    surface state of the ocean.
!  (out)     fluxes - A structure containing pointers to any possible
!                     forcing fields.  Unused fields have NULL ptrs.
!  (in)      day_start - Start time of the fluxes.
!  (in)      day_interval - Length of time over which these fluxes
!                           will be applied.
!  (in)      G - The ocean's grid structure.
!  (in)      CS - The control structure returned by a previous call to
!                 call_tracer_register.

  if (.not. associated(cs)) call mom_error(fatal, "call_tracer_set_forcing"// &
         "Module must be initialized via call_tracer_register before it is used.")
!  if (CS%use_ideal_age) &
!    call ideal_age_tracer_set_forcing(state, fluxes, day_start, day_interval, &
!                                      G, CS%ideal_age_tracer_CSp)

end subroutine call_tracer_set_forcing

!> This subroutine calls all registered tracer column physics
!! subroutines.
subroutine call_tracer_column_fns(h_old, h_new, ea, eb, fluxes, Hml, dt, G, GV, tv, optics, CS, &
                                  debug, evap_CFL_limit, minimum_forcing_depth)
  real, dimension(NIMEM_,NJMEM_,NKMEM_), intent(in) :: h_old  !< Layer thickness before entrainment,
                                                              !! in m (Boussinesq) or kg m-2
                                                              !! (non-Boussinesq).
  real, dimension(NIMEM_,NJMEM_,NKMEM_), intent(in) :: h_new  !< Layer thickness after entrainment,
                                                              !! in m or kg m-2.
  real, dimension(NIMEM_,NJMEM_,NKMEM_), intent(in) :: ea     !< an array to which the amount of
                                          !! fluid entrained from the layer above during this call
                                          !! will be added, in m or kg m-2, the same as h_old.
  real, dimension(NIMEM_,NJMEM_,NKMEM_), intent(in) :: eb     !< an array to which the amount of
                                          !! fluid entrained from the layer below during this call
                                          !! will be added, in m or kg m-2, the same as h_old.
  type(forcing),                         intent(in) :: fluxes !< A structure containing pointers to
                                                              !! any possible forcing fields.
                                                              !! Unused fields have NULL ptrs.
  real, dimension(NIMEM_,NJMEM_),        intent(in) :: Hml    !< Mixed layer depth (m)
  real,                                  intent(in) :: dt     !< The amount of time covered by this
                                                              !! call, in s
  type(ocean_grid_type),                 intent(in) :: G      !< The ocean's grid structure.
  type(verticalgrid_type),               intent(in) :: GV     !< The ocean's vertical grid
                                                              !! structure.
  type(thermo_var_ptrs),                 intent(in) :: tv     !< A structure pointing to various
                                                              !! thermodynamic variables.
  type(optics_type),                     pointer    :: optics !< The structure containing optical
                                                              !! properties.
  type(tracer_flow_control_cs),          pointer    :: CS     !< The control structure returned by
                                                              !! a previous call to
                                                              !! call_tracer_register.
  logical,                               intent(in) :: debug  !< Calculates checksums
  real,                         optional,intent(in) :: evap_CFL_limit !< Limits how much water
                                                              !! can be fluxed out of the top layer
                                                              !! Stored previously in diabatic] CS.
  real,                         optional,intent(in) :: minimum_forcing_depth !< The smallest depth
                                                              !! over which fluxes can be applied
                                                              !! Stored previously in diabatic CS.

!   This subroutine calls all registered tracer column physics
! subroutines.

! Arguments: h_old -  Layer thickness before entrainment, in m (Boussinesq)
!                     or kg m-2 (non-Boussinesq).
!  (in)      h_new -  Layer thickness after entrainment, in m or kg m-2.
!  (in)      ea - an array to which the amount of fluid entrained
!                 from the layer above during this call will be
!                 added, in m or kg m-2, the same as h_old.
!  (in)      eb - an array to which the amount of fluid entrained
!                 from the layer below during this call will be
!                 added, in m or kg m-2, the same as h_old.
!  (in)      fluxes - A structure containing pointers to any possible
!                     forcing fields.  Unused fields have NULL ptrs.
!  (in)      dt - The amount of time covered by this call, in s.
!  (in)      G - The ocean's grid structure.
!  (in)      GV - The ocean's vertical grid structure.
!  (in)      tv - The structure containing thermodynamic variables.
!  (in)      optics - The structure containing optical properties.
!  (in)      CS - The control structure returned by a previous call to
!                 call_tracer_register.
!  (in)      evap_CFL_limit - Limits how much water can be fluxed out of the top layer
!                             Stored previously in diabatic CS.
!  (in)      minimum_forcing_depth - The smallest depth over which fluxes can be applied
!                             Stored previously in diabatic CS.
!  (in)      debug - Calculates checksums

  if (.not. associated(cs)) call mom_error(fatal, "call_tracer_column_fns: "// &
         "Module must be initialized via call_tracer_register before it is used.")

  ! Use the applyTracerBoundaryFluxesInOut to handle surface fluxes
  if (present(evap_cfl_limit) .and. present(minimum_forcing_depth)) then
    ! Add calls to tracer column functions here.
    if (cs%use_USER_tracer_example) &
      call tracer_column_physics(h_old, h_new, ea, eb, fluxes, dt, &
                                 g, gv, cs%USER_tracer_example_CSp)
    if (cs%use_DOME_tracer) &
      call dome_tracer_column_physics(h_old, h_new, ea, eb, fluxes, dt, &
                                      g, gv, cs%DOME_tracer_CSp, &
                                      evap_cfl_limit=evap_cfl_limit, &
                                      minimum_forcing_depth=minimum_forcing_depth)
    if (cs%use_ISOMIP_tracer) &
      call isomip_tracer_column_physics(h_old, h_new, ea, eb, fluxes, dt, &
                                        g, gv, cs%ISOMIP_tracer_CSp, &
                                        evap_cfl_limit=evap_cfl_limit, &
                                        minimum_forcing_depth=minimum_forcing_depth)
    if (cs%use_ideal_age) &
      call ideal_age_tracer_column_physics(h_old, h_new, ea, eb, fluxes, dt, &
                                           g, gv, cs%ideal_age_tracer_CSp, &
                                           evap_cfl_limit=evap_cfl_limit, &
                                           minimum_forcing_depth=minimum_forcing_depth)
    if (cs%use_regional_dyes) &
      call dye_tracer_column_physics(h_old, h_new, ea, eb, fluxes, dt, &
                                     g, gv, cs%dye_tracer_CSp, &
                                     evap_cfl_limit=evap_cfl_limit, &
                                     minimum_forcing_depth=minimum_forcing_depth)
    if (cs%use_oil) &
      call oil_tracer_column_physics(h_old, h_new, ea, eb, fluxes, dt, &
                                     g, gv, cs%oil_tracer_CSp, tv, &
                                     evap_cfl_limit=evap_cfl_limit, &
                                     minimum_forcing_depth=minimum_forcing_depth)

    if (cs%use_advection_test_tracer) &
      call advection_test_tracer_column_physics(h_old, h_new, ea, eb, fluxes, dt, &
                                                g, gv, cs%advection_test_tracer_CSp, &
                                                evap_cfl_limit=evap_cfl_limit, &
                                                minimum_forcing_depth=minimum_forcing_depth)
    if (cs%use_OCMIP2_CFC) &
      call ocmip2_cfc_column_physics(h_old, h_new, ea, eb, fluxes, dt, &
                                     g, gv, cs%OCMIP2_CFC_CSp, &
                                     evap_cfl_limit=evap_cfl_limit, &
                                     minimum_forcing_depth=minimum_forcing_depth)
#ifdef _USE_GENERIC_TRACER
    if (cs%use_MOM_generic_tracer) &
      call mom_generic_tracer_column_physics(h_old, h_new, ea, eb, fluxes, hml, dt, &
                                             g, gv, cs%MOM_generic_tracer_CSp, tv, optics, &
                                             evap_cfl_limit=evap_cfl_limit, &
                                             minimum_forcing_depth=minimum_forcing_depth)
#endif
    if (cs%use_pseudo_salt_tracer) &
      call pseudo_salt_tracer_column_physics(h_old, h_new, ea, eb, fluxes, dt, &
                                     g, gv, cs%pseudo_salt_tracer_CSp, tv, debug,&
                                     evap_cfl_limit=evap_cfl_limit, &
                                     minimum_forcing_depth=minimum_forcing_depth)
    if (cs%use_boundary_impulse_tracer) &
      call boundary_impulse_tracer_column_physics(h_old, h_new, ea, eb, fluxes, dt, &
                                     g, gv, cs%boundary_impulse_tracer_CSp, tv, debug,&
                                     evap_cfl_limit=evap_cfl_limit, &
                                     minimum_forcing_depth=minimum_forcing_depth)


  else ! Apply tracer surface fluxes using ea on the first layer
    if (cs%use_USER_tracer_example) &
      call tracer_column_physics(h_old, h_new, ea, eb, fluxes, dt, &
                                 g, gv, cs%USER_tracer_example_CSp)
    if (cs%use_DOME_tracer) &
      call dome_tracer_column_physics(h_old, h_new, ea, eb, fluxes, dt, &
                                      g, gv, cs%DOME_tracer_CSp)
    if (cs%use_ISOMIP_tracer) &
      call isomip_tracer_column_physics(h_old, h_new, ea, eb, fluxes, dt, &
                                      g, gv, cs%ISOMIP_tracer_CSp)
    if (cs%use_ideal_age) &
      call ideal_age_tracer_column_physics(h_old, h_new, ea, eb, fluxes, dt, &
                                           g, gv, cs%ideal_age_tracer_CSp)
    if (cs%use_regional_dyes) &
      call dye_tracer_column_physics(h_old, h_new, ea, eb, fluxes, dt, &
                                           g, gv, cs%dye_tracer_CSp)
    if (cs%use_oil) &
      call oil_tracer_column_physics(h_old, h_new, ea, eb, fluxes, dt, &
                                     g, gv, cs%oil_tracer_CSp, tv)
    if (cs%use_advection_test_tracer) &
      call advection_test_tracer_column_physics(h_old, h_new, ea, eb, fluxes, dt, &
                                      g, gv, cs%advection_test_tracer_CSp)
    if (cs%use_OCMIP2_CFC) &
      call ocmip2_cfc_column_physics(h_old, h_new, ea, eb, fluxes, dt, &
                                     g, gv, cs%OCMIP2_CFC_CSp)
#ifdef _USE_GENERIC_TRACER
    if (cs%use_MOM_generic_tracer) &
      call mom_generic_tracer_column_physics(h_old, h_new, ea, eb, fluxes, hml, dt, &
                                     g, gv, cs%MOM_generic_tracer_CSp, tv, optics)
#endif
    if (cs%use_pseudo_salt_tracer) &
      call pseudo_salt_tracer_column_physics(h_old, h_new, ea, eb, fluxes, dt, &
                                     g, gv, cs%pseudo_salt_tracer_CSp, tv, debug)
    if (cs%use_boundary_impulse_tracer) &
      call boundary_impulse_tracer_column_physics(h_old, h_new, ea, eb, fluxes, dt, &
                                     g, gv, cs%boundary_impulse_tracer_CSp, tv, debug)


  endif


end subroutine call_tracer_column_fns

!> This subroutine calls all registered tracer packages to enable them to
!! add to the surface state returned to the coupler. These routines are optional.
subroutine call_tracer_stocks(h, stock_values, G, GV, CS, stock_names, stock_units, &
                              num_stocks, stock_index, got_min_max,global_min,  global_max,xgmin, &
                              ygmin, zgmin, xgmax, ygmax, zgmax)
  real, dimension(NIMEM_,NJMEM_,NKMEM_),    &
                                  intent(in)  :: h          !< Layer thicknesses, in H
                                                            !! (usually m or kg m-2).
  real, dimension(:),             intent(out) :: stock_values
  type(ocean_grid_type),          intent(in)  :: G           !< The ocean's grid structure.
  type(verticalgrid_type),        intent(in)  :: GV          !< The ocean's vertical grid structure.
  type(tracer_flow_control_cs),   pointer     :: CS          !< The control structure returned by a
                                                             !! previous call to
                                                             !! call_tracer_register.
  character(len=*), dimension(:), optional, &
                                  intent(out) :: stock_names !< Diagnostic names to use for each
                                                             !! stock.
  character(len=*), dimension(:), optional, &
                                  intent(out) :: stock_units !< Units to use in the metadata for
                                                             !! each stock.
  integer,                        optional, &
                                  intent(out) :: num_stocks  !< The number of tracer stocks being
                                                             !! returned.
  integer,                        optional, &
                                  intent(in)  :: stock_index !< The integer stock index from
                             !! stocks_constans_mod of the stock to be returned.  If this is
                             !! present and greater than 0, only a single stock can be returned.
  logical,  dimension(:),         optional, &
                                  intent(inout) :: got_min_max
  real, dimension(:),             optional, &
                                  intent(out) :: global_min,  global_max
  real, dimension(:),             optional, &
                                  intent(out) :: xgmin, ygmin, zgmin, xgmax, ygmax, zgmax
!   This subroutine calls all registered tracer packages to enable them to
! add to the surface state returned to the coupler. These routines are optional.

! Arguments: h - Layer thickness, in m (Boussinesq) or kg m-2 (non-Boussinesq).
!  (out)     stock_values - The integrated amounts of a tracer on the current
!                           PE, usually in kg x concentration.
!  (in)      G - The ocean's grid structure.
!  (in)      GV - The ocean's vertical grid structure.
!  (in)      CS - The control structure returned by a previous call to
!                 call_tracer_register.
!  (out,opt) stock_names - Diagnostic names to use for each stock.
!  (out,opt) stock_units - Units to use in the metadata for each stock.
!  (out,opt) num_stocks - The number of tracer stocks being returned.
!  (in,opt)  stock_index - The integer stock index from stocks_constans_mod of
!                          the stock to be returned.  If this is present and
!                          greater than 0, only a single stock can be returned.
  character(len=200), dimension(MAX_FIELDS_) :: names, units
  character(len=200) :: set_pkg_name
  real, dimension(MAX_FIELDS_) :: values
  integer :: max_ns, ns_tot, ns, index, pkg, max_pkgs, nn

  if (.not. associated(cs)) call mom_error(fatal, "call_tracer_stocks: "// &
       "Module must be initialized via call_tracer_register before it is used.")

  index = -1 ; if (present(stock_index)) index = stock_index
  ns_tot = 0
  max_ns = size(stock_values)
  if (present(stock_names)) max_ns = min(max_ns,size(stock_names))
  if (present(stock_units)) max_ns = min(max_ns,size(stock_units))

!  Add other user-provided calls here.
  if (cs%use_USER_tracer_example) then
    ns = user_tracer_stock(h, values, g, gv, cs%USER_tracer_example_CSp, &
                           names, units, stock_index)
    call store_stocks("tracer_example", ns, names, units, values, index, stock_values, &
                       set_pkg_name, max_ns, ns_tot, stock_names, stock_units)
  endif
! if (CS%use_DOME_tracer) then
!   ns = DOME_tracer_stock(h, values, G, GV, CS%DOME_tracer_CSp, &
!                          names, units, stock_index)
!   call store_stocks("DOME_tracer", ns, names, units, values, index, stock_values, &
!                      set_pkg_name, max_ns, ns_tot, stock_names, stock_units)
! endif
  if (cs%use_ideal_age) then
    ns = ideal_age_stock(h, values, g, gv, cs%ideal_age_tracer_CSp, &
                         names, units, stock_index)
    call store_stocks("ideal_age_example", ns, names, units, values, index, &
           stock_values, set_pkg_name, max_ns, ns_tot, stock_names, stock_units)
  endif
  if (cs%use_regional_dyes) then
    ns = dye_stock(h, values, g, gv, cs%dye_tracer_CSp, &
                         names, units, stock_index)
    call store_stocks("regional_dyes", ns, names, units, values, index, &
           stock_values, set_pkg_name, max_ns, ns_tot, stock_names, stock_units)
  endif
  if (cs%use_oil) then
    ns = oil_stock(h, values, g, gv, cs%oil_tracer_CSp, &
                         names, units, stock_index)
    call store_stocks("oil_tracer", ns, names, units, values, index, &
           stock_values, set_pkg_name, max_ns, ns_tot, stock_names, stock_units)
  endif
  if (cs%use_OCMIP2_CFC) then
    ns = ocmip2_cfc_stock(h, values, g, gv, cs%OCMIP2_CFC_CSp, names, units, stock_index)
    call store_stocks("MOM_OCMIP2_CFC", ns, names, units, values, index, stock_values, &
                       set_pkg_name, max_ns, ns_tot, stock_names, stock_units)
  endif

  if (cs%use_advection_test_tracer) then
    ns = advection_test_stock( h, values, g, gv, cs%advection_test_tracer_CSp, &
                         names, units, stock_index )
    call store_stocks("advection_test_tracer", ns, names, units, values, index, &
           stock_values, set_pkg_name, max_ns, ns_tot, stock_names, stock_units)
  endif

#ifdef _USE_GENERIC_TRACER
  if (cs%use_MOM_generic_tracer) then
    ns = mom_generic_tracer_stock(h, values, g, gv, cs%MOM_generic_tracer_CSp, &
                                   names, units, stock_index)
    call store_stocks("MOM_generic_tracer", ns, names, units, values, index, stock_values, &
                       set_pkg_name, max_ns, ns_tot, stock_names, stock_units)
    nn=ns_tot-ns+1
    nn=mom_generic_tracer_min_max(nn, got_min_max, global_min,  global_max, xgmin, ygmin, zgmin, xgmax, ygmax, zgmax ,&
                                     g, cs%MOM_generic_tracer_CSp,names, units)

  endif
#endif
  if (cs%use_pseudo_salt_tracer) then
    ns = pseudo_salt_stock(h, values, g, gv, cs%pseudo_salt_tracer_CSp, &
                         names, units, stock_index)
    call store_stocks("pseudo_salt_tracer", ns, names, units, values, index, &
           stock_values, set_pkg_name, max_ns, ns_tot, stock_names, stock_units)
  endif

  if (cs%use_boundary_impulse_tracer) then
    ns = boundary_impulse_stock(h, values, g, gv, cs%boundary_impulse_tracer_CSp, &
                         names, units, stock_index)
    call store_stocks("boundary_impulse_tracer", ns, names, units, values, index, &
           stock_values, set_pkg_name, max_ns, ns_tot, stock_names, stock_units)
  endif

  if (ns_tot == 0) stock_values(1) = 0.0

  if (present(num_stocks)) num_stocks = ns_tot

end subroutine call_tracer_stocks

!> This routine stores the stocks and does error handling for call_tracer_stocks.
subroutine store_stocks(pkg_name, ns, names, units, values, index, stock_values, &
                        set_pkg_name, max_ns, ns_tot, stock_names, stock_units)
  character(len=*),                         intent(in)    :: pkg_name
  integer,                                  intent(in)    :: ns
  character(len=*), dimension(:),           intent(in)    :: names, units
  real, dimension(:),                       intent(in)    :: values
  integer,                                  intent(in)    :: index
  real, dimension(:),                       intent(inout) :: stock_values
  character(len=*),                         intent(inout) :: set_pkg_name
  integer,                                  intent(in)    :: max_ns
  integer,                                  intent(inout) :: ns_tot
  character(len=*), dimension(:), optional, intent(inout) :: stock_names, stock_units

! This routine stores the stocks and does error handling for call_tracer_stocks.
  character(len=16) :: ind_text, ns_text, max_text
  integer :: n

  if ((index > 0) .and. (ns > 0)) then
    write(ind_text,'(i8)') index
    if (ns > 1) then
      call mom_error(fatal,"Tracer package "//trim(pkg_name)//&
          " is not permitted to return more than one value when queried"//&
          " for specific stock index "//trim(adjustl(ind_text))//".")
    elseif (ns+ns_tot > 1) then
      call mom_error(fatal,"Tracer packages "//trim(pkg_name)//" and "//&
          trim(set_pkg_name)//" both attempted to set values for"//&
          " specific stock index "//trim(adjustl(ind_text))//".")
    else
      set_pkg_name = pkg_name
    endif
  endif

  if (ns_tot+ns > max_ns) then
    write(ns_text,'(i8)') ns_tot+ns ; write(max_text,'(i8)') max_ns
    call mom_error(fatal,"Attempted to return more tracer stock values (at least "//&
      trim(adjustl(ns_text))//") than the size "//trim(adjustl(max_text))//&
      "of the smallest value, name, or units array.")
  endif

  do n=1,ns
    stock_values(ns_tot+n) = values(n)
    if (present(stock_names)) stock_names(ns_tot+n) = names(n)
    if (present(stock_units)) stock_units(ns_tot+n) = units(n)
  enddo
  ns_tot = ns_tot + ns

end subroutine store_stocks

!> This subroutine calls all registered tracer packages to enable them to
!! add to the surface state returned to the coupler. These routines are optional.
subroutine call_tracer_surface_state(state, h, G, CS)
  type(surface),                intent(inout) :: state !< A structure containing fields that
                                                       !! describe the surface state of the ocean.
  real, dimension(NIMEM_,NJMEM_,NKMEM_), &
                                intent(in)    :: h     !< Layer thicknesses, in H
                                                       !! (usually m or kg m-2).
  type(ocean_grid_type),        intent(in)    :: G     !< The ocean's grid structure.
  type(tracer_flow_control_cs), pointer       :: CS    !< The control structure returned by a
                                                       !! previous call to call_tracer_register.
!   This subroutine calls all registered tracer packages to enable them to
! add to the surface state returned to the coupler. These routines are optional.

! Arguments: state - A structure containing fields that describe the
!                    surface state of the ocean.
!  (in)      h - Layer thickness, in m (Boussinesq) or kg m-2 (non-Boussinesq).
!  (in)      G - The ocean's grid structure.
!  (in)      CS - The control structure returned by a previous call to
!                 call_tracer_register.

  if (.not. associated(cs)) call mom_error(fatal, "call_tracer_surface_state: "// &
         "Module must be initialized via call_tracer_register before it is used.")

!  Add other user-provided calls here.
  if (cs%use_USER_tracer_example) &
    call user_tracer_surface_state(state, h, g, cs%USER_tracer_example_CSp)
  if (cs%use_DOME_tracer) &
    call dome_tracer_surface_state(state, h, g, cs%DOME_tracer_CSp)
  if (cs%use_ISOMIP_tracer) &
    call isomip_tracer_surface_state(state, h, g, cs%ISOMIP_tracer_CSp)
  if (cs%use_ideal_age) &
    call ideal_age_tracer_surface_state(state, h, g, cs%ideal_age_tracer_CSp)
  if (cs%use_regional_dyes) &
    call dye_tracer_surface_state(state, h, g, cs%dye_tracer_CSp)
  if (cs%use_oil) &
    call oil_tracer_surface_state(state, h, g, cs%oil_tracer_CSp)
  if (cs%use_advection_test_tracer) &
    call advection_test_tracer_surface_state(state, h, g, cs%advection_test_tracer_CSp)
  if (cs%use_OCMIP2_CFC) &
    call ocmip2_cfc_surface_state(state, h, g, cs%OCMIP2_CFC_CSp)
#ifdef _USE_GENERIC_TRACER
  if (cs%use_MOM_generic_tracer) &
    call mom_generic_tracer_surface_state(state, h, g, cs%MOM_generic_tracer_CSp)
#endif

end subroutine call_tracer_surface_state

subroutine tracer_flow_control_end(CS)
  type(tracer_flow_control_cs), pointer :: CS

  if (cs%use_USER_tracer_example) &
    call user_tracer_example_end(cs%USER_tracer_example_CSp)
  if (cs%use_DOME_tracer) call dome_tracer_end(cs%DOME_tracer_CSp)
  if (cs%use_ISOMIP_tracer) call isomip_tracer_end(cs%ISOMIP_tracer_CSp)
  if (cs%use_ideal_age) call ideal_age_example_end(cs%ideal_age_tracer_CSp)
  if (cs%use_regional_dyes) call regional_dyes_end(cs%dye_tracer_CSp)
  if (cs%use_oil) call oil_tracer_end(cs%oil_tracer_CSp)
  if (cs%use_advection_test_tracer) call advection_test_tracer_end(cs%advection_test_tracer_CSp)
  if (cs%use_OCMIP2_CFC) call ocmip2_cfc_end(cs%OCMIP2_CFC_CSp)
#ifdef _USE_GENERIC_TRACER
  if (cs%use_MOM_generic_tracer) call end_mom_generic_tracer(cs%MOM_generic_tracer_CSp)
#endif
  if (cs%use_pseudo_salt_tracer) call pseudo_salt_tracer_end(cs%pseudo_salt_tracer_CSp)
  if (cs%use_boundary_impulse_tracer) call boundary_impulse_tracer_end(cs%boundary_impulse_tracer_CSp)

  if (associated(cs)) deallocate(cs)
end subroutine tracer_flow_control_end

end module mom_tracer_flow_control