= ''ENHANCE-12_SimonM-Tides''

Last edition: '''[[Wikinfo(changed_ts)]]''' by '''[[Wikinfo(changed_by)]]'''

The PI is responsible to closely follow the progress of the action, and especially to contact NEMO project manager if the delay on preview (or review) are longer than the 2 weeks expected.

[[PageOutline(2-3, , inline)]]

== Summary

This action aims to enhance the implementation of tidal forcing with the addition of an optional, alternative parameter set for the harmonic expansion of the tide potential and by converting a currently fixed coefficient into a configurable namelist parameter; this work has previously been implemented and tested by Nicolas Bruneau in a pre-4.0beta version of NEMO.

Further, this action aims to reduce the total number of modules related to tides (the current implementation comprises the modules sbctide, tideini, tide_mod, updtide, and bdytide) and to thereby somewhat simplify the current implementation of tidal forcing.

See ticket #2194.

== Preview 

=== Current implementation of tidal forcing

The current implementation of tide-related functionality is distributed across a number of files and there are intertwined dependencies across the tide-related modules. The current implementation of tidal forcing (tidal potential and forcing at open boundaries) comprises five modules (in separate files):

 * module `sbctide` (source:/NEMO/trunk/src/OCE/SBC/sbctide.F90),
 * module `tideini` (source:/NEMO/trunk/src/OCE/SBC/tideini.F90),
 * module `tide_mod` (source:/NEMO/trunk/src/OCE/SBC/tide_mod.F90),
 * module `updtide` (source:/NEMO/trunk/src/OCE/SBC/updtide.F90), and
 * module `bdytides` (source:/NEMO/trunk/src/OCE/BDY/bdytides.F90).

In addition, the parameters for the current set of selectable tidal constituents are supplied via an include file (source:/NEMO/trunk/src/OCE/SBC/tide.h90). Further, the computation of the surface pressure gradient (source:/NEMO/trunk/src/OCE/DYN/dynspg.F90 and source:NEMO/trunk/src/OCE/DYN/dynspg_ts.F90) with activated tidal potential as well as the harmonic analysis (module `diaharm`, source:/NEMO/trunk/src/OCE/DIA/diaharm.F90) call subroutines and access variables of the modules listed above.

=== Proposed addition of an alternative set of tidal component parameters

The proposed revision of the tidal-forcing functionality of NEMO allows for the possibility to apply tidal boundary conditions that are derived from the [https://www.aviso.altimetry.fr/en/data/products/auxiliary-products/global-tide-fes.html FES2014 version of the Global Tide FES data product], which provides tide elevations, currents and loadings for 34 tidal components (https://www.aviso.altimetry.fr/en/data/products/auxiliary-products/global-tide-fes.html). It includes the addition of an alternative tidal-component parameter set that extends the currently available set of tidal components (19 components; source:/NEMO/trunk/src/OCE/SBC/tide.h90) to correspond to the full range of components available in the FES2014 data product.

The coefficients for the proposed new parameter set have already been compiled, and the coefficients relating to the equilibrium tide amplitudes of all components (including those of the 19 components available in the current model version) have newly been recomputed in a form that is compatible with the conventions used for the existing tidal forcing implementation.

Further, the proposed revision adds long-periodic components (if selected) to the tide potential that currently only comprises the selected diurnal and semidiurnal components.

For reproducibility of the current tidal forcing, a new namelist parameter, `ln_tide_var`, is proposed to permit the combined selection of tidal parameter set and variant of tide-potential computation; the proposed default is the revised parameter set and the inclusion of long-periodic tides in the tide-potential computation.

=== Proposed combination of tide-related functionality into one module in a new source-code subdirectory `OCE/TDE`

The basis of the proposed simplified and clarified tidal-forcing implementation is:

* the relocation of module `tide_mod` (source:/NEMO/trunk/src/OCE/SBC/tide_mod.F90) from the `SBC` subdirectory to a newly created `TDE` subdirectory;

* the merging of most of the current tide-related functionality from modules `sbctide`, `tideini`, and `updtide` into module `tide_mod`; and

* the provision of an appropriate public interface in module `tide_mod` for access to module subroutines and data as required by other modules (`sbctide`, `dynspg`, `dynspg_ts`, `bdytides`, `diaharm`).

Further, specific proposed modifications of the tide-related code include:

 a. the addition of a new namelist parameter `rn_love_number` with a default value of 0.7 that replaces the hard-coded Love-number coefficient in subroutine `tide_init_potential` (currently in module `sbctide`);

 b. the renaming of the current namelist parameters that violate the namelist parameter naming convention (renaming of parameters `rndttideramp` and `clname` to `rn_tide_ramp_dt` and `sn_tide_cnames`, respectively);

 c. the replacement of the array `Wave` that contains parameters for all available tidal components by an array (`tide_components`) that is returned by a new reentrant initialisation subroutine (`tide_init_components`) and only contains the parameters for the selected components, thereby enabling the reading in of alternative tidal parameter databases with differing numbers of components, simplifying the implementation (the subsetting of the database using an array of selected indices, `ntide`, would no longer be required), and making it possible to reuse the initialisation subroutine (e.g., it can be used when a subroutine of module `diaharm` requests a list of harmonics parameters for a specific subset of tidal components, see item e below);

 d. the simplification of the internal representation of amplitudes, frequencies, and phases of the selected tidal components in the new public array `tide_harmonics` (for internal use as well as for external access of tidal harmonics information by module `bdytides`) that contains variables of a new type `tide_harmonic`,

{{{#!f
   TYPE, PUBLIC :: tide_harmonic
      CHARACTER(LEN=4) :: name
      REAL(wp) :: f
      REAL(wp) :: omega
      REAL(wp) :: u
      REAL(wp) :: v
   END TYPE tide_harmonic,
}}}

 and which replaces the arrays `omega_tide`, `v0tide`, `utide`, `ftide` (and additionally stores the names of the components; this feature would be used by subroutine `tide_harmo`, see item e, and module `bdytides`, see item i);

 e. the extension of subroutine `tide_harmo` of module `tide_mod` so that it optionally accepts an array of tidal-component names and, if called with such a list of names, returns a pointer to an array of elements of type `tide_harmonic` that have been filled with the tidal harmonic parameters for the respective components (this proposed development would make use of developments described in items c and d, and take into account the modification described in item g);

 f. the simplified daily synchronisation of the temporal tidal-forcing update in subroutine `sbc_tide` (module `sbctide`) using a single call to a new subroutine `tide_update` of module `tide_mod` (this proposed subroutine would include calls to subroutines `tide_harmo` and `tide_init_potential` and the output of tide-related information);

 g. the replacement of the use of variable `nset_day` by the value of an argument (passed via subroutine `tide_harmo`) in subroutine `astronomic_angle` (module `tide_mod`), in order to remove the dangerous temporary modification of `nday_sec` in module `sbcmod`;

 h. the modification of subroutine `upd_tide`, called in the computation of the surface pressure gradient, so that instead of `kt` and `kt_tide` only the time between midnight and the current (sub)timestep is required as argument (this makes the setting of `kt_tide` in module `sbctide` unnecessary); and

 i. in module `bdytide`, the replacement of references to variables `Wave`, `ftide`, `omega`, `utide`, and `v0tide` by references to components of variable `tide_harmonics`.

=== Previewer's comments

Looks good to me. Maybe an example of the new input format for tidal components would be welcome.

Suggestions:
- Clarify the use of complex conjugate in some places of the code. At least this option should be suppressed for boundary data files as it is a recurrent source of error.
- Clean the bdytide module. There are useless routines. I think that one used to set tidal open boundary data at each barotropic time step, which made things more complex. 

=== Reply to previewer's comments

The previewer's comments concern the implementation of the lateral tidal boundary conditions in module `bdytides` (source:/NEMO/trunk/src/OCE/BDY/bdytides.F90) and include valuable suggestions that would improve the proposed action. The original proposed revision of module `bdytides` solely includes adaptations required to accommodate modifications proposed to be made elsewhere, but neither includes a substantial modification of the module's functionality nor changes the format of tidal boundary-condition input data.

The previewer suggests to suppress the option to internally replace the tidal boundary condition by its complex conjugate. This would both simplify the implementation and reduce the risk for configuration errors. If required, such conversion can be included in the preparation of the input data. In addition to the simplification suggested by the previewer, module `bdytides` could be further reduced by removing the optional extraction of the tidal boundary condition along boundary segments from two-dimensional data fields, which, if required, can also be included in the external preparation of the tidal boundary-condition input files. Therefore, the list of specific proposed modifications is extended to include:

 j. the suppression of the optional conversion of tidal input data to its complex conjugate in module `bdytides` (including the removal of namelist parameter `ln_bdytide_conj`);

and

 k. the suppression of support for the alternative two-dimensional boundary-condition input data format and of the associated extraction of the tidal boundary condition along boundary segements from such two-dimensional input data (including the removal of namelist parameter `ln_bdytide_2ddta`).

The previewer also suggests to clean module `bdytides` from redundant source code. A review of the source code related to module `bdytides` suggests that subroutine `bdytide_update` is redundant (subroutine `bdy_dta` in source:/NEMO/trunk/src/OCE/BDY/bdydta.F90 includes a section with a call of subroutine `bdytide_update`, but since the current trunk model version never calls `bdy_dta` with the optional argument `jit`, the code in this section seems to be redundant). Therefore, the list of specific proposed modifications is further extended to include:

 l. the removal of both the redundant subroutine `bdytide_update` of module `bdytides` and a section of redundant source code in subroutine `bdy_dta` of module `bdydta` (lines 230 to 287, which contain a call of subroutine `bdytide_update`).

Further, the proposed action is extended to include an update of the NEMO manual to reflect the modifications of the model that result from this action.


=== Previewer's comments

I would prefer that you keep ln_bdytide_2ddta option. That would probably ease the future use of "on the fly" interpolation to provide tidal forcing at boundaries. This said, that looks all good to me.

=== Reply to previewer's comments

The previewer suggests to retain the support of the two-dimensional input data format in module `bdytides`; therefore, item k is removed from the above list of specific proposed modifications. I would like to thank the previewer for carrying out the preview of this action and for his valuable comments and suggestions.

== Tests

SETTE results for [source:/NEMO/branches/2019/dev_r10742_ENHANCE-12_SimonM-Tides@12096]:
||=                  =||= restart =||= repro =||= agrif check =||
||= GYRE_PISCES      =||    OK     ||   OK    ||        -      ||
||= ORCA2_ICE_PISCES =||    OK     ||   OK    ||        -      ||
||= ORCA2_OFF_PISCES =||    OK     ||   OK    ||        -      ||
||= AMM12            =||    OK     ||   OK    ||        -      ||
||= ORCA2_SAS_ICE    =||    OK     ||   OK    ||        -      ||
||= AGRIF_DEMO       =||    OK     ||   OK    ||       OK      ||
||= SPITZ12          =||    OK     ||   OK    ||        -      ||
||= ISOMIP           =||    OK     ||   OK    ||        -      ||
||= OVERFLOW         =||    OK     ||   OK    ||        -      ||
||= LOCK EXCHANGE    =||    OK     ||    -    ||        -      ||
||= VORTEX           =||    OK     ||   OK    ||        -      ||
||= ICE AGRIF        =||    OK     ||   OK    ||        -      ||

SETTE results for [source:/NEMO/branches/2019/dev_r11879_ENHANCE-05_SimonM-Harmonic_Analysis@12122]:
||=                  =||= restart =||= repro =||= agrif check =||= comparison with [source:/NEMO/branches/2019/dev_r10742_ENHANCE-12_SimonM-Tides@12096] =||
||= GYRE_PISCES      =||    OK     ||   OK    ||        -      ||  identical  ||
||= ORCA2_ICE_PISCES =||    OK     ||   OK    ||        -      ||  identical  ||
||= ORCA2_OFF_PISCES =||    OK     ||   OK    ||        -      ||  identical  ||
||= AMM12            =||    OK     ||   OK    ||        -      ||  identical  ||
||= ORCA2_SAS_ICE    =||    OK     ||   OK    ||        -      ||  identical  ||
||= AGRIF_DEMO       =||    OK     ||   OK    ||       OK      ||  identical  ||
||= SPITZ12          =||    OK     ||   OK    ||        -      ||  identical  ||
||= ISOMIP           =||    OK     ||   OK    ||        -      ||  identical  ||
||= OVERFLOW         =||    OK     ||   OK    ||        -      ||       -     ||
||= LOCK EXCHANGE    =||    OK     ||    -    ||        -      ||       -     ||
||= VORTEX           =||    OK     ||   OK    ||        -      ||  identical  ||
||= ICE AGRIF        =||    OK     ||   OK    ||        -      ||  identical  ||

{{{#!box help
[[Include(wiki:Developers/DevProcess#tests)]]
}}}

== Review

{{{#!box help
[[Include(wiki:Developers/DevProcess#review)]]
}}}