tilupy.models.lave2D.initsimus

Functions

make_edges_matrices(→ list[numpy.ndarray, numpy.ndarray])

Numbering edges for a regular rectangular grid.

write_simu(→ None)

Prepares all input files required for a Lave2D simulation and saves them in a dedicated folder.

Classes

ModellingDomain

Mesh of simulation topography

Simu

Simulation configuration and input file generator.

Module Contents

Functions

tilupy.models.lave2D.initsimus.make_edges_matrices(nx: int, ny: int) → list[numpy.ndarray, numpy.ndarray]

Numbering edges for a regular rectangular grid.

Considering a matrix M with whape (ny, nx),the convention is that M[0, 0] corresponds to the lower left corner of the matrix, M[0, -1] to the lower right corner, M[-1, 0] to the upper left and M[-1, -1] to the upper right. Edges are numbered cell by cell, counter clockwise : bottom, right, up, left. The first cell is M[0, 0], then cells are processed line by line.

Parameters:

  • nx (int) – Number of faces in the X direction

  • ny (int) – Number of faces in the Y direction

Returns:

  • h_edges (numpy.ndarray) – Matrix containing the global edge indices of all horizontal edges (bottom and top edges of the cells). Rows correspond to y-levels, columns to x-positions.

  • v_edges (numpy.ndarray) – Matrix containing the global edge indices of all vertical edges (left and right edges of the cells). Rows correspond to y-levels, columns to x-positions.

tilupy.models.lave2D.initsimus.write_simu(raster_topo: str, raster_mass: str, tmax: float, dt_im: float, simulation_name: str, lave2D_exe_folder: str, rheology_type: str, rheology_params: dict, folder_out: str = None) → None

Prepares all input files required for a Lave2D simulation and saves them in a dedicated folder.

Parameters:

  • raster_topo (str) – Name of the ASCII topography file.

  • raster_mass (str) – Name of the ASCII initial mass file.

  • tmax (float) – Maximum simulation time.

  • dt_im (float) – Output image interval (in time steps).

  • simulation_name (str) – Simulation/project name.

  • lave2D_exe_folder (str) – Path to the folder containing “Lave2_Arc.exe” and “vf2marc.exe”.

  • rheology_type (str) – Rheology to use for the simulation.

  • rheology_params (dict) –

    Necessary parameters for the rheology. For this case:

    • tau_rho

    • K_tau

  • folder_out (str, optional) – Output folder where simulation inputs will be stored.

Return type:

None

Raises:

ValueError – If the rheology isn’t Herschel_Bulkley.

Classes

class tilupy.models.lave2D.initsimus.ModellingDomain(raster: numpy.ndarray = None, xmin: float = 0, ymin: float = 0, nx: int = None, ny: int = None, dx: float = 1, dy: float = 1)

Mesh of simulation topography

This class represents a structured 2D mesh built either from a raster or from user-specified dimensions and spacing. It stores the topographic data (z), the grid geometry (x, y, dx, dy, nx, ny), and the numbering of edges used for discretization of the domain.

Parameters:

  • raster (numpy.ndarray, str, or None, optional) –

    • If numpy.ndarray: used directly as the elevation grid (z).

    • If str: path to a raster file readable by tilupy.raster.read_raster().

    • If None: grid is generated from nx, ny, dx, dy.

  • xmin (float, optional) – Minimum X coordinate of the grid, used if raster is None, by default 0.0.

  • ymin (float, optional) – Minimum Y coordinate of the grid, used if raster is None, by default 0.0.

  • nx (int, optional) – Number of grid points in the X direction, used if raster is None, by default None.

  • ny (int, optional) – Number of grid points in the Y direction, used if raster is None, by default None.

  • dx (float, optional) – Grid spacing along X, by default 1.0.

  • dy (float, optional) – Grid spacing along Y, by default 1.0.

_z

Elevation values of the mesh nodes ([ny, nx]).

Type:

numpy.ndarray

_nx

Number of grid points along the X direction.

Type:

int

_ny

Number of grid points along the Y direction.

Type:

int

_dx

Grid resolution in the X direction.

Type:

float

_dy

Grid resolution in the Y direction.

Type:

float

_x

Array of X coordinates.

Type:

numpy.ndarray

_y

Array of Y coordinates.

Type:

numpy.ndarray

_h_edges

Matrix of horizontal edge numbers ([ny, nx-1]).

Type:

numpy.ndarray

_v_edges

Matrix of vertical edge numbers ([ny-1, nx]).

Type:

numpy.ndarray

set_edges() → None

Compute and assign horizontal and vertical edge number.

Calls tilupy.initsimus.make_edges_matrices() to build the edge numbering for the grid defined by nx and ny. Results are stored in attributes _h_edges and _v_edges.

get_edge(xcoord: float, ycoord: float, cardinal: str) → int

Get edge number for given coordinates and cardinal direction

Parameters:

  • xcoord (float) – X coordinate of the point.

  • ycoord (float) – Y coordinate of the point.

  • cardinal (str) –

    Cardinal direction of the edge (‘N’, ‘S’, ‘E’, ‘W’):

    • ’N’: top edge of the cell

    • ’S’: bottom edge of the cell

    • ’E’: right edge of the cell

    • ’W’: left edge of the cell

Returns:

Edge number corresponding to the requested location and direction.

Return type:

int

Raises:

AssertionError – If set_edges() has not been called before (i.e. _h_edges and _v_edges are None).

get_edges(xcoords: numpy.ndarray, ycoords: numpy.ndarray, cardinal: str, from_extremities: bool = True) → dict[str:list[int]]

Get edges numbers for a set of coordinates and cardinals direction.

If from_extremities is True, xcoords and ycoords are treated as the extremities of a segment.

Parameters:

  • xcoords (np.ndarray or list) – X coordinates of points. If from_extremities is True, indicated (xmin, xmax).

  • ycoords (np.ndarray or list) – Y coordinates of points. If from_extremities is True, indicated (ymin, ymax).

  • cardinal (str) – Cardinal directions to extract, any combination of {‘N’, ‘S’, ‘E’, ‘W’}. Example: “NS” will return both north and south edges.

  • from_extremities (bool, optional) – If True, xcoords and ycoords are considered as the endpoints of a line, by default True

Returns:

dict[str – Dictionary where keys are the requested cardinals and values are sorted lists of unique edge numbers.

Return type:

list[int]]

class tilupy.models.lave2D.initsimus.Simu(folder: str, name: str)

Simulation configuration and input file generator.

This class manages the setup of lave2D. It creates the necessary input files (topography, numeric parameters, rheology, boundary conditions, initial mass) that will be read by lave2D.

Parameters:

  • folder (str) – Directory where simulation files are written. Created if it does not exist.

  • name (str) – Base name of the simulation (used as file prefix).

_folder

Path to the directory where simulation input and output files are stored.

Type:

str

_name

Base name of the simulation, used as a prefix for generated files. Must have 8 characters.

Type:

str

_x

Array of X coordinates of the topography grid.

Type:

numpy.ndarray

_y

Array of Y coordinates of the topography grid.

Type:

numpy.ndarray

_z

2D array of topographic elevations.

Type:

numpy.ndarray

_tmax

Maximum simulation time.

Type:

float

_dtsorties

Time step for output results.

Type:

float

set_topography(z: numpy.ndarray | str, x: numpy.ndarray = None, y: numpy.ndarray = None, file_out: str = None) → None

Set simulation topography and write it as an ASCII grid.

Parameters:

  • z (ndarray or str) – Topography values as a 2D NumPy array, or path to a raster file.

  • x (ndarray, optional) – X coordinates of the grid, ignored if z is a file path.

  • y (ndarray, optional) – Y coordinates of the grid, ignored if z is a file path.

  • file_out (str, optional) – Output filename (add “.asc”), by defaults “toposimu.asc”. Filenames are truncated or padded to 8 characters.

Return type:

None

set_numeric_params(tmax: float, dtsorties: float, paray: float = 0.00099, dtinit: float = 0.01, cfl_const: int = 1, CFL: float = 0.2, alpha_cor_pente: float = 1.0) → None

Set numerical simulation parameters and write them to file.

Parameters:

  • tmax (float) – Maximum simulation time.

  • dtsorties (float) – Time step for output results.

  • paray (float, optional) – Hydraulic roughness parameter, by default 0.00099.

  • dtinit (float, optional) – Initial time step, by default 0.01.

  • cfl_const (int, optional) – If 1, CFL condition is constant, by default 1.

  • CFL (float, optional) – Courant-Friedrichs-Lewy number, by default 0.2.

  • alpha_cor_pente (float, optional) – Slope correction coefficient, by default 1.0.

Return type:

None

set_rheology(tau_rho: float, K_tau: float = 0.3) → None

Set Herschel-Bulkley rheology parameters

Rheological parameters are tau/rho and K/tau. See :

  • Coussot, P., 1994. Steady, laminar, flow of concentrated mud suspensions in open channel. Journal of Hydraulic Research 32, 535-559. doi.org/10.1080/00221686.1994.9728354

    –> Eq 8 and text after eq 22 for the default value of K/tau

  • Rickenmann, D. et al., 2006. Comparison of 2D debris-flow simulation models with field events. Computational Geosciences 10, 241-264. doi.org/10.1007/s10596-005-9021-3

    –> Eq 9

tau_rhofloat

Yield stress divided by density (\(\tau/\rho\)).

K_taufloat, optional

Consistency index divided by yield stress (\(K/\tau\)). By default 0.3, following Rickenmann (2006).

Return type:

None

set_boundary_conditions(xcoords: list, ycoords: list, cardinal: str, discharges: list | float, times: list = None, thicknesses: list = None, tmax: float = 9999, discharge_from_volume: bool = False) → None

Define and write inflow hydrograph boundary conditions.

Parameters:

  • xcoords (list) – X coordinates of boundary location (two values for segment ends).

  • ycoords (list) – Y coordinates of boundary location (two values for segment ends).

  • cardinal (str) – Boundary orientation (‘N’, ‘S’, ‘E’, ‘W’).

  • discharges (list or float) – If times is None: interpreted as inflow volume (\(m^3\)). Else: Interpreted as discharge values (\(m^3/s\)) at each time step.

  • times (list, optional) – Time vector associated with discharges. If None, a synthetic hydrograph is built from volume. By default None.

  • thicknesses (list, optional) – Flow thicknesses for each time step. If None, put 1m everywhere. By default None.

  • tmax (float, optional) – Maximum time for synthetic hydrograph generation, by default 9999.

  • discharge_from_volume (bool, optional) – If True, discharges are computed from inflow volume, by default False. Not used.

Return type:

None

Raises:

AttributeError – If no topography not been set.

set_init_mass(mass_raster: str, h_min: float = 0.01) → None

Set initial debris-flow mass from a raster file.

Reads an ASCII raster of initial thickness and interpolates it onto the simulation grid cell centers.

Parameters:

  • mass_raster (str) – Path to raster file containing initial mass thickness.

  • h_min (float, optional) – Minimum non-zero thickness assigned to the grid. Default is 0.01.

Return type:

None