Inputs definition

To define the model, one has to fill various input files out (input.txt, savefield.yaml) and add other files (potential mesh file, forcing files, tidal constituents file, restart files, etc.).

The general structure of the working directory should be the following :

/wdir
    exe                    # Tolosa-sw executable
    your_mesh.msh          # Mesh file
    forcing.XXtide.a       # Amplitude and phase for the sea surface height in association with XX tidal component
    forcing.XXtide.b
    ...
    input.txt              # Input file
    m_user_data.f90        # Contains user-subroutines to define initial conditions, boundary conditions, etc ...
    regional.depth-ele.a   # Domain topography
    regional.depth-ele.b
    regional.grid.a        # Longitude and latitude mesh nodes coordinates
    regional.grib.b
    bottom_fric_qua        # Quadratic friction coefficient values at each cell center
    bottom_fric_lin        # Linear    friction coefficient values at each cell center
    bottom_fric_z0         # z0 ?
    savefield.yaml         # Input file
    tide.list              # List of all tidal components and their specifications

Info

The highlighted files are mandatory to run the code. The other files' presence depend on the model definition and its parametrization.

The following paragraphs will present the extent of this model definition.

1. Domain, mesh¶

One could either create a box geometry and mesh with Tolosa using the input.txt geometry variables or create a complex geometry and mesh using Gmsh.

Box geometry and mesh : `input.txt`¶

If one wishes to create a simple box geometry and mesh, one can fill the input.txt file with the following lines out :

!======================================================================================================================!
!  Mesh parameters
!======================================================================================================================!
    mesh_type           =   basic
    part_strat          =   seq
    nx                  =   101
    ny                  =   101
    lx                  =   1.
    ly                  =   1.
    bc_N                =   wall
    bc_S                =   wall
    bc_W                =   wall
    bc_E                =   wall

The dimensions, the domain discretization, and the boundary conditions can be specified.

Info

The values in this example are the default values.

Complex geometry and mesh : Gmsh¶

Gmsh is an open source 3D finite element mesh generator with a built-in CAD engine. Gmsh is built around four modules: geometry, mesh, solver and post-processing. The specification of any input to these modules is done either interactively using the graphical user interface, or in ASCII text files using Gmsh's own scripting language (.geo files). If Gmsh is used, an external .msh file needs to be created to be read by Tolosa-sw. This mesh file should be created using the Mesh 2 format :

gmsh -2 -format msh2 -algo `your_algo` `your_geometry.geo`

When this meshing file is created, one has to call it in the input.txt file.

!======================================================================================================================!
!  Mesh parameters
!======================================================================================================================!
    mesh_name           =   your_mesh.msh
    part_strat          =   seq

Remarks¶

In addition to the stereo mesh file your_mesh.msh : regional.grid.a

One can also import another file to set the nodes coordinates in longitude and latitude. This file has to be named regional.grid.a. The regional.grid.b text file complements the regional.grid.a binary file to read the informations.

In the regional.grid.a file, all the nodes longitudes followed by the nodes latitudes should be written.

On boundary conditions

See Appendix - Inputs to get the boundary conditions' syntax.

More ... On the tidal boundary conditions

If a boundary condition is forced with tide waves, one has to add forcing.XXtide.a files in the working directory ; these files contain the amplitude and the phase for the sea surface height in association with each XX tidal component. The forcing.XXtide.b text file complements the forcing.XXtide.a binary file to read the informations.

2. Bathymetry¶

The bathymetry can either be loaded from a function of (x,y) in a m_user_data.f90 Fortran file or from an external file regional.depth-ele.a. One can also choose to have no bathymetry. Depending on the expected case, the input.txt input file should be filled with :

    !--------------------------------------------------------------------------! 
    ! Bathymetry & others
    !--------------------------------------------------------------------------!
    bathy_in            =   0        ! 0 : no bathymetry
                                     ! 1 : computed from a function in m_user_data.f90
                                     ! 2 : loaded from an external binary file regional.depth-ele.a

Warning

If bathy_in = 2 and no regional.depth-ele.a file is found, the program ends.

3. Fields initialization¶

To get the fields values at the first time step, one has to define the previous state of the domain. The variable restart in the input.txt file enables to set the initialization method :

If restart = 0, the program will search for rest_old_X files where X is the name of a field ; those rest_old_X files are generated at the end of an execution to pursue the computation.
If the case is run for the first time, one can initialize each field's value by writting a function in the m_user_data.f90 Fortran file and declare the restart variable as non-zero.

    !--------------------------------------------------------------------------! 
    ! Initial state
    !--------------------------------------------------------------------------!
    restart             =   0

4. Friction initialization¶

One can integrate bottom friction in the model by filling the input.txt file out. One has to choose the friction model and the friction scheme to create bottom friction :

friction_model = 1 : Friction activated with an oceanic model. If friction_scheme = 1, the friction scheme is an implicit scheme for a logarithmic velocity profile, and if friction_scheme = 2, the friction scheme is a semi-implicit scheme for a logarithmic velocity profile.
friction_model = 2 : Friction activated with an oceanic model and is quadratic computed from z0. If friction_scheme = 1, the friction scheme is an implicit scheme for a logarithmic velocity profile, and if friction_scheme = 2, the friction scheme is a semi-implicit scheme for a logarithmic velocity profile.
friction_model = 3 : Friction activated with the Manning-Strickler model. No matter the friction_scheme value, the friction scheme is an implicit scheme for the Manning-Strickler law.

If no friction is to be added, one has to set friction_model = 0.

    !--------------------------------------------------------------------------! 
    ! Friction
    !--------------------------------------------------------------------------!
    friction_model      =   0
    friction_scheme     =   0

One can either consider friction coefficients for the oceanic model to be constant or variable on the domain. If the friction coefficients are constant, one only has to fill the input.txt file out with the \(C_l\) and \(C_b\) mean values.

Info

See the Appendix to get the friction coefficient variables' names.

On the other hand, one can specify varying friction coefficients on the domain by filling binary files containing \(C_l\) and \(C_b\) values.

Info

The file containing the linear friction coefficient \(C_l\) values has to be named bottom_fric_lin. The file containing the quadratic friction coefficient \(C_b\) values has to named bottom_fric_qua. Those files are binary files. The friction coefficients are defined at each cell center.

5. External forcings and Coriolis force¶

One can add external forcings such as the tidal body force, the wind forcing and the atmospheric pressure. To apply a specific external forcing, one only needs to set the corresponding input.txt variable a greater than zero value. Therefore, if no forcing is to be applied, one has to set tbf_forcing = 0, wind_forcing = 0 and patm_forcing = 0.

Info

When the atmospheric pressure forcing is greater than 1, one considers the inverse barometer effect.

!======================================================================================================================!
!  Forcings
!======================================================================================================================!
    tbf_forcing         =   0                  ! Tidal Body Force ( 0 if not )
    wind_forcing        =   0                  ! Wind forcing ( 0 if not )
    patm_forcing        =   0                  ! Atmospheric pressure ( 0 if not )
    inv_baro            =   0                  ! Inverse barometer effect

Moreover, to define the coriolis force, one also has to fill the input.txt file.

If coriolis = 1 : The coriolis force is computed from external latitude coordinates (read in the regional.grid.a file).
If coriolis = 2 : The coriolis force is computed from a beta-plane approximation.
If coriolis = 0 or coriolis > 2 : No coriolis force applied.

    !--------------------------------------------------------------------------! 
    ! Coriolis Force
    !--------------------------------------------------------------------------!
    coriolis            =   2

Info

The coriolis force constants can be modified in the input.txt file. See Appendix.

6. Scheme and simulation time parameters¶

One has to define the model's scheme and simulation time parameters in the input.txt file. The schemes parameters can be written as :

!======================================================================================================================!
!  Schemes parameters
!======================================================================================================================!
    temp_scheme         =   first              ! Temporal Scheme
    spatial_scheme      =   euler              ! Spatial Scheme
    spatial_order       =   1                  ! Spatial Scheme Order
    adapt_dt            =   1                  ! Activate Adaptive Time Step
    cfl                 =   0.5                ! CFL number in case of Adaptative Time Step
    gamma               =   0.5                ! Low Mach Stability Coefficient
    alpha               =   0.5                ! Low Mach Stability Coefficient
    hcut                =   0.1                ! Cut-off of water depth to switch to dissipate scheme
    nb_level            =   3

On the other hand, the time parameters can be specified in different ways. One can establish a time format in Julian, Julian CNES convention, or in seconds. Therefore, the simulation time can be specified in three ways :

ts : in seconds
simu_time : interpreted string with days, hours, minutes, seconds units
start_date and end_date : if time_format = julian or julian_cnes (???)

Info

If time_format = julian_cnes or julian, start_date is mandatory. end_date is never mandatory ; however, if it is specified, the priority is given for end_date over simu_time or ts.

One can, for example, write the time specifications as :

    !--------------------------------------------------------------------------! 
    ! Time - Date
    !--------------------------------------------------------------------------!
    time_format         =   julian_cnes ! Time format choice (classic, julian, julian_cnes)
    start_date          =   22548       ! Initial date in time format
    simu_time           =   5 days      ! Formatted Simulation Time (seconds, minutes, hours, days)

7. Outputs¶

To extract general Tolosa-sw outputs, it is necessary to fill the input.txtfile out, and/or to create a savefield.yaml file to set the outputs parameters. Outputs can be one dimensional or two dimensional.

Specifications

All the outputs' structure and specifications are detailed in Tolosa-lib / Outputs.

General outputs¶

General outputs can be generated by filling the input.txt file. One can choose to have various outputs concerning the entire computation domain : Tecplot, VTK, Gnuplot and Binary files.

2D output files

VTK : 2D output that can be plotted by reading the .vtk files with Paraview.
Tecplot : 2D output that can be post-treated with the corresponding software.
Binary : 2D output in binary files, as well as binary files containing the mesh connectivity, and information file concerning the content of the binary files.

To be able to get these output files, one has to fill input.txt file out with :

    !--------------------------------------------------------------------------! 
    ! Output
    !--------------------------------------------------------------------------!
    dtw                 =   1.d15    ! Result File    Time Step
    dtp                 =   1.d15    ! Post-Treatment Time Step
    dtb                 =   -1.      ! Binary File    Time Step
    w_tecplot           =   0        ! Tecplot Result File option
    w_vtk               =   0        ! VTK     Result File option
    w_bin               =   0        ! Binary  Result File option
    w_gnuplot           =   0        ! Gnuplot Result File option
    w_python            =   0
    w_exact             =   0        ! Exact solution File option
    w_norm              =   0        ! Error norms    File option
    w_post              =   0        ! Post-treatment      option

Output activation

The written values here are the default values, but to activate an output writting, one has to check the Tolosa-lib / Inputs table and see which value is best suited for his case.

Specific outputs¶

One can also choose to create additional outputs ; this optional feature is activated by filling an additional input file savefield.yaml out. One dimensional outputs (at tide gauges for instance), and two dimensional outputs in smaller windows, to extracting specific fields, etc. are enabled.

Warning

The user has to write all his expected output (1D or 2D) in the same savefield.yaml file, differentiating them with the output_1d and output_2d keys.

Tutorial

Check the river tutorial to see how to write in the savefield.yaml to create complete 1D and 2D outputs.

output_1d:
-
  name: XXX
  cell: 0
  dt: 0
-
  ...

output_2d:
-
  name: YYY
  x_min: 0.
  x_max: 0.
  y_min: 0.
  y_max: 0.
  dt: 0.
-
  ...

1. One dimensional outputs : X-Y Datafiles¶

One can generate 1D outputs in X-Y datafiles, and has to fill the savefield.yaml file out. This table sums up the YML keys and their significations.

Output informations	YML Key(s)	Description
Name	`name`	Name of the tide gauge
Location	`cell` `x`/`y` `lon`/`lat`	GMSH cell number Coordinates in x / y Coordinates in longitude / latitude
Variables (optional)	`variables`	Variables extracted : `ssh`, `sshuvb`, `sshuv`, `sshb`, `huvb`, `huv`, `hb`, `h`. Default : `sshuvb` (sea surface height, horizontal and vertical speed components, and bathymetry).
Time step	`dt`	Time step at which variables are extracted
Time period (optional)	`t_min` `t_max`	Default : `t_min = 0.` and `t_max = ts`
File format (optional)	`format`	File format enabled : `csv`, `gnuplot` (or `gnu`), `tecplot` (or `plt`, `tec`) Default : `csv`

2. Two dimensional outputs¶

Tolosa-sw also enables the user to get a 2D distribution of various fields in a smaller window ; to define this window, the desired variables, etc. the user must also fill the savefield.yaml file out. The keys available to define the expected 2D outputs are given in the following table.

Output informations	YML Key(s)	Description
Name	`name`	Name of the output
Location (optional)	[`x_min` `x_max`] and [`y_min` `y_max`] [`lon_min` `lon_max`] and [`lat_min` `lat_max`]	Window coordinates in x / y Window coordinates in longitude / latitude Default : entire domain
Variables (optional)	`variables`	Variables extracted : `ssh`, `sshuvb`, `sshuv`, `sshb`, `huvb`, `huv`, `hb`, `h`. Default : `sshuvb` (sea surface height, horizontal and vertical speed components, and bathymetry).
Time step	`dt`	Time step at which variables are extracted
Time period (optional)	`t_min` `t_max`	Default : `t_min = 0.` and `t_max = ts`
File format (optional)	`format`	File format enabled : `bin` (one binary file per time step), `binc` (one binary file containing all time steps), `vtk` Default : `vtk`

Conclusion on the `input.txt` file¶

See Appendix - Inputs to get all the input.txt keys and their default and enabled values.

Inputs definition

1. Domain, mesh¶

Box geometry and mesh : input.txt¶

Complex geometry and mesh : Gmsh¶

Remarks¶

2. Bathymetry¶

3. Fields initialization¶

4. Friction initialization¶

5. External forcings and Coriolis force¶

6. Scheme and simulation time parameters¶

7. Outputs¶

General outputs¶

Specific outputs¶

1. One dimensional outputs : X-Y Datafiles¶

2. Two dimensional outputs¶

Conclusion on the input.txt file¶

Box geometry and mesh : `input.txt`¶

Conclusion on the `input.txt` file¶