.. ############################################################################ .. manual/packages/vertex-cfd/nonlinear_solve_direction.rst .. ############################################################################ .. _sec_nonlinear_solve_direction: ******************* NOX Direction ******************* The ``Direction`` sublist selects the search-direction method used by a line-search-based NOX solve and configures its method-specific sublists. .. dropdown:: :icon: multi-select :color: primary :animate: fade-in-slide-down .. py:data:: Method :type: string :value: ``"Newton"``, ``"Steepest Descent"``, ``"NonlinearCG"``, or ``"Broyden"`` :usage: Optional :default: ``"Newton"`` :description: Selects a built-in search-direction method that can be configured entirely from XML. Most Vertex-CFD inputs use ``"Newton"``; ``"Broyden"`` is also used by an inductionless-MHD example. NOX additionally accepts ``"User Defined"`` when a C++ direction-factory object is supplied; that object cannot be represented by an XML string alone. .. dropdown:: Newton :icon: bookmark :color: light :animate: fade-in-slide-down .. py:data:: Forcing Term Method :type: string :value: ``"Constant"``, ``"Type 1"``, or ``"Type 2"`` :usage: Optional with ``Method = "Newton"`` :default: ``"Constant"`` :description: Controls whether the linear-solve tolerance is constant or adjusted with an inexact-Newton forcing term. .. py:data:: Rescue Bad Newton Solve :type: bool :value: ``true`` or ``false`` :usage: Optional with ``Method = "Newton"`` :default: ``true`` :description: When ``true``, NOX uses the computed Newton direction even when the linear solve does not report convergence. When ``false``, a failed linear solve causes the direction computation to fail. .. py:data:: Forcing Term Minimum Tolerance :type: double :value: Minimum inexact-Newton forcing tolerance :usage: Optional with ``Forcing Term Method = "Type 1"`` or ``"Type 2"`` :default: ``1.0e-4`` :description: Sets the lower bound applied to the adjusted linear-solve tolerance. .. py:data:: Forcing Term Maximum Tolerance :type: double :value: Maximum inexact-Newton forcing tolerance :usage: Optional with ``Forcing Term Method = "Type 1"`` or ``"Type 2"`` :default: ``0.9`` :description: Sets the upper bound applied to the adjusted linear-solve tolerance. .. py:data:: Forcing Term Initial Tolerance :type: double :value: Initial inexact-Newton forcing tolerance :usage: Optional with ``Forcing Term Method = "Type 1"`` or ``"Type 2"`` :default: ``0.01`` :description: Sets the linear-solve tolerance used at the first nonlinear iteration. .. py:data:: Forcing Term Alpha :type: double :value: Inexact-Newton forcing exponent :usage: Optional with ``Forcing Term Method = "Type 2"`` :default: ``1.5`` :description: Sets the exponent used by the Type 2 forcing-term update. .. py:data:: Forcing Term Gamma :type: double :value: Inexact-Newton forcing scale :usage: Optional with ``Forcing Term Method = "Type 2"`` :default: ``0.9`` :description: Sets the scale factor used by the Type 2 forcing-term update. .. py:data:: Set Tolerance in Parameter List :type: bool :value: ``true`` or ``false`` :usage: Optional; has no effect for ``Method = "Newton"`` :default: ``true`` :description: Compatibility entry shared with NOX's inexact-Newton utility. The Newton direction validates this entry but does not read it; when Newton uses an adjustable forcing term, it always writes the updated value to ``Linear Solver/Tolerance``. The flag controls that write only in algorithms that use the shared utility, including Broyden. .. dropdown:: Linear Solver :icon: bookmark :color: light :animate: fade-in-slide-down This sublist controls the convergence request passed from the NOX Newton direction to the Thyra linear solve. It is distinct from the top-level ```` block, which selects and configures the actual Stratimikos linear solver and preconditioner. .. py:data:: Tolerance :type: double :value: Requested relative linear-solve tolerance :usage: Optional :default: ``1.0e-10`` :description: Sets the requested tolerance for the Newton linear solve. When an inexact-Newton forcing method is active, NOX updates this entry at each nonlinear iteration. .. py:data:: Solve Measure Numerator :type: string :value: ``"None"``, ``"Norm Residual"``, ``"Norm Solution"``, ``"Norm Initial Residual"``, or ``"Norm RHS"`` :usage: Optional :default: ``"Norm Residual"`` :description: Selects the numerator of the Thyra convergence measure used for the linear solve. .. py:data:: Solve Measure Denominator :type: string :value: ``"None"``, ``"Norm Residual"``, ``"Norm Solution"``, ``"Norm Initial Residual"``, or ``"Norm RHS"`` :usage: Optional :default: ``"Norm Initial Residual"`` :description: Selects the denominator of the Thyra convergence measure used for the linear solve. .. dropdown:: Stratimikos Linear Solver :icon: bookmark :color: light :animate: fade-in-slide-down Vertex-CFD inputs retain this NOX sublist as an empty compatibility container. The active Vertex-CFD path uses ``NOX::Thyra::Group`` and obtains the solver and preconditioner from the top-level ```` block; it does not configure them from this nested list. .. dropdown:: NOX Stratimikos Options :icon: bookmark :color: light :animate: fade-in-slide-down This is an empty compatibility sublist in all searched Vertex-CFD inputs. Options with this name belong to the older NOX Epetra Stratimikos interface and are not read by the Thyra-backed Vertex-CFD solve path. Leave this sublist empty. .. dropdown:: Broyden :icon: bookmark :color: light :animate: fade-in-slide-down This sublist is selected by ``Method = "Broyden"``. NOX creates it with defaults when it is absent, as in the inductionless-MHD example. .. py:data:: Restart Frequency :type: integer :value: Nonlinear iterations between Jacobian restarts :usage: Optional :default: ``10`` :description: Recomputes the Jacobian and clears the stored Broyden updates at this interval. .. py:data:: Max Convergence Rate :type: double :value: Maximum accepted residual convergence rate :usage: Optional :default: ``1.0`` :description: Restarts the Broyden approximation when the nonlinear convergence rate exceeds this value. .. py:data:: Memory :type: integer :value: Number of Broyden updates retained :usage: Optional :default: Value of ``Restart Frequency`` :description: Limits the number of stored Broyden update vectors. ``Broyden`` also accepts the forcing-term entries and a nested ``Linear Solver`` list described under ``Newton``. Its constant-forcing linear tolerance defaults to ``1.0e-4``. .. dropdown:: Steepest Descent :icon: bookmark :color: light :animate: fade-in-slide-down .. py:data:: Scaling Type :type: string :value: ``"2-Norm"``, ``"F 2-Norm"``, ``"Quadratic Model Min"``, or ``"None"`` :usage: Optional with ``Method = "Steepest Descent"`` :default: ``"2-Norm"`` :description: Selects how NOX scales the steepest-descent direction. No searched Vertex-CFD input selects this method. .. dropdown:: Nonlinear CG :icon: bookmark :color: light :animate: fade-in-slide-down .. py:data:: Restart Frequency :type: integer :value: Nonlinear iterations between restarts :usage: Optional with ``Method = "NonlinearCG"`` :default: ``10`` :description: Restarts the nonlinear conjugate-gradient recurrence at this interval. .. py:data:: Precondition :type: string :value: ``"On"`` or ``"Off"`` :usage: Optional with ``Method = "NonlinearCG"`` :default: ``"Off"`` :description: Enables right preconditioning of the nonlinear conjugate-gradient direction. .. py:data:: Orthogonalize :type: string :value: ``"Fletcher-Reeves"`` or ``"Polak-Ribiere"`` :usage: Optional with ``Method = "NonlinearCG"`` :default: ``"Fletcher-Reeves"`` :description: Selects the conjugate-gradient recurrence. .. dropdown:: Linear Solver :icon: bookmark :color: light :animate: fade-in-slide-down Supplies the right-preconditioning parameters when ``Precondition = "On"``. No searched Vertex-CFD input selects nonlinear conjugate gradient. Example ------- .. literalinclude:: ../../../../examples/inputs/plasma_species/plasma_species_gauss_3d.xml :language: xml :linenos: :start-at: :end-at: :emphasize-lines: 2-5 :caption: Newton direction configuration used by a Vertex-CFD implicit solve. The Newton linear-solve tolerance below is copied exactly from ``examples/inputs/incompressible/incompressible_2d_planar_poiseuille.xml``. An inline block is used because that file contains both top-level and NOX-nested lists named ``Linear Solver``, so ``literalinclude`` markers cannot select this complete block unambiguously. .. code-block:: xml :linenos: :caption: Override the requested tolerance for the Newton linear solve.