wolfhece.validation.convergence =============================== .. py:module:: wolfhece.validation.convergence .. autoapi-nested-parse:: Check the convergence of Wolf simulations. This module provides tools for checking the convergence of steady state wolf simulations. Authors: HECE - University of Liege, Utashi Ciraane Docile Created on 16th December 2025 Module Contents --------------- .. py:data:: VALUES :value: 'Values' .. py:data:: COORDS :value: 'Coordinates' .. py:data:: DIFFERENCES :value: 'Differences' .. py:data:: DIFFERENCE_MAX :value: 'Residual [Max. dif.]' .. py:data:: DIFFERENCE_MEAN :value: 'Residual [Mean dif.]' .. py:data:: DIFFERENCE_MEDIAN :value: 'Residual [Median dif.]' .. py:data:: DIFFERENCE_PERCENTILE_99 :value: 'Residual [99th percentile dif.]' .. py:data:: CONVERGENCE :value: 'Convergence' .. py:data:: TIME_STEP :value: 'Time step' .. py:data:: TIMES :value: 'Time [s]' .. py:data:: SIM_TIME_STEPS :value: 'Simulation time steps' .. py:data:: H :value: 'H' .. py:data:: QX :value: 'QX' .. py:data:: QY :value: 'QY' .. py:data:: K :value: 'K' .. py:data:: EPS :value: 'EPS' .. py:data:: TOPO :value: 'TOPO' .. py:data:: FRICTION :value: 'Friction' .. py:data:: INFILTRATION :value: 'Infiltration' .. py:data:: ARRAY_KEYS .. py:data:: FONTSIZE :value: 14 .. py:data:: FONTSIZELEGEND :value: 14 .. py:data:: LINEWIDTH :value: 2.0 .. py:data:: TICKPAD :value: 8 .. py:data:: LABELPADX :value: 8 .. py:data:: LABELPADY :value: 12 .. py:data:: BOXPAD :value: 5 .. py:data:: DARKBLUE :value: '#0A1172' .. py:data:: DARKRED :value: '#B00000' .. py:data:: GREY :value: '#7E7E7E' .. py:class:: SteadyStateChecker(simulation_file: str | pathlib.Path | wolfhece.wolfresults_2D.Wolfresults_2D) Class to check the convergence of steady state simulations. .. py:method:: _harmonize_result_indices(from_result: int = None, to_result: int = None) -> numpy.ndarray Return the array of available result indices in an increasing order for the given bounds. :param : The number of results in the simulation. :type : param nb_of_results: int :param : :type : type nb_of_results: int :param : The time step (result index) to start from. If None, starts from 0. :type : param from_result: int, optional :param : :type : type from_result: int, optional :param : The time step (result index) to end at. If None, ends at the last time step. :type : param to_result: int, optional :param : :type : type to_result: int, optional :param : The range of time steps to consider. :type : return: np.ndarray :param : :type : rtype: np.ndarray .. py:method:: compute_convergence(variable: wolfhece.wolfresults_2D.views_2D, threshold: float | int, previous_result: wolfhece.wolf_array.WolfArray, timestep: int, sim_times: list, sim_timesteps: list) -> tuple[dict, wolfhece.wolf_array.WolfArray] Compute the convergence of a given variable at a specific time step. :param : :type : param variable: View of the variable to check for convergence (e.g., views_2D.WATERDEPTH). :param : :type : type variable: views_2D :param : :type : param threshold: The maximum difference threshold for convergence. :param : :type : type threshold: float|int :param : :type : param previous_result: The result of the variable at the previous time step, :param : :type : type previous_result: WolfArray :param : :type : param timestep: The time step at which to check convergence. :param : :type : type timestep: int :param : :type : param sim_times: A list of simulation times. :param : :type : type sim_times: list :param : :type : param sim_timesteps: A list of simulation time steps. :param : :type : type sim_timesteps: list .. py:method:: check_steadiness(from_result: int = None, to_result: int = None, threshold_h: float = None, threshold_q: float = None, threshold_u: float = None, threshold_k: float = None, threshold_eps: float = None, figsize: tuple = None, figax: tuple = None, show: bool = True, turbulence: bool = True, plot_max: bool = True, plot_median: bool = False, plot_percentile_99: bool = True) -> dict[wolfhece.wolfresults_2D.views_2D, list[dict]] Return a dictionary containing the steadiness results of each variable (4 + 2). - if plot is True, plot the convergence curves of existing variables. - if turbulence is True, PLot the two turbulence variables as well (TKE and Epsilon). Check if a simulation has converged for a given variable at a specific time step. Prameters ----------------- :param from_result: Index of the result to start from. If None, starts from the first result. :type from_result: int, optional :param to_result: Index of the result to end at. If None, ends at the last result. :type to_result: int, optional :param threshold_h: Maximum difference threshold for water depth convergence. If None, defaults to 0.05. :type threshold_h: float, optional :param threshold_q: Maximum difference threshold for discharge convergence. If None, defaults to 0.5. :type threshold_q: float, optional :param threshold_u: Maximum difference threshold for velocity convergence. If None, defaults to 0.05. :type threshold_u: float, optional :param threshold_k: Maximum difference threshold for TKE convergence. If None, defaults to 0.001. :type threshold_k: float, optional :param threshold_eps: Maximum difference threshold for Epsilon convergence. If None, defaults to 0.0005. :type threshold_eps: float, optional :param figsize: Size of the figure to plot. If None, defaults to (24, 12). :type figsize: tuple, optional :param plot: Whether to plot the convergence curves. Defaults to True. :type plot: bool, optional :param turbulence: Whether to check the convergence of turbulence variables (TKE and Epsilon). Defaults to True. :type turbulence: bool, optional :param plot_max: Whether to plot the maximum difference curve. Defaults to True. if not Only the 99th percentile and other metrics are plotted. :type plot_max: bool, optional :param plot_median: Whether to plot the median difference curve. Defaults to False. :type plot_median: bool, optional :param plot_percentile_99: Whether to plot the 99th percentile difference curve. Defaults to True. :type plot_percentile_99: bool, optional return: A dictionary containing the steadiness results for each variable. The keys are the variable names (views_2D) and the values are lists of dictionaries containing the convergence results for each time step. :rtype: dict[views_2D, list[dict]] .. py:method:: check_convergence_under_vector(vect: wolfhece.PyVertexvectors.vector, variable: wolfhece.wolfresults_2D.views_2D = None, threshold: float = None, from_result: int = None, to_result: int = None, ylim: tuple = None, figax: tuple = None, show: bool = True) -> list Check if a simulation has converged for a given variable at a specific time step. :param : The variable to check for convergence. :type : param variable: views_2D :param : :type : type variable: views_2D :param : The threshold for convergence ensure the variable does no longer vary beyond this value. :type : param threshold: float :param : :type : type threshold: float :param : :type : return: list of dict containing the congergence report (results at each time step) :param the variable in each dictionnary are: - Values: np.ndarray The values of the variable at the current time step. - Coordinates: np.ndarray The coordinates of the points under the vector at the current time step. - Differences: np.ndarray The difference (variable evolution) from the previous time step. - Maximum difference: float The maximum difference from the previous time step. - Convergence: bool True if the simulation has converged at the current time step, False otherwise. - Time step: int The current time step. True if the simulation has converged, False otherwise. :param : :type : rtype: list of dict .. py:method:: plot_convergence_results(convergence_results: list, variable_name: str = None, figax: tuple = None, threshold: float = None, ylim: tuple = None, show=True) -> None Plot the convergence results for a given variable. :param : :type : param convergence_results: The convergence results to plot. :param : :type : type convergence_results: list :param : :type : param variable_name: The name of the variable to plot (view2D). :param : :type : type variable_name: str, :param : :type : param figax: A tuple containing the figure and axis to plot on. If None, a new figure and axis will be created. :param : :type : type figax: tuple, optional :param : :type : param threshold: The convergence threshold to plot as a horizontal line. If None, no threshold line will be plotted at 0.001. :param : :type : type threshold: float, optional :param : :type : param ylim: The y-axis limits for the plot. If None, the limits will be automatically determined. :param : :type : type ylim: tuple, optional .. py:method:: plot_steadiness_simulation(steadiness_results: dict, threshold: dict = None, figax: tuple = None, figsize: tuple = None, turbulence: bool = True, plot_max: bool = True, plot_median: bool = True, plot_percentile_99: bool = True, show: bool = True) Plot the convergence results for a given variable. :param : The convergence results to plot. :type : param convergence_results: list :param : :type : type convergence_results: list :param : The name of the variable to plot. :type : param variable_name: str :param : :type : type variable_name: str