tilupy.read =========== .. py:module:: tilupy.read Attributes ---------- .. autoapisummary:: tilupy.read.ALLOWED_MODELS tilupy.read.RAW_STATES tilupy.read.TEMPORAL_DATA_0D tilupy.read.TEMPORAL_DATA_1D tilupy.read.TEMPORAL_DATA_2D tilupy.read.STATIC_DATA_0D tilupy.read.STATIC_DATA_1D tilupy.read.STATIC_DATA_2D tilupy.read.TOPO_DATA_2D tilupy.read.NP_OPERATORS tilupy.read.OTHER_OPERATORS tilupy.read.TIME_OPERATORS tilupy.read.TEMPORAL_DATA tilupy.read.STATIC_DATA tilupy.read.DATA_NAMES Functions --------- .. autoapisummary:: tilupy.read.get_results tilupy.read.use_thickness_threshold Classes ------- .. autoapisummary:: tilupy.read.AbstractResults tilupy.read.TemporalResults tilupy.read.TemporalResults0D tilupy.read.TemporalResults1D tilupy.read.TemporalResults2D tilupy.read.StaticResults tilupy.read.StaticResults0D tilupy.read.StaticResults1D tilupy.read.StaticResults2D tilupy.read.Results Module Contents --------------- Attributes ^^^^^^^^^^ .. py:data:: ALLOWED_MODELS :value: ['shaltop', 'lave2D', 'saval2D'] Allowed models for result reading. .. py:data:: RAW_STATES :value: ['hvert', 'h', 'ux', 'uy'] Raw states at the output of a model. Implemented states : - hvert : Fluid thickness taken vertically - h : Fluid thickness taken normal to topography - ux : X-component of fluid velocity - uy : Y-component of fluid velocity .. py:data:: TEMPORAL_DATA_0D :value: ['ek', 'volume'] Time-varying 0D data. Implemented 0D temporal data : - ek : kinetic energy - volume : Fluid volume Also combine all the assembly possibilities between :data:`TEMPORAL_DATA_2D` and :data:`NP_OPERATORS` (or :data:`OTHER_OPERATORS`), at each point xy following this format: `[TEMPORAL_DATA_2D]_[NP/OTHER_OPERATORS]_xy` For instance with h : - h_max_xy: Maximum value of h over the entire surface for each time step. - h_min_xy: Minimal value of h over the entire surface for each time step. - h_mean_xy: Mean value of h over the entire surface for each time step. - h_std_xy: Standard deviation of h over the entire surface for each time step. - h_sum_xy: Sum of each value of h at each point of the surface for each time step. - h_int_xy: Integrated value of h at each point of the surface for each time step. .. py:data:: TEMPORAL_DATA_1D :value: [] Time-varying 1D data. Combine all the assembly possibilities between :data:`TEMPORAL_DATA_2D` and :data:`NP_OPERATORS` (or :data:`OTHER_OPERATORS`) and with an axis like this: `[TEMPORAL_DATA_2D]_[NP/OTHER_OPERATORS]_[x/y]` For instance with h : - h_max_x: For each Y coordinate, maximum value of h integrating the values of all points on the X axis (along the fixed Y axis) and integrating all time steps, giving hmax(y). - h_max_y: For each X coordinate, maximum value of h integrating the values of all points on the Y axis (along the fixed X axis) and integrating all time steps, giving hmax(x). - h_min_x: For each Y coordinate, minimum value of h integrating the values of all points on the X axis (along the fixed Y axis) and integrating all time steps, giving hmin(y). - h_min_y: For each X coordinate, minimum value of h integrating the values of all points on the Y axis (along the fixed X axis) and integrating all time steps, giving hmin(x). - h_mean_x: For each Y coordinate, mean value of h integrating the values of all points on the X axis (along the fixed Y axis) and integrating all time steps, giving hmean(y). - h_mean_y: For each X coordinate, mean value of h integrating the values of all points on the Y axis (along the fixed X axis) and integrating all time steps, giving hmean(x). - h_std_x: For each Y coordinate, standard deviation of h integrating the values of all points on the X axis (along the fixed Y axis) and integrating all time steps, giving hstd(y). - h_std_y: For each X coordinate, standard deviation of h integrating the values of all points on the Y axis (along the fixed X axis) and integrating all time steps, giving hstd(x). - h_sum_x: For each Y coordinate, sum of each value of h integrating the values of all points on the X axis (along the fixed Y axis) and integrating all time steps, giving hsum(y). - h_sum_y: For each X coordinate, sum of each value of h integrating the values of all points on the Y axis (along the fixed X axis) and integrating all time steps, giving hsum(x). - h_int_x: For each Y coordinate, integrate each value of h integrating the values of all points on the X axis (along the fixed Y axis) and integrating all time steps, giving hint(y). - h_int_y: For each X coordinate, integrate each value of h integrating the values of all points on the Y axis (along the fixed X axis) and integrating all time steps, giving hint(x). .. py:data:: TEMPORAL_DATA_2D :value: ['hvert', 'h', 'u', 'ux', 'uy', 'hu', 'hu2'] Time-varying 2D data. Implemented 2D temporal data : - hvert : Fluid height taken vertically - h : Fluid height taken normal to topography - u : Fluid velocity - ux : X-component of fluid velocity - uy : Y-component of fluid velocity - hu : Momentum flux - hu2 : Convective momentum flux .. py:data:: STATIC_DATA_0D :value: [] Static 0D data. .. py:data:: STATIC_DATA_1D :value: [] Static 1D data. .. py:data:: STATIC_DATA_2D :value: [] Static 2D data. Combine all the assembly possibilities between :data:`TEMPORAL_DATA_2D` and :data:`NP_OPERATORS` (or :data:`OTHER_OPERATORS`) like this: `[TEMPORAL_DATA_2D]_[NP/OTHER_OPERATORS]` For instance with h : - h_max : Maximum value of h at each point on the map, integrating all the time steps. - h_min : Minimum value of h at each point on the map, integrating all the time steps. - h_mean : Mean value of h at each point on the map, integrating all the time steps. - h_std : Standard deviation of h at each point on the map, integrating all the time steps. - h_sum : Sum of h at each point on the map, integrating all the time steps. - h_final : Value of h at each point on the map, for the last time step. - h_init : Value of h at each point on the map, for the first time step. - h_int : Integrated value of h at each point on the map, integrating all the time steps. .. py:data:: TOPO_DATA_2D :value: ['z', 'zinit', 'costh'] Data related to topography. Implemented topographic data : - z : Elevation value of topography - zinit : Initial elevation value of topography (same as z if the topography doesn't change during the flow) - costh : Cosine of the angle between the vertical and the normal to the relief. Factor to transform vertical height (hvert) into normal height (h). .. py:data:: NP_OPERATORS :value: ['max', 'min', 'mean', 'std', 'sum'] Statistical operators. Implemented operators : - max : Maximum - min : Minimum - mean : Mean - std : Standard deviation - sum : Sum .. py:data:: OTHER_OPERATORS :value: ['final', 'init', 'int'] Other operators. Implemented operators : - final : Final value - init : Initial value - int : Integrated value .. py:data:: TIME_OPERATORS :value: ['final', 'init', 'int'] Time-related operators. Implemented operators : - final : Final value - init : Initial value - int : Integrated value .. py:data:: TEMPORAL_DATA :value: ['ek', 'volume', 'hvert', 'h', 'u', 'ux', 'uy', 'hu', 'hu2'] Assembling all temporal data. :data:`TEMPORAL_DATA_0D` + :data:`TEMPORAL_DATA_1D` + :data:`TEMPORAL_DATA_2D` .. py:data:: STATIC_DATA :value: [] Assembling all static data. :data:`STATIC_DATA_0D` + :data:`STATIC_DATA_1D` + :data:`STATIC_DATA_2D` .. py:data:: DATA_NAMES :value: ['ek', 'volume', 'hvert', 'h', 'u', 'ux', 'uy', 'hu', 'hu2'] Assembling all data. :data:`TEMPORAL_DATA` + :data:`STATIC_DATA` Functions ^^^^^^^^^ .. py:function:: get_results(code, **kwargs) -> Results Get simulation results for a given numerical model. Dynamically imports the corresponding reader module from `tilupy.models..read` and instantiates its :class:`tilupy.read.Results` class. :param code: Short name of the simulation model: must be in :data:`ALLOWED_MODELS`. :type code: str :param \*\*kwargs: Additional keyword arguments passed to the :class:`tilupy.read.Results` constructor of the imported module. :type \*\*kwargs: dict :returns: Instance of the :class:`tilupy.read.Results` class containing the simulation outputs. :rtype: tilupy.read.Results :raises ModuleNotFoundError: If the module `tilupy.models..read` cannot be imported. :raises AttributeError: If the module does not define a :class:`tilupy.read.Results` class. .. py:function:: use_thickness_threshold(simu: Results, array: numpy.ndarray, h_thresh: float) -> numpy.ndarray Apply a flow thickness threshold to mask simulation results. Values of :data:`array` are set to zero wherever the flow thickness is below the given threshold. :param simu: Simulation result object providing access to thickness data :data:`h`. :type simu: tilupy.read.Results :param array: Array of values to be masked (must be consistent in shape with thickness). :type array: numpy.ndarray :param h_thresh: Thickness threshold. Cells with thickness < :data:`h_thresh` are set to zero. :type h_thresh: float :returns: Thresholded array, with values set to zero where flow thickness is too low. :rtype: numpy.ndarray Classes ^^^^^^^ .. py:class:: AbstractResults(name: str, d: numpy.ndarray, notation: dict = None, **kwargs) Abstract class for :class:`tilupy.read.TemporalResults` and :class:`tilupy.read.StaticResults`. :param name: Name of the property. :type name: str :param d: Values of the property. :type d: numpy.ndarray :param notation: Dictionnary of argument for creating an instance of the class :class:`tilupy.notations.Notation`. If None use the function :func:`tilupy.notations.get_notation`. By default None. :type notation: dict, optional :param kwargs: .. attribute:: _name Name of the property. :type: str .. attribute:: _d Values of the property. :type: numpy.ndarray .. attribute:: _notation Instance of the class :class:`tilupy.notations.Notation`. :type: tilupy.notations.Notation .. py:property:: d :type: numpy.ndarray Get data values. :returns: Attribute :attr:`_d`. :rtype: np.ndarray .. py:property:: name :type: str Get data name. :returns: Attribute :attr:`_name`. :rtype: str .. py:property:: notation :type: tilupy.notations.Notation Get data notation. :returns: Attribute :attr:`_notation`. :rtype: tilupy.notations.Notation .. py:class:: TemporalResults(name: str, d: numpy.ndarray, t: numpy.ndarray, notation: dict = None) Bases: :py:obj:`AbstractResults` Abstract class for time dependent result of simulation. :param name: Name of the property. :type name: str :param d: Values of the property. :type d: numpy.ndarray :param t: Time steps, must match the last dimension of :data:`d`. :type t: numpy.ndarray :param notation: Dictionnary of argument for creating an instance of the class :class:`tilupy.notations.Notation`. If None use the function :func:`tilupy.notations.get_notation`. By default None. :type notation: dict, optional .. attribute:: _name Name of the property. :type: str .. attribute:: _d Values of the property. :type: numpy.ndarray .. attribute:: _notation Instance of the class :class:`tilupy.notations.Notation`. :type: tilupy.notations.Notation .. attribute:: _t Time steps. :type: numpy.ndarray .. py:method:: get_temporal_stat(stat: str) -> StaticResults2D | StaticResults1D Statistical analysis along temporal dimension. :param stat: Statistical operator to apply. Must be implemented in :data:`NP_OPERATORS` or in :data:`OTHER_OPERATORS`. :type stat: str :returns: Static result object depending on the dimensionality of the data. :rtype: tilupy.read.StaticResults2D or tilupy.read.StaticResults1D .. py:method:: get_spatial_stat(stat, axis) :abstractmethod: Abstract method for statistical analysis along spatial dimension. :param stat: Statistical operator to apply. Must be implemented in :data:`NP_OPERATORS` or in :data:`OTHER_OPERATORS`. :type stat: str :param axis: Axis where to do the analysis. :type axis: str .. py:method:: plot(**kwargs) :abstractmethod: Abstract method to plot the temporal evolution of the results. .. py:method:: save(**kwargs) :abstractmethod: Abstract method to save the temporal results. .. py:method:: extract_from_time_step(**kwargs) :abstractmethod: Abstract method to extract data from specific time steps of a TemporalResults. .. py:property:: t :type: numpy.ndarray Get times. :returns: Attribute :attr:`_t` :rtype: numpy.ndarray .. py:class:: TemporalResults0D(name: str, d: numpy.ndarray, t: numpy.ndarray, scalar_names: list[str] = None, notation: dict = None) Bases: :py:obj:`TemporalResults` Class for simulation results described where the data is one or multiple scalar functions of time. :param name: Name of the property. :type name: str :param d: Values of the property. The last dimension correspond to time. It can be a one dimensionnal Nt array, or a two dimensionnal [Nd, Nt] array, where Nt is the legnth of :data:`t`, and Nd correspond to the number of scalar values of interest (e.g. X and Y coordinates of the center of mass / front). :type d: numpy.ndarray :param t: Time steps, must match the last dimension of :data:`d` (size Nt). :type t: numpy.ndarray :param scalar_names: List of length Nd containing the names of the scalar fields (one name per row of d) :type scalar_names: list[str] :param notation: Dictionnary of argument for creating an instance of the class :class:`tilupy.notations.Notation`. If None use the function :func:`tilupy.notations.get_notation`. By default None. :type notation: dict, optional .. attribute:: _name Name of the property. :type: str .. attribute:: _d Values of the property. :type: numpy.ndarray .. attribute:: _notation Instance of the class :class:`tilupy.notations.Notation`. :type: tilupy.notations.Notation .. attribute:: _t Time steps. :type: numpy.ndarray .. attribute:: _scalar_names List of names of the scalar fields. :type: list[str] .. py:method:: plot(ax: matplotlib.axes._axes.Axes = None, figsize: tuple[float] = None, **kwargs) -> matplotlib.axes._axes.Axes Plot the temporal evolution of the 0D results. :param ax: Existing matplotlib window, if None create one. By default None. :type ax: matplotlib.axes._axes.Axes, optional :param figsize: Size of the figure, by default None. :type figsize: tuple[float], optional :returns: The created plot. :rtype: matplotlib.axes._axes.Axes .. py:method:: save() :abstractmethod: Save the temporal 0D results. :raises NotImplementedError: Not implemented yet. .. py:method:: get_spatial_stat(*arg, **kwargs) :abstractmethod: Statistical analysis along spatial dimension for 0D results. :raises NotImplementedError: Not implemented because irrelevant. .. py:method:: extract_from_time_step(time_steps: float | list[float]) -> StaticResults0D | TemporalResults0D Extract data from specific time steps. :param time_steps: Value of time steps to extract data. :type time_steps: float | list[float] :returns: Extracted data, the type depends on the time step. :rtype: tilupy.read.StaticResults0D | tilupy.read.TemporalResults0D .. py:property:: scalar_names :type: list[str] Get list of names of the scalar fields. :returns: Attribute :attr:`_scalar_names`. :rtype: list[str] .. py:class:: TemporalResults1D(name: str, d: numpy.ndarray, t: numpy.ndarray, coords: numpy.ndarray = None, coords_name: str = None, notation: dict = None) Bases: :py:obj:`TemporalResults` Class for simulation results described by one dimension for space and one dimension for time. :param name: Name of the property. :type name: str :param d: Values of the property. The last dimension correspond to time. It can be a one dimensionnal Nt array, or a two dimensionnal [Nd, Nt] array, where Nt is the legnth of :data:`t`, and Nd correspond to the number of scalar values of interest (e.g. X and Y coordinates of the center of mass / front). :type d: numpy.ndarray :param t: Time steps, must match the last dimension of :data:`d` (size Nt). :type t: numpy.ndarray :param coords: Spatial coordinates. :type coords: numpy.ndarray :param coords_name: Spatial coordinates name. :type coords_name: str :param notation: Dictionnary of argument for creating an instance of the class :class:`tilupy.notations.Notation`. If None use the function :func:`tilupy.notations.get_notation`. By default None. :type notation: dict, optional .. attribute:: _name Name of the property. :type: str .. attribute:: _d Values of the property. :type: numpy.ndarray .. attribute:: _notation Instance of the class :class:`tilupy.notations.Notation`. :type: tilupy.notations.Notation .. attribute:: _t Time steps. :type: numpy.ndarray .. attribute:: _coords Spatial coordinates. :type: numpy.ndarray .. attribute:: _coords_name Spatial coordinates name. :type: str .. py:method:: plot(coords=None, plot_type: str = 'simple', figsize: tuple[float] = None, ax: matplotlib.axes._axes.Axes = None, linestyles: list[str] = None, cmap: str = 'viridis', highlighted_curve: bool = False, **kwargs) -> matplotlib.axes._axes.Axes Plot the temporal evolution of the 1D results. :param coords: Specified coordinates, if None uses the coordinates implemented when creating the instance (:attr:`_coords`). By default None. :type coords: numpy.ndarray, optional :param plot_type: Wanted plot : - "simple" : Every curve in the same graph - "multiples" : Every curve in separate graph - "'shotgather" : Shotgather graph By default "simple". :type plot_type: str, optional :param ax: Existing matplotlib window, if None create one. By default None :type ax: matplotlib.axes._axes.Axes, optional :param linestyles: Custom linestyles for each time step. If None, colors and styles are auto-assigned. Used only for "simple". By default None. :type linestyles: list[str], optional :param cmap: Color map for the ploted curves. Used only for "simple". By default "viridis". :type cmap: str, optional :param hightlighted_curved: Option to display all time steps on each graph of the multiples and highlight the curve corresponding to the time step of the subgraph. Used only for "multiples". By default False. :type hightlighted_curved: bool, optional :param kwargs: Additional arguments for plot functions. :type kwargs: dict, optional :returns: The created plot. :rtype: matplotlib.axes._axes.Axes :raises TypeError: If missing coordinates. .. py:method:: save() :abstractmethod: Save the temporal 1D results. :raises NotImplementedError: Not implemented yet. .. py:method:: get_spatial_stat(stat, **kwargs) -> TemporalResults0D Statistical analysis along spatial dimension for 1D results. :param stat: Statistical operator to apply. Must be implemented in :data:`NP_OPERATORS` or in :data:`OTHER_OPERATORS`. :type stat: str :returns: Instance of :class:`tilupy.read.TemporalResults0D`. :rtype: tilupy.read.TemporalResults0D .. py:method:: extract_from_time_step(time_steps: float | list[float]) -> StaticResults1D | TemporalResults1D Extract data from specific time steps. :param time_steps: Value of time steps to extract data. :type time_steps: float | list[float] :returns: Extracted data, the type depends on the time step. :rtype: tilupy.read.StaticResults1D | tilupy.read.TemporalResults1D .. py:property:: coords :type: numpy.ndarray Get spatial coordinates. :returns: Attribute :attr:`_coords` :rtype: numpy.ndarray .. py:property:: coords_name :type: str Get spatial coordinates name. :returns: Attribute :attr:`_coords_name` :rtype: str .. py:class:: TemporalResults2D(name: str, d: numpy.ndarray, t: numpy.ndarray, x: numpy.ndarray = None, y: numpy.ndarray = None, z: numpy.ndarray = None, notation: dict = None) Bases: :py:obj:`TemporalResults` Class for simulation results described by a two dimensional space and one dimension for time. :param name: Name of the property. :type name: str :param d: Values of the property. The last dimension correspond to time. It can be a one dimensionnal Nt array, or a two dimensionnal [Nd, Nt] array, where Nt is the legnth of :data:`t`, and Nd correspond to the number of scalar values of interest (e.g. X and Y coordinates of the center of mass / front). :type d: numpy.ndarray :param t: Time steps, must match the last dimension of :data:`d` (size Nt). :type t: numpy.ndarray :param x: X coordinate values. :type x: numpy.ndarray :param y: X coordinate values. :type y: numpy.ndarray :param z: Elevation values of the surface. :type z: numpy.ndarray :param notation: Dictionnary of argument for creating an instance of the class :class:`tilupy.notation.Notation`. If None use the function :func:`tilupy.notation.get_notation`. By default None. :type notation: dict, optional .. attribute:: _name Name of the property. :type: str .. attribute:: _d Values of the property. :type: numpy.ndarray .. attribute:: _notation Instance of the class :class:`tilupy.notations.Notation`. :type: tilupy.notations.Notation .. attribute:: _t Time steps. :type: numpy.ndarray .. attribute:: _x X coordinate values. :type: numpy.ndarray .. attribute:: _y X coordinate values. :type: numpy.ndarray .. attribute:: _z Elevation values of the surface. :type: numpy.ndarray .. py:method:: plot(x: numpy.ndarray = None, y: numpy.ndarray = None, z: numpy.ndarray = None, plot_multiples: bool = False, file_name: str = None, folder_out: str = None, figsize: tuple[float] = None, dpi: int = None, fmt: str = 'png', sup_plt_fn=None, sup_plt_fn_args=None, **kwargs) -> None Plot the temporal evolution of the 2D results using :func:`pytopomap.plot.plot_maps`. :param x: X coordinate values, if None use :attr:`_x`. By default None. :type x: numpy.ndarray, optional :param y: Y coordinate values, if None use :attr:`_y`. By default None. :type y: numpy.ndarray, optional :param z: Elevation values, if None use :attr:`_z`. By default None. :type z: numpy.ndarray, optional :param file_name: Base name for the output image files, by default None. :type file_name: str, optional :param folder_out: Path to the output folder. If not provides, figures are not saved. By default None. :type folder_out: str, optional :param figsize: Size of the figure, by default None. :type figsize: tuple[float], optional :param dpi: Resolution for saved figures. Only used if :data:`folder_out` is set. By default None. :type dpi: int, optional :param fmt: File format for saving figures, by default "png". :type fmt: str, optional :param sup_plt_fn: A custom function to apply additional plotting on the axes, by default None. :type sup_plt_fn: callable, optional :param sup_plt_fn_args: Arguments to pass to :data:`sup_plt_fn`, by default None. :type sup_plt_fn_args: dict, optional :raises TypeError: If no value for x, y. .. py:method:: save(folder: str = None, file_name: str = None, fmt: str = 'asc', time: str | int = None, x: numpy.ndarray = None, y: numpy.ndarray = None, **kwargs) -> None Save the temporal 2D results. :param folder: Path to the output folder, if None create a folder with :attr:`_name`. By default None. :type folder: str, optional :param file_name: Base name for the output image files, if None use :attr:`_name`. By default None. :type file_name: str, optional :param fmt: File format for saving result, by default "asc". :type fmt: str, optional :param time: Time instants to save the results. - If time is string, must be "initial" or "final". - If time is int, used as index in :attr:`_t`. - If None use every instant in :attr:`_t`. By default None. :type time: str | int, optional :param x: X coordinate values, if None use :attr:`_x`. By default None. :type x: np.ndarray, optional :param y: Y coordinate values, if None use :attr:`_y`. By default None. :type y: np.ndarray, optional :rtype: None :raises ValueError: If no value for x, y. .. py:method:: get_spatial_stat(stat: str, axis: str | int | tuple[int] = None) -> TemporalResults0D | TemporalResults1D Statistical analysis along spatial dimension for 2D results. :param stat: Statistical operator to apply. Must be implemented in :data:`NP_OPERATORS`. :type stat: str :param axis: Axis where to do the analysis: - If axis is string, replace 'x' by 1, 'y' by 0 and 'xy' by (0, 1). - If axis is int, only use 0 or 1. - If None use (0, 1). By default None. :type axis: tuple[int] :returns: Instance of :class:`tilupy.read.TemporalResults0D` or :class:`tilupy.read.TemporalResults1D`. :rtype: tilupy.read.TemporalResults0D or tilupy.read.TemporalResults1D .. py:method:: extract_from_time_step(time_steps: float | list[float]) -> StaticResults2D | TemporalResults2D Extract data from specific time steps. :param time_steps: Value of time steps to extract data. :type time_steps: float | list[float] :returns: Extracted data, the type depends on the time step. :rtype: tilupy.read.StaticResults2D | tilupy.read.TemporalResults2D .. py:property:: x :type: numpy.ndarray Get X coordinates. :returns: Attribute :attr:`_x`. :rtype: numpy.ndarray .. py:property:: y :type: numpy.ndarray Get Y coordinates. :returns: Attribute :attr:`_y`. :rtype: numpy.ndarray .. py:property:: z :type: numpy.ndarray Get elevations values. :returns: Attribute :attr:`_z`. :rtype: numpy.ndarray .. py:class:: StaticResults(name: str, d: numpy.ndarray, notation: dict = None) Bases: :py:obj:`AbstractResults` Abstract class for result of simulation without time dependence. :param name: Name of the property. :type name: str :param d: Values of the property. :type d: numpy.ndarray :param notation: Dictionnary of argument for creating an instance of the class :class:`tilupy.notations.Notation`. If None use the function :func:`tilupy.notations.get_notation`. By default None. :type notation: dict, optional .. attribute:: _name Name of the property. :type: str .. attribute:: _d Values of the property. :type: numpy.ndarray .. attribute:: _notation Instance of the class :class:`tilupy.notations.Notation`. :type: tilupy.notations.Notation .. py:method:: plot() :abstractmethod: Abstract method to plot the results. .. py:method:: save() :abstractmethod: Abstract method to save the results. .. py:class:: StaticResults0D(name: str, d: numpy.ndarray, notation: dict = None) Bases: :py:obj:`StaticResults` Class for simulation results described where the data is one or multiple scalar. :param name: Name of the property. :type name: str :param d: Values of the property. :type d: numpy.ndarray :param notation: Dictionnary of argument for creating an instance of the class :class:`tilupy.notations.Notation`. If None use the function :func:`tilupy.notations.get_notation`. By default None. :type notation: dict, optional .. attribute:: _name Name of the property. :type: str .. attribute:: _d Values of the property. :type: numpy.ndarray .. attribute:: _notation Instance of the class :class:`tilupy.notations.Notation`. :type: tilupy.notations.Notation .. py:class:: StaticResults1D(name: str, d: numpy.ndarray, coords: numpy.ndarray = None, coords_name: list[str] = None, notation: dict = None) Bases: :py:obj:`StaticResults` Class for simulation results described by one dimension for space. :param name: Name of the property. :type name: str :param d: Values of the property. :type d: numpy.ndarray :param coords: Spatial coordinates. :type coords: numpy.ndarray :param coords_name: Spatial coordinates name. :type coords_name: str :param notation: Dictionnary of argument for creating an instance of the class :class:`tilupy.notations.Notation`. If None use the function :func:`tilupy.notations.get_notation`. By default None. :type notation: dict, optional .. attribute:: _name Name of the property. :type: str .. attribute:: _d Values of the property. :type: numpy.ndarray .. attribute:: _notation Instance of the class :class:`tilupy.notations.Notation`. :type: tilupy.notations.Notation .. attribute:: _coords Spatial coordinates. :type: numpy.ndarray .. attribute:: _coords_name Spatial coordinates name. :type: str .. py:method:: plot(ax: matplotlib.axes._axes.Axes = None, **kwargs) -> matplotlib.axes._axes.Axes Plot the 1D results. :param ax: Existing matplotlib window, if None create one. By default None. :type ax: matplotlib.axes._axes.Axes, optional :returns: The created plot. :rtype: matplotlib.axes._axes.Axes .. py:property:: coords :type: numpy.ndarray Get spatial coordinates. :returns: Attribute :attr:`_coords` :rtype: numpy.ndarray .. py:property:: coords_name :type: str Get spatial coordinates name. :returns: Attribute :attr:`_coords_name` :rtype: str .. py:class:: StaticResults2D(name: str, d: numpy.ndarray, x: numpy.ndarray = None, y: numpy.ndarray = None, z: numpy.ndarray = None, notation: dict = None) Bases: :py:obj:`StaticResults` Class for simulation results described by a two dimensional space result. Inherits from StaticResults. :param name: Name of the property. :type name: str :param d: Values of the property. :type d: numpy.ndarray :param x: X coordinate values. :type x: numpy.ndarray :param y: X coordinate values. :type y: numpy.ndarray :param z: Elevation values of the surface. :type z: numpy.ndarray :param notation: Dictionnary of argument for creating an instance of the class :class:`tilupy.notations.Notation`. If None use the function :func:`tilupy.notations.get_notation`. By default None. :type notation: dict, optional .. attribute:: _name Name of the property. :type: str .. attribute:: _d Values of the property. :type: numpy.ndarray .. attribute:: _notation Instance of the class :class:`tilupy.notations.Notation`. :type: tilupy.notations.Notation .. attribute:: _x X coordinate values. :type: numpy.ndarray .. attribute:: _y X coordinate values. :type: numpy.ndarray .. attribute:: _z Elevation values of the surface. :type: numpy.ndarray .. py:method:: plot(figsize: tuple[float] = None, x: numpy.ndarray = None, y: numpy.ndarray = None, z: numpy.ndarray = None, sup_plt_fn: Callable = None, sup_plt_fn_args: dict = None, ax: matplotlib.axes._axes.Axes = None, **kwargs) -> matplotlib.axes._axes.Axes Plot the 2D results using :func:`pytopomap.plot.plot_data_on_topo`. :param figsize: Size of the figure, by default None :type figsize: tuple[float], optional :param x: X coordinate values, if None use :attr:`_x`. By default None. :type x: numpy.ndarray, optional :param y: Y coordinate values, if None use :attr:`_y`. By default None. :type y: numpy.ndarray, optional :param z: Elevation values, if None use :attr:`_z`. By default None. :type z: numpy.ndarray, optional :param sup_plt_fn: A custom function to apply additional plotting on the axes, by default None. :type sup_plt_fn: callable, optional :param sup_plt_fn_args: Arguments to pass to :data:`sup_plt_fn`, by default None. :type sup_plt_fn_args: dict, optional :param ax: Existing matplotlib window, if None create one. By default None :type ax: matplotlib.axes._axes.Axes, optional :param kwargs: Additional arguments to pass to :func:`pytopomap.plot.plot_data_on_topo`. :returns: The created plot. :rtype: matplotlib.axes._axes.Axes :raises TypeError: If no value for x, y. .. py:method:: save(folder: str = None, file_name: str = None, fmt: str = 'txt', x: numpy.ndarray = None, y: numpy.ndarray = None, **kwargs) -> None Save the 2D results. :param folder: Path to the output folder, if None create a folder with :attr:`_name`. By default None. :type folder: str, optional :param file_name: Base name for the output image files, if None use :attr:`_name`. By default None. :type file_name: str, optional :param fmt: File format for saving result, by default "txt". :type fmt: str, optional :param x: X coordinate values, if None use :attr:`_x`. By default None. :type x: np.ndarray, optional :param y: Y coordinate values, if None use :attr:`_y`. By default None. :type y: np.ndarray, optional :raises ValueError: If no value for x, y. .. py:method:: get_spatial_stat(stat: str, axis=None) -> StaticResults0D | StaticResults1D Statistical analysis along spatial dimension for 2D results. :param stat: Statistical operator to apply. Must be implemented in :data:`NP_OPERATORS`. :type stat: str :param axis: Axis where to do the analysis: - If axis is string, replace 'x' by 1, 'y' by 0 and 'xy' by (0, 1). - If axis is int, only use 0 or 1. - If None use (0, 1). By default None. :type axis: tuple[int] :returns: Instance of :class:`tilupy.read.StaticResults0D` or :class:`tilupy.read.StaticResults1D`. :rtype: tilupy.read.StaticResults0D or tilupy.read.StaticResults1D .. py:property:: x :type: numpy.ndarray Get X coordinates. :returns: Attribute :attr:`_x`. :rtype: numpy.ndarray .. py:property:: y :type: numpy.ndarray Get Y coordinates. :returns: Attribute :attr:`_y`. :rtype: numpy.ndarray .. py:property:: z :type: numpy.ndarray Get elevations values. :returns: Attribute :attr:`_z`. :rtype: numpy.ndarray .. py:class:: Results(*args, **kwargs) Results of thin-layer model simulation This class is the parent class for all simulation results, whatever the kind of input data. Methods and functions for processing results are given here. Reading results from code specific outputs is done in inhereited classes. This class has global attributes used by all child classes and quick access attributes calculated and stored for easier access to the main results of a simulation. The quick attributes are only computed if needed and can be deleted to clean memory. :param args and kwargs: Specific arguments for each models. .. attribute:: _code Name of the code that generated the result. :type: str .. attribute:: _folder Path to find code files (like parameters). :type: str .. attribute:: _folder_output Path to find the results of the code. .. attribute:: _zinit Surface elevation of the simulation. :type: numpy.ndarray .. attribute:: _tim Lists of recorded time steps. :type: list .. attribute:: _x X-coordinates of the simulation. :type: numpy.ndarray .. attribute:: _y Y-coordinates of the simulation. :type: numpy.ndarray .. attribute:: _dx Cell size along X-coordinates. :type: float .. attribute:: _dy Cell size along Y-coordinates. :type: float .. attribute:: _nx Number of cells along X-coordinates. :type: float .. attribute:: _ny Number of cells along Y-coordinates. :type: float .. attribute:: _h Quick access attributes for fluid height over time. :type: tilupy.read.TemporalResults2D .. attribute:: _h_max Quick access attributes for max fluid hieght over time. :type: tilupy.read.TemporalResults0D .. attribute:: _u Quick access attributes for norm of fluid velocity over time. :type: tilupy.read.TemporalResults2D .. attribute:: _u_max Quick access attributes for max norm of fluid velocity over time. :type: tilupy.read.TemporalResults0D .. attribute:: _costh Quick access attributes for value of cos[theta] at any point on the surface. :type: numpy.ndarray .. py:method:: compute_costh() -> numpy.ndarray Get cos(slope) of topography. :returns: Value of cos[theta] at any point on the surface. :rtype: numpy.ndarray .. py:method:: center_of_mass(h_thresh: float = None) -> TemporalResults0D Compute center of mass coordinates depending on time. :param h_thresh: Value of threshold for the flow height, by default None. :type h_thresh: float, optional :returns: Values of center of mass coordinates. :rtype: tilupy.read.TemporalResults0D .. py:method:: volume(h_thresh: float = None) -> TemporalResults0D Compute flow volume depending on time. :param h_thresh: Value of threshold for the flow height, by default None. :type h_thresh: float, optional :returns: Values of flow volumes. :rtype: tilupy.read.TemporalResults0D .. py:method:: get_output(output_name: str, from_file: bool = True, **kwargs) -> TemporalResults0D | StaticResults2D | TemporalResults2D Get all the available outputs for a simulation : - Topographic outputs : "z", "zinit", "costh" - Temporal 2D outputs : "hvert", "h", "u", "ux", "uy", "hu", "hu2" - Other outputs : "centermass", "volume" It is possible to add operators to temporal 2D outputs : - "max", "mean", "std", "sum", "min", "final", "init", "int" And it is possible to add axis (only if using operators) : - "x", "y", "xy" :param output_name: Name of the wanted output, composed of the output name and potentially an operator and an axis: :data:`output_operator_axis`. :type output_name: str :param from_file: If True, find the output in a specific file. By default True. :type from_file: bool, optional :returns: Wanted output. :rtype: tilupy.read.TemporalResults0D, tilupy.read.StaticResults2D or tilupy.read.TemporalResults2D .. py:method:: clear_quick_results() -> None Clear memory by erasing quick access attributes: :attr:`_h`, :attr:`_h_max`, :attr:`_u`, :attr:`_u_max`, :attr:`_costh`. .. py:method:: get_profile(output: str, extraction_method: str = 'axis', **extraction_params) -> tuple[TemporalResults1D | StaticResults1D, numpy.ndarray] Extract a profile from a 2D data. :param output: Wanted data output. :type output: str :param extraction_mode: Method to extract profiles: - "axis": Extracts a profile along an axis. - "coordinates": Extracts a profile along specified coordinates. - "shapefile": Extracts a profile along a shapefile (polylines). Be default "axis". :type extraction_mode: str, optional :param extraction_params: Different parameters to be entered depending on the extraction method chosen. See :meth:`tilupy.utils.get_profile`. :type extraction_params: dict, optional :returns: profile : tilupy.read.TemporalResults1D | tilupy.read.StaticResults1D Extracted profile. data : numpy.ndarray or float or tuple[nympy.ndarray, nympy.ndarray] Specific output depending on :data:`extraction_mode`: - If :data:`extraction_mode == "axis"`: float Position of the profile. - If :data:`extraction_mode == "coordinates"`: tuple[numpy.ndarray] X coordinates, Y coordinates and distance values. - If :data:`extraction_mode == "shapefile"`: numpy.ndarray Distance values. :rtype: tuple[tilupy.read.TemporalResults1D | tilupy.read.StaticResults1D, np.ndarray] :raises ValueError: If :data:`output` doesn't generate a 2D data. .. py:method:: plot(output: str, from_file: bool = True, h_thresh: float = None, time_steps: float | list[float] = None, save: bool = False, folder_out: str = None, dpi: int = 150, fmt: str = 'png', file_suffix: str = None, file_prefix: str = None, display_plot: bool = True, **plot_kwargs) -> matplotlib.axes._axes.Axes Plot output extracted from model's result. :param output: Wanted output to be plotted. Must be in :data:`DATA_NAMES`. :type output: str :param from_file: If True, find the output in a specific file. By default True. :type from_file: bool, optional :param h_thresh: Threshold value to be taken into account when extracting output, by default None. :type h_thresh: float, optional :param time_steps: Time steps to show when plotting temporal data. If None shows every time steps recorded. By default None. :type time_steps: float or list[float], optional :param save: If True, save the plot as an image to the computer, by default False. :type save: bool, optional :param folder_out: Path to the folder where to save the plot, by default None. :type folder_out: str, optional :param dpi: Resolution for the saved plot, by default 150. :type dpi: int, optional :param fmt: Format of the saved plot, by default "png". :type fmt: str, optional :param file_suffix: Suffix to add to the file name when saving, by default None. :type file_suffix: str, optional :param file_prefix: Prefix to add to the file name when saving, by default None. :type file_prefix: str, optional :param display_plot: If True, enables the display of the plot; otherwise, it disables the display to save memory. By default True. :type display_plot: bool, optional :returns: Wanted plot. :rtype: matplotlib.axes._axes.Axes .. py:method:: plot_profile(output: str, from_file: bool = True, extraction_method: str = 'axis', extraction_params: dict = None, time_steps: float | list[float] = None, save: bool = False, folder_out: str = None, display_plot: bool = True, **plot_kwargs) -> matplotlib.axes._axes.Axes Plot a 1D output extracted from a 2D output. :param output: Wanted 2D output to extract the profile from. Must be in :data:`STATIC_DATA_2D` or in :data:`TEMPORAL_DATA_2D`. :type output: str :param from_file: If True, find the output in a specific file. By default True. :type from_file: bool, optional :param extraction_mode: Method to extract profiles: - "axis": Extracts a profile along an axis. - "coordinates": Extracts a profile along specified coordinates. - "shapefile": Extracts a profile along a shapefile (polylines). Be default "axis". :type extraction_mode: str, optional :param extraction_params: Different parameters to be entered depending on the extraction method chosen. See :meth:`tilupy.utils.get_profile`. :type extraction_params: dict, optional :param time_steps: Time steps to show when plotting temporal data. If None shows every time steps recorded. By default None. :type time_steps: float or list[float], optional :param save: If True, save the plot as an image to the computer, by default False. :type save: bool, optional :param folder_out: Path to the folder where to save the plot, by default None. :type folder_out: str, optional :param display_plot: If True, enables the display of the plot; otherwise, it disables the display to save memory. By default True. :type display_plot: bool, optional :returns: Wanted plot. :rtype: matplotlib.axes._axes.Axes :raises ValueError: If the :data:`output` is not a 2D output. .. py:method:: save(output_name: str, folder_out: str = None, file_name: str = None, fmt: str = 'txt', from_file: bool = True, **kwargs) -> None Save simulation outputs (processed results or topographic data) to disk. Depending on the requested output_name, the method either: - Retrieves a result via :meth:`get_output` and calls its own :meth:`save` method, - Or, for static topography data, writes it directly to a raster file. :param output_name: Name of the variable or processed result to save (e.g., "h", "u_mean_t", "centermass", or topographic data like "zinit"). :type output_name: str :param folder_out: Destination folder for saving files. If None, defaults to :data:`_folder_output/processed`. By default None. :type folder_out: str, optional :param file_name: Base name of the output file (without extension). If None, uses :data:`output_name`. By default None. :type file_name: str, optional :param fmt: Output file format (e.g., "txt", "npy", "asc"), by default "txt". :type fmt: str, optional :param from_file: If True, attempt to read precomputed results from file before computing, by default True. :type from_file: bool, optional :param \*\*kwargs: Extra arguments passed to the underlying save function. For raster data, forwarded to :func:`tilupy.raster.write_raster`. :type \*\*kwargs: dict :raises AssertionError: If neither :data:`folder_out` nor :attr:`_folder_output` is defined. .. py:property:: zinit Get initial topography. :returns: Attribute :attr:`_zinit` :rtype: numpy.ndarray .. py:property:: z Get initial topography, alias for zinit. :returns: Attribute :attr:`_zinit` :rtype: numpy.ndarray .. py:property:: x Get X-coordinates. :returns: Attribute :attr:`_x` :rtype: numpy.ndarray .. py:property:: y Get Y-coordinates. :returns: Attribute :attr:`_y` :rtype: numpy.ndarray .. py:property:: dx Get cell size along X. :returns: Attribute :attr:`_dx` :rtype: numpy.ndarray .. py:property:: dy Get cell size along Y. :returns: Attribute :attr:`_dy` :rtype: numpy.ndarray .. py:property:: nx Get number of cells along X. :returns: Attribute :attr:`_nx` :rtype: numpy.ndarray .. py:property:: ny Get number of cells along Y. :returns: Attribute :attr:`_ny` :rtype: numpy.ndarray .. py:property:: tim Get recorded time steps. :returns: Attribute :attr:`_tim` :rtype: numpy.ndarray .. py:property:: h Get flow thickness. Compute it if not stored. :returns: Attribute :attr:`_h` :rtype: tilupy.read.TemporalResults2D .. py:property:: h_max Get maximum flow thickness. Compute it if not stored. :returns: Attribute :attr:`_h_max` :rtype: tilupy.read.TemporalResults0D .. py:property:: u Get flow velocity. Compute it if not stored. :returns: Attribute :attr:`_u` :rtype: tilupy.read.TemporalResults2D .. py:property:: u_max Get maximum flow velocity. Compute it if not stored. :returns: Attribute :attr:`_u_max` :rtype: tilupy.read.TemporalResults0D .. py:property:: costh Get cos(slope) of topography. Compute it if not stored. :returns: Attribute :attr:`_costh` :rtype: numpy.ndarray