How to add another hydrological model

Introduction

For now, TnetRUI can use 2 hydrological models: EROS, used on the french Loire watershed, and J2000 used on french Saône watershed. But other hydrological models can be used.

As an exemple, let’s imagine that we want to add another hydrological model named “MORDOR” in TnetRUI.

NetCDF files

TnetRUI use NetCDF files in order to save all intermediate and final results. In all the function you need to create in order to add another hydrological model, it’s recommended to use TNETutils_createNetCDF() to create the NetCDF file where the result of your function will be store and TNETutils_appendNetCDF to add the data in it. Doing this will unsure you that every files created by TnetRUI will have the same format.

Philosopy behind TnetRUI

All functions in TnetRUI was created with the following assomptions:

• TNET and hydrological models doesn’t share the same hydrographic network. That’s why there is 2 functions to compute Discharge in TnetRUI. TNET_readMODEL (for exemple TNET_readJ2K() or TNET_readEROS()) will read the raw data of the model on the hydrographic network of the model and put it in a NetCDF file, where TNET_computeQ() will dispatch the discharge from the Hydrographic network of the hydrological model to the Hydrographic network used by TNET (for now it’s the french hydrographic network TOPAGE). If you already have the data on the hydrographic network where you want to execute T-NET, you can only use TNET_computeQ() function to read the file with the discharge of all your river segments.

• Hydraulic data are computed using discharge data. TNET_computeHydraulic() is made to compute the hydraulic data with discharge data as a simplification. If your model already compute width, depth and travel time, you can use TNET_computeHydraulic() in order to read files with those results.

1 - Create the TNET_readMORDOR function

If you need to read raw files from modor before dispatching them on TNET hydrographic network, you will nee to create a function TNET_readMORDOR (just like TNET_readJ2K() or TNET_readEROS() functions).

2 - Modify all compute functions

You will need to modify the followings function in order to add the hydrological model MORDOR:

• TNET_computeQ()

• TNET_computeHydraulic()

• TNET_computeQlatSout()

In all those functions, you’ll need to add the following case in order to specify the code to use for the new hydrological model (example for TNET_computeQ())

if (hydro_model == 'MORDOR') {
  results_file <- computeQ_MORDOR(...)
}

and create just bellow the function computeQ_MORDOR with the computation needed. The function needs to return the file created by TNETutils_createNetCDF().

3 - Add the execution squeleton in TNET_prepareSim()

You can add a condition in the TNET_prepareSim() in order to be sure that all function will be executed in the good order

#This example is fictionnal

if (hydro_model == 'MORDOR') {
  #Read MORDOR files
  TNET_readMORDOR(...)
  
  #Dispatch discharge on TNET hydrographique network
  TNET_computeQ(hydro_model = 'MORDOR',...)
  
  #Read hydraulique data from MORDOR
  TNET_computeHydraulic(hydro_model = 'MORDOR',...)
  
  #compute underground lateral discharge
  TNET_computeQlatSout(hydro_model = 'MORDOR',...)
  
}

4 - Add an article explaining your hydrological model

Finally, it is best to add a little article with the presentation of your newly added model in order to help other user to understant it

Add the vignette

To create the vignette relatif to your hydrologial model, you can execute the following in the TnetRUI folder:

usethis::use_vignette('TnetRUI_7',title = "MORDOR hydrological model")

This will create the file where it will be possible to explain how your hydrological model works

Be sure that the file vignette/TnetRUI_7.Rmd do not exist before using this filename

Add the website article

To add your newly created vignette to the website, you’ll have to add the following code in the _pkgdown.yml file, in the Articles menu of the navbar section:

- text: "MORDOR"
  href: articles/TnetRUI_7.html

It’s possible to update the website by using the following sentence in the terminal (in the TnetRUI folder)

make website

Pushing all modification made in the “public” folder to ForgeMIA will update the website.