tilupy.models.lave2D.initsimus ============================== .. py:module:: tilupy.models.lave2D.initsimus Functions --------- .. autoapisummary:: tilupy.models.lave2D.initsimus.make_edges_matrices tilupy.models.lave2D.initsimus.write_simu Classes ------- .. autoapisummary:: tilupy.models.lave2D.initsimus.ModellingDomain tilupy.models.lave2D.initsimus.Simu Module Contents --------------- Functions ^^^^^^^^^ .. py:function:: 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. :param nx: Number of faces in the X direction :type nx: int :param ny: Number of faces in the Y direction :type ny: int :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. .. py:function:: 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. :param raster_topo: Name of the ASCII topography file. :type raster_topo: str :param raster_mass: Name of the ASCII initial mass file. :type raster_mass: str :param tmax: Maximum simulation time. :type tmax: float :param dt_im: Output image interval (in time steps). :type dt_im: float :param simulation_name: Simulation/project name. :type simulation_name: str :param lave2D_exe_folder: Path to the folder containing "Lave2_Arc.exe" and "vf2marc.exe". :type lave2D_exe_folder: str :param rheology_type: Rheology to use for the simulation. :type rheology_type: str :param rheology_params: Necessary parameters for the rheology. For this case: - tau_rho - K_tau :type rheology_params: dict :param folder_out: Output folder where simulation inputs will be stored. :type folder_out: str, optional :rtype: None :raises ValueError: If the rheology isn't Herschel_Bulkley. Classes ^^^^^^^ .. py:class:: 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. :param raster: - If numpy.ndarray: used directly as the elevation grid (z). - If str: path to a raster file readable by :func:`tilupy.raster.read_raster`. - If None: grid is generated from :data:`nx`, :data:`ny`, :data:`dx`, :data:`dy`. :type raster: numpy.ndarray, str, or None, optional :param xmin: Minimum X coordinate of the grid, used if :data:`raster` is None, by default 0.0. :type xmin: float, optional :param ymin: Minimum Y coordinate of the grid, used if :data:`raster` is None, by default 0.0. :type ymin: float, optional :param nx: Number of grid points in the X direction, used if :data:`raster` is None, by default None. :type nx: int, optional :param ny: Number of grid points in the Y direction, used if :data:`raster` is None, by default None. :type ny: int, optional :param dx: Grid spacing along X, by default 1.0. :type dx: float, optional :param dy: Grid spacing along Y, by default 1.0. :type dy: float, optional .. attribute:: _z Elevation values of the mesh nodes ([ny, nx]). :type: numpy.ndarray .. attribute:: _nx Number of grid points along the X direction. :type: int .. attribute:: _ny Number of grid points along the Y direction. :type: int .. attribute:: _dx Grid resolution in the X direction. :type: float .. attribute:: _dy Grid resolution in the Y direction. :type: float .. attribute:: _x Array of X coordinates. :type: numpy.ndarray .. attribute:: _y Array of Y coordinates. :type: numpy.ndarray .. attribute:: _h_edges Matrix of horizontal edge numbers ([ny, nx-1]). :type: numpy.ndarray .. attribute:: _v_edges Matrix of vertical edge numbers ([ny-1, nx]). :type: numpy.ndarray .. py:method:: set_edges() -> None Compute and assign horizontal and vertical edge number. Calls :func:`tilupy.initsimus.make_edges_matrices` to build the edge numbering for the grid defined by nx and ny. Results are stored in attributes :attr:`_h_edges` and :attr:`_v_edges`. .. py:method:: get_edge(xcoord: float, ycoord: float, cardinal: str) -> int Get edge number for given coordinates and cardinal direction :param xcoord: X coordinate of the point. :type xcoord: float :param ycoord: Y coordinate of the point. :type ycoord: float :param cardinal: 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 :type cardinal: str :returns: Edge number corresponding to the requested location and direction. :rtype: int :raises AssertionError: If :meth:`set_edges` has not been called before (i.e. :attr:`_h_edges` and :attr:`_v_edges` are None). .. py:method:: 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 :data:`from_extremities` is True, xcoords and ycoords are treated as the extremities of a segment. :param xcoords: X coordinates of points. If :data:`from_extremities` is True, indicated (xmin, xmax). :type xcoords: np.ndarray or list :param ycoords: Y coordinates of points. If :data:`from_extremities` is True, indicated (ymin, ymax). :type ycoords: np.ndarray or list :param cardinal: Cardinal directions to extract, any combination of {'N', 'S', 'E', 'W'}. Example: "NS" will return both north and south edges. :type cardinal: str :param from_extremities: If True, :data:`xcoords` and :data:`ycoords` are considered as the endpoints of a line, by default True :type from_extremities: bool, optional :returns: **dict[str** -- Dictionary where keys are the requested cardinals and values are sorted lists of unique edge numbers. :rtype: list[int]] .. py:class:: 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. :param folder: Directory where simulation files are written. Created if it does not exist. :type folder: str :param name: Base name of the simulation (used as file prefix). :type name: str .. attribute:: _folder Path to the directory where simulation input and output files are stored. :type: str .. attribute:: _name Base name of the simulation, used as a prefix for generated files. Must have 8 characters. :type: str .. attribute:: _x Array of X coordinates of the topography grid. :type: numpy.ndarray .. attribute:: _y Array of Y coordinates of the topography grid. :type: numpy.ndarray .. attribute:: _z 2D array of topographic elevations. :type: numpy.ndarray .. attribute:: _tmax Maximum simulation time. :type: float .. attribute:: _dtsorties Time step for output results. :type: float .. py:method:: 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. :param z: Topography values as a 2D NumPy array, or path to a raster file. :type z: ndarray or str :param x: X coordinates of the grid, ignored if :data:`z` is a file path. :type x: ndarray, optional :param y: Y coordinates of the grid, ignored if :data:`z` is a file path. :type y: ndarray, optional :param file_out: Output filename (add ".asc"), by defaults "toposimu.asc". Filenames are truncated or padded to 8 characters. :type file_out: str, optional :rtype: None .. py:method:: 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. :param tmax: Maximum simulation time. :type tmax: float :param dtsorties: Time step for output results. :type dtsorties: float :param paray: Hydraulic roughness parameter, by default 0.00099. :type paray: float, optional :param dtinit: Initial time step, by default 0.01. :type dtinit: float, optional :param cfl_const: If 1, CFL condition is constant, by default 1. :type cfl_const: int, optional :param CFL: Courant-Friedrichs-Lewy number, by default 0.2. :type CFL: float, optional :param alpha_cor_pente: Slope correction coefficient, by default 1.0. :type alpha_cor_pente: float, optional :rtype: None .. py:method:: 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_rho : float Yield stress divided by density (:math:`\tau/\rho`). K_tau : float, optional Consistency index divided by yield stress (:math:`K/\tau`). By default 0.3, following Rickenmann (2006). :rtype: None .. py:method:: 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. :param xcoords: X coordinates of boundary location (two values for segment ends). :type xcoords: list :param ycoords: Y coordinates of boundary location (two values for segment ends). :type ycoords: list :param cardinal: Boundary orientation ('N', 'S', 'E', 'W'). :type cardinal: str :param discharges: If :data:`times` is None: interpreted as inflow volume (:math:`m^3`). Else: Interpreted as discharge values (:math:`m^3/s`) at each time step. :type discharges: list or float :param times: Time vector associated with discharges. If None, a synthetic hydrograph is built from volume. By default None. :type times: list, optional :param thicknesses: Flow thicknesses for each time step. If None, put 1m everywhere. By default None. :type thicknesses: list, optional :param tmax: Maximum time for synthetic hydrograph generation, by default 9999. :type tmax: float, optional :param discharge_from_volume: If True, discharges are computed from inflow volume, by default False. Not used. :type discharge_from_volume: bool, optional :rtype: None :raises AttributeError: If no topography not been set. .. py:method:: 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. :param mass_raster: Path to raster file containing initial mass thickness. :type mass_raster: str :param h_min: Minimum non-zero thickness assigned to the grid. Default is 0.01. :type h_min: float, optional :rtype: None