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 # Tolosasw 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 usersubroutines to define initial conditions, boundary conditions, etc ...
regional.depthele.a # Domain topography
regional.depthele.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 builtin CAD engine. Gmsh is built around four modules: geometry, mesh, solver and postprocessing. 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 Tolosasw. 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.depthele.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.depthele.a
Warning
If bathy_in = 2
and no regional.depthele.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 forrest_old_X
files whereX
is the name of a field ; thoserest_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 therestart
variable as nonzero.
!!
! 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. Iffriction_scheme = 1
, the friction scheme is an implicit scheme for a logarithmic velocity profile, and iffriction_scheme = 2
, the friction scheme is a semiimplicit scheme for a logarithmic velocity profile.friction_model = 2
: Friction activated with an oceanic model and is quadratic computed fromz0
. Iffriction_scheme = 1
, the friction scheme is an implicit scheme for a logarithmic velocity profile, and iffriction_scheme = 2
, the friction scheme is a semiimplicit scheme for a logarithmic velocity profile.friction_model = 3
: Friction activated with the ManningStrickler model. No matter thefriction_scheme
value, the friction scheme is an implicit scheme for the ManningStrickler 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 theregional.grid.a
file).  If
coriolis = 2
: The coriolis force is computed from a betaplane approximation.  If
coriolis = 0
orcoriolis > 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 ! Cutoff 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 secondssimu_time
: interpreted string withdays
,hours
,minutes
,seconds
unitsstart_date
andend_date
: iftime_format = julian
orjulian_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 Tolosasw outputs, it is necessary to fill the input.txt
file 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 Tolosalib / 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 posttreated 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 ! PostTreatment 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 ! Posttreatment option
Output activation
The written values here are the default values, but to activate an output writting, one has to check the Tolosalib / 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 : XY Datafiles¶
One can generate 1D outputs in XY 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¶
Tolosasw 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.