tilupy.benchmark ================ .. py:module:: tilupy.benchmark Classes ------- .. autoapisummary:: tilupy.benchmark.Benchmark Module Contents --------------- Classes ^^^^^^^ .. py:class:: 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. .. attribute:: _loaded_results Dictionnary of :class:`tilupy.read.Results` object for each model specified in :meth:`load_numerical_result`. :type: dict[tilupy.read.Results] .. attribute:: _models_tim Dictionnary of recorded time steps for each model specified in :meth:`load_numerical_result`. :type: dict[list] .. attribute:: _simu_z Topographic elevation for the simulation loaded. :type: numpy.ndarray .. py:method:: load_numerical_result(model: str, **kwargs) -> None Load numerical simulation results using :func:`tilupy.read.get_results` for a given model and store the :class:`tilupy.read.Results` object in :attr:`_loaded_results`. :param model: Name of the model to load. Must be one of the :data:`tilupy.read.ALLOWED_MODELS`. :type model: str :param \*\*kwargs: Keyword arguments passed to the result reader for the specific model. :raises ValueError: If size of stored :attr:`_simu_z` is different with new loaded ones. :raises UserWarning: If stored :attr:`_simu_z` are different with new loaded ones. :raises ValueError: If the provided model is not in the allowed list of :data:`tilupy.read.ALLOWED_MODELS`. .. py:method:: 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. :param output: Wanted output for the analytical solution. Can be : "h" or "u". :type output: str :param solution: Callable object representing the analytic solution model (model from :class:`tilupy.analytic_sol.Depth_result`) :type solution: Callable :param model: Wanted model to compute the analytical solution from. Must be loaded first with :meth:`load_numerical_result`. :type model: str :param T: Time or list of times at which to compute the analytic solution. :type T: float | list[float] :param \*\*kwargs: Keyword arguments passed to the analytic solution for the specific model. :raises ValueError: If no solution found. .. py:method:: 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 :meth:`tilupy.read.Results.plot`. :param output: Wanted output, need to be in :data:`tilupy.read.DATA_NAMES`. :type output: str :param model: Wanted model to show the data field. Must be loaded with :meth:`load_numerical_result` :type model: str :param time_steps: 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. :type time_steps: float | list[float] :param show_plot: If True, show the plot, by default True. :type show_plot: bool, optional :returns: The created plot. :rtype: matplotlib.axes._axes.Axes :raises ValueError: If model is not loaded. .. py:method:: 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 :meth:`tilupy.read.Results.plot_profile`. :param output: Wanted output, need to be in :data:`tilupy.read.TEMPORAL_DATA_2D` or :data:`tilupy.read.STATIC_DATA_2D` :type output: str :param model: Wanted model to show the output profile. Must be loaded with :meth:`load_numerical_result` :type model: str :param extraction_method: Wanted profile extraction method. See :func:`tilupy.utils.get_profile`. By default "axis". :type extraction_method: str, optional :param extraction_params: Profile extraction parameters. See :func:`tilupy.utils.get_profile`. Be default None. :type extraction_params: dict, optional :param time_steps: 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. :type time_steps: float | list[float], optional :param show_plot: If True, show the plot, by default True. :type show_plot: bool, optional :returns: The created plot. :rtype: matplotlib.axes._axes.Axes :raises ValueError: If model is not loaded. .. py:method:: 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. :param output: Wanted output, need to be in :data:`tilupy.read.TEMPORAL_DATA_1D`. If using a :data:`tilupy.read.TEMPORAL_DATA_2D`, must use :data:`profile_extraction_args`. :type output: str :param models: Wanted models to show the temporal 1D data. Must be loaded with :meth:`load_numerical_result`. :type models: list[str] :param profile_extraction_args: Arguments for profile extraction. See :func:`tilupy.utils.get_profile`. By default None. :type profile_extraction_args: dict, optional :param analytic_solution: Arguments for plotting an analytic solution. See :meth:`compute_analytic_solution`. By default None. :type analytic_solution: dict, optional :param time_steps: 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. :type time_steps: float | list[float], optional :param axes: Existing matplotlib axe, by default None. :type axes: matplotlib.axes._axes.Axes, optional :param rows_nb: Number of rows when plotting multiple time steps. If None automatically computed. By default None. :type rows_nb: int, optional :param cols_nb: Number of colums when plotting multiple time steps. If None use 3 columns. By default None. :type cols_nb: int, optional :param figsize: Size of the plotted figure (Height, Width), by default None. :type figsize: tuple[float], optional :param colors: List of colors for each model plotted. If None use "black". By default None. :type colors: list, optional :param linestyles: List of linestyles for each model plotted. If None use regular straight line. By default None. :type linestyles: list[str], optional :param plot_kwargs: Additional argument for model's line, by default None. :type plot_kwargs: dict, optional :param as_kwargs: Additional argument for analytical solution's line, by default None. :type as_kwargs: dict, optional :param show_plot: If True, show the plot, by default True. :type show_plot: bool, optional :returns: The created plot. :rtype: matplotlib.axes._axes.Axes :raises ValueError: If models is not loaded. .. py:method:: get_avrg_result(output: str) -> tilupy.read.TemporalResults | tilupy.read.StaticResults Get average result computed with all loaded model (:meth:`load_numerical_result`). :param output: Wanted average output. :type output: str :returns: Average result output. :rtype: tilupy.read.TemporalResults | tilupy.read.StaticResults :raises ValueError: If StaticResults0D output wanted. .. py:method:: compute_area(flow_threshold: float = None) -> tuple[dict, dict] Compute area at each recorded time steps, computed with 'h', for each model loaded using :meth:`load_numerical_result`. :param flow_threshold: Flow threshold to extract flow area, if None use 1% of initial maximal flow height. By default None. :type flow_threshold: float, optional :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. :rtype: tuple[dict, dict] .. py:method:: compute_impacted_area(flow_threshold: float = None) -> tuple[dict, dict] Compute impacted area, computed with 'h_max', for each model loaded using :meth:`load_numerical_result`. :param flow_threshold: Flow threshold to extract flow area, if None use 1% of initial maximal flow height. By default None. :type flow_threshold: float, optional :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. :rtype: tuple[dict, dict] .. py:method:: 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 :meth:`load_numerical_result`. :param flow_threshold: Flow threshold to extract flow area, if None use 1% of initial maximal flow height. By default None. :type flow_threshold: float, optional :returns: area_rms: dict RMS value for each model: area_rms[model] = rms_value. avrg_area: numpy.ndarray Average area surface. :rtype: tuple[dict, np.ndarray] .. py:method:: compute_rms_from_avrg(output: str) -> dict Compute RMS with average result for each model loaded using :meth:`load_numerical_result`. :param output: Wanted output to compute the RMS. :type output: str :returns: RMS value for each model: output_rms[model] = rms_value. :rtype: dict .. py:method:: 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 :meth:`load_numerical_result`. :param flow_threshold: Flow threshold to extract flow area, if None use 1% of initial maximal flow height. By default None. :type flow_threshold: float, optional :returns: init_coord_centermass : dict Coordinates of the initial center of mass for each model: init_coord_centermass[model] = [X, Y, Z]. model_max_dist : dict Maximal distance for each model : model_max_dist[model] = dist. :rtype: tuple[dict, dict] .. py:method:: 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 :meth:`load_numerical_result`. :param distance: Distance used to calculate average speed, if None use :data:`maximal_distance/2`. By default None. :type distance: float, optional :param look_up_direction: Direction to look for the flow front, must be "right" or "left", by default "right". :type look_up_direction: str, optional :param flow_threshold: Flow threshold when extracting front position from profile, if None use 1% of initial maximal flow height. By default None. :type flow_threshold: float, optional :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]. :rtype: tuple[dict, dict, float, dict] .. py:method:: 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 :meth:`load_numerical_result`. :param coussot_params: Arguments for generating Coussot's solution. See :class:`tilupy.analytic_sol.Coussot_shape`. :type coussot_params: dict :param look_up_direction: Direction to look for the flow front, must be "right" or "left", by default "right". :type look_up_direction: str, optional :param flow_threshold: Flow threshold when extracting front position from profile, if None use 1% of initial maximal flow height. By default None. :type flow_threshold: float, optional :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. :rtype: tuple[dict, dict, dict] .. py:method:: 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: - Flow Area: flow area value and difference with mean result (:meth:`compute_impacted_area`). - Impacted Zone: RMS of impacted area versus mean result (:meth:`compute_impacted_area_rms_from_avrg`). - Maximal Height: RMS of flow maximal height versus mean result (:meth:`compute_rms_from_avrg`). - Maximal Momentum: RMS of flow maximal mementum versus mean result (:meth:`compute_rms_from_avrg`). - Average Velocity (if profile): time for flow to reach a given distance and average velocity calculated from these values (:meth:`compute_average_velocity`). - Criteria for the final time step of the simulation: - Final Height: RMS of flow final height versus mean result (:meth:`compute_rms_from_avrg`). - Maximal Extension: distance from the initial center of mass and the final furthest point of the flow (:meth:`compute_dist_centermass`). - Flow Front Position (if profile): maximum distance traveled by the flow and comparison with the average result (:meth:`compute_average_velocity`). - Front Shape (optional): RMS of the front shape versus Coussot's theorical front shape (:meth:`compute_rms_from_coussot`). - Numerical criteria: - Volume: value of the volume at final time steps (compared to initial volume) and RMS versus initial volume value. :param save: If True, save the resulting tab at :data:`folder_out`. By default False. :type save: bool, optional :param folder_out: Path to the folder where the file is saved, if None generate "xlsx_results" folder in code folder. By default None :type folder_out: str, optional :param file_name: Name of the folder, if None use "results_[models]". By default None. :type file_name: str, optional :param fmt: Saving format of the table. Can be "csv" or "xlsx". By default "csv". :type fmt: str, optional :param available_profile: If True, calculate criteria requiring a profile: avrg velocity and final front position. By default False. :type available_profile: bool, optional :param flow_threshold: Flow threshold when extracting front position from profile, by default 1e-1. :type flow_threshold: float, optional :param profile_direction: Direction to look for the flow front, must be "right" or "left", by default "right". :type profile_direction: str, optional :param avrg_velocity_distance: Distance used to calculate average speed, if None use :data:`maximal_distance/2`. By default None. :type avrg_velocity_distance: float, optional :param coussot_criteria: If None, ignore Coussot criteria. Otherwise, list of arguments to generate a Coussot profile, by default None :type coussot_criteria: dict, optional :raises ValueError: If the file already exists. .. py:method:: 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. :param analytic_solution: Argument for the analytic solution. See :meth:`compute_analytic_solution`. :type analytic_solution: dict :param save: If True, save the resulting tab at :data:`folder_out`. By default False. :type save: bool, optional :param folder_out: Path to the folder where the file is saved, if None generate "xlsx_results" folder in code folder. By default None :type folder_out: str, optional :param file_name: Name of the folder, if None use "AS_comparison_[models]". By default None. :type file_name: str, optional :param fmt: Saving format of the table. Can be "csv" or "xlsx". By default "csv". :type fmt: str, optional :param compute_as_u: If True, compute analytic solution for flow velocity. Can be disabled. By default True. :type compute_as_u: bool, optional :param extration_profile_params: Argument for extracting profile. See :meth:`tilupy.read.Results.get_profile`. By default None. :type extration_profile_params: dict, optional :param flow_threshold: Flow threshold when extracting front position from profile, by default None. :type flow_threshold: float, optional :raises ValueError: If the file already exists.