wolfhece.validation.convergence
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
- wolfhece.validation.convergence.DIFFERENCE_PERCENTILE_99 = 'Residual [99th percentile dif.]'[source]
- class wolfhece.validation.convergence.SteadyStateChecker(simulation_file: str | pathlib.Path | wolfhece.wolfresults_2D.Wolfresults_2D)[source]
Class to check the convergence of steady state simulations.
- _harmonize_result_indices(from_result: int = None, to_result: int = None) numpy.ndarray[source]
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
- 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][source]
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
- 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]][source]
- 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]]
- 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[source]
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
- plot_convergence_results(convergence_results: list, variable_name: str = None, figax: tuple = None, threshold: float = None, ylim: tuple = None, show=True) None[source]
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
- 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)[source]
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