tilupy.read

Attributes

`ALLOWED_MODELS`	Allowed models for result reading.
`RAW_STATES`	Raw states at the output of a model.
`TEMPORAL_DATA_0D`	Time-varying 0D data.
`TEMPORAL_DATA_1D`	Time-varying 1D data.
`TEMPORAL_DATA_2D`	Time-varying 2D data.
`STATIC_DATA_0D`	Static 0D data.
`STATIC_DATA_1D`	Static 1D data.
`STATIC_DATA_2D`	Static 2D data.
`TOPO_DATA_2D`	Data related to topography.
`NP_OPERATORS`	Statistical operators.
`OTHER_OPERATORS`	Other operators.
`TIME_OPERATORS`	Time-related operators.
`TEMPORAL_DATA`	Assembling all temporal data.
`STATIC_DATA`	Assembling all static data.
`DATA_NAMES`	Assembling all data.

Functions

`get_results`(→ Results)	Get simulation results for a given numerical model.
`use_thickness_threshold`(→ numpy.ndarray)	Apply a flow thickness threshold to mask simulation results.

Classes

`AbstractResults`	Abstract class for `tilupy.read.TemporalResults` and `tilupy.read.StaticResults`.
`TemporalResults`	Abstract class for time dependent result of simulation.
`TemporalResults0D`	Class for simulation results described where the data is one or multiple scalar functions of time.
`TemporalResults1D`	Class for simulation results described by one dimension for space and one dimension for time.
`TemporalResults2D`	Class for simulation results described by a two dimensional space and one dimension for time.
`StaticResults`	Abstract class for result of simulation without time dependence.
`StaticResults0D`	Class for simulation results described where the data is one or multiple scalar.
`StaticResults1D`	Class for simulation results described by one dimension for space.
`StaticResults2D`	Class for simulation results described by a two dimensional space result.
`Results`	Results of thin-layer model simulation

Module Contents

Attributes

tilupy.read.ALLOWED_MODELS = ['shaltop', 'lave2D', 'saval2D']: Allowed models for result reading.

tilupy.read.RAW_STATES = ['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

tilupy.read.TEMPORAL_DATA_0D = ['ek', 'volume']

Time-varying 0D data.

Implemented 0D temporal data :

ek : kinetic energy

volume : Fluid volume

Also combine all the assembly possibilities between TEMPORAL_DATA_2D and NP_OPERATORS (or 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.

tilupy.read.TEMPORAL_DATA_1D = []

Time-varying 1D data.

Combine all the assembly possibilities between TEMPORAL_DATA_2D and NP_OPERATORS (or 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).

tilupy.read.TEMPORAL_DATA_2D = ['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

tilupy.read.STATIC_DATA_0D = []: Static 0D data.

tilupy.read.STATIC_DATA_1D = []: Static 1D data.

tilupy.read.STATIC_DATA_2D = []

Static 2D data.

Combine all the assembly possibilities between TEMPORAL_DATA_2D and NP_OPERATORS (or 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.

tilupy.read.TOPO_DATA_2D = ['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).

tilupy.read.NP_OPERATORS = ['max', 'min', 'mean', 'std', 'sum']

Statistical operators.

Implemented operators :

max : Maximum

min : Minimum

mean : Mean

std : Standard deviation

sum : Sum

tilupy.read.OTHER_OPERATORS = ['final', 'init', 'int']

Other operators.

Implemented operators :

final : Final value

init : Initial value

int : Integrated value

tilupy.read.TIME_OPERATORS = ['final', 'init', 'int']

Time-related operators.

Implemented operators :

final : Final value

init : Initial value

int : Integrated value

tilupy.read.TEMPORAL_DATA = ['ek', 'volume', 'hvert', 'h', 'u', 'ux', 'uy', 'hu', 'hu2']

Assembling all temporal data.

TEMPORAL_DATA_0D + TEMPORAL_DATA_1D + TEMPORAL_DATA_2D

tilupy.read.STATIC_DATA = []

Assembling all static data.

STATIC_DATA_0D + STATIC_DATA_1D + STATIC_DATA_2D

tilupy.read.DATA_NAMES = ['ek', 'volume', 'hvert', 'h', 'u', 'ux', 'uy', 'hu', 'hu2']

Assembling all data.

TEMPORAL_DATA + STATIC_DATA

Functions

tilupy.read.get_results(code, **kwargs) → Results

Get simulation results for a given numerical model.

Dynamically imports the corresponding reader module from tilupy.models.<code>.read and instantiates its tilupy.read.Results class.

Parameters:

code (str) – Short name of the simulation model: must be in ALLOWED_MODELS.
**kwargs (dict) – Additional keyword arguments passed to the tilupy.read.Results constructor of the imported module.

Returns:

Instance of the tilupy.read.Results class containing the simulation outputs.

Return type:

tilupy.read.Results

Raises:

ModuleNotFoundError – If the module tilupy.models.<code>.read cannot be imported.
AttributeError – If the module does not define a tilupy.read.Results class.

tilupy.read.use_thickness_threshold(simu: Results, array: numpy.ndarray, h_thresh: float) → numpy.ndarray

Apply a flow thickness threshold to mask simulation results.

Values of array are set to zero wherever the flow thickness is below the given threshold.

Parameters:

simu (tilupy.read.Results) – Simulation result object providing access to thickness data h.
array (numpy.ndarray) – Array of values to be masked (must be consistent in shape with thickness).
h_thresh (float) – Thickness threshold. Cells with thickness < h_thresh are set to zero.

Returns:

Thresholded array, with values set to zero where flow thickness is too low.

Return type:

numpy.ndarray

Classes

class tilupy.read.AbstractResults(name: str, d: numpy.ndarray, notation: dict = None, **kwargs)

Abstract class for tilupy.read.TemporalResults and tilupy.read.StaticResults.

Parameters:

name (str) – Name of the property.
d (numpy.ndarray) – Values of the property.
notation (dict, optional) – Dictionnary of argument for creating an instance of the class tilupy.notations.Notation. If None use the function tilupy.notations.get_notation(). By default None.
kwargs

_name

Name of the property.

Type:: str

_d

Values of the property.

Type:: numpy.ndarray

_notation

Instance of the class tilupy.notations.Notation.

Type:: tilupy.notations.Notation

property d: numpy.ndarray

Get data values.

Returns:: Attribute _d.
Return type:: np.ndarray

property name: str

Get data name.

Returns:: Attribute _name.
Return type:: str

property notation: tilupy.notations.Notation

Get data notation.

Returns:: Attribute _notation.
Return type:: tilupy.notations.Notation

class tilupy.read.TemporalResults(name: str, d: numpy.ndarray, t: numpy.ndarray, notation: dict = None)

Bases: AbstractResults

Abstract class for time dependent result of simulation.

Parameters:

name (str) – Name of the property.
d (numpy.ndarray) – Values of the property.
t (numpy.ndarray) – Time steps, must match the last dimension of d.
notation (dict, optional) – Dictionnary of argument for creating an instance of the class tilupy.notations.Notation. If None use the function tilupy.notations.get_notation(). By default None.

_name

Name of the property.

Type:: str

_d

Values of the property.

Type:: numpy.ndarray

_notation

Instance of the class tilupy.notations.Notation.

Type:: tilupy.notations.Notation

_t

Time steps.

Type:: numpy.ndarray

get_temporal_stat(stat: str) → StaticResults2D | StaticResults1D

Statistical analysis along temporal dimension.

Parameters:: stat (str) – Statistical operator to apply. Must be implemented in NP_OPERATORS or in OTHER_OPERATORS.
Returns:: Static result object depending on the dimensionality of the data.
Return type:: tilupy.read.StaticResults2D or tilupy.read.StaticResults1D

abstractmethod get_spatial_stat(stat, axis)

Abstract method for statistical analysis along spatial dimension.

Parameters:

stat (str) – Statistical operator to apply. Must be implemented in NP_OPERATORS or in OTHER_OPERATORS.
axis (str) – Axis where to do the analysis.

abstractmethod plot(**kwargs): Abstract method to plot the temporal evolution of the results.

abstractmethod save(**kwargs): Abstract method to save the temporal results.

abstractmethod extract_from_time_step(**kwargs): Abstract method to extract data from specific time steps of a TemporalResults.

property t: numpy.ndarray

Get times.

Returns:: Attribute _t
Return type:: numpy.ndarray

class tilupy.read.TemporalResults0D(name: str, d: numpy.ndarray, t: numpy.ndarray, scalar_names: list[str] = None, notation: dict = None)

Bases: TemporalResults

Class for simulation results described where the data is one or multiple scalar functions of time.

Parameters:

name (str) – Name of the property.
d (numpy.ndarray) – 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 t, and Nd correspond to the number of scalar values of interest (e.g. X and Y coordinates of the center of mass / front).
t (numpy.ndarray) – Time steps, must match the last dimension of d (size Nt).
scalar_names (list[str]) – List of length Nd containing the names of the scalar fields (one name per row of d)
notation (dict, optional) – Dictionnary of argument for creating an instance of the class tilupy.notations.Notation. If None use the function tilupy.notations.get_notation(). By default None.

_name

Name of the property.

Type:: str

_d

Values of the property.

Type:: numpy.ndarray

_notation

Instance of the class tilupy.notations.Notation.

Type:: tilupy.notations.Notation

_t

Time steps.

Type:: numpy.ndarray

_scalar_names

List of names of the scalar fields.

Type:: list[str]

plot(ax: matplotlib.axes._axes.Axes = None, figsize: tuple[float] = None, **kwargs) → matplotlib.axes._axes.Axes

Plot the temporal evolution of the 0D results.

Parameters:

ax (matplotlib.axes._axes.Axes, optional) – Existing matplotlib window, if None create one. By default None.
figsize (tuple[float], optional) – Size of the figure, by default None.

Returns:

The created plot.

Return type:

matplotlib.axes._axes.Axes

abstractmethod save()

Save the temporal 0D results.

Raises:: NotImplementedError – Not implemented yet.

abstractmethod get_spatial_stat(*arg, **kwargs)

Statistical analysis along spatial dimension for 0D results.

Raises:: NotImplementedError – Not implemented because irrelevant.

extract_from_time_step(time_steps: float | list[float]) → StaticResults0D | TemporalResults0D

Extract data from specific time steps.

Parameters:: time_steps (float | list[float]) – Value of time steps to extract data.
Returns:: Extracted data, the type depends on the time step.
Return type:: tilupy.read.StaticResults0D | tilupy.read.TemporalResults0D

property scalar_names: list[str]

Get list of names of the scalar fields.

Returns:: Attribute _scalar_names.
Return type:: list[str]

class tilupy.read.TemporalResults1D(name: str, d: numpy.ndarray, t: numpy.ndarray, coords: numpy.ndarray = None, coords_name: str = None, notation: dict = None)

Bases: TemporalResults

Class for simulation results described by one dimension for space and one dimension for time.

Parameters:

name (str) – Name of the property.
d (numpy.ndarray) – 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 t, and Nd correspond to the number of scalar values of interest (e.g. X and Y coordinates of the center of mass / front).
t (numpy.ndarray) – Time steps, must match the last dimension of d (size Nt).
coords (numpy.ndarray) – Spatial coordinates.
coords_name (str) – Spatial coordinates name.
notation (dict, optional) – Dictionnary of argument for creating an instance of the class tilupy.notations.Notation. If None use the function tilupy.notations.get_notation(). By default None.

_name

Name of the property.

Type:: str

_d

Values of the property.

Type:: numpy.ndarray

_notation

Instance of the class tilupy.notations.Notation.

Type:: tilupy.notations.Notation

_t

Time steps.

Type:: numpy.ndarray

_coords

Spatial coordinates.

Type:: numpy.ndarray

_coords_name

Spatial coordinates name.

Type:: str

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.

Parameters:

coords (numpy.ndarray, optional) – Specified coordinates, if None uses the coordinates implemented when creating the instance (_coords). By default None.
plot_type (str, optional) –
Wanted plot :
- ”simple” : Every curve in the same graph
- ”multiples” : Every curve in separate graph
- “‘shotgather” : Shotgather graph
By default “simple”.
ax (matplotlib.axes._axes.Axes, optional) – Existing matplotlib window, if None create one. By default None
linestyles (list[str], optional) – Custom linestyles for each time step. If None, colors and styles are auto-assigned. Used only for “simple”. By default None.
cmap (str, optional) – Color map for the ploted curves. Used only for “simple”. By default “viridis”.
hightlighted_curved (bool, optional) – 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.
kwargs (dict, optional) – Additional arguments for plot functions.

Returns:

The created plot.

Return type:

matplotlib.axes._axes.Axes

Raises:

TypeError – If missing coordinates.

abstractmethod save()

Save the temporal 1D results.

Raises:: NotImplementedError – Not implemented yet.

get_spatial_stat(stat, **kwargs) → TemporalResults0D

Statistical analysis along spatial dimension for 1D results.

Parameters:: stat (str) – Statistical operator to apply. Must be implemented in NP_OPERATORS or in OTHER_OPERATORS.
Returns:: Instance of tilupy.read.TemporalResults0D.
Return type:: tilupy.read.TemporalResults0D

extract_from_time_step(time_steps: float | list[float]) → StaticResults1D | TemporalResults1D

Extract data from specific time steps.

Parameters:: time_steps (float | list[float]) – Value of time steps to extract data.
Returns:: Extracted data, the type depends on the time step.
Return type:: tilupy.read.StaticResults1D | tilupy.read.TemporalResults1D

property coords: numpy.ndarray

Get spatial coordinates.

Returns:: Attribute _coords
Return type:: numpy.ndarray

property coords_name: str

Get spatial coordinates name.

Returns:: Attribute _coords_name
Return type:: str

class tilupy.read.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: TemporalResults

Class for simulation results described by a two dimensional space and one dimension for time.

Parameters:

name (str) – Name of the property.
d (numpy.ndarray) – 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 t, and Nd correspond to the number of scalar values of interest (e.g. X and Y coordinates of the center of mass / front).
t (numpy.ndarray) – Time steps, must match the last dimension of d (size Nt).
x (numpy.ndarray) – X coordinate values.
y (numpy.ndarray) – X coordinate values.
z (numpy.ndarray) – Elevation values of the surface.
notation (dict, optional) – Dictionnary of argument for creating an instance of the class tilupy.notation.Notation. If None use the function tilupy.notation.get_notation(). By default None.

_name

Name of the property.

Type:: str

_d

Values of the property.

Type:: numpy.ndarray

_notation

Instance of the class tilupy.notations.Notation.

Type:: tilupy.notations.Notation

_t

Time steps.

Type:: numpy.ndarray

_x

X coordinate values.

Type:: numpy.ndarray

_y

X coordinate values.

Type:: numpy.ndarray

_z

Elevation values of the surface.

Type:: numpy.ndarray

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 pytopomap.plot.plot_maps().

Parameters:

x (numpy.ndarray, optional) – X coordinate values, if None use _x. By default None.
y (numpy.ndarray, optional) – Y coordinate values, if None use _y. By default None.
z (numpy.ndarray, optional) – Elevation values, if None use _z. By default None.
file_name (str, optional) – Base name for the output image files, by default None.
folder_out (str, optional) – Path to the output folder. If not provides, figures are not saved. By default None.
figsize (tuple[float], optional) – Size of the figure, by default None.
dpi (int, optional) – Resolution for saved figures. Only used if folder_out is set. By default None.
fmt (str, optional) – File format for saving figures, by default “png”.
sup_plt_fn (callable, optional) – A custom function to apply additional plotting on the axes, by default None.
sup_plt_fn_args (dict, optional) – Arguments to pass to sup_plt_fn, by default None.

Raises:

TypeError – If no value for x, y.

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.

Parameters:

folder (str, optional) – Path to the output folder, if None create a folder with _name. By default None.
file_name (str, optional) – Base name for the output image files, if None use _name. By default None.
fmt (str, optional) – File format for saving result, by default “asc”.
time (str | int, optional) –
Time instants to save the results.
- If time is string, must be “initial” or “final”.
- If time is int, used as index in _t.
- If None use every instant in _t.
By default None.
x (np.ndarray, optional) – X coordinate values, if None use _x. By default None.
y (np.ndarray, optional) – Y coordinate values, if None use _y. By default None.

Return type:

None

Raises:

ValueError – If no value for x, y.

get_spatial_stat(stat: str, axis: str | int | tuple[int] = None) → TemporalResults0D | TemporalResults1D

Statistical analysis along spatial dimension for 2D results.

Parameters:

stat (str) – Statistical operator to apply. Must be implemented in NP_OPERATORS.
axis (tuple[int]) –
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.

Returns:

Instance of tilupy.read.TemporalResults0D or tilupy.read.TemporalResults1D.

Return type:

tilupy.read.TemporalResults0D or tilupy.read.TemporalResults1D

extract_from_time_step(time_steps: float | list[float]) → StaticResults2D | TemporalResults2D

Extract data from specific time steps.

Parameters:: time_steps (float | list[float]) – Value of time steps to extract data.
Returns:: Extracted data, the type depends on the time step.
Return type:: tilupy.read.StaticResults2D | tilupy.read.TemporalResults2D

property x: numpy.ndarray

Get X coordinates.

Returns:: Attribute _x.
Return type:: numpy.ndarray

property y: numpy.ndarray

Get Y coordinates.

Returns:: Attribute _y.
Return type:: numpy.ndarray

property z: numpy.ndarray

Get elevations values.

Returns:: Attribute _z.
Return type:: numpy.ndarray

class tilupy.read.StaticResults(name: str, d: numpy.ndarray, notation: dict = None)

Bases: AbstractResults

Abstract class for result of simulation without time dependence.

Parameters:

name (str) – Name of the property.
d (numpy.ndarray) – Values of the property.
notation (dict, optional) – Dictionnary of argument for creating an instance of the class tilupy.notations.Notation. If None use the function tilupy.notations.get_notation(). By default None.

_name

Name of the property.

Type:: str

_d

Values of the property.

Type:: numpy.ndarray

_notation

Instance of the class tilupy.notations.Notation.

Type:: tilupy.notations.Notation

abstractmethod plot(): Abstract method to plot the results.

abstractmethod save(): Abstract method to save the results.

class tilupy.read.StaticResults0D(name: str, d: numpy.ndarray, notation: dict = None)

Bases: StaticResults

Class for simulation results described where the data is one or multiple scalar.

Parameters:

name (str) – Name of the property.
d (numpy.ndarray) – Values of the property.
notation (dict, optional) – Dictionnary of argument for creating an instance of the class tilupy.notations.Notation. If None use the function tilupy.notations.get_notation(). By default None.

_name

Name of the property.

Type:: str

_d

Values of the property.

Type:: numpy.ndarray

_notation

Instance of the class tilupy.notations.Notation.

Type:: tilupy.notations.Notation

class tilupy.read.StaticResults1D(name: str, d: numpy.ndarray, coords: numpy.ndarray = None, coords_name: list[str] = None, notation: dict = None)

Bases: StaticResults

Class for simulation results described by one dimension for space.

Parameters:

name (str) – Name of the property.
d (numpy.ndarray) – Values of the property.
coords (numpy.ndarray) – Spatial coordinates.
coords_name (str) – Spatial coordinates name.
notation (dict, optional) – Dictionnary of argument for creating an instance of the class tilupy.notations.Notation. If None use the function tilupy.notations.get_notation(). By default None.

_name

Name of the property.

Type:: str

_d

Values of the property.

Type:: numpy.ndarray

_notation

Instance of the class tilupy.notations.Notation.

Type:: tilupy.notations.Notation

_coords

Spatial coordinates.

Type:: numpy.ndarray

_coords_name

Spatial coordinates name.

Type:: str

plot(ax: matplotlib.axes._axes.Axes = None, **kwargs) → matplotlib.axes._axes.Axes

Plot the 1D results.

Parameters:: ax (matplotlib.axes._axes.Axes, optional) – Existing matplotlib window, if None create one. By default None.
Returns:: The created plot.
Return type:: matplotlib.axes._axes.Axes

property coords: numpy.ndarray

Get spatial coordinates.

Returns:: Attribute _coords
Return type:: numpy.ndarray

property coords_name: str

Get spatial coordinates name.

Returns:: Attribute _coords_name
Return type:: str

class tilupy.read.StaticResults2D(name: str, d: numpy.ndarray, x: numpy.ndarray = None, y: numpy.ndarray = None, z: numpy.ndarray = None, notation: dict = None)

Bases: StaticResults

Class for simulation results described by a two dimensional space result. Inherits from StaticResults.

Parameters:

name (str) – Name of the property.
d (numpy.ndarray) – Values of the property.
x (numpy.ndarray) – X coordinate values.
y (numpy.ndarray) – X coordinate values.
z (numpy.ndarray) – Elevation values of the surface.
notation (dict, optional) – Dictionnary of argument for creating an instance of the class tilupy.notations.Notation. If None use the function tilupy.notations.get_notation(). By default None.

_name

Name of the property.

Type:: str

_d

Values of the property.

Type:: numpy.ndarray

_notation

Instance of the class tilupy.notations.Notation.

Type:: tilupy.notations.Notation

_x

X coordinate values.

Type:: numpy.ndarray

_y

X coordinate values.

Type:: numpy.ndarray

_z

Elevation values of the surface.

Type:: numpy.ndarray

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 pytopomap.plot.plot_data_on_topo().

Parameters:

figsize (tuple[float], optional) – Size of the figure, by default None
x (numpy.ndarray, optional) – X coordinate values, if None use _x. By default None.
y (numpy.ndarray, optional) – Y coordinate values, if None use _y. By default None.
z (numpy.ndarray, optional) – Elevation values, if None use _z. By default None.
sup_plt_fn (callable, optional) – A custom function to apply additional plotting on the axes, by default None.
sup_plt_fn_args (dict, optional) – Arguments to pass to sup_plt_fn, by default None.
ax (matplotlib.axes._axes.Axes, optional) – Existing matplotlib window, if None create one. By default None
kwargs – Additional arguments to pass to pytopomap.plot.plot_data_on_topo().

Returns:

The created plot.

Return type:

matplotlib.axes._axes.Axes

Raises:

TypeError – If no value for x, y.

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.

Parameters:

folder (str, optional) – Path to the output folder, if None create a folder with _name. By default None.
file_name (str, optional) – Base name for the output image files, if None use _name. By default None.
fmt (str, optional) – File format for saving result, by default “txt”.
x (np.ndarray, optional) – X coordinate values, if None use _x. By default None.
y (np.ndarray, optional) – Y coordinate values, if None use _y. By default None.

Raises:

ValueError – If no value for x, y.

get_spatial_stat(stat: str, axis=None) → StaticResults0D | StaticResults1D

Statistical analysis along spatial dimension for 2D results.

Parameters:

stat (str) – Statistical operator to apply. Must be implemented in NP_OPERATORS.
axis (tuple[int]) –
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.

Returns:

Instance of tilupy.read.StaticResults0D or tilupy.read.StaticResults1D.

Return type:

tilupy.read.StaticResults0D or tilupy.read.StaticResults1D

property x: numpy.ndarray

Get X coordinates.

Returns:: Attribute _x.
Return type:: numpy.ndarray

property y: numpy.ndarray

Get Y coordinates.

Returns:: Attribute _y.
Return type:: numpy.ndarray

property z: numpy.ndarray

Get elevations values.

Returns:: Attribute _z.
Return type:: numpy.ndarray

class tilupy.read.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.

Parameters:: kwargs (args and) – Specific arguments for each models.

_code

Name of the code that generated the result.

Type:: str

_folder

Path to find code files (like parameters).

Type:: str

_folder_output: Path to find the results of the code.

_zinit

Surface elevation of the simulation.

Type:: numpy.ndarray

_tim

Lists of recorded time steps.

Type:: list

_x

X-coordinates of the simulation.

Type:: numpy.ndarray

_y

Y-coordinates of the simulation.

Type:: numpy.ndarray

_dx

Cell size along X-coordinates.

Type:: float

_dy

Cell size along Y-coordinates.

Type:: float

_nx

Number of cells along X-coordinates.

Type:: float

_ny

Number of cells along Y-coordinates.

Type:: float

_h

Quick access attributes for fluid height over time.

Type:: tilupy.read.TemporalResults2D

_h_max

Quick access attributes for max fluid hieght over time.

Type:: tilupy.read.TemporalResults0D

_u

Quick access attributes for norm of fluid velocity over time.

Type:: tilupy.read.TemporalResults2D

_u_max

Quick access attributes for max norm of fluid velocity over time.

Type:: tilupy.read.TemporalResults0D

_costh

Quick access attributes for value of cos[theta] at any point on the surface.

Type:: numpy.ndarray

compute_costh() → numpy.ndarray

Get cos(slope) of topography.

Returns:: Value of cos[theta] at any point on the surface.
Return type:: numpy.ndarray

center_of_mass(h_thresh: float = None) → TemporalResults0D

Compute center of mass coordinates depending on time.

Parameters:: h_thresh (float, optional) – Value of threshold for the flow height, by default None.
Returns:: Values of center of mass coordinates.
Return type:: tilupy.read.TemporalResults0D

volume(h_thresh: float = None) → TemporalResults0D

Compute flow volume depending on time.

Parameters:: h_thresh (float, optional) – Value of threshold for the flow height, by default None.
Returns:: Values of flow volumes.
Return type:: tilupy.read.TemporalResults0D

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”

Parameters:

output_name (str) – Name of the wanted output, composed of the output name and potentially an operator and an axis: output_operator_axis.
from_file (bool, optional) – If True, find the output in a specific file. By default True.

Returns:

Wanted output.

Return type:

tilupy.read.TemporalResults0D, tilupy.read.StaticResults2D or tilupy.read.TemporalResults2D

clear_quick_results() → None: Clear memory by erasing quick access attributes: _h, _h_max, _u, _u_max, _costh.

get_profile(output: str, extraction_method: str = 'axis', **extraction_params) → tuple[TemporalResults1D | StaticResults1D, numpy.ndarray]

Extract a profile from a 2D data.

Parameters:

output (str) – Wanted data output.
extraction_mode (str, optional) –
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”.
extraction_params (dict, optional) – Different parameters to be entered depending on the extraction method chosen. See tilupy.utils.get_profile().

Returns:

profiletilupy.read.TemporalResults1D | tilupy.read.StaticResults1D

Extracted profile.

datanumpy.ndarray or float or tuple[nympy.ndarray, nympy.ndarray]

Specific output depending on extraction_mode:

If extraction_mode == "axis": float
Position of the profile.

If extraction_mode == "coordinates": tuple[numpy.ndarray]
X coordinates, Y coordinates and distance values.

If extraction_mode == "shapefile": numpy.ndarray
Distance values.

Return type:

tuple[tilupy.read.TemporalResults1D | tilupy.read.StaticResults1D, np.ndarray]

Raises:

ValueError – If output doesn’t generate a 2D data.

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.

Parameters:

output (str) – Wanted output to be plotted. Must be in DATA_NAMES.
from_file (bool, optional) – If True, find the output in a specific file. By default True.
h_thresh (float, optional) – Threshold value to be taken into account when extracting output, by default None.
time_steps (float or list[float], optional) – Time steps to show when plotting temporal data. If None shows every time steps recorded. By default None.
save (bool, optional) – If True, save the plot as an image to the computer, by default False.
folder_out (str, optional) – Path to the folder where to save the plot, by default None.
dpi (int, optional) – Resolution for the saved plot, by default 150.
fmt (str, optional) – Format of the saved plot, by default “png”.
file_suffix (str, optional) – Suffix to add to the file name when saving, by default None.
file_prefix (str, optional) – Prefix to add to the file name when saving, by default None.
display_plot (bool, optional) – If True, enables the display of the plot; otherwise, it disables the display to save memory. By default True.

Returns:

Wanted plot.

Return type:

matplotlib.axes._axes.Axes

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.

Parameters:

output (str) – Wanted 2D output to extract the profile from. Must be in STATIC_DATA_2D or in TEMPORAL_DATA_2D.
from_file (bool, optional) – If True, find the output in a specific file. By default True.
extraction_mode (str, optional) –
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”.
extraction_params (dict, optional) – Different parameters to be entered depending on the extraction method chosen. See tilupy.utils.get_profile().
time_steps (float or list[float], optional) – Time steps to show when plotting temporal data. If None shows every time steps recorded. By default None.
save (bool, optional) – If True, save the plot as an image to the computer, by default False.
folder_out (str, optional) – Path to the folder where to save the plot, by default None.
display_plot (bool, optional) – If True, enables the display of the plot; otherwise, it disables the display to save memory. By default True.

Returns:

Wanted plot.

Return type:

matplotlib.axes._axes.Axes

Raises:

ValueError – If the output is not a 2D output.

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 get_output() and calls its own save() method,

Or, for static topography data, writes it directly to a raster file.

Parameters:

output_name (str) – Name of the variable or processed result to save (e.g., “h”, “u_mean_t”, “centermass”, or topographic data like “zinit”).
folder_out (str, optional) – Destination folder for saving files. If None, defaults to _folder_output/processed. By default None.
file_name (str, optional) – Base name of the output file (without extension). If None, uses output_name. By default None.
fmt (str, optional) – Output file format (e.g., “txt”, “npy”, “asc”), by default “txt”.
from_file (bool, optional) – If True, attempt to read precomputed results from file before computing, by default True.
**kwargs (dict) – Extra arguments passed to the underlying save function. For raster data, forwarded to tilupy.raster.write_raster().

Raises:

AssertionError – If neither folder_out nor _folder_output is defined.

property zinit

Get initial topography.

Returns:: Attribute _zinit
Return type:: numpy.ndarray

property z

Get initial topography, alias for zinit.

Returns:: Attribute _zinit
Return type:: numpy.ndarray

property x

Get X-coordinates.

Returns:: Attribute _x
Return type:: numpy.ndarray

property y

Get Y-coordinates.

Returns:: Attribute _y
Return type:: numpy.ndarray

property dx

Get cell size along X.

Returns:: Attribute _dx
Return type:: numpy.ndarray

property dy

Get cell size along Y.

Returns:: Attribute _dy
Return type:: numpy.ndarray

property nx

Get number of cells along X.

Returns:: Attribute _nx
Return type:: numpy.ndarray

property ny

Get number of cells along Y.

Returns:: Attribute _ny
Return type:: numpy.ndarray

property tim

Get recorded time steps.

Returns:: Attribute _tim
Return type:: numpy.ndarray

property h

Get flow thickness. Compute it if not stored.

Returns:: Attribute _h
Return type:: tilupy.read.TemporalResults2D

property h_max

Get maximum flow thickness. Compute it if not stored.

Returns:: Attribute _h_max
Return type:: tilupy.read.TemporalResults0D

property u

Get flow velocity. Compute it if not stored.

Returns:: Attribute _u
Return type:: tilupy.read.TemporalResults2D

property u_max

Get maximum flow velocity. Compute it if not stored.

Returns:: Attribute _u_max
Return type:: tilupy.read.TemporalResults0D

property costh

Get cos(slope) of topography. Compute it if not stored.

Returns:: Attribute _costh
Return type:: numpy.ndarray