Move some parts of btstep() into subroutines (#845)

* Move some parts of btstep() into subroutines

The short description of each routine is:
btstep_ubt_from_layer: Calculate the zonal and meridional velocity from the 3-D velocity.
btstep_find_Cor: Find the Coriolis force terms _zon and _mer.
btloop_setup: Set ubt, vbt, eta, find face areas, and set valid array size at the beginning of each barotropic loop.
btloop_setup_eta: A routine to set eta_pred and the running time integral of uhbt and vhbt.
btloop_setup_OBCs: Setup old or previous ubt, vbt, vbt, and vhbt for different OBC options before the next step in the btstep loop.
btloop_update_v:  Update meridional velocity.
btloop_update_u: Update zonal velocity.
btstep_layer_accel:  Calculate the zonal and meridional acceleration of each layer due to the barotropic calculation.

* Address issues with modularize btstep

  This commit builds upon the recent refactoring of MOM_barotropic.F90 by
correcting the openMP directives, dealing with use_old_coriolis_bracket_bug via
an optional argument to to btloop_update_v, simplifying what is done in
btstep_ubt_from_layer, restoring parentheses to btstep_layer_accel that are
needed for rotational symmetry with FMAs enabled and adding doxygen comments
describing several arguments.  All answers are bitwise identical.

* Replace btloop_setup with truncate_velocities

  Replaced btloop_setup with truncate_velocities and moved the halo updates
that had been in btloop_setup out of this routine, making it more functionally
targeted.  Also replaced the index range arguments to btloop_update_u and
btloop_update_v to simply pass the ranges that are used rather than having to
reconstruct them inside these routines.

  Doxygen comments were added to describe several arguments to the newly added
routines, and several comments were also added describing what the various calls
within btstep do.  All answers are bitwise identical.

* Replace btloop_setup_OBCs with store_u_for_OBCs

  Replace btloop_setup_OBCs with store_u_for_OBCS and store_v_for_OBCs for more
functional targeting and simpler routines.  Also because ubt_old and ubt_prev
were copies of the same thing, ubt_old is no longer used in btstep while
ubt_prev is set over a slightly larger loop range in store_u_for_OBCs, and
similarly for vbt_old and vbt_prev.  All answers are bitwise identical.

* Add separate doxygen comments in MOM_barotropic

  Added doxygen comments to describe all individual arguments, rather than
documenting them in groups, which should correct the previous problems with
failing testing.  Also avoided using a separate variables wt_accel_n and
wt_accel2_n in btstep.  All answers are bitwise identical.

* Change name of btloop_setup_eta

Change name of new routine btloop_setup_eta to btloop_eta_predictor.

---------

Co-authored-by: Theresa Morrison <Theresa.Morrison@gaea68.ncrc.gov>
Co-authored-by: Robert Hallberg <Robert.Hallberg@noaa.gov>
Co-authored-by: Theresa Morrison <Theresa.Morrison@gaea61.ncrc.gov>

Author: 4 people