VERY IMPORTANT: replaced UV_PSOURCE, Q_PSOURSE, and TS_PSOURCE with logical switches

[arango]

This ticket includes very important updates to the repository:

• The CPP options UP_PSOURCE, Q_PSOURCE and TS_PSOURCE used to activate point Sources and Sinks for momentum and tracers were eliminated and replaced with logical switches (LuvSrc, LwSrc, and LtracerSrc, respectively) to facilitate nesting, specially refinement grids in applications with river runoff. These logical switches are set-up in ocean.in:

  ! Logical switches (TRUE/FALSE) to activate horizontal momentum transport
  ! point Sources/Sinks (like river runoff transport) and mass point
  ! Sources/Sinks (like volume vertical influx), [1:Ngrids].
  
        LuvSrc == F                          ! horizontal momentum transport
         LwSrc == F                          ! volume vertical influx
  
  ! Logical switches (TRUE/FALSE) to activate tracers point Sources/Sinks
  ! (like river runoff) and to specify which tracer variables to consider:
  ! [1:NAT+NPT,Ngrids].
  ! See glossary below for details.
  
    LtracerSrc == F F                        ! temperature, salinity, inert
  

  In nesting applications, turn on only the grids that needs point Sources and/or Sinks. A particular nesting grid may or may not have Sources and/or Sinks forcing. This change is required to get the correct results in nesting applications!

• The Sources and/or Sinks input NetCDF forcing file (like river runoff) is now specified with its own keyword in ocean.in:

  ! Input Sources/Sinks forcing (like river runoff) file name.
  
       SSFNAME == ocean_rivers.nc
  

  That is, the river runoff forcing file is separated from the regular forcing file list (see FRCNAME in ocean.in) to allow manipulations over nested grids and facilitate internal processing in ROMS.

• For example, in an application with 3 nested grids but with river forcing in grids 1 and 3 we would have:

                       LuvSrc == T F T
                        LwSrc == F F F
                   LtracerSrc == 2*T 2*F 2*T
  ...
                      SSFNAME == my_rivers_grid1.nc \
                                 my_rivers_grid2.nc \
                                 my_rivers_grid3.nc
  

  Here, my_rivers_grid2.nc is a dummy file name that will never be processed in ROMS because of the logical switches are FALSE for the second grid.

WARNING: You need to remove the UV_PSOURCE, TS_PSOURCE or Q_PSOURCE from the header file or build script. Otherwise, ROMS will give you an error and will stop running. This is to force you to make the appropriate change in your ocean.in and configuration.

• The switch LuvSrc has the same capability than the obsolete option UV_PSOURCE. Usually, it is used to specify river runoff horizontal transport in the 2D and 3D momentum equations at the specified (Isrc,Jsrc) locations as a point Source/Sink. That is, the values of the computed horizontal momentum (ubar, vbar, u, or v) will be replaced with the specified values (computed from input transport Qsrc) according to the direction of the Source/Sink point, Dsrc. Hence, the setting of the Isrc and Jsrc is crucial in your forcing file.

• The switch LwSrc has the same capability than the obsolete option Q_PSOURCE. Usually, it is used to specify a vertical mass influx in the W-momentum (omega) equation at the specified (Isrc,Jsrc) locations as a point Source/Sink. This is operated on the divergence of the 3D continuity equation and vertical advection. It does not input horizontal momentum to the (Isrc,Jsrc) cell but it changes its volume. Currently, we cannot activate LuvSrc and LwSrc at the same time because it uses the same fields from the input river forcing NetCDF file. I will think about how to allow both switches in the future. Anyway, in mostly all applications we will be using LuvSrc.

• The switch LtracerSrc has the same capability as before (​src:ticket:376). In addition, it is used to replace obsolete option TS_PSOURCE. Usually, it is used to specify point Sources/Sinks in the tracer equations at the specified (Isrc,Jsrc) locations. If LwSrc is off, the tracer Source/Sink is applied to the tracer horizontal advective fluxes. If LwSrc is on, the tracer Source/Sink is is applied to the tracer vertical advective flux.

In river forcing, we need to apply tracer point sources to both temperature and salinity. As before, if you want to add other tracer variables (other than temperature and salinity) as a source for a particular river(s), you just need to specify such values on those river(s). Then, set the values to ZERO on the other river(s) that do not require such river forcing for that tracer. Recall that you need to specify the tracer values for all rivers, even if their values are zero.

---

• Corrected a bug that I introduced recently in ad_rho_eos.F, tl_rho_eos.F, and rp_rho_eos.F when adding the potential density pden (see ​src:tricket:612). This was giving a fatal algorithm result message in 4D-Var when POSTERIOR_EOFS or POSTERIOR_ERROR_I was activated. This one is kind of mysterious but it seems that the symmetry properties or the posterior error covariance was affected. We would look at the causes for this since pden will be used in the future for horizontal mixing.

• Corrected a bug in routine error_covariance (convolve.F) when ADJUST_STFLUX and/or ADJUST_WSTRESS is turned off in the 4D-Var algorithms. Many thanks to Julia Levin for bringing this to my attention.

• Corrected a bug in mod_ncparam.F when initializing ANANAME. This bug was introcuded recently in ​src:ticket:609. Many thanks to Mark Hadfield for ​bringing this to my attention.

---

The nesting algorithms seem to be working well for one-way nesting in refinement applications. We have complex refinement applications in the South China Sea and the Gulf of Mexico running successfully when ONE_WAY is activated. These applications include both tides and river forcing. I will add some figures soon to the ROMS forum. The two-way nesting set-up runs but it creates noise at the contact boundary. I either have a bug in routine fine2coarse, a logic error in coarse grid contact point inside the refined grid, or some fancy filtering is required when averaging the finer grid solution at the coarse grid locations.

Anyway, I am pleased with my progress in the nesting algorithms. It is nice to run complex coastal applications and avoid the messy lateral boundary conditions. The nesting algorithms are quite complex due to the ambitious capabilities. I hope that have two-way nesting working soon.