VERY IMPORTANT, Please READ: Overhaul of sponges, climatology, and nudging

[arango]

This is a very important update. It includes changes on how sponge areas are specified. A sponge is an area of increased horizontal viscosity and/or diffusivity. It also includes changes to the processing of climatology fields and nudging of climatology fields. These changes are made to activate or not such capabilities during nesting over multiple grids. Several C-preprocessing options are eliminated and replaced with logical switches that read from standard input ocean.in and, if appropriate, from biology and sediment input scripts.

---

• Sponge areas: The CPP option SPONGE is eliminated and replaced with logical switches LuvSponge and LtracerSponge, which are set in input script ocean.in:

  ! Logical switches (TRUE/FALSE) to increase/decrease horizontal viscosity
  ! and/or diffusivity in specific areas of the application domain (like
  ! sponge areas) for the desired application grid.
  
      LuvSponge == F                              ! horizontal momentum
  LtracerSponge == F F                            ! temperature, salinity, inert
  

  LuvSponge are logical switches to increase/decrease the horizontal viscosity in specific areas of the domain for a particular grid. It can be used to set sponge areas with larger viscosity coefficients for the damping of high frequency noise due to open boundary conditions or nesting. The horizontal viscosity distribution is set in ini_hmixcoef.F as, if UV_VIS2 or UV_VIS4 are activated:

                    visc2_r(i,j) = visc_factor(i,j) * visc2_r(i,j)
                    visc4_r(i,j) = visc_factor(i,j) * visc4_r(i,j)
  

  The new variable visc_factor can be read from the application GRID NetCDF file. Alternatively, the horizontal viscosity in the sponge area can be set-up with analytical functions in the new header file ana_sponge.h using new CPP option ANA_SPONGE when the switch LuvSponge is turned ON for a particular grid. Check the examples in ana_sponge.h to see how this is done. However, I highly recommend users to add the variable visc_factor to their GRID NetCDF file to facilitate complex sponges and avoid parallel coding errors:

        double visc_factor(eta_rho, xi_rho) ;
                visc_factor:long_name = "horizontal viscosity sponge factor" ;
                visc_factor:valid_min = 0. ;
                visc_factor:coordinates = "lon_rho lat_rho" ;
  

  Users may use new Matlab script add_sponge.m to append the sponge variables to their application GRID NetCDF file. Notice that you can easily plot their values to verify the desired distribution. The values of visc_factor must be positive and defined at RHO-points. Usually their values are linearly tapered from one or zero at the inner sponge edge (interior points) to the desired maximum factor (>1) at the outer sponge edge (like domain perimeter). If a factor of zero is set over the interior points, the viscosity will be turned OFF over such points. Contrarily if a factor of one is set over the interior points, the viscosity will be that set in ocean.in (visc2/visc4) and post-processed in ini_hmixcoef.F (if scaled by grid size with VISC_GRID).

LtracerSponge are logical switches to increase/decrease the horizontal diffusivity in specific areas of the domain for a particular tracer and grid. It can be used to set sponge areas with larger diffusivity coefficients for the desired tracer(s) in order to damp high frequency noise due to open boundary conditions or nesting. The switches for biological and sediment tracer are specified in their respective input scripts. The horizontal diffusivity distribution is set in ini_hmixcoef.F as, if TS_DIF2 or TS_DIF4 are activated:

                  diff2(i,j,itrc) = diff_factor(i,j) * diff2(i,j,itrc)
                  diff4(i,j,itrc) = diff_factor(i,j) * diff4(i,j,itrc)

The new variable diff_factor can be read from the application GRID NetCDF file. Alternatively, the horizontal diffusivity in the sponge area can be set-up with analytical functions in the new header file ana_sponge.h using new CPP option ANA_SPONGE when the switches LtracerSponge are turned ON for a particular tracer and grid. Notice that the diff_factor is the same for all active and passive tracers. Check the examples in ana_sponge.h to see how this is done. However, I highly recommend users to add the variable diff_factor to their GRID NetCDF file to facilitate complex sponges and avoid parallel coding errors:

      double diff_factor(eta_rho, xi_rho) ;
              diff_factor:long_name = "horizontal diffusivity sponge factor" ;
              diff_factor:valid_min = 0. ;
              diff_factor:coordinates = "lon_rho lat_rho" ;

Again, users may use new Matlab script add_sponge.m to append the sponge variables to their application GRID NetCDF file. Notice that you can easily plot their values to verify the desired distribution. The values of diff_factor must be positive and defined at RHO-points. Usually their values are linearly tapered from one or zero at the inner sponge edge (interior points) to the desired maximum factor (>1) at the outer sponge edge (like domain perimeter). If a factor of zero is set over the interior points, the viscosity will be turned OFF over such points. Contrarily if a factor of one is set over the interior points, the diffusivity will be that set in ocean.in and passive models (biology, sediment) input scripts (tnu2/tnu4) and post-processed in ini_hmixcoef.F (if scaled by grid size with DIFF_GRID).

---

• Climatology Fields: The CPP options ZCLIMATOLOGY, M2CLIMATOLOGY, M3CLIMATOLOGY, and TCLIMATOLOGY used to process climatology fields are eliminated and replaced with logical switches LsshCLM, Lm2CLM, Lm3CLM, and LtracerCLM, respectively. They are set in input script ocean.in:

  ! Logical switches (TRUE/FALSE) to read and process climatology fields.
  ! See glossary below for details.
  
       LsshCLM == F                          ! sea-surface height
        Lm2CLM == F                          ! 2D momentum
        Lm3CLM == F                          ! 3D momentum
  
    LtracerCLM == F F                        ! temperature, salinity, inert
  

  The switches for the biological and sediment tracers are specified in their respective input scripts. These climatology processing switches are either used to read climatology from a NetCDF file or to set their values with analytical functions. The climatology fields can be used for open boundary conditions, nudging in sponge areas, nudging relaxation terms, and horizontal mixing (tracers only).

The sea-surface height (SSH) climatology. CLIMA(ng)%ssh, is not used but it is kept for future use. The nudging of SSH on the free-surface governing equation (vertically integrated continuity equation) is not allowed because it violates mass/volume conservation. Recall that the time rate of change of free-surface is computed from the divergence of ubar and vbar. If such nudging term is required, it needs to be specified on the momentum equations for (u,v) and/or (ubar,vbar). If done on (u,v) only, its effects enter the 2D momentum equations via the residual vertically integrated forcing term.

The LtracerCLM switches determine which trace to process and the size of the fourth dimension of CLIMA(ng)%tclm. It is only dimensioned to the number of tracers to process, NTCLM(ng), in order to reduce memory usage. An internal counter, ic, is used in the code to use the correct tracer:

    ic=0
    DO itrc=1,NT(ng)
       IF (LtracerCLM(itrc,ng).and.LnudgeTCLM(itrc,ng)) THEN
         ic=ic+1
         DO k=1,N(ng)
           DO j=JstrR,JendR
             DO i=IstrR,IendR
               t(i,j,k,nnew,itrc)=t(i,j,k,nnew,itrc)+                  &
    &                             dt(ng)*                              &
    &                             CLIMA(ng)%Tnudgcof(i,j,k,ic)*        &
    &                             (CLIMA(ng)%tclm(i,j,k,ic)-           &
    &                              t(i,j,k,nnew,itrc))
             END DO
           END DO
         END DO
       END IF
     END DO

---

• Nudging: The nudging to climatology CPP options M2CLM_NUDGING, M3CLM_NUDGING, TCLM_NUDGING are eliminated and replaced with logical switches LnudgeM2CLM, LnudgeM3CLM, and LnudgeTCLM, respectively. They are set in input script ocean.in:

  ! Logical switches (TRUE/FALSE) to nudge the desired climatology field(s).
  ! If not analytical climatology fields, users need to turn ON the logical
  ! switches above to process the fields from the climatology NetCDF file
  ! that are needed for nudging. See glossary below for details.
  
   LnudgeM2CLM == F                          ! 2D momentum
   LnudgeM3CLM == F                          ! 3D momentum
  
    LnudgeTCLM == F F                        ! temperature, salinity, inert