The HydroflowModel class#

What it does#

HydroflowModel builds a hydrodynamic physical model. This class controls the hydrodynamic simulation:

set up of the appropriate initial and boundary conditions
modification of the specific simulation properties such as CFL number, flux scheme, etc.

Whenever you use this class, it is essential to conclude your script by employing the export_data() function and resolving your specified problem through the solve() function.

Documentation#

class watlab.hydroflow.HydroflowModel(mesh: Mesh)#

Hydrodynamic simulation model. The simulation model is made of a physical Mesh and is linked to the Export class

This class must be used to design your problem by providing a solver, initial and boundary conditions. The function solve() is used to launch the simulation by calling the C++ solver.

property Cfl_number#

Convergence condition by Courant-Friedrichs-Lewy: Must always be below 1

Getter:: Returns Courant-Friedrichs-Lewy number
Setter:: Sets Courant-Friedrichs-Lewy number
Type:: float

export_data() → None#: Calls the export class to export the needed files in the input folder Please inspect the input folder to see the designed problem. Informations about initial conditions, nodes, edges or eventual gauges places are included

property flux_order#

order used to compute the fluxes

Getter:: returns the order used to compute the fluxes
Setter:: Sets the order used to compute the fluxes (1 or 2)
Type:: int (default : 1)

property flux_scheme#

Scheme used to compute the fluxes at the interfaces of the mesh: FOR THE MOMENT ONLY HLLC AVAILABLE

Getter:: returns the flux scheme
Setter:: Sets scheme used to compute the fluxes at the interfaces of each edge (HLLC, Roe or other)
Type:: string

get_boundary_conditions()#: Returns the boundary conditions in a dictionary

property is_fixed_bed_level#: Indicates to the c++ code if there is a fixed bed level :return: 0 or 1 :rtype: Boolean of type int (0,1)

property is_friction#

Indicates to the c++ code if there is friction to be considered

Returns:: 0 or 1
Return type:: Boolean of type int (0,1)

property is_infiltration#

Indicates to the c++ code if there is infiltration to be considered

Returns:: 0 or 1
Return type:: Boolean of type int (0,1)

property is_init_infiltration#

Indicates to the c++ code if there is initial cumulative infiltration to be considered

Returns:: 0 or 1
Return type:: Boolean of type int (0,1)

property is_rainfall#

Indicates to the c++ code if there is rainfall to be considered

Returns:: 0 or 1
Return type:: Boolean of type int (0,1)

property is_sediments#

Indicates to the c++ code if there is sediments to be considered

Returns:: 0 or 1
Return type:: Boolean of type int (0,1)

resume_simulation(pic_file, display=True, isParallel=False, isSameMesh=True)#

Allows the user to restart a simulation from a former pic.txt file.

Parameters:

pic_file (string) – pic.txt file used as initial conditions for the simulation
display (bool, optional) – if True shows the cpp outputed informations, defaults to True
isParallel (bool, optional) – if True the parallel version of the code is used, defaults to False
isSameMesh (bool, optional) – if True no interpolation is performed. Initial conditions are not interpolated, defaults to True

set_bedrock_level(regions: str | int | list, bedrock_levels: float | list | Callable[[float, float], float])#

Sets the initial bedrock level to the cells in the domain. Either a constant value or a function can be provided.

Parameters:

regions (list(string, int), string or int) – the regions names (string) or the regions tags (int)
bedrock_levels (float or list) – the values to be given to the cells in the corresponding region.

set_boundary_hydrograph(boundaries, hydrograph_paths, linear_discharge_correction=True, initial_hydrogram_correct=False)#

Sets a hydrograph type of boundary condition. This method assigns time-varying discharge (hydrograph) boundary conditions to the specified boundaries in the model. It supports various input formats including Excel files, text files, and numpy arrays/lists.

Your input file must be organized as follows:

For Excel files, the first two columns will be interpreted as time and discharge values. For text files or arrays, data should be structured as two columns: time (s) and discharge.

Parameters:

boundaries (str, int, list, tuple) – The boundary names (string) or the boundary tags (int). Can be a single boundary or a list/tuple of boundaries.
hydrograph_paths (str, list, numpy.ndarray) – The paths of the hydrographs associated with the boundaries. If boundaries is a list/tuple, this should be a list of corresponding hydrograph paths. Can be file paths (Excel or txt) or 2D arrays/lists with time and discharge values.
linear_discharge_correction (bool) – Whether to divide the discharge by the length of the boundary. Default is True.
initial_hydrogram_correct (bool) – Whether to apply initial hydrograph correction.

Raises:

ValueError – If the hydrograph format is not supported.
FileNotFoundError – If the hydrograph file is not found.

Returns:

None

set_boundary_limnigram(boundaries, limnigram_paths)#

Sets a limnigram type of boundary condition

Parameters:

boundaries (str, int, list, tuple) – The boundary names (string) or the boundary tags (int). Can be a single boundary or a list/tuple of boundaries.
limnigram_paths (string or list) – the paths of the limnigrams associated to the edges in the corresponding boundary.

Raises:

FileNotFoundError – If the hydrograph file is not found.

Returns:

None

set_boundary_water_discharge(boundaries, water_discharges)#

Defines the imposed water discharge through the edges of the boundaries. You must introduce the total discharge. Positive value flows in the system

Parameters:

boundaries (string or int) – the boundary names (string) or the boundary tags (int)
water_discharges (float or list) – the values to be given to the edges in the corresponding boundary.

set_boundary_water_level(boundaries, water_levels)#

Defines the imposed water level at edges of the boundaries.

Parameters:

boundaries (string or tag) – the boundary names (string) or the boundary tags (int)
water_levels (float or list) – the values to be given to the edges in the corresponding boundary.

set_friction_coefficient(regions, friction_coefficients)#

Sets the friction coefficients associated to each cell in the domain.

If only one value is given, all cells will get the same value.

Parameters:

regions (string or int) – the regions names (string) or the regions tags (int)
friction_coefficients (float or list or .tif file) – the values to be given to the cells in the corresponding region.

set_green_ampt_infiltration_model(regions: str | int | list, Ks: float, Psi: float, hum_init: float, hum_sat: float, Ho: float, ds: float)#

Set the Green-Ampt infiltration model to the cells of given regions.

Parameters:

regions (list(string, int), string or int) – the regions names (string) or the regions tags (int) on which the infiltration model is applied
Ks (float [m/s]) – The saturated hydraulic conductivity. Must be positive.
Psi (float [m]) – The average suction head at the wetting front. Must be positive.
hum_init (float [m3/m3]) – The initial water content
hum_sat (float [m3/m3]) – The saturated water content. Must be greater than hum_init and less than 1
Ho (float [m]) – Maximal storage capacity of the soil, expressed in water equivalent. Theoretically corresponds to the soil depth times the average porosity. Must be positive.
ds (float [1/day]) – Coefficient of exponential emptying of the infiltrated layer, simulating the drainage of the soil. A value of 1 leads to a daily drainage rate of 63% (=1-exp(-1)) and a hourly drainage rate of 4% (=1-exp(-1/24)). Should be between 0 (no drainage) and infinity (instantaneous drainage). Must be positive.

set_horton_infiltration_model(regions: str | int | list, f0: float, fc: float, k: float, S: float, ds: float)#

Set the Horton infiltration model to the cells of given regions.

Parameters:

regions (list(string, int), string or int) – the regions names (string) or the regions tags (int) on which the infiltration model is applied
f0 (float [m/s]) – Initial infiltration capacity. Must be positive and greater than fc.
fc (float [m/s]) – Final infiltration capacity. Must be positive and lower than f0.
k (float [1/m]) – Coefficient of exponential decay of the infiltration capacity. Must be positive.
S (float [m]) – Maximal storage capacity of the soil, expressed in water equivalent. Theoretically corresponds to the soil depth times the average porosity. Must be positive.
ds (float [1/day]) – Coefficient of exponential emptying of the infiltrated layer, simulating the drainage of the soil. A value of 1 leads to a daily drainage rate of 63% (=1-exp(-1)) and a hourly drainage rate of 4% (=1-exp(-1/24)). Should be between 0 (no drainage) and infinity (instantaneous drainage). Must be positive.

set_infiltration(regions: str | int | list, type: str, parameters: list)#

Set a given infiltration model to the cells of given regions.

You are not supposed to call this function directly, but rather use a specific infiltration model.

set_initial_cumulative_infiltration(regions, Ft)#

Sets the initial cumulative infiltration to the cells in the domain.

If only one value is given, all cells will get the same value.

Parameters:

regions (string or int) – the regions names (string) or the regions tags (int)
Ft (float or list) – the values to be given to the cells in the corresponding region.

set_initial_cumulative_infiltration_from_picture(pic_file, isSameMesh=True)#

Allows the user to set the initial cumulative infiltration from a former pic.txt file.

Parameters:

pic_file (string) – pic.txt file used as initial conditions for the simulation
isSameMesh (bool, optional) – if True no interpolation is performed. Initial conditions are not interpolated, defaults to True

set_initial_water_discharge(regions, discharges)#

Sets the initial water levels to the cells in the domain.

If only one value is given, all cells will get the same value.

Parameters:

regions (string or int) – the regions names (string) or the regions tags (int)
discharges (List) – the values to be given to the cells in the correspondint region. Each entry must be composed of two elements (discharge x and discharge y).

set_initial_water_height(regions, water_heights)#

Sets the initial water height to the cells in the domain.: If only one value is given, all cells will get the same value.

Parameters:

regions (string or int) – the regions names (string) or the regions tags (int)
water_heights (float or list) – the values to be given to the cells in the correspondant region.

set_initial_water_level(regions, water_levels)#

Sets the initial water levels to the cells in the domain.

If only one value is given, all cells will get the same value.

Parameters:

regions (string or int) – the regions names (string) or the regions tags (int)
water_levels (float or list) – the values to be given to the cells in the correspondant region.

set_rainfall_intensity(regions, hyetogram, units='mm/h', dt: int = 60)#

Set a given rainfall intensity to the cells of given regions.

Parameters:

regions (list(string, int), string or int) – the regions names (string) or the regions tags (int)
hyetogram (float or list(tuple)) – the values to be given to the cells in the corresponding region. Could be a constant value for the duration of the simulation or a list of tuples (time, intensity)
units (string) – the units of the hyetogram, defaults to “mm/h”. Supported units are “mm/h” and “m/s”
dt (int, optional) – the time step to use for the hyetogram in seconds, defaults to 60. If it is bigger than the smallest time step of the hyetogram, it will be set to the smallest time step of the hyetogram

set_rainfall_intensity_from_csv_file(regions: str | int | list, hyetogram_path, units, dt=60, initial_time='1970-01-01 00:00')#

Set a given hyetogram to the cells of given regions using a standardized CSV file.

Parameters:

regions (list(string, int), string or int) – the regions names (string) or the regions tags (int)
hyetogram_path (string) – the path to the CSV file
units (string) – the units of the hyetogram, defaults to “mm/h”. Supported units are “mm/h” and “m/s”
dt (int, optional) – the time step to use for the hyetogram in seconds, defaults to 60
initial_time (string) – the initial time of the simulation, defaults to “1970-01-01 00:00”

set_rainfall_intensity_from_spw_file(regions, hyetogram_path: str, dt=60, initial_time='1970-01-01 00:00')#

Set a given hyetogram to the cells of given regions using a SPW file. Units are extracted from the file.

Parameters:

regions (list(string, int), string or int) – the regions names (string) or the regions tags (int)
hyetogram_path (string) – the path to the SPW file (in xlsx format)
dt (int, optional) – the time step to use for the hyetogram in seconds, defaults to 60
initial_time (string) – the initial time of the simulation, defaults to “1970-01-01 00:00”

set_transmissive_boundaries(boundaries)#

Defines which edges behave like a transmissive interfaces.

Parameters:: boundaries (string or int) – the boundary names (string) or the boundary tags (int) where the edges behave like transmissive interfaces.

set_wall_boundaries(boundaries)#

Defines which edges behave like wall interfaces.

Parameters:: boundaries (string or int) – the boundary names (string) or the boundary tags (int) where the edges behave like wall interfaces.

property slope_limiter#

This function assigns slope_limiter

Getter:: returns the slope_limiter
Setter:: 1 or 2 ???
Type:: int (default : 0)

solve(display=True, isParallel=False) → None#: Calls the C++ executable of meshchecker if the parameter meshchecking of mesh is set to True Calls the C++ executable and solve the current designed model

property zero_depth_value#

Convergence condition by Courant-Friedrichs-Lewy: Must always be below 1

Getter:: Returns Courant-Friedrichs-Lewy number
Setter:: Sets Courant-Friedrichs-Lewy number
Type:: float