Options

gridFile: str = default.cgns: This is the grid file to use. It must be a multiblock structured or overset CGNS file containing all block-to-block information and boundary condition information.

restartFile: str or list or NoneType = None: Accepts a single string or a list of strings pointing to a CGNS file(s) which must be a volume solution file that was written by ADflow. For steady state restart, one CGNS file is sufficient and does not need to be provided as a list with a single item. For unsteady restart, you typically provide a list with 2 items for second order restart.

meshSurfaceFamily: str or NoneType = None: This is a custom family that can be defined to identify the surface mesh to ADflow. This variable is used to set self.meshFamilyGroup in pyADflow. If None, all wall surfaces are used as the surface mesh. This information is later used for mesh warping and surface output related operations.

designSurfaceFamily: str or NoneType = None: This is the custom family that is used to define what part of the surface mesh is the “design” surface, meaning that the surface might be modified geometrically. This variable is used to set self.designFamilyGroup in pyADflow. If None, all wall surfaces are used as the design surface. This can be useful when you want to distinguish between regular surface nodes and design surface nodes. The regular nodes will not change as the design is updated, but they are still included in meshFamilyGroup for mesh warping purposes.

closedSurfaceFamilies: list or NoneType = None: This is the set of surfaces that form a closed surface. This information is used in the overset initialization to figure out the wall cells. If None, all wall surfaces are used.

storeRindLayer: bool = True: Flag to write halo or “rind cell” information into CGNS files. This is required for some postprocessors (such as Tecplot) to compute contour lines correctly.

outputDirectory: str = ./: Directory where output files are written.

outputSurfaceFamily: str = allSurfaces: The family included in surface output files.

writeSurfaceSolution: bool = True: Flag to write surface solution (automatically) after the end of each solution call.

writeVolumeSolution: bool = True: Flag to write volume solution (automatically) after the end of each solution call.

writeSolutionEachIter: bool = False: Flag to write solution files after every nonlinear solver iteration. The solution files written depend on writeTecplotSurfaceSolution, writeVolumeSolution, and writeSurfaceSolution. This useful when debugging or developing the solver.

writeTecplotSurfaceSolution: bool = False: Flag to write a surface output in Tecplot format. This can be useful because it requires less tweaking in Tecplot to get the end result. This also includes the zipper mesh and only the active overset cells if a zipper mesh was created.

nSaveVolume: int = 1: When running unsteady simulations, the volume output will be written every this many unsteady iterations.

nSaveSurface: int = 1: When running unsteady simulations, the surface output will be written every this many unsteady iterations.

solutionPrecision: str = single

The precision used when writing volume solution files.

single: This is the best option if you are not planning on using restart files. The output files will be half the size, and the accuracy should be enough for visualization purposes.
double: This is best used for restart files.

gridPrecision: str = double

The precision used when writing the volume mesh in volume output files.

double: This is preferred, especially for RANS grids because lower precision can adversely affect the cells in the boundary layer.
single: This is not typically used.

solutionPrecisionSurface: str = single

The precision used when writing surface solution files.

single: This results in a smaller file at the cost of accuracy. The accuracy should be enough for visualization purposes.
double: This is preferred for running numerical analyses using the data from the output files.

gridPrecisionSurface: str = single

The precision used when writing the surface mesh in surface output files.

single: This results in a smaller file at the cost of accuracy. The accuracy should be enough for visualization purposes.
double: This is preferred for running numerical analyses using the data from the output files.

isosurface: dict = {}: Dictionary specifying the type and values to be used for isosurfaces. Any of the volumeVariables may be used. An example dictionary is : {"Vx":-0.001, "shock":1.0}. This will place an isosurface at (essentially) 0 x-velocity and an isosurface at the shock sensor value of 1 (used to visualize the shock region).

isoVariables: list = []: The state variables to be included on the isosurfaces requested with the isosurface option.

viscousSurfaceVelocities: bool = True: Only applicable for RANS and laminar NS computations. Write surface velocities as the value on the first cell off the wall. This means that the velocities on the surface will not be zero as enforced by the boundary conditions. This option enables postprocessing software to compute oil-flow surface streamline patterns.

discretization: str = central plus scalar dissipation

Set the discretization method. The default is generally recommended for both robustness and speed, at the cost of numerical accuracy.

central plus scalar dissipation: Uses a central finite volume scheme with JST scalar dissipation.
central plus matrix dissipation: Uses a central finite volume scheme with JST matrix dissipation. This scheme may be beneficial for poor meshes but might show minimal improvements on pyHyp meshes for a well posed problem. For convergence issues try lowering vis4 to 0.1 and lowering the CFL number.
upwind: Uses an upwind scheme.

coarseDiscretization: str = central plus scalar dissipation

Set the discretization method for the coarse grid. Generally should be the same as the discretization option.

central plus scalar dissipation: Uses a central finite volume scheme with JST scalar dissipation.
central plus matrix dissipation: Uses a central finite volume scheme with JST matrix dissipation. This scheme may be beneficial for poor meshes but might show minimal improvements on pyHyp meshes for a well posed problem. For convergence issues try lowering vis4 to 0.1 and lowering the CFL number.
upwind: Uses an upwind scheme.

limiter: str = van Albada

Type of flux limiter to use for the upwind scheme.

van Albada: van Albada
minmod: Minmod
no limiter: No limiter

smoother: str = DADI

Type of smoother to use with the multigrid solver.

DADI: Diagonalized diagonally dominant alternating direction implicit (D3ADI) scheme. This is typically faster than the Runge-Kutta scheme but may be less robust.
Runge-Kutta: Five-stage fourth-order low-memory explicit Runge–Kutta time stepping scheme.

equationType: str = RANS

The type of equations to solve.

RANS: Reynolds-averaged Navier-Stokes
Euler: Euler
laminar NS: laminar Navier-Stokes

equationMode: str = steady

The temporal mode of the equations to solve.

steady: Extensively tested
unsteady: Not well tested
time spectral: Extensively tested

flowType: str = external

Type of flow simulation.

external: Extensively tested
internal: Not well tested

turbulenceModel: str = SA

The turbulence model to use for RANS simulations.

SA: Spalart-Allmaras. This is the recommended option for external aerodynamic flow applications because it is the only turbulence model that has been differentiated. This is also the only turbulence model that is tested.
SA-Edwards: Spalart-Allmaras with Edwards Modification
k-omega Wilcox: Wilcox k-omega
k-omega modified: Wilcox modified k-omega
k-tau: k-tau
Menter SST: Menter SST k-omega
v2f: v2-f

turbulenceOrder: str = first order

The numerical order of accuracy of the turbulence model.

first order: The recommended approach because the adjoint systems are much easier to solve with the first order discretization
second order: Not typically used

turbResScale: float or list or NoneType = None

This parameter affects how the total residual is scaled. It is set automatically, depending on what turbulence model you select. The defaults are usually sufficient. Depending on the turbulence model, values can be a float scalar to a 4 element list of floats. Refer to the list below for the defaults and the type of input expected:

SA - Type: float scalar - Default: 10e4

SA-Edwards - NOT IMPLEMENTED

k-omega Wilcox - NOT IMPLEMENTED

k-omega modified - NOT IMPLEMENTED

k-tau - NOT IMPLEMENTED

Menter SST - Type: float list of 2 elements - Default: [1e3, 1e-6]

v2f - NOT IMPLEMENTED

turbulenceProduction: str = strain

How to compute the production term in the turbulent kinetic energy equation (k equation). Only valid for turbulence models that involve k.

strain: Use the strain formulation
vorticity: Use the vorticity formulation
Kato-Launder: Use the Kato-Launder formulation

useQCR: bool = False: Use the QCR2000 version of the Spalart-Allmaras turbulence model.

useRotationSA: bool = False: Use the rotation correction with the Spalart-Allmaras turbulence model.

useft2SA: bool = True: Include the ft2 term in the Spalart-Allmaras turbulence model.

eddyVisInfRatio: float = 0.009: Free stream value of eddy viscosity. See here for more details.

useWallFunctions: bool = False: Flag specifying if wall functions are to be used. This is generally not recommended since they give (potentially very) poor drag estimates. Furthermore, the required routines are not differentiated, so wall function simulations cannot be used for optimization.

useApproxWallDistance: bool = True: Flag to use a cheap wall distance calculation. When True, the exact wall distances are computed during initialization and the parametric location of the closest wall point is stored for each cell. After the geometry deforms (such as during an optimization) the spatial search algorithm is not run, but the distance between the (new) parametric location and the (new) grid cell center is computed and taken as the wall distance. This is substantially faster and permits efficient wall-distance updates for use in aerostructural analysis.

eulerWallTreatment: str = linear pressure extrapolation

Specifies how wall boundary conditions are implemented for inviscid simulations. Generally, the default value does not need to be changed.

linear pressure extrapolation: Known to work with the adjoint method
constant pressure extrapolation: Known to work with the adjoint method
quadratic pressure extrapolation: Not tested
normal momentum: Not tested

viscWallTreatment: str = constant pressure extrapolation

Specifies how wall boundary conditions are implemented for viscous simulations. Generally, the default value does not need to be changed.

constant pressure extrapolation: Standard
linear pressure extrapolation: Not typically used

dissipationScalingExponent: float = 0.67: Exponent factor to use in the JST dissipation scheme. This value typically will not need to be changed from the default. The value of 2/3 is the theoretical best value assuming an orthogonal 3-dimensional grid.

vis4: float = 0.0156: Coefficient of the fourth order dissipation used in the scalar and matrix JST dissipation scheme. The default value is generally recommended if a converged solution can be obtained. It may be raised slightly in the range of 0.02-0.025 which may help achieve better convergence properties at the expense of numerical accuracy.

vis2: float = 0.25: Coefficient of the second order dissipation used in the scalar and matrix JST dissipation schemes. This dissipation is only turned on at shocks, and thus may be set to 0.0 if the user knows a simulation will be entirely subsonic.

vis2Coarse: float = 0.5: The value of vis2 used for the coarse grid. This is typically larger than vis2. The default value of 0.5 is usually sufficient for most cases.

restrictionRelaxation: float = 0.8: The relaxation factor for the restriction operation in multigrid. The value must be between 0.0 and 1.0. A value of 1.0 will not perform any relaxation. On some problems, this may be faster, while slower on others. The default value of 0.80 appears to work well for a wide variety of cases.

liftIndex: int = 2

Specify the coordinate index that will be considered the lift direction.

2: y-axis
3: z-axis

lowSpeedPreconditioner: bool = False: Whether or not to use the low-speed preconditioner. This was previously used for very low Mach number cases but has been phased out in favor of the ANK solver.

wallDistCutoff: float = 1e+20: The cutoff value for distance where we stop computing the wall distance. For nodes that are farther than this distance away from any surface, the wall distance is set to a large constant.

infChangeCorrection: bool = True: Useful option. Setting this to True will adjust the flowfield everywhere if the angle of attack changes between optimization iterations. The idea is that when the angle of attack is changed after a converged simulation, the residuals can stay low since this value only initially affects the residuals of the farfield boundary cells. As a result, the solver logic can do weird stuff because it is often based on the L2 norm of the residual. If this option is set to True, we do a simple linear adjustment of every velocity vector in the solution with the same change in alpha. As a result, the residuals jump up and the solver logic works as designed. This supersedes the RKReset approach.

cavitationNumber: float = 1.4: The -Cp value used to trigger the cavitation sensor.

nCycles: int = 2000: The maximum number of “iterations” to run. Iterations are counted differently for the different solvers. For the multigrid solver, this refers to the number of multigrid cycles on the fine grid. For the ANK solver, this refers to the number of steps plus the number of KSP iterations. For the NK solver, this refers to the number of function evalautions either for matrix-vector products or during a line search. Each function evaluation corresponds roughly to single residual evaluation. The run will terminate once the combined number of iterations exceeds nCycles.

timeLimit: float = -1.0: If set to a positive value, this is the maximum number of seconds that the solver will run. The mechanism to trigger this internally is by setting the total number of iterations to the max number, so the solver will say analysis failed. It is up to the user to use this and manage the fail flags. This option can be useful when some cases take extremely long in optimizations, and we are okay with just calling it quits and going back to the line search.

nCyclesCoarse: int = 500: The maximum number of iterations to run on the coarse grid when performing a full-multigrid start-up procedure.

nSubiterTurb: int = 3: The number of iterations of the turbulent DADI solver to run. Only meaningful for RANS simulations. Increasing this parameter to 5-7 may lower the overall solution time for some cases.

nSubiter: int = 1: Number of RK or D3ADI iterations to perform in each nonlinear iteration (between turbulence updates). This does not do anything for the NK or ANK solvers.

CFL: float = 1.7: The Courant–Friedrichs–Lewy (CFL) number to use for the Runge-Kutta simulations. This is the main parameter that determines the overall speed and robustness of RK simulations. Lower CFL numbers give more robust solutions but are slower. The default value of 1.5 is a good place to start. Some experimentation is usually required to determine the maximum CFL for a particular simulation.

CFLCoarse: float = 1.0: The CFL number to use on the coarse grids of the multigrid simulations. It is often desirable to have this number somewhat lower than the CFL number of the fine grid.

MGCycle: str = sg: The type of multigrid cycle to use. The dimensions of the grid must be such that the requested multigrid level is possible. To run a single grid simulation (no multigrid) use sg. To run 3 multigrid levels with a ‘w’ cycle use 3w. To use a ‘v’ cycle use 3v, and so on.

MGStartLevel: int = -1: Specify the starting grid level. This is used to perform a “full multigrid startup” procedure. This can lead to significantly reduced simulation times since a good starting point can be obtained from approximate solutions on the coarser grids. A -1 indicates that the coarsest grid level should be used. For RANS simulations, it is often not possible to start on the coarsest grid, especially if the coarse grid has very few cells. This should be 1 for an unsteady simulation.

resAveraging: str = alternate

How frequently to perform residual averaging (also known as residual smoothing) for the RK solver.

alternate: On every second RK stage. This saves computation but with minimal impact on the convergence properties.
never: Never
always: On every RK stage

smoothParameter: float = 1.5: Parameter used in residual smoothing. This value will typically not need to be changed from the default.

CFLLimit: float = 1.5: The maximum CFL that can be run without residual smoothing. If the actual CFL is lower than this, no smoothing will be applied, regardless of the resAveraging option.

useBlockettes: bool = True: Helps speed up residual calculations by working with a smaller subset of data, reducing the number of cache misses. These subsets of data are fractions of the initial block size and thus are called blockettes. The amount of speedup is problem dependent but ranges from 2-3 times. This option has not been exhaustively tested and has been found to cause errors in the past. Verify that it does not change your results.

useLinResMonitor: bool = False: Enables the linear residual monitor for the NK and ANK solvers. The output should look like the linear residual output from the adjoint solver.

nearWallDist: float = 0.1: Distance used to determine if a cell will be flagged as “nearWall”.

backgroundVolScale: float = 1.0: A factor that modifies the perceived quality of background cells. A higher value will discourage use of the background mesh during implicit hole cutting.

oversetProjTol: float = 1e-12: Tolerance used when projecting search points onto the surface definition of a block.

overlapFactor: float = 0.9: How much to derate cell volumes when looking for a donor. The value should be less than 1.0. For example, with an overlap factor of 0.9, a cell with volume 1.0 will not get a cell with volume 0.99 as a donor because 0.99 is greater than 1.0 multiplied by the overlap factor. This is designed to create smoother cuts in an overlap region with very similar cell sizes. Changing the overlap factor generally does not change the overlap much because there are checks for ensuring you have valid donors.

oversetLoadBalance: bool = True: Toggle whether to use load balancing for the implicit hole cutting connectivity algorithm. Results with and without load balancing are shown in “An Efficient Parallel Overset Method for Aerodynamic Shape Optimization” (Kenway2017a).

debugZipper: bool = False: Toggles verbose printing and writing of information that is useful for debugging issues with the zipper mesh.

zipperSurfaceFamily: str or NoneType = None: Surface families to use when creating the zipper meshes .

cutCallback: function or NoneType = None

A user-provided Python function that is used to explicitly blank a number of cells based on whatever pattern the user requires. A typical use case for this is to blank the cells that are on the wrong side of the symmetry plane. The mesh extrusion for a component with free edges may actually go to the other side of the symmetry plane, and we want to explicitly remove these cells from the overset mesh. To do this, ADflow internally sets the flagged cells as a flood seed cell. The cutCallback function is called from pyADflow and the user filled array flags is used to determine which cells are flagged. The function signature looks like this:

def cutCallback(xCen, CGNSZoneNameIDs, cellIDs, flags):
   flags[xCen[:, 1] < 0] = 1

The user would then provide this in the option dictionary as: "cutCallback": cutCallback. The xCen array returns the center coordinates of the cells. CGNSZoneNameIDs and cellIDs can also be used to figure out the blanking pattern. flags is the NumPy array we fill and return back to pyADflow. In this example, we have a symmetry plane on the x-z surface, and we want to only use the +y half of the 3D coordinate system. Therefore, we are flagging every cell where the y-component of the center coordinate (index 0:x, 1:y, 2:z) has a negative value. The flags array is initialized to zero internally by pyADflow, and a value of 1 for a cell tags it for flooding.

oversetUpdateMode: str = frozen

How to update the overset connectivity after mesh warping.

frozen: The overset connectivity is not updated after initialization. This is the cheapest option to use when the entire overset mesh is warped together, such as with USMesh in IDWarp.
fast: Only the weights are updated and the donors are unchanged. This is usually a fairly small correction and is fast to run. This is used when the entire overset mesh is warped together, such as with USMesh in IDWarp.
full: The overset connectivity is recomputed from stratch. This is usually only used when the component meshes are warped independently, such as with MultiUSMesh in IDWarp.

nRefine: int = 10: The maximum number of refinement loop iterations used in the implicit hole cutting method.

nFloodIter: int = -1: Number of iterations for the flooding algorithm at each overset hole cutting iteration. Only useful for debugging meshes that flood completely on the first iteration of the overset. The default is set to -1, which will be inactive and run the flooding algorithm until the flooded cells stop changing. Setting a positive integer value will stop the flooding algorithm at the prescribed number of iterations.

useZipperMesh: bool = True: Determine whether a zipper mesh will be used. Zipper meshes are required to accurately compute integrated quantities (such as lift and drag) when the surface meshes of interest overlap.

useOversetWallScaling: bool = False: Modifies the perceived quality of cells during implicit hole cutting to favor cells that are aligned with viscous walls.

selfZipCutoff: float = 120.0: The cutoff angle in degrees used in the self-zip step of the zipper mesh gap triangulation. Triangulation is triggered if the angle between adjacent substrings is less than the cutoff. This value is only used for the first self-zip iteration at each node. The cutoff angle is 90 degrees for all subsequent iterations.

oversetPriority: dict = {}: Modifies the perceived quality of cells in block. The dictionary keys are the block IDs, and the values are the multipliers for quality. A higher factor will discourage use of that block mesh. A lower factor will encourage the usage of that block mesh. This option may be required to get the flooding algorithm working properly.

timeIntegrationScheme: str = BDF

The type of time integration scheme to use for unsteady analysis.

BDF: Backward differentiation formula (BDF). Second order BDF is currently the only option known to work.
explicit RK: Explicit Runge-Kutta
implicit RK: Implicit Runge-Kutta

timeAccuracy: int = 2

Order of accuracy of the time integration scheme.

2: Second order
1: First order
3: Third order

nTimeStepsCoarse: int = 48: Number of time steps to be done on the coarse mesh. Only useful for periodic problems where full multigrid can be performed.

nTimeStepsFine: int = 400: Number of time steps to run in an unsteady simulation.

deltaT: float = 0.01: Time step to use for unsteady simulation.

useALE: bool = True: Use the arbitrary Lagrangian-Eulerian (ALE) formulation for unsteady mesh deformations.

useGridMotion: bool = False: Whether or not a rigid body motion of the grid has been specified.

coupledSolution: bool = False: Flag that determines if ADflow is coupled to other solvers, but only in unsteady mode. Previously used for aerothermoelastic analysis.

timeIntervals: int = 1: The number of “spectral instances” to use for a time spectral simulation. This option is only meaningful when equationMode is time spectral.

alphaMode: bool = False: Use a specified alpha motion for the time spectral analysis.

betaMode: bool = False: Use a specified beta motion for the time spectral analysis. Untested.

machMode: bool = False: Use a specified Mach number motion for the time spectral analysis. Untested.

pMode: bool = False: Use a specified p-motion (roll) for the time spectral analysis. Untested.

qMode: bool = False: Use a specified q-motion (pitch) for the time spectral analysis.

rMode: bool = False: Use a specified r-motion (yaw) for the time spectral analysis. Untested.

altitudeMode: bool = False: Use a specified h-variation motion for the time spectral analysis. Untested.

windAxis: bool = False: The wind axis used for time spectral stability derivative computations.

alphaFollowing: bool = True: Whether or not alpha follows the body in p, q, r mode.

TSStability: bool = False: Flag to compute time spectral stability information from a time-spectral CFD solution.

useTSInterpolatedGridVelocity: bool = False: Use spectral differentiation to compute the grid velocity for the time spectral equation.

useExternalDynamicMesh: bool = False: Use externally provided deformed mesh for the time spectral equation. Each time instance gets its own deformed grid. This can be used for both an aerodynamic case or an aeroelastic case.

L2Convergence: float = 1e-08: This specifies the desired convergence factor. For the multigrid solver, this is taken relative to the initial residual on the fine grid. Since this prolonged solution may be a fairly good starting point, the actual convergence relative to the freestream residual may be 1 to 2 orders of magnitudes lower. For the NK solver, this option also determines the convergence, but the reference is taken as the freestream residual.

L2ConvergenceRel: float = 1e-16: This option is typically only used when ADflow is used in conjunction with an aerostructural solver. This specifies the relative tolerance in relation to the current starting point.

L2ConvergenceCoarse: float = 0.01: The convergence factor on the coarse grids during multigrid startup. Most of the benefits of the start-up procedure is obtained after converging between 2 and 3 orders of magnitude so this option is typically 1e-2 to 1e-3.

maxL2DeviationFactor: float = 1.0: If the solver runs out of iterations, the maximum factor the residual can be above the target residual (determined by L2Convergence) and still be considered “converged”.

useNKSolver: bool = False: Flag to turn on the Newton–Krylov (NK) solver. If False, the remainder of the options that begin with “NK” will have no effect.

NKSwitchTol: float = 1e-05: The relative tolerance to converge before the switch is made to the NK solver. This must be low enough that most of the difficult transients have been passed. If the NK solver stalls, this value can be set to a lower value which will run the startup procedure for longer before switching.

NKSubspaceSize: int = 60: The size of the GMRES subspace for the NK solver. For difficult problems, convergence may be improved by increasing this value at the expense of more memory.

NKLinearSolveTol: float = 0.3: The initial tolerance to solve the linear system resulting from the Newton approximation. This value is only used for the first iteration if NKUseEW is True.

NKUseEW: bool = True: Flag to use the Eisenstat-Walker algorithm to determine linear convergence at each iteration. If False, the NK solver will always try to converge the linear system to NKLinearSolveTol. If True, only the initial iteration will target the prescribed NKLinearSolveTol. The following iterations will pick a new linear tolerance based on the nonlinear convergence of the previous iteration. This is done to avoid wasting computation when we are far away from the nonlinear solution and also to nail down the linear solution when we are near the nonlinear solution. See this paper for more details. If the algorithm works as expected, the NK solver should converge in a few (or maybe tens) of iterations. However, the algorithm might pick a very low linear convergence repeatedly and get stuck in a loop. For these cases, it might be better to disable this option, but the better approach would be to switch to the NK solver later in the nonlinear convergence.

NKADPC: bool = False: Flag determines if the AD version of the NK preconditioner is used. If False, we use finite-difference. Using AD improves preconditioner accuracy and linear solver performance at the cost of more expensive preconditioner computations.

NKViscPC: bool = False: Flag that determines if the full viscous stencil is used for the NK preconditioner. This will have a memory and cost penalty, but the resulting preconditioner will be more accurate. Users should experiment with other linear solver options as a smaller stencil preconditioner is usually good enough.

NKASMOverlap: int = 1: The number of overlap levels in the additive Schwarz preconditioner for the NK solver. More overlap levels result in a stronger preconditioner, at the expense of more expensive iterations and more memory. Typical values range from 1 for easy cases and up to 2 or 3 for more difficult cases.

NKPCILUFill: int = 2: The number of levels of fill to use on the local Incomplete LU (ILU) factorization in the NK solver. Typical values are 1 for easy cases and up to 3 for more difficult cases. More levels of fill result in a stronger preconditioner which will result in fewer (linear) iterations, but individual iterations will be more costly and consume more memory.

NKJacobianLag: int = 20: The option determines the frequency at which the NK preconditioner is reformed. In other words, the Jacobian used for the preconditioner is “lagged” behind the actual solution by this many iterations. For simple problems, it may be possible to increase the Jacobian lag to such a high value that the preconditioner is never reformed at all during a solution. For more difficult cases, a lower value may help convergence. A lower value will result in more preconditioner Jacobian assemblies, which are fairly costly in ADflow.

applyPCSubspaceSize: int = 10: This option is only used when ADflow is used in an aerostructural analysis. This parameter determines the subspace size and the total number of iterations to run when ADflow is only being used to precondition residuals via the globalNKPrecon function.

NKInnerPreconIts: int = 1: Number of local preconditioning iterations for the NK solver. More iterations may help converge the linear system faster. This should be left at 1 unless a very difficult problem is encountered.

NKOuterPreconIts: int = 1: Number of global preconditioning iterations for the NK solver adjoint solution. More iterations may help converge the linear system faster. Typical values are from 1 to 3.

NKLS: str = cubic

The type of line search used with the NK solver.

cubic: Cubic interpolation
none: No line search
non-monotone: Non-monotone line search

NKFixedStep: float = 0.25: The step size for the NK solver with no line search ("NKLS": "none").

RKReset: bool = False: Option to run nRKReset Runge-Kutta startup iterations when using the NK solver and restarting from a previously converged solution. This allows the residual to increase and prevents the NK solver from stalling.

nRKReset: int = 5: The number of Runge-Kutta startup iterations to run when RKReset is True.

AGMGLevels: int = 1: Agglomerated multigrid preconditioner levels. Experimental; should not be modified.

AGMGNSmooth: int = 3: Agglomerated multigrid preconditioner parameter. Experimental; should not be modified.

useANKSolver: bool = True: Flag to enable the ANK solver.

ANKUseTurbDADI: bool = True: Flag to determine if turbulence variables are solved with the DADI solver. Only applies to decoupled ANK. If False, an internal ANK-like solver is used for the turbulence in the decoupled mode.

ANKSwitchTol: float = 1000.0: Relative convergence in the residual norm before we switch to the ANK solver. For most cases, the default value should ensure that the ANK solver is used from the first iteration, even after design changes.

ANKSubspaceSize: int = -1: A positive value sets the subspace size for the ANK solver. Otherwise, the maximum iteration value is taken as the subspace size.

ANKMaxIter: int = 40: Maximum number of linear iterations at each ANK step.

ANKLinearSolveTol: float = 0.05: Linear solver tolerance for the ANK solver.

ANKLinResMax: float = 0.1: A parameter that is used to adaptively adjust the CFL number so that the linear residual with the ANK solver does not go above the prescribed value. The target linear convergence may not be reached during nonlinear iterations with the given linear solver options, and this may be fine. However, we want to manage the CFL number so that the linear residual after we run out of linear iterations is still below this target value. This can be seen as the maximum allowed linear residual at each iteration.

ANKASMOverlap: int = 1: Similar to the NKASMOverlap option but for the ANK solver.

ANKPCILUFill: int = 2: Similar to the NKPCILUFill option but for the ANK solver.

ANKJacobianLag: int = 10: Number of nonlinear iterations between every preconditioner update. The preconditioner update is determined by an adaptive algorithm, so the updates can happen more frequently. This option sets the upper limit. See “A Jacobian-free approximate Newton–Krylov startup strategy for RANS simulations” (Yildirim2019b) for more details.

ANKInnerPreconIts: int = 1: Similar to the NKInnerPreconIts option but for the ANK solver.

ANKOuterPreconIts: int = 1: Similar to the NKOuterPreconIts option but for the ANK solver.

ANKCFL0: float = 5.0: The initial CFL number for the ANK solver.

ANKCFLMin: float = 1.0: The coefficient in the minimum CFL algorithm for the ANK solver. The minimum CFL number increases as the simulation converges, and this is the initial value. See “A Jacobian-free approximate Newton–Krylov startup strategy for RANS simulations” (Yildirim2019b) for more details.

ANKCFLLimit: float = 100000.0: Upper limit for the CFL number in the ANK solver. A larger CFL number will be better for nonlinear convergence at the cost of robustness and expensive linear solutions.

ANKCFLFactor: float = 10.0: Multiplication factor used in the CFL ramping algorithm for the ANK solver. See “A Jacobian-free approximate Newton–Krylov startup strategy for RANS simulations” (Yildirim2019b) for more details.

ANKCFLExponent: float = 0.5: The exponent used in the CFL ramping algorithm for the ANK solver. See “A Jacobian-free approximate Newton–Krylov startup strategy for RANS simulations” (Yildirim2019b) for more details.

ANKCFLCutback: float = 0.5: The cutback factor for the CFL number in the ANK solver. This is the factor used when the CFL is adaptively reduced.

ANKStepFactor: float = 1.0: The initial step size taken by the ANK solver. This value will be used to initialize the line searches in ANK. The actual step size can be lower than this but not higher.

ANKStepMin: float = 0.01: The minimum step size in the ANK solver. If a step less than this value is required, then the CFL is cut back.

ANKConstCFLStep: float = 0.4: If the step size in the ANK solver is lower than this value, we do not ramp up the CFL and keep it constant. If the step size from the last iteration is larger than this (implying that the solver can make progress), we ramp us the CFL.

ANKPhysicalLSTol: float = 0.2: The physical line search parameter in the ANK solver. A value of 0.2 means that the physical parameters (density and energy) are allowed to change by 20% at each iteration for each cell. The line search adjusts the step size to obey this change globally.

ANKPhysicalLSTolTurb: float = 0.99: The physicality check parameter for the turbulence model in the ANK solver. The turbulence model variable is allowed to increase freely, but it is only allowed to decrease by the specified amount at each iteration. A value of 0.99 means that the turbulence model variable can decrease by 99% at each iteration. Because the initial value of the turbulence model is always positive, this effectively prevents negative values.

ANKUnsteadyLSTol: float = 1.0: The reduction factor used in the unsteady line search for the ANK solver. A value of 1.0 means that the unsteady line search will accept any step that does not increase the unsteady residual norm. See “A Jacobian-free approximate Newton–Krylov startup strategy for RANS simulations” (Yildirim2019b) for more details.

ANKSecondOrdSwitchTol: float = 1e-16: The relative convergence target where the ANK solver switches to a second order accurate implicit formulation. For transonic flows, this target should be set to be right after the shocks are settled in the solution, which is typically around relative convergence of 1e-4 to 1e-6.

ANKCoupledSwitchTol: float = 1e-16: The relative convergence target where the ANK solver switches to a coupled turbulence formulation. In the coupled formulation, the flow and turbulence variables are all solved together. This improves nonlinear convergence but reduces robustness. This should be used after 5 to 6 orders of magnitude of nonlinear convergence.

ANKTurbCFLScale: float = 1.0: The scaling value for the CFL value used for the separate turbulence solver in the ANK solver.

ANKUseFullVisc: bool = True: Flag to use the full viscous terms in the implicit formulation for the ANK solver. Setting this to True results in the R1 residual approximation level. See “A Jacobian-free approximate Newton–Krylov startup strategy for RANS simulations” (Yildirim2019b) for more details.

ANKPCUpdateTol: float = 0.5: If the ANK solver converges by this amount relative to the last nonlinear iteration where the preconditioner was updated, the preconditioner is updated again.

ANKADPC: bool = False: Whether or not to use the AD-based preconditioner for the ANK solver. The finite-difference preconditioner is usually good enough and is cheaper to compute.

ANKNSubiterTurb: int = 1: The number of turbulent subiterations between each ANK iteration if ANK turbKSP is used ("ANKUseTurbDADI": False). This should be kept at 1 for most cases because the turbKSP solver is more effective and expensive.

ANKTurbKSPDebug: bool = False: Enables debug printout from the ANK turbKSP solver. If turbDADI is disabled, turbKSP is used to solve the turbulence. Without this option also set to true, you will not get any diagnostic output for the turbulence solver.

ANKUseMatrixFree: bool = True: Use the matrix-free Jacobian for the ANK solver. If True, we use the approximate Jacobian formulated for the preconditioner matrix as the implicit formulation.

blockSplitting: bool = True: Flag determining if the block may be split to obtain better load balancing.

loadImbalance: float = 0.1: This is the allowable load imbalance. The tolerated load imbalance between processors when mapping the blocks onto these processors. A value of 0.1 means there is 10 percent load imbalance.

loadBalanceIter: int = 10: Number of METIS graph partitioning iterations. Increasing this number will give you better load balancing. However, it will also tend to split up blocks more often. Therefore, there is a penalty on communication cost.

partitionOnly: bool = False: Flag determines whether to only run the partitioning algorithm, not the flow solution. This is used when checking the load balancing of a grid without running a CFD solution.

partitionLikeNProc: int = -1: If this is set to a positive value, the solver partitions the grid like it has that many processors. Useful to recreate a partition-related issue that shows up on a large number of procs using a smaller number of procs. This is a purely debug option. When it is used, the number of processor partitions will be greater than the number of procs. As a result, the remainder partitions will be distributed to procs, and you will likely get a load imbalance of 1.0, which is bad for performance.

numberSolutions: bool = True: Flag to set whether to attach the numbering of the AeroProblem to the grid solution file.

printIterations: bool = True: Flag to set whether to print out the monitoring values at each iteration.

printTiming: bool = True: Flag to set whether to print the time taken for the initialization, flow solution, function evaluations, and adjoint solution.

printIntro: bool = True: Flag to set whether to print the ADflow intro message during initialization.

printAllOptions: bool = True: Flag to set whether to print all the options during initialization.

setMonitor: bool = True: Flag to set whether to monitor the adjoint iterations.

printWarnings: bool = True: Flag to print warning messages like for bad quality volumes, etc.

monitorVariables: list = ['cpu', 'resrho', 'resturb', 'cl', 'cd']

List of the variables whose convergence should be monitored. The possible monitoring variables are:

resrho (density residual)

resmom (momentum residuals)

resrhoe (total energy residual)

resturb (turbulence residuals)

cl (lift coefficient)

clp (pressure part of cl)

clv (viscous part of cl)

cd (drag coefficient)

cdp (pressure part of cd)

cdv (viscous part of cd)

cfx (force coefficient in x-direction)

cfy (force coefficient in y-direction)

cfz (force coefficient in z-direction)

cmx (moment coefficient in x-direction)

cmy (moment coefficient in y-direction)

cmz (moment coefficient in z-direction)

hdiff (maximum relative difference between H and Hinf)

mach (maximum mach number)

yplus (maximum y+ value)

eddyv (maximum ratio of eddy viscosity and laminar viscosity)

surfaceVariables: list = ['cp', 'vx', 'vy', 'vz', 'mach']

The variables which are written to the CGNS surface solution file. The available keywords are:

rho (density)

p (pressure)

temp (temperature)

vx (velocity in x-direction)

vy (velocity in y-direction)

vz (velocity in z-direction)

cp (pressure coefficient)

ptloss (relative total pressure loss)

mach (mach number)

cf (magnitude of the skin friction)

cfx (x-component of the skin friction)

cfy (y-component of the skin friction)

cfz (z-component of the skin friction)

ch (Stanton number)

yplus (y+ value of the cell center of the first cell)

lift (lift force)

blank (cell iblank values used for visualization or other post-processing)

volumeVariables: list = ['resrho']

The variables which are, in addition to the variables needed for the restart, written to the CGNS volume solution file. The available keywords are:

mx (momentum in x-direction)

my (momentum in y-direction)

mz (momentum in z-direction)

rhoe (total energy)

temp (temperature)

vort (magnitude of the vorticity)

vortx (x-component of the vorticity)

vorty (y-component of the vorticity)

vortz (z-component of the vorticity)

cp (pressure coefficient)

mach (Mach number)

macht (turbulent Mach number)

ptloss (relative total pressure loss)

eddy (eddy viscosity)

eddyratio (ratio of eddy viscosity and laminar viscosity)

dist (wall distance to the nearest viscous wall)

resrho (density residual)

resmom (momentum residuals)

resrhoe (total energy residual)

resturb (turbulence residuals)

blank (cell iblank values used for visualization or other post-processing)

storeConvHist: bool = True: Flag to save convergence history information into fortran arrays. This data can be accessed after the solve using getConvergenceHistory.

forcesAsTractions: bool = True: Flag to return tractions instead of forces.

adjointL2Convergence: float = 1e-06: Adjoint solution tolerance relative to the residual for a zero initial guess. In some cases (such as with zipper meshes), the adjoint solution can stall well before a typical relative convergence value is reached. For these cases, running the adjoint solution until the absolute residual reaches a minimum should still give accurate derivatives.

adjointL2ConvergenceRel: float = 1e-16: Adjoint solution tolerance relative to the residual at the start of the adjoint call (including a possible non-zero restart).

adjointL2ConvergenceAbs: float = 1e-16: Adjoint solution absolute tolerance.

adjointDivTol: float = 100000.0: The relative amount the adjoint residual can increase before the solver concludes that the method is diverging.

adjointMaxL2DeviationFactor: float = 1.0: Similar to maxL2DeviationFactor but for the adjoint solution. This factor is only applied to adjointL2Convergence.

approxPC: bool = True: Whether or not to use the approximate Jacobian for the adjoint preconditioner.

ADPC: bool = False: Whether or not to use AD for the adjoint preconditioner.

viscPC: bool = False: Whether or not to keep cross derivative terms in the adjoint preconditioner.

useDiagTSPC: bool = True: Whether or not the off-time instance terms are included in the time spectral adjoint preconditioner.

restartAdjoint: bool = True: Whether or not we want to restart the adjoint from the previous solution.

adjointSolver: str = GMRES

Type of linear solver for the adjoint. See PETSc documentation for details.

GMRES: GMRES. Typically gives the best performance.
TFQMR: Transpose free QMR
Richardson: Preconditioned Richardson iterative method
BCGS: BiCGStab
IBCGS: Improved BiCGStab

adjointMaxIter: int = 500: Maximum number of iterations for the adjoint solution.

adjointSubspaceSize: int = 100: The size of the Krylov subspace for the adjoint solution.

GMRESOrthogonalizationType: str = modified Gram-Schmidt

Which orthogonalization method to use with GMRES. This will affect the adjoint solver the most, but the same option is also used in the linear solvers in the ANK and NK solvers.

modified Gram-Schmidt: Modified Gram-Schmidt. This typically gives the best accuracy (relative to complex step for the adjoint) and performance.
CGS never refine: Classical Gram-Schmidt with no refinement. Fast but not the most accurate.
CGS refine if needed: Classical Gram-Schmidt with refinement as needed. Slow and inaccurate.
CGS always refine: Classical Gram-Schmidt with refinement at every iteration. Slow and inaccurate.

adjointMonitorStep: int = 10: The adjoint residual norm is written out every this many iterations.

dissipationLumpingParameter: float = 6.0: Scaling parameter for dissipation lumping in the approximate preconditioner for the adjoint solution.

preconditionerSide: str = right

Which side to apply the adjoint preconditioner.

right: Right side
left: Left side

matrixOrdering: str = RCM

The matrix ordering algorithm used for the adjoint preconditioner. See PETSc documentation for details.

RCM: reverse Cuthill-McKee
natural: natural
nested dissection: nested dissection
one way dissection: one way dissection
quotient minimum degree: quotient minimum degree

globalPreconditioner: str = additive Schwarz

The type of (global) preconditioner to use for the adjoint system.

additive Schwarz: Restricted additive Schwarz method (ASM)
multigrid: Agglomerated multigrid (AGMG)

localPreconditioner: str = ILU

The type of preconditioner to use for the local preconditioning iteration in the adjoint solution.

ILU: Incomplete LU (ILU) factorization. Currently the only supported option.

ILUFill: int = 2: The number of levels of fill to use on the local Incomplete LU (ILU) factorization in the adjoint solution. Typical values are 1 for easy cases and up to 3 for more difficult cases. More levels of fill result in a stronger preconditioner which will result in fewer (linear) iterations, but individual iterations will be more costly and consume more memory.

ASMOverlap: int = 1: The number of overlap levels in the additive Schwarz preconditioner for the adjoint solution. More overlap levels result in a stronger preconditioner, at the expense of more expensive iterations and more memory. Typical values range from 1 for easy cases and up to 2 or 3 for more difficult cases.

innerPreconIts: int = 1: Number of local preconditioning iterations for the adjoint solution. Increasing this number may help with difficult problems. However, each iteration will take more time.

outerPreconIts: int = 3: Number of global preconditioning iterations for the adjoint solution. Increasing this number may help with difficult problems. However, each iteration will take more time. The default should be sufficient for most problems.

applyAdjointPCSubspaceSize: int = 20: The Krylov subspace size for the adjoint preconditioner.

frozenTurbulence: bool = False: Flag to set whether to use frozen turbulence assumption in the adjoint. Frozen turbulence neglects the linearization of the turbulence model. Currently, only the Spalart-Allmaras model is ADed. Using this flag may help with convergence for high transonic flows. However, the resulting sensitivity is less accurate.

useMatrixFreedrdw: bool = True: Flag that determines if ADflow will use the matrix-free routines to compute mat-vec products with the full Jacobian. If False, ADflow will form the full matrix exactly and mat-vec multiplications will be matrix-based. This should always be True for overset meshes, otherwise the gradients will be inaccurate. This is a known bug in ADflow (see https://github.com/mdolab/adflow/issues/204). The matrix-free routines have lower memory usage. For runtime, there is a tradeoff between the Jacobian assembly and adjoint solution times. See “Effective Adjoint Approaches for Computational Fluid Dynamics” (Kenway2019a) for more details.

skipAfterFailedAdjoint: bool = True: If this option is True, and one of the adjoints fail in the current sensitivity evaluation, the rest of the adjoints will be skipped for the sake of efficiency. The user should use the checkAdjointFailure method to get the correct fail flag in the dictionary passed back to the optimizer for these cases. In the following design evaluation, ADflow will try to solve the adjoints again. If this option is set to False, all of the adjoints will be solved (to whatever tolerance possible with the given options), and the (possibly) partially converged solutions will be used for total derivative computations. It is again up to the user to decide if this is the behavior they want.

firstRun: bool = True: This option is for debugging the adjoint only. Setting this to False will turn on the Tapenade debugger.

verifyState: bool = True: This option is for debugging the adjoint only. It is used to verify dRdw.

verifySpatial: bool = True: This option is for debugging the adjoint only. It is used to verify dRdx.

verifyExtra: bool = True: This option is for debugging the adjoint only. It is used to verify dIda.

sepSensorOffset: float = 0.0: The offset value used for the separation sensor. See “Buffet-Onset Constraint Formulation for Aerodynamic Shape Optimization” (Kenway2017b) for more details.

sepSensorSharpness: float = 10.0: The sharpness parameter for the separation sensor. See “Buffet-Onset Constraint Formulation for Aerodynamic Shape Optimization” (Kenway2017b) for more details.

computeCavitation: bool = False: Whether or not to compute cavitation.