tilupy.benchmark

Classes

Benchmark

Benchmark of simulation results.

Module Contents

Classes

class tilupy.benchmark.Benchmark

Benchmark of simulation results.

This class groups together all the methods for processing and analyzing the results of various simulation models, allowing, among other things, the comparison of results between models.

_loaded_results

Dictionnary of tilupy.read.Results object for each model specified in load_numerical_result().

Type:

dict[tilupy.read.Results]

_models_tim

Dictionnary of recorded time steps for each model specified in load_numerical_result().

Type:

dict[list]

_simu_z

Topographic elevation for the simulation loaded.

Type:

numpy.ndarray

load_numerical_result(model: str, **kwargs) → None

Load numerical simulation results using tilupy.read.get_results() for a given model and store the tilupy.read.Results object in _loaded_results.

Parameters:

  • model (str) – Name of the model to load. Must be one of the tilupy.read.ALLOWED_MODELS.

  • **kwargs – Keyword arguments passed to the result reader for the specific model.

Raises:

  • ValueError – If size of stored _simu_z is different with new loaded ones.

  • UserWarning – If stored _simu_z are different with new loaded ones.

  • ValueError – If the provided model is not in the allowed list of tilupy.read.ALLOWED_MODELS.

compute_analytic_solution(output: str, solution: Callable, model: str, T: float | list[float], **kwargs) → None

Compute the analytic solution for the given time steps using the provided model.

Parameters:

  • output (str) – Wanted output for the analytical solution. Can be : “h” or “u”.

  • solution (Callable) – Callable object representing the analytic solution model (model from tilupy.analytic_sol.Depth_result)

  • model (str) – Wanted model to compute the analytical solution from. Must be loaded first with load_numerical_result().

  • T (float | list[float]) – Time or list of times at which to compute the analytic solution.

  • **kwargs – Keyword arguments passed to the analytic solution for the specific model.

Raises:

ValueError – If no solution found.

show_output(output: str, model: str, time_steps: float | list[float] = None, show_plot: bool = True, **plot_kwargs) → matplotlib.axes._axes.Axes

Plot output for a given model using tilupy.read.Results.plot().

Parameters:

  • output (str) – Wanted output, need to be in tilupy.read.DATA_NAMES.

  • model (str) – Wanted model to show the data field. Must be loaded with load_numerical_result()

  • time_steps (float | list[float]) – Value or list of time steps display output. If None displays the output for all recorded time steps in the model’s result. By default None.

  • show_plot (bool, optional) – If True, show the plot, by default True.

Returns:

The created plot.

Return type:

matplotlib.axes._axes.Axes

Raises:

ValueError – If model is not loaded.

show_output_profile(output: str, model: str, extraction_method: str = 'axis', extraction_params: dict = None, time_steps: float | list[float] = None, show_plot: bool = True, **plot_kwargs) → matplotlib.axes._axes.Axes

Plot profile from 2D temporal or static output for a given model using tilupy.read.Results.plot_profile().

Parameters:

  • output (str) – Wanted output, need to be in tilupy.read.TEMPORAL_DATA_2D or tilupy.read.STATIC_DATA_2D

  • model (str) – Wanted model to show the output profile. Must be loaded with load_numerical_result()

  • extraction_method (str, optional) – Wanted profile extraction method. See tilupy.utils.get_profile(). By default “axis”.

  • extraction_params (dict, optional) – Profile extraction parameters. See tilupy.utils.get_profile(). Be default None.

  • time_steps (float | list[float], optional) – Value or list of time steps required to extract and display profiles. If None displays the profiles for all recorded time steps in the model’s result. Only available for models. By default None.

  • show_plot (bool, optional) – If True, show the plot, by default True.

Returns:

The created plot.

Return type:

matplotlib.axes._axes.Axes

Raises:

ValueError – If model is not loaded.

show_comparison_temporal1D(output: str, models: list[str], profile_extraction_args: dict = None, analytic_solution: dict = None, time_steps: float | list[float] = None, axes: matplotlib.axes._axes.Axes = None, rows_nb: int = None, cols_nb: int = None, figsize: tuple[float] = None, colors: list = None, linestyles: list[str] = None, plot_kwargs: dict = None, as_kwargs: dict = None, show_plot: bool = True) → matplotlib.axes._axes.Axes

Plot multiple temporal 1D data in the same graph.

Parameters:

  • output (str) – Wanted output, need to be in tilupy.read.TEMPORAL_DATA_1D. If using a tilupy.read.TEMPORAL_DATA_2D, must use profile_extraction_args.

  • models (list[str]) – Wanted models to show the temporal 1D data. Must be loaded with load_numerical_result().

  • profile_extraction_args (dict, optional) – Arguments for profile extraction. See tilupy.utils.get_profile(). By default None.

  • analytic_solution (dict, optional) – Arguments for plotting an analytic solution. See compute_analytic_solution(). By default None.

  • time_steps (float | list[float], optional) – Value or list of time steps required to extract and display profiles. If None displays the profiles for all recorded time steps in the model’s result. Only available for models. By default None.

  • axes (matplotlib.axes._axes.Axes, optional) – Existing matplotlib axe, by default None.

  • rows_nb (int, optional) – Number of rows when plotting multiple time steps. If None automatically computed. By default None.

  • cols_nb (int, optional) – Number of colums when plotting multiple time steps. If None use 3 columns. By default None.

  • figsize (tuple[float], optional) – Size of the plotted figure (Height, Width), by default None.

  • colors (list, optional) – List of colors for each model plotted. If None use “black”. By default None.

  • linestyles (list[str], optional) – List of linestyles for each model plotted. If None use regular straight line. By default None.

  • plot_kwargs (dict, optional) – Additional argument for model’s line, by default None.

  • as_kwargs (dict, optional) – Additional argument for analytical solution’s line, by default None.

  • show_plot (bool, optional) – If True, show the plot, by default True.

Returns:

The created plot.

Return type:

matplotlib.axes._axes.Axes

Raises:

ValueError – If models is not loaded.

get_avrg_result(output: str) → tilupy.read.TemporalResults | tilupy.read.StaticResults

Get average result computed with all loaded model (load_numerical_result()).

Parameters:

output (str) – Wanted average output.

Returns:

Average result output.

Return type:

tilupy.read.TemporalResults | tilupy.read.StaticResults

Raises:

ValueError – If StaticResults0D output wanted.

compute_area(flow_threshold: float = None) → tuple[dict, dict]

Compute area at each recorded time steps, computed with ‘h’, for each model loaded using load_numerical_result().

Parameters:

flow_threshold (float, optional) – Flow threshold to extract flow area, if None use 1% of initial maximal flow height. By default None.

Returns:

area_surf: dict

2D area for each model: area_surf[model] = TemporalResults2D.

area_num: dict

Area value for each model: area_num[model] = TemporalResults0D.

Return type:

tuple[dict, dict]

compute_impacted_area(flow_threshold: float = None) → tuple[dict, dict]

Compute impacted area, computed with ‘h_max’, for each model loaded using load_numerical_result().

Parameters:

flow_threshold (float, optional) – Flow threshold to extract flow area, if None use 1% of initial maximal flow height. By default None.

Returns:

area_surf: dict

2D area for each model: area_surf[model] = StaticResults2D.

area_num: dict

Area value for each model: area_num[model] = area_val.

Return type:

tuple[dict, dict]

compute_impacted_area_rms_from_avrg(flow_threshold: float = None) → tuple[dict, numpy.ndarray]

Compute impacted area, computed with ‘h_max’, RMS with average result for each model loaded using load_numerical_result().

Parameters:

flow_threshold (float, optional) – Flow threshold to extract flow area, if None use 1% of initial maximal flow height. By default None.

Returns:

area_rms: dict

RMS value for each model: area_rms[model] = rms_value.

avrg_area: numpy.ndarray

Average area surface.

Return type:

tuple[dict, np.ndarray]

compute_rms_from_avrg(output: str) → dict

Compute RMS with average result for each model loaded using load_numerical_result().

Parameters:

output (str) – Wanted output to compute the RMS.

Returns:

RMS value for each model: output_rms[model] = rms_value.

Return type:

dict

compute_dist_centermass(flow_threshold: float = None) → tuple[dict, dict]

Compute the distance between the initial position of the center of mass and the final furthest point for each model loaded using load_numerical_result().

Parameters:

flow_threshold (float, optional) – Flow threshold to extract flow area, if None use 1% of initial maximal flow height. By default None.

Returns:

init_coord_centermassdict

Coordinates of the initial center of mass for each model: init_coord_centermass[model] = [X, Y, Z].

model_max_distdict

Maximal distance for each model : model_max_dist[model] = dist.

Return type:

tuple[dict, dict]

compute_average_velocity(distance: float = None, look_up_direction: str = 'right', flow_threshold: float = None, **extration_profile_params) → tuple[dict, dict, float, dict]

Compute average velocity for each model loaded using load_numerical_result().

Parameters:

  • distance (float, optional) – Distance used to calculate average speed, if None use maximal_distance/2. By default None.

  • look_up_direction (str, optional) – Direction to look for the flow front, must be “right” or “left”, by default “right”.

  • flow_threshold (float, optional) – Flow threshold when extracting front position from profile, if None use 1% of initial maximal flow height. By default None.

Returns:

model_avrg_vel: dict

Average velocity value for each model: model_avrg_vel[model] = avrg_velocity.

model_time: dict

Time for each model to reach the distance: model_time[model] = time.

distance: float

Distance used to compute the average velocity.

model_pos: dict

Front position of the profile of each model: model_pos[model] = [init_front_pos, final_front_pos, maximal_distance].

Return type:

tuple[dict, dict, float, dict]

compute_rms_from_coussot(coussot_params: dict, look_up_direction: str = 'right', flow_threshold: float = None, **extration_profile_params) → tuple[dict, dict, dict]

Compute RMS with Coussot’s front shape for each model loaded using load_numerical_result().

Parameters:

  • coussot_params (dict) – Arguments for generating Coussot’s solution. See tilupy.analytic_sol.Coussot_shape.

  • look_up_direction (str, optional) – Direction to look for the flow front, must be “right” or “left”, by default “right”.

  • flow_threshold (float, optional) – Flow threshold when extracting front position from profile, if None use 1% of initial maximal flow height. By default None.

Returns:

output_rms: dict

RMS value for each model: output_rms[model] = rms_value.

model_front_pos: dict

Position of Coussot’s profile for each model: model_front_pos[model] = pos_value.

model_coussot: dict

Coussot’s profile for each model: model_coussot[model] = StaticResults1D.

Return type:

tuple[dict, dict, dict]

generate_simulation_comparison_csv(save: bool = False, folder_out: str = None, file_name: str = None, fmt: str = 'csv', available_profile: bool = False, extration_profile_params: dict = None, flow_threshold: float = 0.1, profile_direction: str = 'right', avrg_velocity_distance: float = None, coussot_criteria: dict = None) → None

Generate a csv file summarizing comparison criteria between flow models.

Generates a file grouping comparison criteria between numerical flow models:

  • Criteria integrated throughout the simulation:

    and average velocity calculated from these values (compute_average_velocity()).

  • Criteria for the final time step of the simulation:

  • Numerical criteria:

    • Volume: value of the volume at final time steps (compared to initial volume) and RMS versus initial volume value.

Parameters:

  • save (bool, optional) – If True, save the resulting tab at folder_out. By default False.

  • folder_out (str, optional) – Path to the folder where the file is saved, if None generate “xlsx_results” folder in code folder. By default None

  • file_name (str, optional) – Name of the folder, if None use “results_[models]”. By default None.

  • fmt (str, optional) – Saving format of the table. Can be “csv” or “xlsx”. By default “csv”.

  • available_profile (bool, optional) – If True, calculate criteria requiring a profile: avrg velocity and final front position. By default False.

  • flow_threshold (float, optional) – Flow threshold when extracting front position from profile, by default 1e-1.

  • profile_direction (str, optional) – Direction to look for the flow front, must be “right” or “left”, by default “right”.

  • avrg_velocity_distance (float, optional) – Distance used to calculate average speed, if None use maximal_distance/2. By default None.

  • coussot_criteria (dict, optional) – If None, ignore Coussot criteria. Otherwise, list of arguments to generate a Coussot profile, by default None

Raises:

ValueError – If the file already exists.

generate_analytical_comparison_csv(analytic_solution: dict, save: bool = False, folder_out: str = None, file_name: str = None, fmt: str = 'csv', compute_as_u: bool = True, extration_profile_params: dict = None, flow_threshold: float = None) → None

Generate a csv file summarizing comparison criteria between flow models and analytic solution.

Generates a file grouping comparison criteria between numerical flow models and analytic solution:

  • Criteria integrated throughout the simulation:

    • Total Height: RMS of flow height versus analytical solution.

    • Total Momentum: RMS of flow h*u versus analytical solution.

    • Total Front Position: RMS of flow front versus analytical solution.

  • Criteria for the final time step of the simulation:

    • Final Height: RMS of flow final height versus analytical solution.

    • Flow Front Position: maximum distance traveled by the flow and comparison with the analytic solution.

  • Numerical criteria:

    • Volume: value of the volume at final time steps (compared to initial volume) and RMS versus initial volume value.

Parameters:

  • analytic_solution (dict) – Argument for the analytic solution. See compute_analytic_solution().

  • save (bool, optional) – If True, save the resulting tab at folder_out. By default False.

  • folder_out (str, optional) – Path to the folder where the file is saved, if None generate “xlsx_results” folder in code folder. By default None

  • file_name (str, optional) – Name of the folder, if None use “AS_comparison_[models]”. By default None.

  • fmt (str, optional) – Saving format of the table. Can be “csv” or “xlsx”. By default “csv”.

  • compute_as_u (bool, optional) – If True, compute analytic solution for flow velocity. Can be disabled. By default True.

  • extration_profile_params (dict, optional) – Argument for extracting profile. See tilupy.read.Results.get_profile(). By default None.

  • flow_threshold (float, optional) – Flow threshold when extracting front position from profile, by default None.

Raises:

ValueError – If the file already exists.