.. ############################################################################ .. manual/packages/vertex-cfd/nonlinear_solve_status_tests.rst .. ############################################################################ .. _sec_nonlinear_solve_status_tests: ******************* NOX Status Tests ******************* The ``Status Tests`` sublist defines the convergence and failure conditions for the nonlinear solve. A combo test contains consecutively numbered ``Test N`` sublists, and each numbered sublist selects its own test type. .. dropdown:: :icon: multi-select :color: primary :animate: fade-in-slide-down .. py:data:: Test Type :type: string :value: ``"Combo"``, ``"NormF"``, ``"NormUpdate"``, ``"NormWRMS"``, ``"FiniteValue"``, ``"MaxIters"``, ``"Divergence"``, ``"Stagnation"``, ``"RelativeNormF"``, or ``"NStep"`` :usage: Required :default: ``"Combo"`` in the Tempus default solver :description: Selects the status-test factory. Vertex-CFD inputs use an outer ``"Combo"`` test and place the individual convergence and failure tests in numbered ``Test N`` sublists. NOX also accepts ``"User Defined"``, but that choice requires a C++ status-test object and cannot be configured using XML values alone. .. py:data:: Combo Type :type: string :value: ``"AND"`` or ``"OR"`` :usage: Required with ``Test Type = "Combo"`` :default: ``"AND"`` in NOX; ``"OR"`` in the Tempus default solver :description: Combines the results of the numbered ``Test N`` sublists. The standard ``"OR"`` configuration terminates when the residual converges or the iteration limit is reached. .. py:data:: Number of Tests :type: integer :value: Number of numbered subtests :usage: Required with ``Test Type = "Combo"`` :default: ``2`` in the Tempus default solver :description: Sets the number of consecutively numbered sublists, from ``Test 0`` through ``Test N-1``. The number in ``Test N`` does not determine the test type. Each numbered sublist is dispatched independently from its required ``Test Type`` entry. Tempus creates ``Test 0 = NormF`` and ``Test 1 = MaxIters`` by default; a user-provided combo may put any supported status-test type at either index. .. dropdown:: Test 0 :icon: bookmark :color: light :animate: fade-in-slide-down .. py:data:: Test Type :type: string :value: ``"NormF"`` in the Tempus default configuration :usage: Required :default: ``"NormF"`` in the Tempus default solver :description: Declares a residual-norm convergence test. ``Test 0`` is not intrinsically a ``NormF`` test; this is the assignment made by Tempus and used by the searched Vertex-CFD inputs. .. py:data:: Tolerance :no-index: :type: double :value: Residual-norm convergence tolerance :usage: Optional with ``Test Type = "NormF"`` :default: ``1.0e-8`` :description: Declares convergence when the selected residual norm satisfies this tolerance. The default norm is the unscaled two-norm. .. py:data:: Norm Type :type: string :value: ``"Two Norm"``, ``"One Norm"``, or ``"Max Norm"`` :usage: Optional with ``Test Type = "NormF"`` :default: ``"Two Norm"`` :description: Selects the residual norm used by the absolute residual test. .. py:data:: Scale Type :type: string :value: ``"Unscaled"`` or ``"Scaled"`` :usage: Optional with ``Test Type = "NormF"`` :default: ``"Unscaled"`` :description: With ``"Scaled"``, divides the two-norm by the square root of the vector length and divides the other supported norms by the vector length before comparing with ``Tolerance``. .. dropdown:: Test 1 :icon: bookmark :color: light :animate: fade-in-slide-down .. py:data:: Test Type :type: string :value: ``"MaxIters"`` in the Tempus default configuration :usage: Required :default: ``"MaxIters"`` in the Tempus default solver :description: Declares a nonlinear-iteration limit test. ``Test 1`` is not intrinsically a ``MaxIters`` test; this is the assignment made by Tempus and used by the searched Vertex-CFD inputs. .. py:data:: Maximum Iterations :type: integer :value: Positive integer :usage: Optional with ``Test Type = "MaxIters"`` :default: ``20`` in NOX; ``10`` in the Tempus default solver :description: Sets the maximum number of NOX nonlinear iterations before the status test reports failure. .. dropdown:: Test 2 :icon: bookmark :color: light :animate: fade-in-slide-down Searched Vertex-CFD inputs use ``Test 2`` for either a relative-residual test or a prescribed-iteration test. NOX does not otherwise restrict the type assigned to this index. .. py:data:: Test Type :type: string :value: ``"RelativeNormF"`` or ``"NStep"`` in searched Vertex-CFD inputs :usage: Required :default: None :description: Selects the additional status test. ``"RelativeNormF"`` checks reduction from the initial residual; ``"NStep"`` reports convergence after a prescribed number of nonlinear iterations. .. py:data:: Tolerance :no-index: :type: double :value: Relative residual reduction :usage: Optional with ``Test Type = "RelativeNormF"`` :default: ``1.0e-8`` :description: Declares convergence when the current residual norm is less than this value multiplied by the initial residual norm. .. py:data:: Scale Norms by Length :type: bool :value: ``true`` or ``false`` :usage: Optional with ``Test Type = "RelativeNormF"`` :default: ``false`` :description: Divides the initial and current residual norms by the square root of the residual-vector length before comparison. .. py:data:: Norm Type :type: string :value: ``"Two Norm"``, ``"One Norm"``, or ``"Max Norm"`` :usage: Optional with ``Test Type = "RelativeNormF"`` :default: ``"Two Norm"`` :description: Selects the residual norm used by the relative convergence test. .. py:data:: Number of Nonlinear Iterations :type: integer :value: Nonlinear iterations before convergence :usage: Optional with ``Test Type = "NStep"`` :default: ``1`` :description: Sets the prescribed iteration count after the initial ramping phase. .. py:data:: Number of Initial Ramping Steps :type: integer :value: Number of nonlinear solves in the ramping phase :usage: Optional with ``Test Type = "NStep"`` :default: ``0`` :description: Applies the ramping-phase iteration count to this many initial nonlinear solves. .. py:data:: Number of Nonlinear Iterations in Ramping Phase :type: integer :value: Nonlinear iterations before convergence during ramping :usage: Optional with ``Test Type = "NStep"`` :default: ``10`` :description: Sets the prescribed iteration count while the initial ramping phase is active. .. dropdown:: Test 3 :icon: bookmark :color: light :animate: fade-in-slide-down Some Vertex-CFD inputs use ``Test 3`` for ``NStep`` when ``Test 2`` is ``RelativeNormF``. This index is not reserved for ``NStep``; its type is selected by its own required ``Test Type`` entry. When it is ``NStep``, it accepts the same three iteration-count entries documented under ``Test 2``. Examples -------- .. literalinclude:: ../../../../examples/inputs/plasma_species/plasma_species_gauss_3d.xml :language: xml :linenos: :start-at: :end-at: :emphasize-lines: 2-4,6-7,10-11 :caption: Residual convergence and maximum-iteration tests used by a Vertex-CFD implicit solve. The following block adds relative-residual and prescribed-iteration tests: .. literalinclude:: ../../../../examples/inputs/incompressible/incompressible_2d_k_tau_channel.xml :language: xml :linenos: :start-at: :end-at: :caption: Additional RelativeNormF and NStep tests used by a turbulence solve.