wolfhece.eikonal

Module Contents

wolfhece.eikonal._evaluate_distance_and_data_first_order_iso(i, j, fixed: numpy.ndarray, where_compute: numpy.ndarray, dx_mesh: float, dy_mesh: float, times: numpy.ndarray, base_data: numpy.ndarray, test_data: numpy.ndarray, speed: float = 1.0) → tuple[float, float][source]

Evaluate the time and data using a first order isotropic method.

Parameters:

  • i – (int): The row index.

  • j – (int): The column index.

  • fixed – (2D numpy array): A boolean array where True indicates fixed points.

  • where_compute – (2D numpy array): A boolean array where True indicates cells to be included in computation.

  • dx_mesh – (float): The mesh size in x direction.

  • dy_mesh – (float): The mesh size in y direction.

  • times – (2D numpy array): The time function.

  • base_data – (2D numpy array): The base data that will propagate.

  • test_data – (2D numpy array): The test data that will be used to validate propagation.

  • speed – (float): The isotropic propagation speed.

Returns:

tuple[float, float]: The time and data.

wolfhece.eikonal.__solve_eikonal_with_data(sources: list[list[int, int]], where_compute: numpy.ndarray, base_data: numpy.ndarray, test_data: numpy.ndarray, speed: numpy.ndarray, dx_mesh: float, dy_mesh: float) → numpy.ndarray[source]

Solve the Eikonal equation using the Fast Marching Method (FMM).

Jit version of the function. The next one is the non-jit version which uses this.

wolfhece.eikonal._solve_eikonal_with_data(sources: list[tuple[int, int]], where_compute: numpy.ndarray = None, base_data: numpy.ndarray = None, test_data: numpy.ndarray = None, speed: numpy.ndarray = None, dx_mesh: float = 1.0, dy_mesh: float = 1.0) → numpy.ndarray[source]

Solve the Eikonal equation using the Fast Marching Method (FMM).

Parameters:

  • sources – (list of tuples): The coordinates of the source points.

  • where_compute – (2D numpy array, optional): A boolean array where True indicates cells to be included in computation.

  • base_data – (2D numpy array, optional): The base data that will propagate.

  • test_data – (2D numpy array, optional): The test data that will be used to validate propagation.

  • speed – (2D numpy array): The speed function.

  • dx_mesh – (float, optional): The mesh size in x direction.

  • dy_mesh – (float, optional): The mesh size in y direction.

Returns:

2D numpy array The solution to the Eikonal equation.

wolfhece.eikonal._extract_patch_slices_with_margin(shape, labels, margin=2)[source]

Extract the slices of the patches with a margin around the labels.

Parameters:

  • shape – (tuple): The shape of the array.

  • labels – (2D numpy array): The labels of the patches.

  • margin – (int, optional): The margin around the labels.

wolfhece.eikonal._process_submatrix(args)[source]

Function to process a submatrix in a multiprocess.

wolfhece.eikonal._solve_eikonal_with_value_on_submatrices(where_compute: numpy.ndarray, base_data: numpy.ndarray, test_data: numpy.ndarray = None, speed: numpy.ndarray = None, multiprocess: bool = False, dx: float = 1.0, dy: float = 1.0, ignore_last_patches: int = 1, NoDataValue: float = 0.0) → numpy.ndarray[source]

Propagate data inside the mask using the Fast Marching Method (FMM).

“base_data” will be updated with the new values.

Parameters:

  • where_compute – (2D numpy array): A boolean array where True indicates cells to be included in computation.

  • base_data – (2D numpy array): The base data that will propagate.

  • test_data – (2D numpy array, optional): The test data that will be used to validate propagation (we used upstream data only if base_data > test_data).

  • speed – (2D numpy array, optional): The isotropic propagation speed.

  • multiprocess – (bool, optional): Whether to use multiprocessing.

  • dx – (float, optional): The mesh size in x direction.

  • dy – (float, optional): The mesh size in y direction.

Returns:

2D numpy array The solution to the Eikonal equation.

wolfhece.eikonal.count_holes(mask: numpy.ndarray = None)[source]

Count the number of holes in the mask.

wolfhece.eikonal.inpaint_array(data: numpy.ndarray | numpy.ma.MaskedArray, where_compute: numpy.ndarray, test: numpy.ndarray, ignore_last_patches: int = 1, inplace: bool = True, dx: float = 1.0, dy: float = 1.0, NoDataValue: float = 0.0, multiprocess: bool = True) → tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray][source]

Inpaint the array using the Fast Marching Method (FMM).

Main idea:

  • We have a 2D array “data” that we want to inpaint.

  • We have a 2D array “test” that will be used to validate the inpainting.

  • We have a 2D array “where_compute” that indicates where to compute the inpainting.

  • We will use the FMM to propagate the data inside the mask.

  • We will update the data only if the new value is greater than the test data.

  • (We can ignore n greatest patches to avoid computation in some large areas.)

Parameters:

  • data – (2D numpy array): The water level to inpaint.

  • mask – (2D numpy array): The simulation’s Digital Elevation Model (DEM).

  • test – (2D numpy array, optional): The digital terrain model (DTM).

  • ignore_last_patches – (int, optional): The number of last patches to ignore.

  • inplace – (bool, optional): Whether to update the water_level in place.

  • dx – (float, optional): The mesh size in x direction.

  • dy – (float, optional): The mesh size in y direction.

  • NoDataValue – (float, optional): The NoDataValue, used if mask is not explicitly provided (mask atribute or water_level as a Numpy MaskedArray). Default is 0.

  • multiprocess – (bool, optional): Whether to use multiprocessing.

wolfhece.eikonal.inpaint_waterlevel(water_level: numpy.ndarray | numpy.ma.MaskedArray, dem: numpy.ndarray, dtm: numpy.ndarray, ignore_last_patches: int = 1, inplace: bool = True, dx: float = 1.0, dy: float = 1.0, NoDataValue: float = 0.0, multiprocess: bool = True, epsilon: float = 0.001) → tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray][source]

Inpaint the water level using the Fast Marching Method (FMM). Similar to the HOLES.EXE Fortran program.

Assumptions:

  • The simulations are in a steady state.

  • The flood extent is limited by:

    • natural topography (where DEM == DTM)

    • buildings or blocks of buildings

    • protective structures

The goal is to propagate the free surface elevations into the buildings.

We calculate the difference between the DEM (including buildings and walls) and the DTM to identify where the buildings are.

Specifically:

  • if it is natural topography, the differences will be zero or almost zero

  • if it is a building or anthropogenic structure, the differences are significant

We set the elevations of the cells where the difference is zero to a value unreachable by the flood. Thus, only buildings in contact with the flood will be affected and filled.

HOLES.EXE vs Python code:
  • In “holes.exe”, we must provide “in”, “mask”, and “dem” files:

    • “in” is the water level

    • “dem” is the digital terrain model (DTM) associated with the simulation’s topo-bathymetry (not the topo-bathymetry itself)

    • “mask” is the DTM where the buildings are identified and a large value (above the maximum water level) if the cell is not inside a building.

    • The patches are identified by the water level “0.0” in the “in” file.

    • FMM is used and new water levels are calculated and retained if greater than the “mask” value.

    • The DTM is only used in the final part when evaluating the new water depths (Z-DTM).

  • In Python, we must provide the water level, the DEM, and the DTM:

    • The patches will be identified by the buildings array (filtered DEM - DTM).

    • FMM is used and new water levels are calculated and retained if greater than the DTM value.

    • FMM is only propagated in the cells where “buildings = True”.

  • Final results must be the same even if the algorithm is a little bit different.

  • Fortran code demands the “mask” file to be provided (pre-computed/modified by the user), but in Python, we calculate it automatically from the DEM and DTM.

  • We can use “inpaint_array” to be more flexible… by manually providing a “where_compute” and a “test” arrays

Parameters:

  • water_level – (2D numpy array): The water level to inpaint.

  • dem – (2D numpy array): The simulation’s Digital Elevation Model (DEM).

  • dtm – (2D numpy array, optional): The digital terrain model (DTM).

  • ignore_last_patches – (int, optional): The number of last patches to ignore.

  • inplace – (bool, optional): Whether to update the water_level in place.

  • dx – (float, optional): The mesh size in x direction.

  • dy – (float, optional): The mesh size in y direction.

  • NoDataValue – (float, optional): The NoDataValue, used if mask is not explicitly provided (mask attribute or water_level as a Numpy MaskedArray). Default is 0.

  • multiprocess – (bool, optional): Whether to use multiprocessing.