wolfhece.validation.sensitivity_mesh

Module for Sensitivity Analyses. This module provides tools and functions to perform sensitivity analyses on various simulation outputs.

Author: Utashi Ciraane Docile

Module Contents

wolfhece.validation.sensitivity_mesh.NEWTON_RAPHSON = 'Newton-Raphson'

wolfhece.validation.sensitivity_mesh.BISECTION = 'Bisection'

wolfhece.validation.sensitivity_mesh.MONOTONIC_CONVERGENCE = 'Monotonic Convergence'

wolfhece.validation.sensitivity_mesh.MONOTONIC_DIVERGENCE = 'Monotonic Divergence'

wolfhece.validation.sensitivity_mesh.OSCILLATORY_CONVERGENCE = 'Oscillatory Convergence'

wolfhece.validation.sensitivity_mesh.OSCILLATORY_DIVERGENCE = 'Oscillatory Divergence'

class wolfhece.validation.sensitivity_mesh.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.

_array = None

_dimensions = None

_nb_cells = None

_work_in_relative = False

property work_in_relative: 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

property array: wolfhece.wolf_array.WolfArray

Return the provided mesh. :return: The WolfArray object. :rtype: WolfArray

property dimensions: int

Return the number of dimensions of the mesh. :return: The number of dimensions. :rtype: int

property nb_cells: 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

property length: 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

_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

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.

Parameters:

• nb_cells (int) – The number of cells in the mesh.

• sum_of_root_of_average_areas (float|int) – The sum of the root of average areas of the cells in the mesh.

Returns:

The representative cell size.

Return type:

float

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.

Parameters:

• nb_cells (int) – The number of cells in the mesh.

• sum_of_cubic_root_of_average_volumes (float|int) – The sum of the cubic root of average volumes of the cells in the mesh.

Returns:

The representative cell size.

Return type:

float

class wolfhece.validation.sensitivity_mesh.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.

_cells_length_fine = None

_cells_length_coarse = None

property cells_length_fine: int | float

Return the cell length of the fine mesh. :return: The cell length of the fine mesh. :rtype: int|float

property cells_length_coarse: int | float

Return the cell length of the coarse mesh. :return: The cell length of the coarse mesh. :rtype: int|float

property ratio: float

Compute the refinement ratio between two meshes. :return: The refinement ratio. :rtype: float

property ratio_checked: 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

Returns:

The cell size ratio if it is good.

Return type:

float

_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.

class wolfhece.validation.sensitivity_mesh.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).

_r21

_r32

_s

_epsilon21

_epsilon32

property r21: float

Return the refinement ratio between fine and medium meshes (grids).

property r32: float

property s: int

Return the sign of grid convergence - (1) for Monotonic convergence (same sign of errors), - (-1) for Oscillatory convergence (different sign of errors).

property epsilon21: float

Return the absolute difference (error) between fine and medium mesh solutions.

property epsilon32: float

Return the absolute difference (error) between medium and coarse mesh solutions.

property convergence_ratio: float

Compute the convergence ratio. $C_R = epsilon_{21} / epsilon_{32}$ :return: The convergence ratio. :rtype: float

property convergence_type: str

property convergence_check: bool

Check if the grid convergence is achieved. :return: True if grid convergence is achieved, False otherwise. :rtype: bool

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

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

bisection()

Compute the order of convergence using the bisection method. :return: The computed order of convergence. :rtype: float

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

class wolfhece.validation.sensitivity_mesh.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.

_array_fine = None

_array_medium = None

_array_coarse = None

_solution_fine = None

_solution_medium = None

_solution_coarse = None

_computation_method = None

property computation_method: str

Return the computation method for the order of convergence. :return: The computation method. :rtype: str

_work_in_relative = False

property work_in_relative: 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

property e21_diff_fine_medium: wolfhece.wolf_array.WolfArray | float

Return the difference between fine and medium solutions. :return: The difference between fine and medium solutions. :rtype: WolfArray|float

property e32_diff_medium_coarse: wolfhece.wolf_array.WolfArray | float

Return the difference between medium and coarse solutions. :return: The difference between medium and coarse solutions. :rtype: WolfArray|float

property s_sign_of_convergence: 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

property h1_representative_cell_length_fine: float

Return the representative cell length of the fine mesh. :return: The representative cell length of the fine mesh. :rtype: float

property h2_representative_cell_length_medium: float

Return the representative cell length of the medium mesh. :return: The representative cell length of the medium mesh. :rtype: float

property h3_representative_cell_length_coarse: float

Return the representative cell length of the coarse mesh. :return: The representative cell length of the coarse mesh. :rtype: float

property r21_refinement_ratio: float

Return the refinement ratio between fine and medium meshes. :return: The refinement ratio between fine and medium meshes. :rtype: float

property r32_refinement_ratio: float

Return the refinement ratio between medium and coarse meshes. :return: The refinement ratio between medium and coarse meshes. :rtype: float

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.

Parameters:

• array_fine (WolfArray|int) – The fine mesh array (WolfArray or number of cells).

• array_medium (WolfArray|int) – The medium mesh array (WolfArray or number of cells).

• array_coarse (WolfArray|int) – The coarse mesh array (WolfArray or number of cells).

• solution_fine (WolfArray|float|int) – The solution on the fine mesh (WolfArray or float).

• solution_medium (WolfArray|float|int) – The solution on the medium mesh (WolfArray or float).

• solution_coarse (WolfArray|float|int) – The solution on the coarse mesh (WolfArray or float).

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.

Parameters:

• phi1 (float) – The first solution value.

• phi2 (float) – The second solution value.

Returns:

The difference between the two solutions.

Return type:

float

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.

Parameters:

• epsilon21 (float) – Error between fine and medium mesh solutions.

• epsilon32 (float) – Error between medium and coarse mesh solutions.

Returns:

1 if the ratio is positive (indicating monotonic convergence),

-1 otherwise (indicating oscillatory convergence). :rtype: int

factor_21() → float

Compute the refinement factor between fine and medium meshes. :return: The refinement factor between fine and medium meshes. :rtype: float

factor_31() → float

Compute the refinement factor between fine and coarse meshes. :return: The refinement factor between fine and coarse meshes. :rtype: float

property order_of_convergence: 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

property extrapolated_solution: 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

property extrapolated_relative_error_21: 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

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.

Parameters:

• phi1 (float) – The first solution value.

• phi2 (float) – The second solution value.

Returns:

The relative error between the two solutions.

Return type:

float

property relative_error_21: 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

property relative_error_32: 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

property grid_convergence_index_21: 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

Parameters:

• rel_error_21 (float) – The relative error between the fine and medium mesh solutions.

• r21 (float) – The grid refinement ratio between the fine and medium meshes.

• p (float) – The order of convergence.

Returns:

The Grid Convergence Index (GCI).

Return type:

float

property grid_convergence_index_32: 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

Parameters:

• rel_error_32 (float) – The relative error between the medium and coarse mesh solutions.

• r32 (float) – The grid refinement ratio between the medium and coarse meshes.

• p (float) – The order of convergence.

Returns:

The Grid Convergence Index (GCI).

Return type:

float

property AsymptoticRange: bool | wolfhece.wolf_array.WolfArray

return the investment on computational cost

optimal_refinement_ratio_from_GCI(GCI_target: float) → float

Compute the optimal refinement ratio to achieve a target GCI.

Parameters:

GCI_target (float) – The target Grid Convergence Index (GCI).

Returns:

The optimal refinement ratio.

Return type:

float

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

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

Returns:

A dictionary containing errors and related metrics.

Return type:

dict

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

Parameters:

• self – Description

• precision – Description

Returns:

Description

Return type:

dict