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 inmeshFamilyGroup
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 loweringvis4
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 loweringvis4
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 Albadaminmod
: Minmodno 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-StokesEuler
: Eulerlaminar NS
: laminar Navier-Stokes
- equationMode: str = steady
The temporal mode of the equations to solve.
steady
: Extensively testedunsteady
: Not well testedtime spectral
: Extensively tested
- flowType: str = external
Type of flow simulation.
external
: Extensively testedinternal
: 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 Modificationk-omega Wilcox
: Wilcox k-omegak-omega modified
: Wilcox modified k-omegak-tau
: k-tauMenter SST
: Menter SST k-omegav2f
: 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 discretizationsecond 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: 10e4SA-Edwards
- NOT IMPLEMENTEDk-omega Wilcox
- NOT IMPLEMENTEDk-omega modified
- NOT IMPLEMENTEDk-tau
- NOT IMPLEMENTEDMenter 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 formulationvorticity
: Use the vorticity formulationKato-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.
- 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 methodconstant pressure extrapolation
: Known to work with the adjoint methodquadratic pressure extrapolation
: Not testednormal 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
: Standardlinear 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 thanvis2
. 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-axis3
: 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 use3w
. To use a ‘v’ cycle use3v
, 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 be1
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
: Neveralways
: 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 arrayflags
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
. ThexCen
array returns the center coordinates of the cells.CGNSZoneNameIDs
andcellIDs
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-Kuttaimplicit RK
: Implicit Runge-Kutta
- timeAccuracy: int = 2
Order of accuracy of the time integration scheme.
2
: Second order1
: First order3
: 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
istime 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 prescribedNKLinearSolveTol
. 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 interpolationnone
: No line searchnon-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.
- 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 toadjointL2Convergence
.
- 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 QMRRichardson
: Preconditioned Richardson iterative methodBCGS
: BiCGStabIBCGS
: 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 sideleft
: Left side
- matrixOrdering: str = RCM
The matrix ordering algorithm used for the adjoint preconditioner. See PETSc documentation for details.
RCM
: reverse Cuthill-McKeenatural
: naturalnested dissection
: nested dissectionone way dissection
: one way dissectionquotient 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.