The particular key="Operational" allows to create test case without having to create a new ICBC class constructor meaning without having to recompile Uhaina. It is a generic ICBC class constructor entirely controlled by the config file. This approach is particularly suitable for industrial applications.
In order to use Uhaina Operational, set the test case name to Operational
:
<testcase>
<sparam key="name" val="Operational" />
</testcase>
There is also a number of inquiries to set through the config file. They are the external variables (bathymetry, manning, atmospheric pressure, wind, spectral waves, pulses) if needed for the test case, initialisation, boundary type and boundary signal to impose.
The way to set them is identical when reading a TXT or netcdf file as described in the paragraph Keys relative to external variables and Keys relative to boundary signals from Configuration files section. Some more example will be shown anyway in the following. The main difference is while using ICBC functions. In the file icbc_Operational.hpp
, there are a number a pre-defined functions that can be used if informations through the config file are set accordingly.
Uhaina can read both TXT and netcdf files in cartesian or spherical coordinates.
We can read 2 different types of TXT file by using the key word TXT
:
TXT Structured:
In that case, it is necessary to project the data on the mesh by using the key word Projected
. See boucholeurs example:
<sparam key="bathymetry" val="1;0;TXT;data/Bathy_Boucholeur.xyz;Projected;415;423" />
<sparam key="manning" val="1;0;TXT;data/Manning_ok.xyz;Projected;415;423" />
The numbers following the key word Projected
correspond to nx
and ny
the resolution of the TXT mesh. See Keys relative to external variables* from Configuration files.
TXT Unstructured:
In that case, the data is already on node location so Uhaina just have to read its values. See authie bay example:
<sparam key="bathymetry" val="1;0;TXT;DATA/Bathy_authieBayScenario1Delaunay_5m.xyz;OnNode" />
<sparam key="manning" val="1;0;TXT;DATA/Manning_authieBayScenario1Delaunay_5m.xyz;OnNode" />
See Keys relative to external variables* from Configuration files.
Netcdf structured:
To read netcdf structured file, use the key word NETCDF
in the config file. As for using TXT structured file, Uhaina has to project the data on the mesh using a bilinear interpolation.
If the variable is time dependent (like the pressure in the following example), Uhaina does a bilinear interpolation at time t_n and t_n+1 from the netcdf file (with the simulation time in between t_n and t_n+1). Then a linear interpolation is made between t_n and t_n+1 to have the value at the simulation time. See translatingStorm with a random manning and bathymetry:
<sparam key="atmosphericPressure" val="1;1;NETCDF;netcdf/translatingStormMeteo_12km_6min.nc;press;time-lat-lon;2020-05-01 00:00:00" />
<sparam key="wind" val="0;0" />
<sparam key="bathymetry" val="1;0;NETCDF;netcdf/BathytranslatingStormMeteo.nc;Bathy;lat-lon;2020-05-01 00:00:00" />
<sparam key="manning" val="1;0;NETCDF;netcdf/ManningtranslatingStormMeteo.nc;Manning;lat-lon;2020-05-01 00:00:00" />
The bathymetry and the manning depends on the latitude and longitude - The pressure has an additional dependency the time. In this example, Uhaina starts reading the pressure data at time 2020-05-01 00:00:00
which corresponds to the simulation time t = 0s
.
See Keys relative to external variables* from Configuration files.
Netcdf unstructured:
To read netcdf unstructured file, use the key word NETCDF_UGRID
in the config file. In that case, the data is already on node location so Uhaina just have to read its values. See example:
<!--sparam key="bathymetry" val="1;0;NETCDF_UGRID;netcdf/netcdfFile.nc;bathymetry;node;2000-01-01 00:00:00" /-->
<!--sparam key="manning" val="1;0;NETCDF_UGRID;netcdf/netcdfFile.nc;manning;node;2000-01-01 00:00:00" /-->
The bathymetry and the manning only depends on the node number here.
See Keys relative to external variables* from Configuration files.
ICBC inputs using pre-defined functions:
The ICBC files are used to define a test case meaning with function specific to the test case. So to create a generic ICBC class, a number a pre-defined functions have been set in the file icbc_Operational.hpp
that can be controlled through the config file.
For the moment, only the CONSTANT
function is available but the goal is to extend it for the user to have numerous choices.
Make sure the test case name is set to Operational
here is a generic example:
<sparam key="bathymetry" val="1;0;ICBC;CONSTANT;bathy_value" />
<sparam key="manning" val="1;0;ICBC;CONSTANT;manning_value" />
<sparam key="initialisation" val="1;0;ICBC;CONSTANT;eta_value;hu_value;hv_value" />
<sparam key="wind" val="1;1;ICBC;CONSTANT;uwind_value;vwind_value" />
<sparam key="atmosphericPressure" val="1;1;ICBC;CONSTANT;pressure_value" />
Initialisation:
Initialisation can be red exactly like bathy, manning, pressure, wind from TXT structured and unstructured, netcdf structured and unstructured and ICBC (see example above). In the following example, we initialize the calculation by extracting the sea surface height from a netcdf unstructured file:
-
"initialisation"
ex :
<sparam key="initialisation" val="1;0;NETCDF_UGRID;netcdf/Initialisation.nc;eta;node;2000-01-01 00:00:00" />
An other key has been created to set a dry region
only at the initialisation. It allows to have dry topology below the sea surface height suitable for simulating overtopping and overflooding.
In order to do so, the user has to define the new key:
<sparam key="setDryRegion" val="xmin:xmax;ymin:ymax" />
for 2d cases or <sparam key="setDryRegion" val="xmin:xmax" />
for 1d cases.
In 2d, it means that only a dry square can be defined (we will see later if it is necessary to defined more complex geometry to set dry regions. TXT, ICBC or NETCDF file can easily be used after few modifications).
Boundary Conditions:
To set the boundaries, two keys are necessary to be defined. One defines the type (see List of boundary conditions for available type) and the second is the signal to impose:
- "boundaryType"
<sparam key="boundaryType" val="color1:BCtype;color1:BCtype" />
The first parameter sets the color number specific to the mesh. The second parameter is the BC type separated by :
. All colors are separated by ;
. If the color number is not defined in the config file, a Wall is set by default. In the previous example, all the colors different from 1 and 2 will be set on Wall
automatically.
- "boundaryTemporalSignal"
<sparam key="boundaryTemporalSignal" val="TXT;color;PathToTXT|ICBC;color;CONSTANT;eta_signal" />
It is possible to read a temporal signal from TXT file, NETCDF file or with a pre-defined function from the generic ICBC class. This is the first parameter to set as in the example above. The second parameter is the color number specific to the mesh. If the first key word is ICBC
the third parameter is the name of the pre-defined function and the following parameters are inputs for this pre-defined function. Informations are separated by ;
for a specific colors and all colors are separated by |
.
If the color number is not defined in the config file, a NULL
function is set by default.
For the moment, only the CONSTANT
function is available but the goal is to extend it for the user to have numerous choices. Here is an example:
<sparam key="boundaryType" val="1:WHI_NonReflective;2:WHI_NonReflective" />
<sparam key="boundaryTemporalSignal" val="TXT;1;serie_tempo_hauteur.dat|ICBC;2;CONSTANT;2.36" />
In this example, the color 1 impose a temporal signal red in a TXT file and at the colors 2, a constant signal is imposed with a value of 2.36.
It is possible to modify each signals (old variable named waterSetUp
) by adding a constant scalar to the signal. It is useful because output signals from other softwares might have a mean free surface height different from the Uhaina simulation. This offset allows to run different scenario without having to rewrite the temporal signal TXT file. For example:
<sparam key="boundaryType" val="4:Dirichlet:0.16;2:Dirichlet" />
Here we impose Dirichlet on color 4 and 2. For color 4, a waterSetup is apply with a value of 0.16. If not defined, it is set to 0 like for color 2. Previously, we were using the key word "testcase.waterSetup" but it means that it is apply to all color. Now each color can have is own value of waterSetup.
How to create a new pre-define function
To create a new predefined function in Operational mode, the parameters are given through the vector params (static void funcBoundaryNEWFunc(const Coord3& c, const Real& time, const Real* const params, Real* solution){
) meaning that it is possible to give as many parameters as you want. Here is a generic form :
<sparam key="boundaryTemporalSignal" val="ICBC;color;NEWFUNC;parm1;parm2;parm3;...;parmN " />
val
is a string of characters where key words are separated by ;
. A loop is implemented to read automatically all the parameters no matter what pre function is used.
See Keys relative to external variables and Keys relative to boundary signals from Configuration files for more examples.