tracer_example.F90

Go to the documentation of this file.

module user_tracer_example
!***********************************************************************
!*                   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 Robert Hallberg, 2002                                           *
!*                                                                     *
!*    This file contains an example of the code that is needed to set  *
!*  up and use a set (in this case one) of dynamically passive tracers.*
!*                                                                     *
!*    A single subroutine is called from within each file to register  *
!*  each of the tracers for reinitialization and advection and to      *
!*  register the subroutine that initializes the tracers and set up    *
!*  their output and the subroutine that does any tracer physics or    *
!*  chemistry along with diapycnal mixing (included here because some  *
!*  tracers may float or swim vertically or dye diapycnal processes).  *
!*                                                                     *
!*                                                                     *
!*  Macros written all in capital letters are defined in MOM_memory.h. *
!*                                                                     *
!*     A small fragment of the grid is shown below:                    *
!*                                                                     *
!*    j+1  x ^ x ^ x   At x:  q                                        *
!*    j+1  > o > o >   At ^:  v                                        *
!*    j    x ^ x ^ x   At >:  u                                        *
!*    j    > o > o >   At o:  h, tr                                    *
!*    j-1  x ^ x ^ x                                                   *
!*        i-1  i  i+1  At x & ^:                                       *
!*           i  i+1    At > & o:                                       *
!*                                                                     *
!*  The boundaries always run through q grid points (x).               *
!*                                                                     *
!********+*********+*********+*********+*********+*********+*********+**

use mom_diag_mediator, only : post_data, register_diag_field, safe_alloc_ptr
use mom_diag_mediator, only : diag_ctrl
use mom_diag_to_z, only : register_z_tracer, diag_to_z_cs
use mom_error_handler, only : mom_error, fatal, warning
use mom_file_parser, only : get_param, log_param, log_version, param_file_type
use mom_forcing_type, only : forcing
use mom_grid, only : ocean_grid_type
use mom_hor_index, only : hor_index_type
use mom_io, only : file_exists, read_data, slasher, vardesc, var_desc, query_vardesc
use mom_open_boundary, only : ocean_obc_type
use mom_restart, only : register_restart_field, mom_restart_cs
use mom_sponge, only : set_up_sponge_field, sponge_cs
use mom_time_manager, only : time_type, get_time
use mom_tracer_registry, only : register_tracer, tracer_registry_type
use mom_tracer_registry, only : add_tracer_diagnostics, add_tracer_obc_values
use mom_variables, only : surface
use mom_verticalgrid, only : verticalgrid_type

use coupler_util, only : set_coupler_values, ind_csurf
use atmos_ocean_fluxes_mod, only : aof_set_coupler_flux

implicit none ; private

#include <MOM_memory.h>

public user_register_tracer_example, user_initialize_tracer, user_tracer_stock
public tracer_column_physics, user_tracer_surface_state, user_tracer_example_end

! NTR is the number of tracers in this module.
integer, parameter :: ntr = 1

type p3d
  real, dimension(:,:,:), pointer :: p => null()
end type p3d

type, public :: user_tracer_example_cs ; private
  logical :: coupled_tracers = .false.  ! These tracers are not offered to the
                                        ! coupler.
  character(len=200) :: tracer_ic_file ! The full path to the IC file, or " "
                                   ! to initialize internally.
  type(time_type), pointer :: time ! A pointer to the ocean model's clock.
  type(tracer_registry_type), pointer :: tr_reg => null()
  real, pointer :: tr(:,:,:,:) => null()   ! The array of tracers used in this
                                           ! subroutine, in g m-3?
  real, pointer :: tr_aux(:,:,:,:) => null() ! The masked tracer concentration
                                             ! for output, in g m-3.
  type(p3d), dimension(NTR) :: &
    tr_adx, &! Tracer zonal advective fluxes in g m-3 m3 s-1.
    tr_ady, &! Tracer meridional advective fluxes in g m-3 m3 s-1.
    tr_dfx, &! Tracer zonal diffusive fluxes in g m-3 m3 s-1.
    tr_dfy   ! Tracer meridional diffusive fluxes in g m-3 m3 s-1.
  real :: land_val(ntr) = -1.0 ! The value of tr used where land is masked out.
  logical :: mask_tracers  ! If true, tracers are masked out in massless layers.
  logical :: use_sponge

  integer, dimension(NTR) :: ind_tr ! Indices returned by aof_set_coupler_flux
             ! if it is used and the surface tracer concentrations are to be
             ! provided to the coupler.

  type(diag_ctrl), pointer :: diag ! A pointer to a structure of shareable
                             ! ocean diagnostic fields and control variables.
  integer, dimension(NTR) :: id_tracer = -1, id_tr_adx = -1, id_tr_ady = -1
  integer, dimension(NTR) :: id_tr_dfx = -1, id_tr_dfy = -1

  type(vardesc) :: tr_desc(ntr)
end type user_tracer_example_cs

contains

function user_register_tracer_example(HI, GV, param_file, CS, tr_Reg, restart_CS)
  type(hor_index_type),    intent(in)   :: HI
  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(user_tracer_example_cs), pointer :: CS
  type(tracer_registry_type), pointer   :: tr_Reg
  type(mom_restart_cs),       pointer   :: restart_CS
! This subroutine is used to register tracer fields and subroutines
! to be used with MOM.
! 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.
  character(len=80)  :: name, longname
! This include declares and sets the variable "version".
#include "version_variable.h"
  character(len=40)  :: mdl = "tracer_example" ! This module's name.
  character(len=200) :: inputdir
  real, pointer :: tr_ptr(:,:,:) => null()
  logical :: USER_register_tracer_example
  integer :: isd, ied, jsd, jed, nz, m
  isd = hi%isd ; ied = hi%ied ; jsd = hi%jsd ; jed = hi%jed ; nz = gv%ke

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

  ! Read all relevant parameters and write them to the model log.
  call log_version(param_file, mdl, version, "")
  call get_param(param_file, mdl, "TRACER_EXAMPLE_IC_FILE", cs%tracer_IC_file, &
                 "The name of a file from which to read the initial \n"//&
                 "conditions for the DOME tracers, or blank to initialize \n"//&
                 "them internally.", default=" ")
  if (len_trim(cs%tracer_IC_file) >= 1) then
    call get_param(param_file, mdl, "INPUTDIR", inputdir, default=".")
    cs%tracer_IC_file = trim(slasher(inputdir))//trim(cs%tracer_IC_file)
    call log_param(param_file, mdl, "INPUTDIR/TRACER_EXAMPLE_IC_FILE", &
                   cs%tracer_IC_file)
  endif
  call get_param(param_file, mdl, "SPONGE", cs%use_sponge, &
                 "If true, sponges may be applied anywhere in the domain. \n"//&
                 "The exact location and properties of those sponges are \n"//&
                 "specified from MOM_initialization.F90.", default=.false.)

  allocate(cs%tr(isd:ied,jsd:jed,nz,ntr)) ; cs%tr(:,:,:,:) = 0.0
  if (cs%mask_tracers) then
    allocate(cs%tr_aux(isd:ied,jsd:jed,nz,ntr)) ; cs%tr_aux(:,:,:,:) = 0.0
  endif

  do m=1,ntr
    if (m < 10) then ; write(name,'("tr",I1.1)') m
    else ; write(name,'("tr",I2.2)') m ; endif
    write(longname,'("Concentration of Tracer ",I2.2)') m
    cs%tr_desc(m) = var_desc(name, units="kg kg-1", longname=longname, caller=mdl)

    ! This is needed to force the compiler not to do a copy in the registration
    ! calls.  Curses on the designers and implementers of Fortran90.
    tr_ptr => cs%tr(:,:,:,m)
    ! Register the tracer for the restart file.
    call register_restart_field(tr_ptr, cs%tr_desc(m), .true., restart_cs)
    ! Register the tracer for horizontal advection & diffusion.
    call register_tracer(tr_ptr, cs%tr_desc(m), param_file, hi, gv, tr_reg, &
                         tr_desc_ptr=cs%tr_desc(m))

    !   Set coupled_tracers to be true (hard-coded above) to provide the surface
    ! values to the coupler (if any).  This is meta-code and its arguments will
    ! currently (deliberately) give fatal errors if it is used.
    if (cs%coupled_tracers) &
      cs%ind_tr(m) = aof_set_coupler_flux(trim(name)//'_flux', &
          flux_type=' ', implementation=' ', caller="USER_register_tracer_example")
  enddo

  cs%tr_Reg => tr_reg
  user_register_tracer_example = .true.
end function user_register_tracer_example

subroutine user_initialize_tracer(restart, day, G, GV, h, diag, OBC, CS, &
                                  sponge_CSp, diag_to_Z_CSp)
  logical,                            intent(in) :: restart
  type(time_type), target,            intent(in) :: day
  type(ocean_grid_type),              intent(in) :: G    !< The ocean's grid structure
  type(verticalgrid_type),            intent(in) :: GV   !< The ocean's vertical grid structure
  real, dimension(SZI_(G),SZJ_(G),SZK_(G)), &
                                      intent(in) :: h    !< Layer thicknesses, in H (usually m or kg m-2)
  type(diag_ctrl), target,            intent(in) :: diag
  type(ocean_obc_type),               pointer    :: OBC
  type(user_tracer_example_cs),       pointer    :: CS
  type(sponge_cs),                    pointer    :: sponge_CSp
  type(diag_to_z_cs),                 pointer    :: diag_to_Z_CSp
!   This subroutine initializes the NTR tracer fields in tr(:,:,:,:)
! and it sets up the tracer output.

! Arguments: restart - .true. 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 or kg m-2.
!  (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/out)  CS - The control structure returned by a previous call to
!                 USER_register_tracer_example.
!  (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)  diag_to_Z_Csp - A pointer to the control structure for diagnostics
!                            in depth space.
  real, allocatable :: temp(:,:,:)
  real, pointer, dimension(:,:,:) :: &
    OBC_tr1_u => null(), & ! These arrays should be allocated and set to
    obc_tr1_v => null()    ! specify the values of tracer 1 that should come
                           ! in through u- and v- points through the open
                           ! boundary conditions, in the same units as tr.
  character(len=32) :: name     ! A variable's name in a NetCDF file.
  character(len=72) :: longname ! The long name of that variable.
  character(len=48) :: units    ! The dimensions of the variable.
  character(len=48) :: flux_units ! The units for tracer fluxes, usually
                            ! kg(tracer) kg(water)-1 m3 s-1 or kg(tracer) s-1.
  real, pointer :: tr_ptr(:,:,:) => null()
  real :: PI     ! 3.1415926... calculated as 4*atan(1)
  real :: tr_y   ! Initial zonally uniform tracer concentrations.
  real :: dist2  ! The distance squared from a line, in m2.
  integer :: i, j, k, is, ie, js, je, isd, ied, jsd, jed, nz, m
  integer :: IsdB, IedB, JsdB, JedB, lntr

  if (.not.associated(cs)) return
  is = g%isc ; ie = g%iec ; js = g%jsc ; je = g%jec ; nz = gv%ke
  isd = g%isd ; ied = g%ied ; jsd = g%jsd ; jed = g%jed
  isdb = g%IsdB ; iedb = g%IedB ; jsdb = g%JsdB ; jedb = g%JedB

  lntr = ntr ! Avoids compile-time warning when NTR<2
  cs%Time => day
  cs%diag => diag

  if (.not.restart) then
    if (len_trim(cs%tracer_IC_file) >= 1) then
!  Read the tracer concentrations from a netcdf file.
      if (.not.file_exists(cs%tracer_IC_file, g%Domain)) &
        call mom_error(fatal, "USER_initialize_tracer: Unable to open "// &
                        cs%tracer_IC_file)
      do m=1,ntr
        call query_vardesc(cs%tr_desc(m), name, caller="USER_initialize_tracer")
        call read_data(cs%tracer_IC_file, trim(name), &
                       cs%tr(:,:,:,m), domain=g%Domain%mpp_domain)
      enddo
    else
      do m=1,ntr
        do k=1,nz ; do j=js,je ; do i=is,ie
          cs%tr(i,j,k,m) = 1.0e-20 ! This could just as well be 0.
        enddo ; enddo ; enddo
      enddo

!    This sets a stripe of tracer across the basin.
      pi = 4.0*atan(1.0)
      do j=js,je
        dist2 = (g%Rad_Earth * pi / 180.0)**2 * &
               (g%geoLatT(i,j) - 40.0) * (g%geoLatT(i,j) - 40.0)
        tr_y = 0.5*exp(-dist2/(1.0e5*1.0e5))

        do k=1,nz ; do i=is,ie
!      This adds the stripes of tracer to every layer.
          cs%tr(i,j,k,1) = cs%tr(i,j,k,1) + tr_y
        enddo ; enddo
      enddo
    endif
  endif ! restart

  if ( cs%use_sponge ) then
!   If sponges are used, this example damps tracers in sponges in the
! northern half of the domain to 1 and tracers in the southern half
! to 0.  For any tracers that are not damped in the sponge, the call
! to set_up_sponge_field can simply be omitted.
    if (.not.associated(sponge_csp)) &
      call mom_error(fatal, "USER_initialize_tracer: "// &
        "The pointer to sponge_CSp must be associated if SPONGE is defined.")

    allocate(temp(g%isd:g%ied,g%jsd:g%jed,nz))
    do k=1,nz ; do j=js,je ; do i=is,ie
      if (g%geoLatT(i,j) > 700.0 .and. (k > nz/2)) then
        temp(i,j,k) = 1.0
      else
        temp(i,j,k) = 0.0
      endif
    enddo ; enddo ; enddo

!   do m=1,NTR
    do m=1,1
      ! This is needed to force the compiler not to do a copy in the sponge
      ! calls.  Curses on the designers and implementers of Fortran90.
      tr_ptr => cs%tr(:,:,:,m)
      call set_up_sponge_field(temp, tr_ptr, g, nz, sponge_csp)
    enddo
    deallocate(temp)
  endif

  if (associated(obc)) then
    call query_vardesc(cs%tr_desc(1), name, caller="USER_initialize_tracer")
    if (obc%specified_v_BCs_exist_globally) then
      allocate(obc_tr1_v(g%isd:g%ied,g%jsd:g%jed,nz))
      do k=1,nz ; do j=g%jsd,g%jed ; do i=g%isd,g%ied
        if (k < nz/2) then ; obc_tr1_v(i,j,k) = 0.0
        else ; obc_tr1_v(i,j,k) = 1.0 ; endif
      enddo ; enddo ; enddo
      call add_tracer_obc_values(trim(name), cs%tr_Reg, &
                                 0.0, obc_in_v=obc_tr1_v)
    else
      ! This is not expected in the DOME example.
      call add_tracer_obc_values(trim(name), cs%tr_Reg, 0.0)
    endif
    ! All tracers but the first have 0 concentration in their inflows. As this
    ! is the default value, the following calls are unnecessary.
    do m=2,lntr
      call query_vardesc(cs%tr_desc(m), name, caller="USER_initialize_tracer")
      call add_tracer_obc_values(trim(name), cs%tr_Reg, 0.0)
    enddo
  endif

  ! This needs to be changed if the units of tracer are changed above.
  if (gv%Boussinesq) then ; flux_units = "kg kg-1 m3 s-1"
  else ; flux_units = "kg s-1" ; endif

  do m=1,ntr
    ! Register the tracer for the restart file.
    call query_vardesc(cs%tr_desc(m), name, units=units, longname=longname, &
                       caller="USER_initialize_tracer")
    cs%id_tracer(m) = register_diag_field("ocean_model", trim(name), cs%diag%axesTL, &
        day, trim(longname) , trim(units))
    cs%id_tr_adx(m) = register_diag_field("ocean_model", trim(name)//"_adx", &
        cs%diag%axesCuL, day, trim(longname)//" advective zonal flux" , &
        trim(flux_units))
    cs%id_tr_ady(m) = register_diag_field("ocean_model", trim(name)//"_ady", &
        cs%diag%axesCvL, day, trim(longname)//" advective meridional flux" , &
        trim(flux_units))
    cs%id_tr_dfx(m) = register_diag_field("ocean_model", trim(name)//"_dfx", &
        cs%diag%axesCuL, day, trim(longname)//" diffusive zonal flux" , &
        trim(flux_units))
    cs%id_tr_dfy(m) = register_diag_field("ocean_model", trim(name)//"_dfy", &
        cs%diag%axesCvL, day, trim(longname)//" diffusive zonal flux" , &
        trim(flux_units))
    if (cs%id_tr_adx(m) > 0) call safe_alloc_ptr(cs%tr_adx(m)%p,isdb,iedb,jsd,jed,nz)
    if (cs%id_tr_ady(m) > 0) call safe_alloc_ptr(cs%tr_ady(m)%p,isd,ied,jsdb,jedb,nz)
    if (cs%id_tr_dfx(m) > 0) call safe_alloc_ptr(cs%tr_dfx(m)%p,isdb,iedb,jsd,jed,nz)
    if (cs%id_tr_dfy(m) > 0) call safe_alloc_ptr(cs%tr_dfy(m)%p,isd,ied,jsdb,jedb,nz)

!    Register the tracer for horizontal advection & diffusion.
    if ((cs%id_tr_adx(m) > 0) .or. (cs%id_tr_ady(m) > 0) .or. &
        (cs%id_tr_dfx(m) > 0) .or. (cs%id_tr_dfy(m) > 0)) &
      call add_tracer_diagnostics(name, cs%tr_Reg, cs%tr_adx(m)%p, &
                                  cs%tr_ady(m)%p,cs%tr_dfx(m)%p,cs%tr_dfy(m)%p)

    call register_z_tracer(cs%tr(:,:,:,m), trim(name), longname, units, &
                           day, g, diag_to_z_csp)
  enddo

end subroutine user_initialize_tracer

subroutine tracer_column_physics(h_old, h_new,  ea,  eb, fluxes, dt, G, GV, CS)
  type(ocean_grid_type),              intent(in) :: G    !< The ocean's grid structure
  type(verticalgrid_type),            intent(in) :: GV   !< The ocean's vertical grid structure
  real, dimension(SZI_(G),SZJ_(G),SZK_(G)), intent(in) :: h_old, h_new, ea, eb
  type(forcing),                      intent(in) :: fluxes
  real,                               intent(in) :: dt   !< The amount of time covered by this call, in s
  type(user_tracer_example_cs),       pointer    :: CS
!   This subroutine applies diapycnal diffusion and any other column
! tracer physics or chemistry to the tracers from this file.
! This is a simple example of a set of advected passive tracers.

! Arguments: h_old -  Layer thickness before entrainment, in m or kg m-2.
!  (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.
!  (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.
!  (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)      CS - The control structure returned by a previous call to
!                 USER_register_tracer_example.
!
! The arguments to this subroutine are redundant in that
!     h_new[k] = h_old[k] + ea[k] - eb[k-1] + eb[k] - ea[k+1]

  real :: hold0(szi_(g))       ! The original topmost layer thickness,
                               ! with surface mass fluxes added back, m.
  real :: b1(szi_(g))          ! b1 and c1 are variables used by the
  real :: c1(szi_(g),szk_(g))  ! tridiagonal solver.
  real :: d1(szi_(g))          ! d1=1-c1 is used by the tridiagonal solver.
  real :: h_neglect            ! A thickness that is so small it is usually lost
                               ! in roundoff and can be neglected, in m.
  real :: b_denom_1 ! The first term in the denominator of b1, in m or kg m-2.
  integer :: i, j, k, is, ie, js, je, nz, m

! The following array (trdc) determines the behavior of the tracer
! diapycnal advection.  The first element is 1 if tracers are
! passively advected.  The second and third are the concentrations
! to which downwelling and upwelling water are set, respectively.
! For most (normal) tracers, the appropriate vales are {1,0,0}.

  real :: trdc(3)
!   Uncomment the following line to dye both upwelling and downwelling.
! data trdc / 0.0,1.0,1.0 /
!   Uncomment the following line to dye downwelling.
! data trdc / 0.0,1.0,0.0 /
!   Uncomment the following line to dye upwelling.
! data trdc / 0.0,0.0,1.0 /
!   Uncomment the following line for tracer concentrations to be set
! to zero in any diapycnal motions.
! data trdc / 0.0,0.0,0.0 /
!   Uncomment the following line for most "physical" tracers, which
! are advected diapycnally in the usual manner.
  data trdc / 1.0,0.0,0.0 /
  is = g%isc ; ie = g%iec ; js = g%jsc ; je = g%jec ; nz = gv%ke

  if (.not.associated(cs)) return
  h_neglect = gv%H_subroundoff

  do j=js,je
    do i=is,ie
!   The following line is appropriate for quantities like salinity
! that are left behind by evaporation, and any surface fluxes would
! be explicitly included in the flux structure.
      hold0(i) = h_old(i,j,1)
!   The following line is appropriate for quantities like temperature
! that can be assumed to have the same concentration in evaporation
! as they had in the water.  The explicit surface fluxes here would
! reflect differences in concentration from the ambient water, not
! the absolute fluxes.
  !   hold0(i) = h_old(i,j,1) + ea(i,j,1)
      b_denom_1 = h_old(i,j,1) + ea(i,j,1) + h_neglect
      b1(i) = 1.0 / (b_denom_1 + eb(i,j,1))
!       d1(i) = b_denom_1 * b1(i)
      d1(i) = trdc(1) * (b_denom_1 * b1(i)) + (1.0 - trdc(1))
      do m=1,ntr
        cs%tr(i,j,1,m) = b1(i)*(hold0(i)*cs%tr(i,j,1,m) + trdc(3)*eb(i,j,1))
 !      Add any surface tracer fluxes to the preceding line.
      enddo
    enddo
    do k=2,nz ; do i=is,ie
      c1(i,k) = trdc(1) * eb(i,j,k-1) * b1(i)
      b_denom_1 = h_old(i,j,k) + d1(i)*ea(i,j,k) + h_neglect
      b1(i) = 1.0 / (b_denom_1 + eb(i,j,k))
      d1(i) = trdc(1) * (b_denom_1 * b1(i)) + (1.0 - trdc(1))
      do m=1,ntr
        cs%tr(i,j,k,m) = b1(i) * (h_old(i,j,k)*cs%tr(i,j,k,m) + &
                 ea(i,j,k)*(trdc(1)*cs%tr(i,j,k-1,m)+trdc(2)) + &
                 eb(i,j,k)*trdc(3))
      enddo
    enddo ; enddo
    do m=1,ntr ; do k=nz-1,1,-1 ; do i=is,ie
      cs%tr(i,j,k,m) = cs%tr(i,j,k,m) + c1(i,k+1)*cs%tr(i,j,k+1,m)
    enddo ; enddo ; enddo
  enddo

  if (cs%mask_tracers) then
    do m = 1,ntr ; if (cs%id_tracer(m) > 0) then
      do k=1,nz ; do j=js,je ; do i=is,ie
        if (h_new(i,j,k) < 1.1*gv%Angstrom) then
          cs%tr_aux(i,j,k,m) = cs%land_val(m)
        else
          cs%tr_aux(i,j,k,m) = cs%tr(i,j,k,m)
        endif
      enddo ; enddo ; enddo
    endif ; enddo
  endif

  do m=1,ntr
    if (cs%mask_tracers) then
      if (cs%id_tracer(m)>0) &
        call post_data(cs%id_tracer(m),cs%tr_aux(:,:,:,m),cs%diag)
    else
      if (cs%id_tracer(m)>0) &
        call post_data(cs%id_tracer(m),cs%tr(:,:,:,m),cs%diag)
    endif
    if (cs%id_tr_adx(m)>0) &
      call post_data(cs%id_tr_adx(m),cs%tr_adx(m)%p(:,:,:),cs%diag)
    if (cs%id_tr_ady(m)>0) &
      call post_data(cs%id_tr_ady(m),cs%tr_ady(m)%p(:,:,:),cs%diag)
    if (cs%id_tr_dfx(m)>0) &
      call post_data(cs%id_tr_dfx(m),cs%tr_dfx(m)%p(:,:,:),cs%diag)
    if (cs%id_tr_dfy(m)>0) &
      call post_data(cs%id_tr_dfy(m),cs%tr_dfy(m)%p(:,:,:),cs%diag)
  enddo

end subroutine tracer_column_physics

function user_tracer_stock(h, stocks, G, GV, CS, names, units, stock_index)
  type(ocean_grid_type),              intent(in)    :: G    !< The ocean's grid structure
  type(verticalgrid_type),            intent(in)    :: GV   !< The ocean's vertical grid structure
  real, dimension(SZI_(G),SZJ_(G),SZK_(G)), &
                                      intent(in)    :: h    !< Layer thicknesses, in H (usually m or kg m-2)
  real, dimension(:),                 intent(out)   :: stocks
  type(user_tracer_example_cs),       pointer       :: CS
  character(len=*), dimension(:),     intent(out)   :: names
  character(len=*), dimension(:),     intent(out)   :: units
  integer, optional,                  intent(in)    :: stock_index
  integer                                           :: USER_tracer_stock
! This function calculates the mass-weighted integral of all tracer stocks,
! returning the number of stocks it has calculated.  If the stock_index
! is present, only the stock corresponding to that coded index is returned.

! Arguments: h - Layer thickness, in m or kg m-2.
!  (out)     stocks - the mass-weighted integrated amount of each tracer,
!                     in kg times concentration units.
!  (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
!                 register_USER_tracer.
!  (out)     names - the names of the stocks calculated.
!  (out)     units - the units of the stocks calculated.
!  (in,opt)  stock_index - the coded index of a specific stock being sought.
! Return value: the number of stocks calculated here.

  integer :: i, j, k, is, ie, js, je, nz, m
  is = g%isc ; ie = g%iec ; js = g%jsc ; je = g%jec ; nz = gv%ke

  user_tracer_stock = 0
  if (.not.associated(cs)) return

  if (present(stock_index)) then ; if (stock_index > 0) then
    ! Check whether this stock is available from this routine.

    ! No stocks from this routine are being checked yet.  Return 0.
    return
  endif ; endif

  do m=1,ntr
    call query_vardesc(cs%tr_desc(m), name=names(m), units=units(m), caller="USER_tracer_stock")
    units(m) = trim(units(m))//" kg"
    stocks(m) = 0.0
    do k=1,nz ; do j=js,je ; do i=is,ie
      stocks(m) = stocks(m) + cs%tr(i,j,k,m) * &
                             (g%mask2dT(i,j) * g%areaT(i,j) * h(i,j,k))
    enddo ; enddo ; enddo
    stocks(m) = gv%H_to_kg_m2 * stocks(m)
  enddo
  user_tracer_stock = ntr

end function user_tracer_stock

subroutine user_tracer_surface_state(state, h, G, CS)
  type(ocean_grid_type),              intent(in)    :: G    !< The ocean's grid structure
  type(surface),                      intent(inout) :: state
  real, dimension(SZI_(G),SZJ_(G),SZK_(G)), intent(in)    :: h    !< Layer thicknesses, in H (usually m or kg m-2)
  type(user_tracer_example_cs),       pointer       :: CS
!   This particular tracer package does not report anything back to the coupler.
! The code that is here is just a rough guide for packages that would.
! Arguments: state - A structure containing fields that describe the
!                    surface state of the ocean.
!  (in)      h - Layer thickness, in m or kg m-2.
!  (in)      G - The ocean's grid structure.
!  (in)      CS - The control structure returned by a previous call to
!                 register_USER_tracer.
  integer :: i, j, m, is, ie, js, je
  is = g%isc ; ie = g%iec ; js = g%jsc ; je = g%jec

  if (.not.associated(cs)) return

  if (cs%coupled_tracers) then
    do m=1,ntr
      !   This call loads the surface vlues into the appropriate array in the
      ! coupler-type structure.
      call set_coupler_values(cs%tr(:,:,1,1), state%tr_fields, cs%ind_tr(m), &
                              ind_csurf, is, ie, js, je)
    enddo
  endif

end subroutine user_tracer_surface_state

subroutine user_tracer_example_end(CS)
  type(user_tracer_example_cs), pointer :: CS
  integer :: m

  if (associated(cs)) then
    if (associated(cs%tr)) deallocate(cs%tr)
    if (associated(cs%tr_aux)) deallocate(cs%tr_aux)
    do m=1,ntr
      if (associated(cs%tr_adx(m)%p)) deallocate(cs%tr_adx(m)%p)
      if (associated(cs%tr_ady(m)%p)) deallocate(cs%tr_ady(m)%p)
      if (associated(cs%tr_dfx(m)%p)) deallocate(cs%tr_dfx(m)%p)
      if (associated(cs%tr_dfy(m)%p)) deallocate(cs%tr_dfy(m)%p)
    enddo

    deallocate(cs)
  endif
end subroutine user_tracer_example_end

end module user_tracer_example