COUPLER of MUSTANG (interface between host hydrodynamical model and MUSTANG module)

The coupler of MUSTANG includes three files :

  • the first file allows to declare the parameters and the fixed data associated with the hydro model (horizontal and vertical grid, ..)
    • its name in MARS is : coupleur_dimhydro_MUSTANG.h
    • it contains some USE (parameters, comsubstance)
  • the second file defines the vocabulary of the interface :
    • its name is : coupleur_define_MUSTANG.h
    • it defines generic names that the compiler will replace with the names chosen by the user to match the vocabulary of the host model.
    • it defines also the dimensions of tables and some spatial formulas.
    • Examples :
      • # define IMIN_BOUCL liminp2
      • # define PROC_IN_ARRAY limin :limax , ljmin :ljmax
      • # define ARRAY_WAT_SETTL kmax,nv_adv,PROC_IN_ARRAY
      • # define BATHY_h0 h0
      • # define HTOT_NEAR_E htot(i+1,j)
    • See Variable Exchange between host hydrodynamical model and MUSTANG
  • the third file is a module containing several routines :
    • its name is : coupleur_MUSTANG.F90
    • routines define some variables or parameters not known by host hydrodynamical model if needed
    • one routine converts tables of variables to exchange them between the two models (the order of indexes in the tables may differ), if needed
    • one routine recovers for MUSTANG the values of salinity, temperature, concentrations of variables, layer thickness in the bottom layet. It calculates also the total water height and elevation of the calculation point of the concentration in the bottom layer.

Variable Exchange between host hydrodynamical model and MUSTANG

  • The list of variables required by MUSTANG and exchanged from the host hydrodynamical model to MUSTANG is presented below.
  • The “generic names” given in this table correspond to the names that will be replaced by the compiler using the “vocabulary” defined by the coupler (coupler_define_MUSTANG.h).
  • The dimensions of the tables of this “hydro” data are also defined by the coupler in coupler_define_MUSTANG.h.
  • some variables are exchanged via the arguments of the subroutines, others are declared (via an USE or an include) in the coupleur_dimhydro_MUSTANG.h file (in MARS) or in module_MUSTANG.F (in CROCO)
+------------------------------+-----------------------------------------+-------------------------------+-------------------------------------+----------------+
|   generic name               |                                         |    Shape - dimensions         |   used in MUSTANG for estimate      | name in MARS   |
+------------------------------+-----------------------------------------+-------------------------------+-------------------------------------+----------------+
| CELL_DX, CELL_DY             |   Computational grid:                   |    2D (i,j)                   |   Sliding deposits (bottom slope)   | dx,dy          |
|                              |   spatial step on the X and Y axes (m)  |     ARRAY_CELL_DX             |                                     |                |
+------------------------------+-----------------------------------------+-------------------------------+-------------------------------------+----------------+
| NB_LAYER_WAT                 |   Number of layers on the vertical      |    0D                         |  array dimensions of settling rates | kmax           |
|                              |   (water column)                        |                               |   turbulent viscosity..             |                |
+------------------------------+-----------------------------------------+-------------------------------+-------------------------------------+----------------+
| BATHY_H0                     |   Bathymetry (depth)(m)                 |    2D (i,j)                   |  total water height (htot)          |   h0           |
|                              |                                         |   ARRAY_BATHY_h0              |  sliding deposits (bottom slope)    |                |
+------------------------------+-----------------------------------------+-------------------------------+-------------------------------------+----------------+
| CELL_SURF                    |   grid mesh surface (m)                 |    2D (i,j)                   |  IWS fluxes                         |  surf          |
|                              |                                         |   ARRAY_CELL_SURF             |                                     |                |
+------------------------------+-----------------------------------------+-------------------------------+-------------------------------------+----------------+
| RESIDUAL_THICKNESS_W         |   residual water depth (m) below which  |    0D                         |  test                               |  h0fond        |
|                              |   it is considered there is no water    |                               |                                     |                |
+------------------------------+-----------------------------------------+-------------------------------+-------------------------------------+----------------+
| NUMBER_PI                    |   pi                                    |    0D (double precision)      |  flocculation                       |  pi            |
|                              |   it is considered there is no water    |                               |                                     |                |
+------------------------------+-----------------------------------------+-------------------------------+-------------------------------------+----------------+
| TRANSPORT_TIME_STEP          |   time step for advection equation      |    0D (double precision)      |  sediment processes                 |  halfdt        |
|                              |   resolution                            |                               |                                     |                |
+------------------------------+-----------------------------------------+-------------------------------+-------------------------------------+----------------+
| CURRENT_TIME                 |   time                                  |    0D (double precision)      |  sediment processes                 |  t             |
|                              |                                         |                               |                                     |                |
+------------------------------+-----------------------------------------+-------------------------------+-------------------------------------+----------------+
| WATER_ELEVATION              |   Elevation of the free surface         |     2D (i,j)                  |  total water height (htot)          |  ssh           |
|                              |                                         |     ARRAY_WATER_ELEVATION     |                                     |                |
+------------------------------+-----------------------------------------+-------------------------------+-------------------------------------+----------------+
| BAROTROP_ZONAL_VELOCITY_U    |   Barotropic currents                   |     2D (i,j)                  |  lateral erosion                    |  u             |
| BAROTROP_ZONAL_VELOCITY_V    |                                         |     ARRAY_ZONAL_VELOCITY_U    |                                     |  v             |
|                              |                                         |  ARRAY_MERIDIONAL_VELOCITY_V  |                                     |                |
+------------------------------+-----------------------------------------+-------------------------------+-------------------------------------+----------------+
| RHOREF                       |   Density of reference water            |     0D                        |  sand setttling rates,              |  rhoref        |
|                              |                                         |                               |  shear stress                       |                |
+------------------------------+-----------------------------------------+-------------------------------+-------------------------------------+----------------+
| TEMPREF_LIN                  |   Reference temperature and salinity    |     0D                        |  supernatant water density          |  tetaref_lin   |
| SALIREF_LIN                  |   (linear profile)                      |                               |  shear stress                       |  saliref_lin   |
+------------------------------+-----------------------------------------+-------------------------------+-------------------------------------+----------------+
| SALINITY_MOD                 |   Salinity and temperature              |     3D   (k,i,j) or (i,j,k)   |  temperature and saliity            |  sal           |
| TEMPERATURE_MOD              |   in hydro model                        |     ARRAY_TEMPSAL             |  at water bottom                    |  temp          |
+------------------------------+-----------------------------------------+-------------------------------+-------------------------------------+----------------+
| WAT_SETTL                    |   settling rates of substances in water |     4D   hydro model order    |  settling, deposit                  |  ws3           |
|                              |                                         |     DIM_MODELE_HYDRO_ws       |                                     |                |
+------------------------------+-----------------------------------------+-------------------------------+-------------------------------------+----------------+
| WATER_CONCENTRATION          |   concentration of substances in water  |     4D   hydro model order    |  settling rates, diffusion          |  cv_wat        |
|                              |                                         |     ARRAY_WATER_CONC          |                                     |                |
+------------------------------+-----------------------------------------+-------------------------------+-------------------------------------+----------------+
| LATITUDE, LONGITUDE          |   latitude, longitude of grid points    |     2D (i,j)                  |  debug point coordinates            |  lat2d_g       |
|                              |                                         |     ARRAY_LATLON              |  (if key_MUSTANG_debug              |  lon2d_g       |
+------------------------------+-----------------------------------------+-------------------------------+-------------------------------------+----------------+
  • MUSTANG calculates water and substance fluxes at the water/sediment interface, horizontal fluxes corrections for sands, and settling rates that the hydro model must incorporate into transport equations
  • The list of variables estimated by MUSTANG and exchanged from MUSTANG to the host hydrodynamical model is presented below.
  • They are declared and allocated in comMUSTANG.F90, with their names and their dimensions defined via the coupler_define_MUSTANG.h
+------------------------------------+----------------------------------------------+-------------------------------+----------------------------------+----------------+
|   generic name                     |                                              |    Shape - dimensions         |   used in host hydro model       | name in MARS   |
+------------------------------------+----------------------------------------------+-------------------------------+----------------------------------+----------------+
| EROS_FLUX_s2w                      | Erosion flux brought from sediment to water  |    3D (iv,i,j)                |  transport eq.                   | flx_s2w        |
|                                    |   for each substance   (Mass/m2/s)           |     ARRAY_EROS_FLUX_s2w       |                                  |                |
+------------------------------------+----------------------------------------------+-------------------------------+----------------------------------+----------------+
| EROS_FLUX_TEMP_s2w                 | Erosion flux brought from sediment to water  |    3D (i,j)                   |  transport eq.                   | flx_s2w        |
| EROS_FLUX_SAL_s2w                  |   for Temperatur and salinity   (Mass/m2/s)  |  ARRAY_EROS_FLUX_TEMSAL_s2w   |                                  |                |
+------------------------------------+----------------------------------------------+-------------------------------+----------------------------------+----------------+
| SETTL_FLUX_w2s                     | Deposit flux (trend in m/s)                  |    3D (iv,i,j)                |  transport eq.                   | flx_w2s        |
|                                    |   only for particulate variables             |   ARRAY_SETTL_FLUX_w2s        |                                  |                |
+------------------------------------+----------------------------------------------+-------------------------------+----------------------------------+----------------+
| CORFLUX_SAND                       | corrective term for sand flux                |    3D (iv,i,j) or (i,j,iv)    |  transport eq.                   | corflux        |
| CORFLUY_SAND                       |                                              |   ARRAY_CORFLUX_SAND          |                                  | corfluy        |
|                                    |                                              |   ARRAY_CORFLUY_SAND          |                                  |                |
+------------------------------------+----------------------------------------------+-------------------------------+----------------------------------+----------------+
| SETTL_FLUXSUM_w2s                  | Effective deposit flux from water to sed.    |    ARRAY_SETTL_FLUXSUM_w2s    |  estimate in transport eq.       | flx_w2s_sum    |
|                                    |                                              |                               |  used in MUSTANG for deposit     |                |
+------------------------------------+----------------------------------------------+-------------------------------+----------------------------------+----------------+
| WATER_FLUX_INPUTS                  | Imported water flux  at the interface        | ARRAY_WATER_FLUX_INPUTS (3D)  |  continuity eq                   | phieau         |
|                                    | water/sediment brought in the bottom mesh    |                               |                                  |                |
+------------------------------------+----------------------------------------------+-------------------------------+----------------------------------+----------------+
| WATER_FLUX_INPUTS_BOTCELL          | Imported water flux  at the IWS              | ARRAY_WATER_FLUX_INPUTS )     |  continuity eq                   | phieau(1,:,:)  |
|                                    | in the bottom mesh                           |           (k=1,i,j)           |                                  |                |
+------------------------------------+----------------------------------------------+-------------------------------+----------------------------------+----------------+

CALLS FOR MUSTANG in host hydrodynamical model

Les interventions dans le modèle hôte sont de plusieurs sortes :
  • Au début de la simulation
    : appels aux routines de départ (déclaration et allocation des variables, lecture des namelists pour connaître les paramètres, appel au coupleur pour définir les substances à transporter (si ce n’est pas fait dans un module comme le module « substance »), initialisation du sédiment :
    • Appel au coupleur
    • Appel à MUSTANG_initialization (lecture namelist, allocation des tableaux)
    • Appel à MUSTANG_init_sediment (initialisation des sédiments)
    • Appel à MUSTANG_init_output (initialisation des tableaux à sortir dans le fichier résultat).
  • A chaque pas de temps (a): appel à MUSTANG_update avant la résolution des équations de mouvement, de la continuité et du transport pour :
    • Réactualiser la bathymétrie si le calcul morphodynamique est pris en compte
    • Evaluer les vitesses de chute, tensions de fond, taux de cisaillement, vitesse de frottement (u*), tendances ou vitesses de dépôt, plus les corrections de flux pour les sables – après avoir récupéré du modèle hydro les hauteurs d’eau totales, les concentrations des variables au fond, la hauteur de la couche de fond dans la colonne d’eau.
    • Gérer les processus dans le sédiment (compaction, diffusion, bioturbation) et son évolution due aux processus d’érosion - calculer les flux d’eau qui accompagnent ces flux d’érosion à l’interface eau/sédiment.
  • A chaque pas de temps (b) : appel à MUSTANG_deposition après la résolution des équations de transport pour appliquer les flux de dépôts effectifs et mettre à jour la colonne sédimentaire.
  • A chaque pas de temps (c) : appel à une routine de sortie des résultats, qui appelle la routine qui interpole les résultats et écrit les résultats dans le fichier
  • Dans les équations résolues par le modèle hydrodynamique, introduction de termes supplémentaires et adaptation du schéma de résolution du transport vertical :
    • Prendre en compte les flux d’eau à l’interface eau/sédiment, dus à l’érosion, dépôt, consolidation dans les équations de continuité. Il ne devrait pas y avoir d’intrusion dans le modèle hydro si les flux d’eau à introduire dans la maille du fond sont déjà formalisés dans le modèle hydro, et qu’ils peuvent être repérés et être mis à jour dans MUSTANG (voir coupleur). Sinon, il faut programmer une manière d’introduire cet apport d’eau dans le fond de la colonne d’eau. Ceci est important pour préserver la conservativité des substances, notamment par faible profondeur.
    • Prendre en compte les corrections des flux horizontaux pour les sables dans la résolution des équations de transport horizontaux. Ces corrections sont importantes pour le transport des sables fins et grossiers en suspension qui sont concentrés plutôt près du fond et dont le courant moyen dans la couche de fond peut ne pas être suffisamment précis pour reproduire leur advection. On tient compte alors de la variation du courant au dessus du fond, simulée par un profil de Rouse.
    • Si le modèle hydro permet de traiter certaines variables en 2D (intégrée sur la hauteur d’eau) au lieu de 3D, prendre en compte les corrections sur les termes de transport pour ces substances. Dans ce cas, seule la concentration dans la couche de fond est non nulle et représente la concentration intégrée sur la colonne d’eau de la substance. Ce traitement peut être nécessaire pour les substances qui chutent très vite (par exemple les sables). Si cette possibilité n’existe pas dans le modèle hydro, le booléen (l_subs2D) devra toujours être pris « faux » mais il faut que le schéma d’advection verticale dans la colonne d’eau supporte bien les très fortes vitesses de chute des sables qui sont transportés en suspension.
    • Prise en compte des flux à l’interface eau/sédiment (érosion/dépôt/diffusion) et des vitesses de chute pour le transport vertical dans la colonne d’eau
    • La réactualisation de la bathymétrie si la morphodynamique est simulée est réalisée par MUSTANG actuellement ; les profondeurs et les niveaux d’eau sont recalculés et passés en argument des routines (INOUT). Il est donc nécessaire de faire des échanges entre processeurs voisins pour que ces variations soient connues sur tout le domaine.