pterasoftware.convergence¶

Contains functions for analyzing the convergence of SteadyProblems and UnsteadyProblems.

Functions¶

`analyze_steady_convergence`	Finds the converged parameters of a SteadyProblem solved using a given steady solver.
`analyze_unsteady_convergence`	Finds the converged parameters of an UnsteadyProblem solved using the UnsteadyRingVortexLatticeMethodSolver.

Module Contents¶

pterasoftware.convergence.analyze_steady_convergence(ref_problem: pterasoftware.problems.SteadyProblem, solver_type: str, panel_aspect_ratio_bounds: tuple[int, int] = (4, 1), num_chordwise_panels_bounds: tuple[int, int] = (3, 12), convergence_criteria: float | int = 5.0) → tuple[int, int] | tuple[None, None][source]¶

Finds the converged parameters of a SteadyProblem solved using a given steady solver.

Procedure:

Convergence is found by varying the SteadyProblem’s Airplanes’ Panels’ aspect ratios their Wings’ numbers of chordwise Panels. These values are iterated over via two nested for loops (with the number of chordwise Panels as the inner loop).

With each new combination of these values, the SteadyProblem is solved, and its resultant load coefficients are stored. Each Airplanes’ three force coefficients are combined by taking their root-sum-square to find the resultant force coefficient. Then, the absolute percent change (APE) of each Airplanes’ resultant force coefficient is found between this iteration, and the iterations with incrementally coarser meshes in the two parameter directions (panel aspect ratio and number of chordwise panels). These two steps are repeated for the three moment coefficients.

The maximums of the resultant force coefficient APEs and resultant moment coefficient APEs are found. This leaves us with two maximum APEs, one for each parameter direction, per Airplane. Next, we take the maximum of each parameter directions’ APEs across all Airplanes, leaving us with two maximum APEs total. If either of the parameter direction APEs is below the convergence criteria, then this iteration has found a converged solution for that parameter direction.

If an iteration’s two APEs are both below the converged criteria, then we exit the nested for loops and return the converged parameters. However, the converged parameters are actually the values incrementally coarser than the final values (because the incrementally coarser values were found to be within the convergence criteria percent difference from the final values).

Notes:

There are two edge cases to this function. The first is if the user inputs equal values for the coarsest and finest values of either the Panel aspect ratio or the number of chordwise Panels (e.g. panel_aspect_ratio_bounds=(2, 2)). Then, this parameter will not be iterated over, and convergence will only be checked for the other parameter.

The second edge case happens if the Panel aspect ratio has not converged at a value of 1. This is the gold standard value for Panel aspect ratio, so this function will return 1 for the converged value of Panel aspect ratio. In the code below, this state is referred to as a “saturated” Panel aspect ratio case.

Parameters:

ref_problem – The SteadyProblem whose converged parameters will be found.
solver_type – Determines what type of steady solver will be used to analyze the SteadyProblem. The options are “steady horseshoe vortex lattice method” and “steady ring vortex lattice method”.
panel_aspect_ratio_bounds – A tuple of two ints, in descending order, that determines the range of Panel aspect ratios to consider, from largest to smallest. This value dictates the Panels’ average y component length (in wing cross section parent axes) divided their average x component width (in wing cross section parent axes). Historically, these values range between 5 and 1. Values above 5 can be used for a coarser mesh, but the minimum value cannot be less than 1. The default is (4, 1).
num_chordwise_panels_bounds – A tuple of two ints, in ascending order, that determines the range of values to use for the Wings’ numbers of chordwise panels. The default is (3, 12).
convergence_criteria – A positive number (int or float) that determines the point at which the function considers the simulation to have converged. Specifically, it is the maximum absolute percent change in the combined load coefficients. Therefore, it is in units of percent. Refer to the description in this function’s docstring for more details on how it affects the solver. In short, set this value to 5.0 for a lenient convergence, and 1.0 for a strict convergence. Values are converted to floats internally. The default is 5.0.

Returns:

A tuple of two ints or a tuple of two Nones. In order, they are the converged of Panel aspect ratio and the converged number of chordwise Panels. If the function could not find a set of converged parameters, it returns (None, None).

pterasoftware.convergence.analyze_unsteady_convergence(ref_problem: pterasoftware.problems.UnsteadyProblem, prescribed_wake: bool | numpy.bool_ = True, free_wake: bool | numpy.bool_ = True, num_cycles_bounds: tuple[int, int] | None = None, num_chords_bounds: tuple[int, int] | None = None, panel_aspect_ratio_bounds: tuple[int, int] = (4, 1), num_chordwise_panels_bounds: tuple[int, int] = (3, 12), convergence_criteria: float | int = 5.0, show_solver_progress: bool | numpy.bool_ = True) → tuple[bool, int, int, int] | tuple[None, None, None, None][source]¶

Finds the converged parameters of an UnsteadyProblem solved using the UnsteadyRingVortexLatticeMethodSolver.

Procedure:

Convergence is found by varying the UnsteadyRingVortexLatticeMethodSolver’s wake state (prescribed or free), the final length of the UnsteadyProblem’s wake (in number of chord lengths for static geometry or number of maximum-period motion cycles for variable geometry), the Airplanes’ Wings’ Panels’ aspect ratios, and the Airplanes’ Wings’ numbers of chordwise Panels. These values are iterated over via four nested loops. The outermost loop is the wake state. The next loop is the wake length. The loop after that is the Panel aspect ratios, and the innermost loop is the number of chordwise Panels.

With each new combination of these values, the UnsteadyProblem is solved, and each Airplanes’ final load coefficients are stored. As this function deals with UnsteadyProblems, it considers the final load coefficients to be the final-cycle’s RMS load coefficients for UnsteadyProblems with variable geometry, and the final time step’s load coefficients for static geometry cases. For each Airplane, the three final force coefficients are combined by taking their root-sum-square to find the resultant final force coefficient for that Airplane. Then, the absolute percent change (APE) of this Airplane’s resultant final force coefficient is found between this iteration and the iterations with incrementally coarser meshes in all four parameter directions (wake state, wake length, Panel aspect ratio, and number of chordwise Panels). These steps are repeated for the three final moment coefficients.

For each Airplane, the maximums of the resultant final force coefficient APEs and resultant final moment coefficient APEs are found. This leaves us with four maximum APEs per Airplane, one for each parameter direction. Next, we find the maximum across all the Airplanes for each parameter directions’ maximum APE. Now, we are left with four maximum APEs total. If any of the four parameter direction APEs is below the convergence criteria, then this iteration has found a converged solution for that parameter direction.

If an iteration’s four APEs are all below the converged criteria, then we exit the nested for loops and return the converged parameters. However, the converged parameters are actually the values incrementally coarser than the final values ( because the incrementally coarser values were found to be within the convergence criteria percent difference from the final values).

Notes:

There are two edge cases to this function. The first occurs when the user indicates that they only want check a single value for any of the four parameters (e.g. panel_aspect_ratio_bounds=(2, 2), both prescribed_wake=True and free_wake=False, etc.). Then, this parameter will not be iterated over, and convergence will only be checked for the other parameters.

The second edge case happens if the Panel aspect ratio has not converged at a value of 1 or if the wake state hasn’t converged once it’s set to a free wake. These conditions are the gold standards for Panel aspect ratio and wake state, so this function will return 1 for the converged value of Panel aspect ratio and a free wake for the converged wake state. In the code below, this state is referred to as a “saturated” Panel aspect ratio or wake state.

Parameters:

ref_problem – The UnsteadyProblem whose converged parameters will be found.
prescribed_wake – Determines if a prescribed wake state should be analyzed. If this parameter is False, then the free_wake parameter must be set to True. Can be a bool or a numpy bool and will be converted to a bool internally. The default is True.
free_wake – Determines if a free wake state should be analyzed. If this parameter is False, then the prescribed_wake parameter must be set to True. Can be a bool or a numpy bool and will be converted to a bool internally. The default is True.
num_cycles_bounds – For problems with non static geometry, determines the range of wake lengths (measured in number of maximum-period motion cycles) to simulate. For problems with static geometry, this must be None, and the num_chords_bounds parameter will control the range of wake lengths instead. Otherwise, it must be a tuple of two positive ints with the first value less than or equal to the second value. Reasonable values range from 1 to 10, depending strongly on the Strouhal number. The default is None.
num_chords_bounds – For problems with static geometry, determines the range of wake lengths (measured in number of reference chords) to simulate. For problems with non static geometry, it must be None, and the num_cycles_bounds parameter will control the wake length instead. Otherwise, it must be a tuple of two positive ints with the first value less than or equal to the second value. Reasonable values range from 3 to 20. The default is None.
panel_aspect_ratio_bounds – A tuple of two ints, in descending order, that determines the range of Panel aspect ratios to consider, from largest to smallest. This value dictates the Panels’ average y component length (in wing cross section parent axes) divided their average x component width (in wing cross section parent axes). Historically, these values range between 5 and 1. Values above 5 can be used for a coarser mesh, but the minimum value cannot be less than 1. The default is (4, 1).
num_chordwise_panels_bounds – A tuple of two ints, in ascending order, that determines the range of values to use for the Wings’ numbers of chordwise panels. The default is (3, 12).
convergence_criteria – A positive number (int or float) that determines the point at which the function considers the simulation to have converged. Specifically, it is the maximum absolute percent change in the combined load coefficients. Therefore, it is in units of percent. Refer to the description in this function’s docstring for more details on how it affects the solver. In short, set this value to 5.0 for a lenient convergence, and 1.0 for a strict convergence. Values are converted to floats internally. The default is 5.0.
show_solver_progress – Set this to True to show the TQDM progress bar during each run of the unsteady solver. For showing progress bars and displaying log statements, set up logging using the setup_logging function. It can be a bool or a numpy bool and will be converted internally to a bool. The default is True.

Returns:

A tuple of one bool and three ints. In order, they are the converged wake state (prescribed=True and free=False), the converged wake length (in number of cycles for non static geometries and number of chords for static geometries), the converged Panel aspect ratio, and the converged number of chordwise Panels. If the function could not find a set of converged parameters, it returns (None, None, None, None).