Solver Specifications¶

This required section directs the nonlinear iteration strategy with associated parameters (e.g., Newton’s method options), matrix solution strategy and parameters, and other sundry options and toggles for the pressure stabilization approach and linear stability analysis capability. With regard to the parameters associated with matrix solution methods, it is important to understand that there are two major classes of solvers - direct and iterative solvers. Direct solvers are the most robust, but can be computationally impractical for some larger systems. Iterative solvers and associated preconditioners are the only practical options for large-scale problems (viz., very large twodimensional problems and virtually all three-dimensional problems). Choosing the solver settings for good convergence of iterative matrix solvers can be an artful task for Navier-Stokes problems and other poorly conditioned systems. It is recommended that the user consult the comprehensive report by Schunk, et al. (2002) for an overview and further usage tips.

Solution Algorithm¶

Solution Algorithm = {char_string}

Description / Usage¶

This required card selects an algorithm for the solution of the linear matrix system that arises at each Newton iteration (either for a steady-state solution or for the solution at each discrete time). Please note that at the time of this writing, new solver capabilities were being generated; although the following information was complete and accurate, it will likely be out of date by the time of publishing. Users should consult the CD version of this document in the Goma Documentation System for up to date options.

There are three major matrix solver packages accessible in Goma, two direct factorization collections and an iterative solver package. The first collection of direct factorization methods in Goma include the Sparse1.3 package (Kundert and Sangiovanni-Vincentelli, 1988) and Y12M direct factorization technique (Zlatev, Wasniewski and Schaumburg, 1981) accessible via the Aztec linear solver package. The second collection of direct factorization methods include two frontal solvers, SNL_MPFRONT, an adaptation of R. Benner’s implementation of Hood’s (1976) frontal method, and UMFPACK (Davis and Duff, 1997). SNL_MPFRONT is a traditional frontal method while UMFPACK is a multi-frontal solver.

The Aztec 2.x linear solver package (Tuminaro, et. al., 1999) is the iterative solver component of Goma. A successor to the krysolve 1.0 package (Schunk and Shadid, 1992) and the Aztec 1.0 package (Hutchinson, Shadid and Tuminaro, 1995), Aztec 2.x includes support for distributed memory architectures and for matrices in either a modified sparse row (MSR) format or a variable block row (VBR) format, as well as their distributed memory extensions. Generally, convergence of these iterative methods can be accelerated by judicious use of a preconditioner (which many of the other Solver Specifications cards address).

The options for this input card are listed below, but additional usage comments are included as part of the Technical Discussion section of this card. These comments provide assistance in choosing the Solution Algorithm for your problem.

Valid options for {char_string} are as follows:

lu

Direct factorization via Gaussian elimination using Sparse 1.3. This solver is robust even for poorly conditioned matrix systems. It is unavailable when running Goma on multiple processors.

front

Direct factorization based on Benner’s SNL_MPFRONT that eliminates equations and variables as the fully assembled rows of the matrix are acquired. This is the latest solver installed within Goma and users are encouraged to report their successes and failures with this option as part of testing. It is unavailable when running Goma on multiple processors.

umf/umff

Direct factorization using UMFPACK. This multi-frontal solver has been hardwired to perform elimination only upon complete assembly. The umff option forces a full factorization every time, whereas umf does not. It is unavailable when running Goma on multiple processors.

y12m

Direct factorization using the Y12M package. This package is accessible through the Aztec matrix solver interface and cannot be used for multiple processor computations. Other direct solvers are recommended against this one.

gmres

Iterative solver from the Aztec package using the restarted generalized minimum residual method. Iterative solver options are important to convergence of this method, e.g. Preconditioner, Size of Krylov subspace, Matrix, etc.

cg

Iterative solver from the Aztec package using the conjugate gradient method. Like other iterative solvers, the successful convergence of the conjugate gradient method for a linear system depends on preconditioners and other cards in the Solver Specifications section.

cgs

Iterative solver from the Aztec package using the conjugate gradient squared method. Convergence of this method is frequently contingent on the linear system and on the choice of other cards in the Solver Specifications section.

tfqmr

Iterative solver from the Aztec package using the transposefree quasi-minimum residual method. Convergence of this method is frequently contingent on the linear system and on the choice of other cards in the Solver Specifications section.

bicgstab

Iterative solver from the Aztec package using the biconjugate gradient with stabilization. Convergence of this method is frequently contingent on the linear system and on the choice of other cards in the Solver Specifications section.

amesos

Allows access to direct solver options implemented in parallel. Please see the user-notes below for Goma build options that must be exercised. This package is part of the Trilinos 6.0 framework. With this option, you must add an additional input card to specify the parallel direct solvers:

Amesos Solver Package = {superlu | mumps | klu | umfpack}

Of these four options, we currently recommend mumps. All options can be run in parallel.

Examples¶

Following is a sample card:

Solution Algorithm = lu

Another example (two cards) shows how to invoke a parallel direct solver:

Solution Algorithm = amesos

Amesos Solver Package = superlu

Technical Discussion¶

The direct factorization options are the most robust but consume the most computational resources (CPU time and memory, particularly for large and 3D problems). The iterative methods consume less resources but may take some experimentation to obtain convergence to the solution of the linear system. For example, a poorly conditioned linear system may require a lot of preconditioning. The conjugate gradient method may not be very useful on linear systems that are not symmetric positive definite. Although the following guidelines are useful, selection of the “right” linear solver requires experience, understanding and sometimes, luck.

lu - The Sparse1.3 direct solver, is the most robust solver in Goma in terms of obtaining successful convergence for even poorly conditioned matrix systems. A significant disadvantage, however, is that it can be computationally expensive for large problems. Not only do the memory and CPU requirements grow with problem size, but the initial symbolic factorization that seeks optimal reordering also consumes greater CPU resources with larger problem sizes. For example, a problem with 70,000 degrees of freedom that required 22 hours of CPU for the initial factorization required only 1/2 hour for subsequent factorizations. Furthermore, this solver is unavailable when Goma is run on multiple processors. Its robustness makes it an excellent choice for small- and medium-sized problems.
front - This solver is an adaptation for Goma of R. Benner’s frontal solver, which itself includes considerable improvements compared to the pioneering frontal solvers (Irons, 1970; Hood, 1976). The SNL_MPFRONT library is compiled and linked into Goma only by choice. Direct factorization is done as the fully assembled rows of the matrix are acquired. The frontal solver consumes CPU time roughly comparable to Sparse 1.3, with the noted advantage of eliminating intraelement fully summed equations as they are encountered and only keeping the active working matrix in-core, thereby reducing memory requirements and possible storage of matrix components to disk.
umf/umff - UMFPACK 2.0d is a powerful direct solver that is generally faster than Sparse 1.3a, though it might lack the robustness of the latter on infrequent occasions. The implementation of UMFPACK within Goma is only barebones, i.e. the multi-frontal solver has been hardwired to perform elimination only upon complete assembly. Finally, usage of UMFPACK is governed by a license that limits usage to educational, research and benchmarking purposes by nonprofit organizations and the U.S. government. Please refer to the license statement contained in the UMFPACK distribution for exact details. This solver was implemented prior to front so it was the only direct solver alternative to lu for a period of time. User’s should now evaluate performance of this solver against front on a case by case basis.
gmres, cg, cgs, tfqmr, bicgstab - The convergence of each of these iterative solvers is highly influenced by the kind of preconditioning selected. Often, the method(s) will not converge at all without an appropriate level of preconditioning. GMRES is considered one of the best iterative methods available, although there are instances where each of the others is superior. It is a Krylov-based method and has an additional input card, Size of Krylov subspace. As mentioned earlier, CG should only be used on systems that are symmetric positive definite. See the Matrix subdomain solver card, and other Solver Specifications cards for guidance on appropriate use of preconditioners; also consult Schunk, et. al. (2002).
amesos: superlu, klu, umfpack - These solvers are all direct (not iterative, but based on Gaussian elimination) and can be run in parallel with mpi. We recommend these solvers when robustness is required over iterative solvers and when the matrix assembly time is excessive, which is often the case when overloaded equations like species diffusion, porous media equations, etc. are used. This option also performs well for three-dimensional problems of small to moderate size.

References¶

SAND2001-3512J: Iterative Solvers and Preconditioners for Fully-coupled Finite Element Formulations of Incompressible Fluid Mechanics and Related Transport Problems, P. R. Schunk, M. A. Heroux, R. R. Rao, T. A. Baer, S. R. Subia and A. C. Sun, March 2002.

G. H. Golub and C. F. V. Loan, Matrix Computations, Johns Hopkins University Press, Baltimore, MD 3rd ed. (1996)

For all other references, please see References at the end of this manual.

Matrix Storage Format¶

Matrix storage format = {msr | vbr}

Description / Usage¶

This optional card can be used to choose between two formats accepted by the Aztec 2.1 solver package. Valid options are:

msr: modified sparse row format (see Schunk and Shadid, 1992). This option is the default option and is automatically used for all direct solver options.
vbr: variable block row format (see Heroux, 1992). This option should only be selected when an Aztec iterative solver is chosen.
epetra: Compressed Sparse Row format using the Epetra library from Trilinos

Examples¶

Following is a sample card:

Matrix storage format = msr

Technical Discussion¶

Goma supports two global matrix formats for its linear solvers. The advantage of choosing vbr over the default msr format is a matter of which preconditioner option is selected. (See Schunk, et al., 2002 on iterative methods.) When using the front solver package, another format known as estifm is employed internally but not specified by this card, which is not used in this case.

References¶

SAND92-1158: Iterative Solvers in Implicit Finite Element Codes, Sandia Technical Report, Schunk, P. R. and Shadid, J. N. (1992)

SAND2001-3512J: Iterative Solvers and Preconditioners for Fully-coupled Finite Element Formulations of Incompressible Fluid Mechanics and Related Transport Problems, P. R. Schunk, M. A. Heroux, R. R. Rao, T. A. Baer, S. R. Subia and A. C. Sun, March 2002.

TR/PA/92/90: M. A. Heroux, A proposal for a sparse BLAS toolkit, Technical Report, CERFACS, December 1992.

Preconditioner¶

Preconditioner = {char_string}

Description / Usage¶

Iterative techniques for solving a linear matrix system (see above) often benefit from preconditioning to aid convergence. This optional card provides for the selection of a preconditioner from those available through Aztec. For direct factorization Solution Algorithm specifications, the Preconditioner specification is immaterial since none is performed; in such cases, this card should be omitted.

Valid options for {char_string} are listed below.

none: No preconditioning is performed. This is the default specification if no preconditioner has been specified.
Jacobi: A k-step Jacobi preconditioner is used (block Jacobi for VBR matrices). The number of Jacobi steps, k, is set using the Matrix polynomial order card.
Neumann: A Neumann series polynomial preconditioner is used, where the order of the polynomial, k, is set using the Matrix polynomial order card.
ls: A least-squares polynomial preconditioner is used, where the order of the polynomial, k, is set using the Matrix polynomial order card.
sym_GS: A k-step symmetric Gauss-Seidel preconditioner is used for non-overlapping domain decomposition (additive Schwarz). In parallel, each processor performs one step of symmetric Gauss-Seidel on its local matrix, followed by communication to update boundary values from adjacent processors before performing the next local symmetric Gauss-Seidel step. The number of steps, k, is set using the Matrix polynomial order card.
lu: Approximately solve the processor’s local matrix via direct factorization using Sparse 1.3 in conjunction with a userspecified Matrix drop tolerance.
dom_decomp: A domain-decomposition-based preconditioner (additive Schwarz). Each processor augments its local matrix according to the Matrix factorization overlap card and then approximately solves the resulting linear system using the solver specified by the Matrix subdomain solver card. This is the most often used Preconditioner card.

Examples¶

Following is a sample card:

Preconditioner = dom_decomp

Technical Discussion¶

Note that prior to Aztec 2.x, certain subdomain solvers were specified simply as arguments to the Preconditioner card. While this historical usage is permitted via limited backward compatibility in order to ease the transition from Aztec 1 usage, the preferred usage is to specify ILU (and similar) preconditioners as a subdomain solver using the more powerful and flexible options that are available using Aztec 2.x together with this option for the preconditioner. Since subdomain solvers such as ILU and ILUT are powerful and frequently used, this preconditioner option will predominate when iterative solvers are being used, even in serial execution.

The most popular setting is dom_decomp, with a subdomain solver specified in the Matrix Subdomain Solver card. For further details, consult Mike Heroux’s recipe for applying preconditioners and what to dial the knobs to (in Schunk, et. al., 2002).

References¶

SAND2001-3512J: Iterative Solvers and Preconditioners for Fully-coupled Finite Element Formulations of Incompressible Fluid Mechanics and Related Transport Problems, P. R. Schunk, M. A. Heroux, R. R. Rao, T. A. Baer, S. R. Subia and A. C. Sun, March 2002.

Matrix Subdomain Solver¶

Matrix subdomain solver = {char_string}

Description / Usage¶

This optional card selects a solver to use in constructing a preconditioner. It is used in conjunction with a Preconditioner setting.

Preconditioner = dom_decomp

All of these preconditioners are available through the Aztec library. Valid options for {char_string} are listed below.

lu

Approximately solve the processor’s local matrix via direct factorization using Sparse 1.3 in conjunction with a userspecified Matrix drop tolerance.

ilut

Approximately solve the processor’s local matrix via ILUT (Saad, 1994.) The factorization is affected by user-specified options for Matrix drop tolerance as well as Matrix ILUT fill factor.

This subdomain solver is among the more robust to recommend as a first attempt; thus it has been chosen as the default if no subdomain solver is specified.

ilu

Approximately factor the processor’s local matrix using ILU(k), where k is specified by the user in the argument to Matrix graph fillin.

rilu

Approximately factor the processor’s local matrix using RILU(k,ω), where k is specified by the user in the argument to Matrix graph fillin and ω is specified by the user in the argument to Matrix RILU relax factor. (This option applies only to Trilinos.)

bilu

Approximately factor the processor’s local matrix using block ILU(k) for a VBR format matrix, where k is specified by the user in the argument to Matrix graph fillin. While not the most efficient preconditioner, bilu is very robust. (This option applies only to Trilinos.)

icc

Incomplete Cholesky factorization. See the Aztec manual for a reference.

If this Matrix subdomain solver card is omitted, then the default selection is ilut.

Examples¶

Following is a sample card:

Matrix subdomain solver = ilut

Technical Discussion¶

There is no real recipe to follow when choosing a preconditioner. In general, the cheapest preconditioner that works should be used. If ILUT(1) does the job, great. Sometimes the only preconditioner(s) that will work are very expensive. When the preconditioner seems to take too much time, remember that you may not be choosing the “wrong” preconditioner; the problem may just be that difficult.

Although Aztec 2.1 is being maintained and supported as a solver package for Goma, the interative solvers and preconditioners are now primarily accessed through the Trilinos library (as AztecOO), which is actively being developed and maintained at Sandia National Laboratories. Note that some features can only be accessed through Trilinos, as indicated above.

References¶

SAND2001-3512J: Iterative Solvers and Preconditioners for Fully-coupled Finite Element Formulations of Incompressible Fluid Mechanics and Related Transport Problems, P. R. Schunk, M. A. Heroux, R. R. Rao, T. A. Baer, S. R. Subia and A. C. Sun, March 2002.

Saad, Y., 1994. “ILUT: a dual threshold incomplete ILU factorization”, Numerical Linear Algebra with Applications, 1:387-402.

Matrix Scaling¶

Matrix scaling = {char_string}

Description / Usage¶

This optional card selects a scaling for the linear matrix system solution step.Valid options for {char_string} are listed below.

none: No scaling is performed. This is the default if no Matrix Scaling card is present.
Jacobi: Point Jacobi scaling is performed.
BJacobi: Block Jacobi scaling is performed if the underlying matrix format is VBR. If the MSR matrix format is used, the scaling reverts to point Jacobi.
row_sum: Scale each row so the sum of the magnitudes of the nonzero elements is 1.
sym_diag: Symmetric scaling so that diagonal elements are 1.
sym_row_sum: Symmetric scaling using the matrix row sums.

If the Matrix Scaling card is omitted, the default selection is none.

Examples¶

Following is a sample card:

Matrix scaling = sym_diag

Technical Discussion¶

All of these scalings are supplied via the Aztec library and thus will not affect the linear systems that are solved by other means (using front, for example). In an odd twist of fate, the linear system always undergoes a row sum scaling (equivalent to the row_sum option) before these other scalings are applied. Note that when a nontrivial scaling is selected, the matrix is overwritten with a rescaled system.

Matrix Residual Norm Type¶

Matrix residual norm type = {char_string}

Description / Usage¶

This optional card selects the type of norm that is used to measure the size of the residuals occurring during the solution of the linear matrix system \(r \left( z \right) = b - Az\), where \(z\) is an approximation to the solution \(x\) of the linear matrix problem \(Ax = b\). The types of norms used by the linear solver are controlled by values of {char_string}:

{char_string}	Norm type
r0	\(\frac{\lVert r \rVert_2}{\lVert r^0 \rVert_2}\)
rhs	\(\frac{\lVert r \rVert_2}{\lVert b \rVert_2}\)
Anorm	\(\frac{\lVert r \rVert_2}{\lVert A \rVert_{\infty}}\)
sol	\(\frac{\lVert r \rVert_{\infty}}{\lVert A \rVert_{\infty} \lVert x \rVert_1 + \lVert b \rVert_{\infty} }\)
noscaled	\(\lVert r \rVert_2\)

The (0) superscript for the r0 specification indicates the initial value of the residual.

If the Matrix residual norm type card is omitted, the default is r0.

Examples¶

Following is a sample card:

Matrix residual norm type = r0

Technical Discussion¶

For direct factorization linear solution algorithms, the norm should become very small in the single iteration that is performed. This card is more pertinent when an iterative solution algorithm has been specified.

Note the distinction between the residual for the overall global Newton iteration and use of the term residual to describe an aspect of the linear solver iteration. For the linear matrix systems, a residual \(r\) may be computed for any guess of the solution to \(Ax = b\) as \(r(z) = b - Az\). If \(z = x\), the actual solution, then the residual is zero; otherwise, it is some vector with a nonzero norm.

Matrix Output Type¶

Matrix output type = {char_string}

Description / Usage¶

This optional card indicates a level of diagnostic output for Aztec. The valid input parameters for {char_string} are either a string or a positive integer:

all: Print matrix and indexing vectors for each processor and all intermediate residual expressions.
none: No intermediate results are printed. This is the default.
warnings: Only Aztec warnings are printed.
last: Only the final residual expression is printed.
k: Residual expressions are printed every k iterations, k > 0.

If the Matrix output type card is omitted, the default is none.

Examples¶

Following is a sample card:

Matrix output type = 10

Matrix Factorization Reuse¶

Matrix factorization reuse = {char_string}

Description / Usage¶

This optional card directs the approximate factorization solvers used in preconditioner construction to reuse matrix information that may have been obtained during previous linear solution stages. This card only has an effect when using an Aztec solver. Valid options for {char_string} are:

calc: Use no information from previous linear solutions.
recalc: Use information from previous linear solutions but recalculate the preconditioning factors, with the implication that the symbolic factorization will be similar.
reuse: Use information from previous linear solution; do not recalculate preconditioner factorizations. However, use scaling factors from previous linear solutions to scale righthand sides, initial guesses, and final solutions.

If the Matrix factorization reuse card is omitted, the default is recalc.

Examples¶

Following is a sample card:

Matrix factorization reuse = recalc

Technical Discussion¶

See related discussions for Matrix factorization save.

Matrix Graph Fillin¶

Matrix graph fillin = <integer>4.7.10_matrix_factorization_overlap.txt

Description / Usage¶

This optional card sets the graph level of fill-in for approximate factorizations used in preconditioner construction for ILU(k), ICC(k) and BILU(k). The input parameter is defined as

<integer>: k, specifies the graph level of fill-in, k > 0.

If the Matrix graph fillin card is omitted, the default value of k is 0.

Examples¶

Following is a sample card:

Matrix graph fillin = 2

Technical Discussion¶

As the level of graph fill-in increases, the accuracy (usefulness) of the preconditioner increases; however, so does memory usage as well as the time required to compute the preconditioner.

Matrix Factorization Overlap¶

Matrix factorization overlap = {char_string}

Description / Usage¶

This optional card determines how much matrix factorization overlap occurs with other processors. This specification is only relevant for parallel computations. The valid options for {char_string} are:

none: No augmentation is performed, equivalent to a setting of k=0. This is the default.
diag: Augment the processor’s local matrix to include the diagonal (MSR) or diagonal blocks (VBR) for external rows.
k: Augment the processor’s local matrix to include external rows. The rows are selected by examining non-zero columns from the current local system that refer to offprocessor unknowns, and including the rows associated with those off-processor unknowns. This process is repeated k times, where k > 0. When complete, all non-zero columns whose associated rows have not been included are discarded. A value of 0 is equivalent to a setting of none.

If the Matrix factorization overlap card is omitted, the default is none.

Examples¶

Following is a sample card:

Matrix factorization overlap = 1

Technical Discussion¶

This optional card determines how much a processor’s local matrix is to be augmented with information from adjacent processors during the approximate factorizations used to build preconditioners. This card should be omitted or given a value of none for serial executions.

Matrix Overlap Type¶

Matrix overlap type = {standard | symmetric}

Description / Usage¶

This card selects the kind of matrix overlap that occurs (for parallel computations). Valid options are:

standard: The local processor considers only its own estimate for any unknown; results from adjacent processors are ignored. This is the default.
symmetric: The local processor adds its own estimate together with estimates from adjacent processors, retaining symmetry of preconditioners if a symmetric technique is being employed.

If the Matrix ovelap type card is omitted, the default is standard.

Examples¶

Following is a sample card:

Matrix overlap type= symmetric

Technical Discussion¶

This optional card determines how overlapping subdomain solver results are combined when different processors derive different estimates for the same solution unknown.

This overlap option is moot for serial problems whose data decomposition is trivial.

Matrix Auxiliary Vector¶

Matrix auxiliary vector = {resid | rand}

Description / Usage¶

This optional card indicates to Aztec how the auxiliary vector r is determined. Permissible options are:

resid: The auxiliary vector is set to the initial residual vector, viz. \(r = r(0)\).
rand: The auxiliary vector is filled with random numbers, each in the range \([-1,1]\).

If the Matrix auxiliary vector card is omitted, the default is resid.

Examples¶

Following is a sample card:

Matrix auxiliary vector = rand

Technical Discussion¶

The auxiliary vector is only used for certain iterative linear matrix solution algorithms.

The rand option may cause difficulties with initial iterative solver steps because different processors may have different initial unknown values at shared unknowns.

Matrix Drop Tolerance¶

Matrix drop tolerance = <float>

Description / Usage¶

This optional card indicates to Aztec a drop tolerance to be used in conjunction with preconditioners based on LU or on ILUT. The <float> input parameter is:

<float>: tol, a floating point number ( \(tol \geq 0\) ) that specifies the drop tolerance.

If the Matrix drop tolerance card is omitted, the default is 0.0.

Examples¶

Following is a sample card:

Matrix drop tolerance = 0.01

Technical Discussion¶

When constructing the partial factorization(s), any value less than tol is dropped. If set to 0.0, then other parameters will govern preconditioner size and components (e.g., Matrix ILUT fill factor for the ILUT preconditioner).

The two main parameters when using the ILUT preconditioner are this card and the Matrix ILUT fill factor card. The restrictions in Matrix ILUT fill factor take precedence over the dropped entries caused by this card.

Matrix Polynomial Order¶

Matrix polynomial order = <integer>

Description / Usage¶

This optional card allows selection of polynomial order when a polynomial preconditioning option is selected (see the Preconditioner card). The input parameter is defined as:

<integer>: Number of steps, k ( ≥ 0 ), to take when using matrix polynomial based preconditioners (Jacobi and symmetric Gauss-Seidel, for example).

If the Matrix polynomial order card is omitted, then the default selection is k=3.

Examples¶

Following is a sample card:

Matrix polynomial order = 4

Technical Discussion¶

When used, the value of this parameter should be greater than 0, and probably no more than 10. In some, if not all, cases, a value of 0 is meaningless.

This card is not used if the preconditioner does not use matrix polynomials.

Matrix Reorder¶

Matrix reorder = {none | rcm}

Description / Usage¶

This optional card determines whether RCM (Reverse Cuthill-McKee) reordering of the linear system is to be performed. Valid options are:

none: the equations are not reordered.
rcm: the equations are reordered using an RCM scheme.

If the Matrix reorder card is omitted, then the default selection is none.

Examples¶

Following is a sample card:

Matrix reorder = rcm

Technical Discussion¶

Note that reordering frequently is helpful in achieving convergence for iterative solution of linear systems. In a few instances, however, Goma users have noted that RCM reordering hinders convergence for selected problems. The default for Goma is to not use the RCM reordering so that quantitatively comparable results are obtained using either Aztec 1 (which did not have RCM reordering as an option) or Aztec 2.x. In summary, users are encouraged to try RCM reordering when using iterative solvers, foregoing the option only as a further resort in the face of repeated convergence failures.

Matrix Factorization Save¶

Matrix factorization save = {0 | 1}

Description / Usage¶

This optional card is a boolean specification that determines whether the preconditioner factorization information should be kept after a solve. Valid options are

0: Factorization information is discarded.
1: Factorization information is kept for that step.

If the Matrix factorization save card is omitted, then the default selection is 0.

Examples¶

Following is a sample card:

Matrix factorization save = 1

Technical Discussion¶

This option is most useful for iterative solution techniques where the computed preconditioning matrix found from an incomplete factorization requires significant computational resources. Such a preconditioner may be useful in later matrix solves and obviate the need to compute another expensive preconditioner at the later stage. Although a lot of time may be saved by re-using a previous factorization, the loss in accuracy may cause convergence problems.

Matrix ILUT Fill Factor¶

Matrix ILUT fill factor = <float>

Description / Usage¶

This optional card provides a second criterion to Aztec to be used in conjunction with preconditioners based on ILUT approximate factorization, where

<float>: fac, a floating point value ( fac ≥ 0 ) that specifies, very crudely, how many nonzero entries the approximate factorization will contain relative to the number of nonzero entries in the original matrix.

If the Matrix ILUT fill factor card is omitted, the default is 1.

Examples¶

Following is a sample card:

Matrix ILUT fill factor = 2.0

Technical Discussion¶

By increasing this factor, the preconditioner becomes more accurate because more terms in the preconditioner (pseudo-inverse) are retained. A value of 1.0 indicates that the preconditioner would contain approximately the same number of nonzero entries as the original matrix.

The two main parameters when using the ILUT preconditioner are this card and the Matrix drop tolerance card. If the Matrix drop tolerance is 0.0, then this card determines the size of the preconditioner. If Matrix drop tolerance is greater than 0.0, then the approximate factorization is first created subject to this card’s restriction, and then the drop tolerance is applied. This can result in a preconditioner with significantly fewer nonzero entries.

Matrix RILU Relax Factor¶

Matrix RILU relax factor = <float>

Description / Usage¶

This optional card provides a relaxation factor to Aztec to be used in conjunction with preconditioners based on RILU(k,ω) approximate factorization. The input parameter <float> is defined as

<float>: fac, a floating point number ( fac ≥ 0 ) that specifies a relaxation factor.

If the Matrix RILU relax factor card is omitted, the default is 1.

Examples¶

Following is a sample card:

Matrix RILU relax factor = 0.5

Technical Discussion¶

Some limiting values for fac provide specific behavior:

for a value of zero, the ILU(k) is obtained
for a value of one, the MILU(k) is obtained.

The value of k is set by the Matrix graph fillin card.

Matrix BILU Threshold¶

Matrix BILU threshold = <float>

Description / Usage¶

This capability is only present within the Trilinos library. This optional card provides a means to modify the way the block ILU preconditioner (Matrix subdomain solver = bilu) is constructed. The input parameter is defined as:

<float>: t, a floating point number ( t ≥ 0.0 ) that sets the Matrix Relative Threshold and Matrix Absolute Threshold thresholds.

When the Matrix BILU threshold card is omitted, the default value is 0.0.

Examples¶

Following is a sample card:

Matrix BILU Threshold = 1.0e-14

Technical Discussion¶

Using this card is equivalent to supplying both the Matrix Relative Threshold and Matrix Absolute Threshold with the value specified with this card.

The value of t defaults to zero, and if given a small value, say 1.0e-14, the condition number of the preconditioner, as reported when using the bilu option, should decrease. Try increasing up to around 1.0e-3 to get added benefit. The bilu preconditioner is not actually the cheapest or most efficient preconditioner, but it is very robust.

Matrix Relative Threshold¶

Matrix Relative Threshold = <float>

Description / Usage¶

This card is only available with the Trilinos library. The effect of this card is to impose a relative lower bound to either a diagonal value or a singular value. The legal values for <float> are:

<float>: r, a floating point number ( r ≥ 0.0 ) that specifies a relative threshold.

If this card is omitted, the default is 0.0.

Examples¶

A sample input card follows:

Matrix Relative Threshold = 1.e-4

Technical Discussion¶

This card, along with the Matrix Absolute Threshold card, allow the user to modify the linear system prior to calculation of the preconditioner. Note that the modification is only to change the “initial condition” of the preconditioner–it does not actually change the linear system.

Let t be the value specified with the Matrix Absolute Threshold card. For a scalar-based preconditioner (ilut, ilu, rilu, icc), each value on the diagonal undergoes the following substitution:

\[d_{\mathrm{new}} = r * d_{\mathrm{old}} + \mathrm{sgn} \left( d_{\mathrm{old}} \right) * t\]

For the bilu preconditioner, each singular value of the diagonal block preconditioner is compared to:

\[\sigma_{\mathrm{min}} = r * \sigma_1 + t\]

where σ1 is the largest singular value of the diagonal block under consideration. All \(\sigma_k\) are modified (if necessary) to be at least as large as \(\sigma_{\mathrm{min}}\).

The appropriate values for the threshold can vary over many orders of magnitude depending on the situation. Refer to Schunk, et. al., 2002 for information and for further guidance.

References¶

SAND2001-3512J: Iterative Solvers and Preconditioners for Fully-coupled Finite Element Formulations of Incompressible Fluid Mechanics and Related Transport Problems, P. R. Schunk, M. A. Heroux, R. R. Rao, T. A. Baer, S. R. Subia and A. C. Sun, March 2002.

Matrix Absolute Threshold¶

Matrix Absolute Threshold = <float>

Description / Usage¶

This card is only available with the Trilinos library. It allows the user to specify a lower bound for either a diagonal entry or a singular value. The exact meaning depends on the kind of preconditioner used (scalar-based or block-based). The legal values are:

<float>: t, a floating point number ( t ≥ 0.0 ) that specifies a minimum threshold value for diagonal or singular value.

Along with the Matrix Relative Threshold card, this card gives the user the ability to modify what matrix the preconditioner operates on. See the Matrix Relative Threshold card for a full description.

If this card is omitted, the default is 0.0.

Examples¶

A sample input card follows:

Matrix Absolute Threshold = 1.e-4

Technical Discussion¶

Refer to the discussion for card Matrix Relative Threshold. The appropriate values for the threshold can vary over many orders of magnitude depending on the situation. Refer to Schunk, et. al., 2002 for information and for further guidance.

References¶

SAND2001-3512J: Iterative Solvers and Preconditioners for Fully-coupled Finite Element Formulations of Incompressible Fluid Mechanics and Related Transport Problems, P. R. Schunk, M. A. Heroux, R. R. Rao, T. A. Baer, S. R. Subia and A. C. Sun, March 2002.

Size of Krylov Subspace¶

Size of Krylov subspace = <integer>

Description / Usage¶

This optional card allows the user to specify the dimension (size) of the Krylov subspace for the gmres option of the Solution Algorithm card, where

<integer>: m, specifies the number of orthogonalization directions and can be any positive integer less than or equal to the order of the matrix.

If the Size of Krylov subspace card is omitted, then the default dimension is m = 30.

Examples¶

The following is a sample input card:

Size of Krylov subspace = 128

Technical Discussion¶

If the size of the subspace is at least as large as the maximum number of iterations permitted by the solver then the gmres iteration will not include any restarts. Depending on the problem, restarts may be beneficial, and then again they may not. Particularly poorly conditioned linear systems may never converge below a certain tolerance if gmres is allowed to restart (i.e. they “level off”). However, some linear systems will admit a converged solution more rapidly with restarts than without. Consequently, the user may wish to experiment with different values of this parameter. See the Orthogonalization card for related information.

gmres’ internal iterations create a Krylov subspace up to dimension m (less in some circumstances, such as convergence). The time and space required by the internal iterations increases nonlinearly with m (but see the Orthogonalization card) - a doubling of m will result in more than a doubling of space and time requirements. So simply choosing a very large dimension is generally not recommended.

Orthogonalization¶

Orthogonalization = {classic | modified}

Description / Usage¶

This optional card selects the orthogonalization scheme used internally for the gmres solution algorithm (see the Solution Algorithm card). Valid options are

classic | classical: Two steps of classical Gram-Schmidt orthogonalization.
modified: A modified Gram-Schmidt orthogonalization.

If the Orthogonalization card is omitted, then the default selection is classic. Goma’s parser will accept classical as equivalent to classic.

Examples¶

Following is a sample card:

Orthogonalization = modified

Technical Discussion¶

By specifying modified, the user is greatly speeding up the gmres algorithm at the expense of possibly losing convergence. A good indication that you should not have used the modified setting is a premature “leveling off” of the sequence of residuals produced internally within gmres.

Maximum Linear Solve Iterations¶

Maximum Linear Solve Iterations = <integer>

Description / Usage¶

This optional card limits the maximum number of iterations used by iterative linear solver algorithms. The input parameter is defined as

<integer>: <integer> n, any positive integer ( n > 0 ) that specifies the maximum number of iterations.

If the Maximum Linear Solve Iterations card is omitted, the default selection is 500.

Examples¶

Following is a sample card:

Maximum Linear Solve Iterations = 5

Technical Discussion¶

If the linear system can be solved within a specified tolerance (see the Residual Ratio Tolerance card) in less than n iterations, then a normal return from Aztec occurs and the actual number of iterations required to obtain convergence will be printed on the status line. If the specified convergence tolerance is not met within n iterations, then an abnormal return status occurs and, in place of the number of iterations, the string “max” will be printed on the status line under the LIS (linear iteration status) heading. Other abnormal returns from Aztec are possible and are indicated on the LIS status line; see the Aztec User’s Guide (Hutchinson, Shadid and Tuminaro, 1995) for further interpretation of different abnormal return status indicators.

References¶

SAND95-1559: Aztec User’s Guide Version 1.0, Sandia Internal Report, Hutchinson, S. A., Shadid, J. N. and Tuminaro, R. S., 1995.

Number of Newton Iterations¶

Number of Newton Iterations = <integer1> [integer2]

Description / Usage¶

This required card sets the maximum number of iterations allowed for convergence of the Newton nonlinear iteration loop. It also provides an optional parameter for setting the reformation stride for the Jacobian matrix. Definitions of the input parameters are as follows:

<integer1>: n₁, any integer indicating the maximum number of iterations allowed for convergence of the Newton nonlinear iteration loop.
[integer2]: n₂, an optional parameter indicating the reformation stride for the Jacobian matrix.

The Number of Newton Iterations card is required, there is no default.

See the Jacobian Reform Time Stride card for some detailed examples of the interaction amongst various input parameters that influence when a Jacobian reformation occurs.

Examples¶

Following is a sample card:

Number of Newton Iterations = 5

Technical Discussion¶

For an unrelaxed Newton iteration with a good initial guess, five or six iterations (for n₁) should be sufficient to achieve convergence for most problems. One iteration will suffice for problems that are linear; two can be specified, with the second iteration verifying that the residual norms are small. More iterations may be required for relaxed Newton iteration schemes using the correction factor described in the Newton correction factor card. This parameter can also be controlled from the command line (see the -n option in the section on Command-line Arguments, Chapter 3).

The optional second parameter can be used to invoke a modified Newton iteration. If this value is missing, the stride is set to unity. This capability enables the user to save on assembly time when near a solution, particularly when doing transient simulations.

Modified Newton Tolerance¶

Modified Newton Tolerance = <float1> <float2>

Description / Usage¶

This optional card allows the user to exert finer control over Jacobian formation than a stride specification (as with the Number of Newton Iterations card’s second parameter or the Jacobian Reform Time Stride card). Input parameters are defined as:

<float1>: r, if the convergence rate is below this level ( r > 0.0 ), a Jacobian reformation will be forced.
<float2>: t, if the residual norm is above this level ( t ≥ 0.0 ), a Jacobian reformation will be forced.

If the Modified Newton Tolerance card is omitted, then reformations are always computed, subject to the Number of Newton Iterations’ second parameter and the Jacobian Reform Time Stride value.

See the Jacobian Reform Time Stride card for some detailed examples of the interaction amongst various cards that influence when a Jacobian reformation occurs.

Examples¶

Following is a sample card:

Modified Newton Tolerance = 1.5 1.0e-8

Technical Discussion¶

The convergence rate is defined as:

\[\mathrm{convergence} \, \mathrm{rate} = \frac{\log \left( \mathrm{current} L_1 \mathrm{norm} \right) }{\log \left( \mathrm{previous} L_1 \mathrm{norm} \right)}\]

This rate should be equal to 2 when Newton’s method is in its region of convergence (this is what it means to converge quadratically). A secant method would have a convergence rate of \(1 + \sqrt{5}/2\) (the golden ratio!), approximately 1.6.

The residual norm is simply the L₁ norm of the residual after a Newton iteration.

The method used to determine if a Jacobian reformation should take place is conservative. If either test condition for reformation is satisfied, a reformation occurs. Often, this card will allow you to speed up your runs by foregoing a fresh Jacobian reformation, but still maintain strong convergence. Moreover, without a Jacobian reformation, the lu solver (see the Solution Algorithm card) can use a previously factored matrix and simply do a resolve.

Jacobian Reform Time Stride¶

Jacobian Reform Time Stride = <integer>

Description / Usage¶

This optional card has a single input parameter:

<integer>: k, the stride length for Jacobian reformations ( \(k \geq 1\) ).

The Jacobian Reform Time Stride card is optional; there is no default.

Examples¶

Three examples are provided to illustrate how to use this card.

Example #1:

Number of Newton Iterations = 12 1

Modified Newton Tolerance = 1.9 0.1

Jacobian Reform Time Stride = 2

Newton correction factor = 1

This will reform the Jacobian every 2 steps. Furthermore, if the convergence rate falls below 1.9 or the L₁ residual is greater than 0.1 on an off-stride step a Jacobian reformation will occur. Specifically, the*Modified Newton Tolerance* takes precedence over a reformation stride setting (from either Number of Newton Iterations or Jacobian Reform Time Stride).

Example #2:

Number of Newton Iterations = 12 1

# Modified Newton Tolerance = 1.9 0.1

Jacobian Reform Time Stride = 2

Newton correction factor = 1

Note this differs from the previous example only by omitting the Modified Newton Tolerance card. This causes the Jacobian to be reformed every other time step.

Example #3:

Number of Newton Iterations = 12 2

# Modified Newton Tolerance = 1.9 0.1

Jacobian Reform Time Stride = 1

Newton correction factor = 1

We’ve changed the Jacobian Reform Time Stride from 2 to 1 and changed the second parameter of the Number of Newton Iterations card from 1 to 2. This will cause the Jacobian to be reformed every other step.

Technical Discussion¶

If the second parameter on the Number of Newton Iterations card is present and greater than 1, this Jacobian Reform Time Stride card is ignored. Otherwise, this card simply forces the Jacobian to be rebuilt every k Newton steps. Often, this card will allow you to speed up your runs by foregoing a fresh Jacobian formation, but still maintain strong convergence. Moreover, without a Jacobian formation, the lu solver (see the Solution Algorithm card) can use a previously factored matrix and simply do a resolve.

Newton Correction Factor¶

Newton correction factor = <float_list>

Description / Usage¶

This required card indicates the damping (or relaxation) factor for the Newton updates and offers customization of the relaxation choice based on the size of the nonlinear residual from the Newton iteration. Definitions of the <float_list> input parameters, from one (f₁) to six (f₂, … f₆) floating point numbers (one required and five optional), are as follows:

<float1>: f₁, damping factor for the Newton updates, where ( 0.0 < f₁ ≤ 1.0 ). A value of 1.0 gives the usual Newton’s method, otherwise, only a portion of the Newton update is applied to the solution. Values near 0 (e.g., 0.1) may be used effectively to aid convergence for sensitive problems where the initial guess is not very close to the final solution for the first several Newton iterations. This parameter can also be controlled from the command line (see -r option, Command-line Arguments, Chapter 3).
[floatn]: These five floats [f₂, … f₆] are optional but give a way to more finely control the amount of relaxation applied to Newton updates. See the description below and the example for an explanation.

Examples¶

A simple example is the following:

Newton correction factor = 0.1

This tells Goma to take the specified number of Newton iterations (from the Number of Newton Iterations card) at a fixed relaxation parameter of 0.1. This is a moderately large amount of relaxation, but of course “moderately large” is always problem dependent.

A more interesting example:

Newton correction factor = 0.8 1.0e-6 0.4 1.0e-4 0.1 1.0e-3

causes the following relaxation scheme to be used according to the L_∞ norm of the nonlinear residual:

If L_∞ > 1.0e – 3, the relaxation factor is taken as 0.1.
If 1.0e – 4 < L_∞ ≤ 1.0e – 3, the relaxation factor is taken as 0.4.
If 1.0e – 6 < L_∞ ≤ 1.0e – 4, the relaxation factor is taken as 0.8.
If L_∞ ≤ 1.0e – 6, the relaxation factor is taken as the usual Newton’s method relaxation of 1.0.

The default relaxation level for small residuals is 1.0.

Technical Discussion¶

The relaxation factor is used to intentionally shorten the solution update vector computed by the Newton iteration. There are many factors that can cause the effective radius of convergence of Newton’s method to be quite small or malformed:

the underlying nonlinear problem is stiff,
the initial solution is poor,
non-analytic constitutive models or boundary conditions,
poor linear solver performance, etc.

Under these kinds of circumstances, the update computed by Newton’s method may be too large and end up not improving the overall solution. In such cases it is recommended that one uses some relaxation (e.g., 0.9), and possibly a lot (e.g., 0.05).

What one really wishes to do is to use shortened updates when far from convergence, and full updates as the solution converges. This is the capability that the optional five parameters makes available. While they don’t directly measure how far the solution is from convergence, it does use the residual as an indicator. The full set of six parameters allows the user to specify four different residual intervals with four different relaxation factors. The f₁, f₃ and f₅ values are relaxation factors and must lie in 0.0 < f_i ≤ 1.0, while the f₂, f₄, and f₆ values are interval endpoints. The supplied interval endpoints must be in ascending order, 0 < f₂ < f₄ < f₆. Although no such restriction is put on the relaxation factors, they should generally satisfy 0 < f₅ ≤ f₃ ≤ f₁ ≤ 1.0.

Normalized Residual Tolerance¶

Normalized Residual Tolerance = <float>

Description / Usage¶

This required card indicates the value of the L₂ norm of the global nonlinear residual vector that indicates termination of Newton’s method (i.e., convergence). The input parameter is defined as

<float>: tol, a non-negative floating point number ( tol ≥ 0.0 ) specifying the L₂ convergence tolerance for the global nonlinear residual vector.

The Normalized Residual Tolerance card is required; there is no default.

Examples¶

Following is a sample card:

Normalized Residual Tolerance = 1.0e-11

Technical Discussion¶

Newton’s method is terminated when the global nonlinear residual falls below tol, or the maximum number of iterations specified in the Number of Newton Iterations is reached.

Normalized Correction Tolerance¶

Normalized Correction Tolerance = <float>

Description / Usage¶

This optional card sets the tolerance for a mixed measure of the size of the update vector which must be satisfied for the solution to be considered converged. The input parameter is defined as

<float>: rel, a floating point value ( rel ≥ 0.0 ) used as the convergence tolerance for the mixed measure of the update vector (defined in the Technical Discussion).

When the Normalized Correction Tolerance card is omitted, the default value of rel is 1.0e+10.

Examples¶

Following is a sample card:

Normalized Correction Tolerance = 1.0e-4

Technical Discussion¶

The mixed measure used here is:

\[\sqrt{ \sum \frac{ {\Delta x_i}^2}{1 + {x_i}^2} }\]

This measures the relative size of the update vector when the solution vector is large (i.e., size of unknowns is greater than 1), and measures the absolute size of the update vector when the solution vector is small (i.e., size of unknowns is much less than 1).

This mixed measure must be less than rel, in addition to the nonlinear residual satisfying the absolute residual tolerance specified in the Normalized Residual Tolerance card for a solution to be considered converged.

If rel < 1.0 (larger values are not really imposing any restrictions), mixed measure values are output instead of the update vector norms.

Residual Ratio Tolerance¶

Residual Ratio Tolerance = <float>

Description / Usage¶

This optional card sets the convergence criterion for the iterative solution of the linear matrix system solved at each Newton iteration. The input parameter is defined as

<float>: tol, a non-negative real number ( tol ≥ 0.0 ) specifying the value of the convergence criterion.

The default value of tol is 1.0e-6.

Examples¶

Following is a sample card:

Residual Ratio Tolerance = 1.0e-3

Technical Discussion¶

The value of tol is ignored when a direct factorization algorithm (such as lu) for the linear solve is specified in the Solution Algorithm card. When an iterative matrix solution technique is specified (such as gmres), tol acts as the inner iteration termination relative tolerance. Letting r₀ represent the initial residual norm, when the n_th iteration’s linear residual norm r_n satisfies r_n / r:sub :0 ≤ tol, the iterative solution is deemed acceptable and the inner iterations terminate. The number of iterations required is reported under the LIS column of the Newton iteration output. If the maximum number of iterations (specified in the Maximum Linear Solve Iterations card) is reached, then max appears instead of a number. Although the standard residual is usually used as the residual norm, the type of matrix residual norm used can be changed through the Matrix residual norm type card.

Pressure Stabilization¶

Pressure Stabilization = {yes | no | local | pspp | pspp_e}

Description / Usage¶

This optional card indicates whether or not pressure stabilization should be used. Valid options are

yes: Use the Galerkin Least square pressure stabilization method developed by Hughes, et. al. (1986).
local: Use the Galerkin Least square pressure stabilization method with local scaling.
pspp: Use polynomial stabilized pressure projection stabilization method developed by Dohrmann and Bochev (2004). Please see Level Set PSPP filtering card if using with the level-set front tracking technique.
pspp_e: Use polynomial stabilized pressure projection method with upgrade for nonuniform/graded meshes (recommended)
no: Do not use any pressure stabilization.

The amount of pressure stabilization to use is specified with the Pressure Stabilization Scaling card.

The default is no, to not use pressure stabilization.

Examples¶

Following is a sample card:

Pressure Stabilization = yes

Technical Discussion¶

If input for this card is yes, the Hughes, et al. (1986) method adds the residual of the momentum equation weighted by the gradient of the Galerkin weight function to the Galerkin continuity equation. The result is that the continuity equation now has a diagonal term to stabilize it and improve the condition of the matrix, allowing for the use of iterative solvers. When pressure stabilization is used, equal-order interpolation can (and should) be used for velocity and pressure, e.g., velocity and pressure both Q2 or both Q1. If input for this card is no, then the standard Galerkin finite-element weight functions are used and velocity and pressure interpolations should be chosen to satisfy the Babuska-Brezzi condition, e.g., velocity Q2 and pressure Q1 or P1, or velocity Q1 and pressure P0.

An improvement on the Hughes approach was developed by Bochev and Dohrmann (2004) called the polynomial stabilized pressure projection. In its fundamental form, it is like PSPG just an additional term on the continuity equation residual that helps stabilize the pressure, and it is predicated on the fact that the pressure field is governed by an elliptical equation known as the pressure Poisson equation. Please consult this paper for details. An additional improvement to that technique was developed internally to Sandia which better accommodates graded meshes. This technique is invoked with the pspp_e option, which we recommend.

References¶

Hughes, T. J. R., L. P. Franca and M. Balestra, “A New Finite Element Formulation for Computational Fluid Dynamics: V. Circumventing the Babuska-Brezzi Condition: A Stable Petrov-Galerkin Formulation of the Stokes Problem Accommodating Equal- Order Interpolations,” Comput. Methods Appl. Mech. Engrg., 59 (1986) 85-99.

Pressure Stabilization Scaling¶

Pressure Stabilization Scaling = <float>

Description / Usage¶

This optional card is only used if the Pressure Stabilization card is set to yes, where

<float>: tau, a positive real value ( tau > 0.0 ) that scales the momentum residual being added to the continuity equation for pressure stabilization.

The default value of tau is 0.1. If the Pressure Stabilization card is omitted, or set to no, then tau is ignored.

Examples¶

Following is a sample card:

Pressure Stabilization Scaling = 0.01

Technical Discussion¶

Generally, if tau is small, then more accurate solutions may be obtained at the cost of a more ill-conditioned matrix system that may not be easily amenable to iterative solvers (but stay tuned!). Conversely, larger values of this parameter result in equation systems that are easier to solve using the available iterative matrix solvers, but the solution thus obtained may be less accurate. A good choice for tau is 0.1.

The scaling value, tau, is further scaled inside of Goma. Knowledge of this scaling is sometimes useful. First, an average Reynolds number (Re) is computed according to:

\[\mathrm{Re} = \frac{\rho \lVert U \rVert \langle h \rangle }{2 \mu}\]

where \(\rho\) and \(\mu\) are local values for density and viscosity, \(\lVert U \rVert\) is a norm of the velocity field, and \(\langle h \rangle\) is a global average value for element size. If Re < 3.0, the pressure stabilization scaling is given by this expression:

\[\frac{ \mathrm{tau} {\langle h \rangle}^2 }{12 \mu}\]

On the other hand, if Re > 3.0, the following scales the pressure stabilization terms in the continuity equation:

\[\frac{ \mathrm{tau} {\langle h \rangle} }{2 \rho \lVert U \rVert}\]

Linear Stability¶

Linear Stability = {char_list}

Description / Usage¶

This optional card indicates whether or not linear stability analysis should be performed, as well as what kind.

The valid options for {char_list} are:

no: Do not perform any kind of linear stability analysis.
yes: Perform regular linear stability analysis. If your problem was 2D, then 2D analysis is performed. If your problem was 3D, then 3D analysis is performed.
inline: Same as yes, perform regular linear stability analysis.
3D: Subject the 2D flow to 3D linear stability analysis by normal mode expansion for the modes specified with the Eigen Wave Numbers card.
file: Set up the problem as in yes or inline, but output the matrices involved instead of determining stability.
3Dfile: Set up the problem as in 3D, but output the matrices involved instead of determining stability.

The default value is no.

Examples¶

Here is a sample card:

Linear Stability = yes

Technical Discussion¶

When linear stability analysis is performed, a steady-state solution is first acquired, and then the eigenvalue/eigenvector spectrum is computed subject to the choices made in the Eigensolver Specifications section. In the case of file or 3Dfile, the steady-state solution is acquired and then the matrices that would have been used to compute the spectrum are exported to file and no spectrum is actually computed. Refer to the Advanced Capabilities (Gates, et. al., 2001) document for a more thorough description.

The name of the output files when file is specified are:

LSA_mass_coo.out for the mass matrix, B or M,
LSA_jac_coo.out for the jacobian matrix, J,
LSA_vars.out for variable names associated with unknowns.

When 3Dfile is specified, the names are:

LSA_mass_coo-<f>.out, for the mass matrix, B or M,
LSA_jac_coo-<f>.out, for the jacobian matrix, J,
LSA_vars.out, for variable names associated with unknowns.

where <f> is the value of the requested normal mode (see the Eigen Wave Numbers card). The Eigen Matrix Output card must be set to yes in order to create and write these files.

When computing the 3D stability of a base 2D flow, other modifications need to be made (see the 3D stability of 2D flow memo).

See the Advanced Capabilities document (Gates, et. al., 2001), or it’s replacement (Labreche, et. al., 2002).

References¶

SAND2000-2465: Advanced Capabilities in Goma 3.0 - Augmenting Conditions, Automatic Continuation, and Linear Stability Analysis, I. D. Gates, D. A. Labreche and M. M. Hopkins (January 2001)

SAND2002-xxxx: Advanced Capabilities in Goma 4.0 - Augmenting Conditions, Automatic Continuation, and Linear Stability Analysis, Labreche, D. A., Wilkes, E. D., Hopkins, M. M. and Sun, A. C., (in preparation)

Filter Concentration¶

Filter Concentration = <integer> <float1> <float2>

Description / Usage¶

This optional card allows the user to enforce strict bounds on the concentration of a specific species. The input parameters are defined as:

<integer>: i, this integer indicates which species ( i ≥ 0 ) receives this special restriction.
<float1>: min, a real number indicating the minimum concentration.
<float2>: max, a real number indicating the maximum concentration.

There are no default values; concentrations take on whatever values are naturally dictated by the Newton iterations.

Examples¶

The following is a sample card:

Filter Concentration = 0 0.0 1.0

Technical Discussion¶

Although a correct solution should not have concentrations less than 0 or greater than 1.0, such values may arise in the solution vector due to various sources. Intermediate solutions during the Newton iteration may cause non-physical values to arise. Numerical error due to inexact linear solves, rounding, etc., may cause the values to be inexact. This card allows the user to force the concentration of species i to be corrected to fall within a strict concentration range [min,max] after the Newton iterations have terminated.

Disable Viscosity Sensitivities¶

Disable Viscosity Sensitivities = {yes | no}

Description / Usage¶

This optional card permits the analyst to omit the sensitivities of a shear-thinning viscosity model with respect to shear rate from the Jacobian.Valid options for this card are

yes: Omit the sensitivities of a shear-thinning viscosity model with respect to shear rate from the Jacobian
no: Form the complete Jacobian.

Currently, this card will have an effect only when using the following viscosity models: POWER_LAW, CARREAU, BINGHAM (see the Liquid Constitutive Equation card).

The default value is no.

Examples¶

The following is a sample card:

Disable Viscosity Sensitivities = yes

Technical Discussion¶

It has been observed that when these terms are included for very highly shear-thinning models the result can be non-convergence. In such situations, disabling these terms can often result in a convergent answer but at a convergence rate far less than the usual quadratic.