wolfhece.validation.sensitivity_mesh ==================================== .. py:module:: wolfhece.validation.sensitivity_mesh .. autoapi-nested-parse:: Module for Sensitivity Analyses. This module provides tools and functions to perform sensitivity analyses on various simulation outputs. Author: Utashi Ciraane Docile Module Contents --------------- .. py:data:: NEWTON_RAPHSON :value: 'Newton-Raphson' .. py:data:: BISECTION :value: 'Bisection' .. py:data:: MONOTONIC_CONVERGENCE :value: 'Monotonic Convergence' .. py:data:: MONOTONIC_DIVERGENCE :value: 'Monotonic Divergence' .. py:data:: OSCILLATORY_CONVERGENCE :value: 'Oscillatory Convergence' .. py:data:: OSCILLATORY_DIVERGENCE :value: 'Oscillatory Divergence' .. py:class:: RepCell(cells: wolfhece.wolf_array.WolfArray | int, dimensions: Literal['1D', '2D', '3D'] = None, work_in_relative: bool = False) Class to compute the representative cell length based on mesh characteristics. Currently, only a number of cell or WolfArray are totally supported. .. py:attribute:: _array :value: None .. py:attribute:: _dimensions :value: None .. py:attribute:: _nb_cells :value: None .. py:attribute:: _work_in_relative :value: False .. py:property:: work_in_relative :type: bool Return whether the computation of the representative cell length is done in relative terms (True) or absolute terms (False). Relative computation assumes a unit domain size, meaning the total length/area/volume is 1. This formula is mostly used when the mesh is uniform and square/cubic. One can consult https://turbmodels.larc.nasa.gov/bump_sa.html, for more information. :return: Whether to compute the representative cell length in relative terms. :rtype: bool .. py:property:: array :type: wolfhece.wolf_array.WolfArray Return the provided mesh. :return: The WolfArray object. :rtype: WolfArray .. py:property:: dimensions :type: int Return the number of dimensions of the mesh. :return: The number of dimensions. :rtype: int .. py:property:: nb_cells :type: int Return the number of cells in the mesh. In case the mesh is a WolfArray, it returns the number of non-null cells. :return: The number of cells. :rtype: int .. py:property:: length :type: float Compute the representative cell length based on the number of cells and dimensions of the mesh. FIXME Only uniform square/cubic meshes are currently supported for wolfarrays. :return: The representative cell length. :rtype: float .. py:method:: _get_info_from_WolfArray(wolfarray: wolfhece.wolf_array.WolfArray) Get the necessary information from a WolfArray object and populate the attributes accordingly. :param cells: The WolfArray object containing the mesh data. :type cells: WolfArray .. py:method:: compute_representative_cell_length_2D_unstructured_grid(nb_cells: int, sum_of_root_of_average_areas: float | int) -> float Compute the representative cell size of a 2D unstructured mesh. Formula: h = (sum of root of average areas)/N or $h = 1/N * ΣA_p^{1/2}$ FIXME: Kept for unstructured grids or multiblock arrays when needed. :param nb_cells: The number of cells in the mesh. :type nb_cells: int :param sum_of_root_of_average_areas: The sum of the root of average areas of the cells in the mesh. :type sum_of_root_of_average_areas: float|int :return: The representative cell size. :rtype: float .. py:method:: compute_representative_cell_length_3D_unstructured_grid(nb_cells: int, sum_of_cubic_root_of_average_volumes: float | int) -> float Compute the representative cell size of a 3D unstructured mesh. Formula: h = (sum of cubic root of average volumes)/N or $h = 1/N * ΣV_p^{1/3}$ FIXME: Kept for unstructured grids or multiblock arrays when needed. :param nb_cells: The number of cells in the mesh. :type nb_cells: int :param sum_of_cubic_root_of_average_volumes: The sum of the cubic root of average volumes of the cells in the mesh. :type sum_of_cubic_root_of_average_volumes: float|int :return: The representative cell size. :rtype: float .. py:class:: RefinementRatio(cell_length_fine: int | float, cell_length_coarse: int | float) Class to compute the refinement ratio between two meshes based on the number of cells and dimensions of the meshes. Only for uniform square/cubic meshes. .. py:attribute:: _cells_length_fine :value: None .. py:attribute:: _cells_length_coarse :value: None .. py:property:: cells_length_fine :type: int | float Return the cell length of the fine mesh. :return: The cell length of the fine mesh. :rtype: int|float .. py:property:: cells_length_coarse :type: int | float Return the cell length of the coarse mesh. :return: The cell length of the coarse mesh. :rtype: int|float .. py:property:: ratio :type: float Compute the refinement ratio between two meshes. :return: The refinement ratio. :rtype: float .. py:property:: ratio_checked :type: float Check if the cell size ratios are good for sensitivity analysis (Richardson extrapolation). A good ratio is typically greater than 1.3 see Celik et al. (2008). Celik I, Ghia U, Roache P and Freitas C, (2008) ’ Procedure for Estimation and Reporting of Uncertainty due to Discretisation in CFD Applications’, Journal of Fluids Engineering, 130(7), 078001. DOI: 10.1115/1.2960953 :return: The cell size ratio if it is good. :rtype: float .. py:method:: _set_cell_lengths(cell_length_fine: int | float, cell_length_coarse: int | float) Set the cell lengths ensuring that the fine mesh has a smaller cell length than the coarse mesh. .. py:class:: OrderOfConvergence(r21: float, r32: float, s: int, epsilon21: float, epsilon32: float) Class to compute the order of convergence p used in Richardson extrapolation and Grid Convergence Index (GCI). .. py:attribute:: _r21 .. py:attribute:: _r32 .. py:attribute:: _s .. py:attribute:: _epsilon21 .. py:attribute:: _epsilon32 .. py:property:: r21 :type: float Return the refinement ratio between fine and medium meshes (grids). .. py:property:: r32 :type: float .. py:property:: s :type: int Return the sign of grid convergence - (1) for Monotonic convergence (same sign of errors), - (-1) for Oscillatory convergence (different sign of errors). .. py:property:: epsilon21 :type: float Return the absolute difference (error) between fine and medium mesh solutions. .. py:property:: epsilon32 :type: float Return the absolute difference (error) between medium and coarse mesh solutions. .. py:property:: convergence_ratio :type: float Compute the convergence ratio. $C_R = \epsilon_{21} / \epsilon_{32}$ :return: The convergence ratio. :rtype: float .. py:property:: convergence_type :type: str .. py:property:: convergence_check :type: bool Check if the grid convergence is achieved. :return: True if grid convergence is achieved, False otherwise. :rtype: bool .. py:method:: compute_q(p: float) -> float Compute the q value based on the order of convergence and refinement ratios. :param p: The order of convergence. :type p: float :return: The computed q value. :rtype: float .. py:method:: compute_residual_of_p(p: float) -> float Compute the residual of the order of convergence. :param p: The order of convergence. :type p: float :return: The computed residual. :rtype: float .. py:method:: bisection() Compute the order of convergence using the bisection method. :return: The computed order of convergence. :rtype: float .. py:method:: newton_raphson() -> float Compute the order of convergence using the Newton-Raphson method. :param initial_guess: The initial guess for the order of convergence. :type initial_guess: float :param tolerance: The tolerance for convergence. :type tolerance: float :param max_iterations: The maximum number of iterations. :type max_iterations: int :return: The computed order of convergence. :rtype: float .. py:class:: RichardsonExtrapolation(array_fine: wolfhece.wolf_array.WolfArray | int, array_medium: wolfhece.wolf_array.WolfArray | int, array_coarse: wolfhece.wolf_array.WolfArray | int, solution_fine: wolfhece.wolf_array.WolfArray | float | int, solution_medium: wolfhece.wolf_array.WolfArray | float | int, solution_coarse: wolfhece.wolf_array.WolfArray | float | int, dimensions: Literal['2D', '3D'] = None, computation_method: Literal['Bisection', 'Newton-Raphson'] = None, work_in_relative: bool = False) Class to perform Richardson extrapolation and related calculations. .. py:attribute:: _array_fine :value: None .. py:attribute:: _array_medium :value: None .. py:attribute:: _array_coarse :value: None .. py:attribute:: _solution_fine :value: None .. py:attribute:: _solution_medium :value: None .. py:attribute:: _solution_coarse :value: None .. py:attribute:: _computation_method :value: None .. py:property:: computation_method :type: str Return the computation method for the order of convergence. :return: The computation method. :rtype: str .. py:attribute:: _work_in_relative :value: False .. py:property:: work_in_relative :type: bool Return whether the computation of the representative cell length is done in relative terms (True) or absolute terms (False). Relative computation assumes a unit domain size, meaning the total length/area/volume is 1. This formula is mostly used when the mesh is uniform and square/cubic. One can consult https://turbmodels.larc.nasa.gov/bump_sa.html, for more information. :return: Whether to compute the representative cell length in relative terms. :rtype: bool .. py:property:: e21_diff_fine_medium :type: wolfhece.wolf_array.WolfArray | float Return the difference between fine and medium solutions. :return: The difference between fine and medium solutions. :rtype: WolfArray|float .. py:property:: e32_diff_medium_coarse :type: wolfhece.wolf_array.WolfArray | float Return the difference between medium and coarse solutions. :return: The difference between medium and coarse solutions. :rtype: WolfArray|float .. py:property:: s_sign_of_convergence :type: wolfhece.wolf_array.WolfArray | int Return the sign of the convergence based on the differences between solutions. :return: The sign of convergence. :rtype: WolfArray|int .. py:property:: h1_representative_cell_length_fine :type: float Return the representative cell length of the fine mesh. :return: The representative cell length of the fine mesh. :rtype: float .. py:property:: h2_representative_cell_length_medium :type: float Return the representative cell length of the medium mesh. :return: The representative cell length of the medium mesh. :rtype: float .. py:property:: h3_representative_cell_length_coarse :type: float Return the representative cell length of the coarse mesh. :return: The representative cell length of the coarse mesh. :rtype: float .. py:property:: r21_refinement_ratio :type: float Return the refinement ratio between fine and medium meshes. :return: The refinement ratio between fine and medium meshes. :rtype: float .. py:property:: r32_refinement_ratio :type: float Return the refinement ratio between medium and coarse meshes. :return: The refinement ratio between medium and coarse meshes. :rtype: float .. py:method:: set_arrays_and_solutions(array_fine: wolfhece.wolf_array.WolfArray | int, array_medium: wolfhece.wolf_array.WolfArray | int, array_coarse: wolfhece.wolf_array.WolfArray | int, solution_fine: wolfhece.wolf_array.WolfArray | float | int, solution_medium: wolfhece.wolf_array.WolfArray | float | int, solution_coarse: wolfhece.wolf_array.WolfArray | float | int) Set the mesh arrays and mesh solutions (characteristics) for Richardson extrapolation. :param array_fine: The fine mesh array (WolfArray or number of cells). :type array_fine: WolfArray|int :param array_medium: The medium mesh array (WolfArray or number of cells). :type array_medium: WolfArray|int :param array_coarse: The coarse mesh array (WolfArray or number of cells). :type array_coarse: WolfArray|int :param solution_fine: The solution on the fine mesh (WolfArray or float). :type solution_fine: WolfArray|float|int :param solution_medium: The solution on the medium mesh (WolfArray or float). :type solution_medium: WolfArray|float|int :param solution_coarse: The solution on the coarse mesh (WolfArray or float). :type solution_coarse: WolfArray|float|int .. py:method:: difference_between_solutions(coarse: wolfhece.wolf_array.WolfArray | float, fine: wolfhece.wolf_array.WolfArray | float) -> wolfhece.wolf_array.WolfArray | float Compute the difference between two solutions. :param phi1: The first solution value. :type phi1: float :param phi2: The second solution value. :type phi2: float :return: The difference between the two solutions. :rtype: float .. py:method:: sign_of_convergence(epsilon21: float | wolfhece.wolf_array.WolfArray, epsilon32: float | wolfhece.wolf_array.WolfArray) -> wolfhece.wolf_array.WolfArray | int Determine the sign of convergence based on the ratio of errors. :param epsilon21: Error between fine and medium mesh solutions. :type epsilon21: float :param epsilon32: Error between medium and coarse mesh solutions. :type epsilon32: float :return: 1 if the ratio is positive (indicating monotonic convergence), -1 otherwise (indicating oscillatory convergence). :rtype: int .. py:method:: factor_21() -> float Compute the refinement factor between fine and medium meshes. :return: The refinement factor between fine and medium meshes. :rtype: float .. py:method:: factor_31() -> float Compute the refinement factor between fine and coarse meshes. :return: The refinement factor between fine and coarse meshes. :rtype: float .. py:property:: order_of_convergence :type: wolfhece.wolf_array.WolfArray | float Compute the order of convergence p using the specified method. :param compute_method: The method to compute the order of convergence ('Bisection' or 'Newton-Raphson'). Default is Newton-Raphson to avoid convergence issues. :return: The order of convergence p. :rtype: float|WolfArray .. py:property:: extrapolated_solution :type: float | wolfhece.wolf_array.WolfArray Compute the extrapolated solution (ideal mesh) using Richardson extrapolation. :param phi_fine: The solution on the fine mesh. :type phi_fine: float :param phi_medium: The solution on the medium mesh. :type phi_medium: float :param r21: The grid refinement ratio between the fine and medium meshes. :type r21: float :param p: The order of convergence. :type p: float :return: The extrapolated solution. :rtype: float .. py:property:: extrapolated_relative_error_21 :type: float | wolfhece.wolf_array.WolfArray Compute the relative error between the fine mesh solution and the extrapolated solution. :param phi_fine: The solution on the fine mesh. :type phi_fine: float :param phi_extrapolated: The extrapolated solution. :type phi_extrapolated: float :return: The relative error. :rtype: float .. py:method:: compute_relative_error(coarse: float | wolfhece.wolf_array.WolfArray, fine: float | wolfhece.wolf_array.WolfArray) -> float | wolfhece.wolf_array.WolfArray Compute the relative error between two solutions. :param phi1: The first solution value. :type phi1: float :param phi2: The second solution value. :type phi2: float :return: The relative error between the two solutions. :rtype: float .. py:property:: relative_error_21 :type: float | wolfhece.wolf_array.WolfArray Return the relative error between the fine and medium mesh solutions. :return: The relative error between the fine and medium mesh solutions. :rtype: float|WolfArray .. py:property:: relative_error_32 :type: float | wolfhece.wolf_array.WolfArray Return the relative error between the medium and coarse mesh solutions. :return: The relative error between the medium and coarse mesh solutions. :rtype: float|WolfArray .. py:property:: grid_convergence_index_21 :type: float | wolfhece.wolf_array.WolfArray Compute the Grid Convergence Index (GCI) for the fine and medium mesh solutions. see Roache (1994) for more details. Roache P. J. (1994), ’Perspective: A method for uniform reporting of grid refinement studies’, Journal of Fluids Engineering, 116, pp. 405-413 :param rel_error_21: The relative error between the fine and medium mesh solutions. :type rel_error_21: float :param r21: The grid refinement ratio between the fine and medium meshes. :type r21: float :param p: The order of convergence. :type p: float :return: The Grid Convergence Index (GCI). :rtype: float .. py:property:: grid_convergence_index_32 :type: float | wolfhece.wolf_array.WolfArray Compute the Grid Convergence Index (GCI) for the medium and coarse mesh solutions. see Roache (1994) for more details. Roache P. J. (1994), ’Perspective: A method for uniform reporting of grid refinement studies’, Journal of Fluids Engineering, 116, pp. 405-413 :param rel_error_32: The relative error between the medium and coarse mesh solutions. :type rel_error_32: float :param r32: The grid refinement ratio between the medium and coarse meshes. :type r32: float :param p: The order of convergence. :type p: float :return: The Grid Convergence Index (GCI). :rtype: float .. py:property:: AsymptoticRange :type: bool | wolfhece.wolf_array.WolfArray return the investment on computational cost .. py:method:: optimal_refinement_ratio_from_GCI(GCI_target: float) -> float Compute the optimal refinement ratio to achieve a target GCI. :param GCI_target: The target Grid Convergence Index (GCI). :type GCI_target: float :return: The optimal refinement ratio. :rtype: float .. py:method:: plot_extrapolated_solution(ax=None, figure_size: tuple = (8, 6), color='red', title: str = 'Extrapolated Solution', ylabel: str = 'Solution Value', ylim: tuple | None = None, xlim: tuple | None = None, yfactor: int | float = None, label: str = 'Solutions', show: bool = False) -> matplotlib.pyplot.Axes .. py:method:: get_errors_summary(precision=4) -> dict Get a dictionary of errors and related metrics. in the dictionary there are: - E_extr %: extrapolated relative error in percentage - E_rel %: relative error in percentage - GCI %: grid convergence index in percentage - p - Order of convergence - GCI_32: grid convergence index between medium and coarse meshes in percentage :return: A dictionary containing errors and related metrics. :rtype: dict .. py:method:: get_results_summary(precision=None, precision_error=None) -> dict in the dictionary there are: - h fine: representative cell length of the fine mesh - h medium: representative cell length of the medium mesh - h coarse: representative cell length of the coarse mesh - h extrapolated: representative cell length of the extrapolated mesh (infinite cells) - phi fine: solution value for the fine mesh - phi medium: solution value for the medium mesh - phi coarse: solution value for the coarse mesh - phi extrapolated: extrapolated solution value :param self: Description :param precision: Description :return: Description :rtype: dict