.. ############################################################################ .. manual/packages/vertex-cfd/nonlinear_solve.rst .. ############################################################################ .. _sec_nonlinear_solve: ****************************** Nonlinear solve (NOX) ****************************** Implicit Tempus steppers use NOX to solve the nonlinear system formed at each time step or implicit stage. Vertex-CFD passes the named solver list to Tempus and registers an observer that prints nonlinear-iteration diagnostics. Most entries in the ``NOX`` list are validated and used by Trilinos NOX rather than by Vertex-CFD directly. The common Vertex-CFD configuration follows this hierarchy:: Tempus `-- Default Stepper |-- Solver Name |-- Zero Initial Guess `-- Default Solver `-- NOX |-- Direction | `-- Newton | `-- Linear Solver |-- Line Search | `-- Full Step |-- Printing | `-- Output Information |-- Solver Options |-- Thyra Group Options (optional) |-- Status Tests | `-- Test 0, Test 1, ... `-- Reuse Preconditioner (optional) .. note:: Keep the exact names ``Default Stepper`` and ``Default Solver`` in a Vertex-CFD input. Although Tempus can select named stepper and solver lists, the Vertex-CFD driver uses this exact path when it installs the NOX observer and checks for preconditioner reuse. .. dropdown:: :icon: multi-select :color: primary :animate: fade-in-slide-down The nonlinear solver is configured under ``Default Stepper``, followed by ``Default Solver`` and its ``NOX`` sublist. .. dropdown:: Default Stepper :icon: bookmark :color: light :animate: fade-in-slide-down .. py:data:: Solver Name :type: string :value: ``"Default Solver"`` :usage: Required for an explicitly configured Vertex-CFD implicit solver :default: ``"Default Solver"`` :description: Selects the solver sublist containing the ``NOX`` configuration. Keep ``"Default Solver"`` because the Vertex-CFD driver accesses that sublist directly when installing its NOX observers. .. py:data:: Zero Initial Guess :type: bool :value: ``true`` or ``false`` :usage: Optional :default: ``false`` :description: When ``true``, initializes the solution vector to zero before each implicit nonlinear solve. When ``false``, the stepper-provided initial guess is retained. .. dropdown:: Default Solver :icon: bookmark :color: light :animate: fade-in-slide-down ``Default Solver`` is the solver-list name expected by the Vertex-CFD driver. .. dropdown:: NOX :icon: bookmark :color: light :animate: fade-in-slide-down .. py:data:: Nonlinear Solver :type: string :value: ``"Line Search Based"``, ``"Newton"``, ``"Trust Region Based"``, ``"Inexact Trust Region Based"``, ``"Tensor Based"``, ``"Anderson Accelerated Fixed-Point"``, ``"Single Step"``, or ``"Pseudo-Transient"`` :usage: Optional :default: ``"Line Search Based"`` :description: Selects the NOX nonlinear-solver algorithm. ``"Newton"`` is accepted as an alias for ``"Line Search Based"``. Vertex-CFD example and regression inputs use ``"Line Search Based"``; other choices require their corresponding NOX method-specific sublists. ``"Pseudo-Transient"`` is available when NOX is built with Thyra support. .. dropdown:: Strategy-specific NOX sublists :icon: bookmark :color: light :animate: fade-in-slide-down This is a documentation grouping, not an XML sublist. No searched Vertex-CFD input selects the alternative nonlinear solvers below. NOX accepts the listed sublists, but their use with Vertex-CFD remains unverified because no matching example or regression input is available. .. dropdown:: Trust Region :icon: bookmark :color: light :animate: fade-in-slide-down Used by ``"Trust Region Based"`` and ``"Inexact Trust Region Based"``. The standard trust-region solver reads ``Minimum Trust Region Radius`` (``1.0e-6``), ``Maximum Trust Region Radius`` (``1.0e10``), ``Initial Trust Region Radius`` (``1.0``), ``Minimum Improvement Ratio`` (``1.0e-4``), ``Contraction Trigger Ratio`` (``0.1``), ``Expansion Trigger Ratio`` (``0.75``), ``Contraction Factor`` (``0.25``), ``Expansion Factor`` (``4.0``), ``Recovery Step`` (``1.0``), and ``Use Ared/Pred Ratio Calculation`` (``false``). The inexact solver adds its own trust-region controls; no searched Vertex-CFD input exercises either solver. .. dropdown:: Cauchy Direction :icon: bookmark :color: light :animate: fade-in-slide-down Used by the trust-region solvers to configure their steepest-descent Cauchy direction. .. dropdown:: Steepest Descent :icon: bookmark :color: light :animate: fade-in-slide-down The trust-region solvers create this nested direction list with ``Scaling Type = "Quadratic Model Min"`` by default. .. dropdown:: Tensor-based solver sublists :icon: bookmark :color: light :animate: fade-in-slide-down This is a documentation grouping for ``Nonlinear Solver = "Tensor Based"``, not an XML sublist. That solver interprets ``Direction`` and ``Line Search`` itself rather than using the ordinary direction and line-search factories. .. dropdown:: Tensor :icon: bookmark :color: light :animate: fade-in-slide-down With ``Direction/Method = "Tensor"`` (the tensor-solver default), this selected direction sublist accepts ``Rescue Bad Newton Solve`` with a default of ``true`` and a nested ``Linear Solver`` convergence-request list. ``Direction/Use Modified Bouaricha`` defaults to ``true``. .. dropdown:: Tensor line-search method sublists :icon: bookmark :color: light :animate: fade-in-slide-down This is a documentation grouping, not an XML sublist. ``Line Search/Method`` selects ``Curvilinear``, ``Dual``, ``Standard``, ``Full Step``, or ``Newton`` and defaults to ``"Curvilinear"``. The selected sublist reads ``Recovery Step Type`` (``"Constant"``), ``Minimum Step`` (``1.0e-12``), ``Default Step`` (``1.0``), ``Recovery Step`` (``0.0``), ``Max Iters`` (``40``), ``Alpha Factor`` (``1.0e-4``), ``Lambda Selection`` (``"Halving"``), and ``Sufficient Decrease Condition`` (``"Armijo-Goldstein"``). .. dropdown:: Anderson Parameters :icon: bookmark :color: light :animate: fade-in-slide-down Used by ``"Anderson Accelerated Fixed-Point"``. NOX validates ``Storage Depth`` (``2``), ``Mixing Parameter`` (``1.0``), ``Reorthogonalization Frequency`` (``0``), ``Adjust Matrix for Condition Number`` (``false``), ``Condition Number Drop Tolerance`` (``1.0e12``), and ``Acceleration Start Iteration`` (``1``). ``Disable Checks for Unit Testing`` defaults to ``false`` and is explicitly not intended for user input. .. dropdown:: Preconditioning :icon: bookmark :color: light :animate: fade-in-slide-down ``Precondition`` enables Anderson preconditioning and defaults to ``false``. ``Recompute Jacobian`` controls whether NOX computes the Jacobian for that preconditioner and also defaults to ``false``. .. dropdown:: Single Step Solver :icon: bookmark :color: light :animate: fade-in-slide-down Used by ``"Single Step"``. ``Ignore Linear Solver Failures`` defaults to ``false``; ``Update Jacobian`` defaults to ``true``; and ``Print Norms`` and ``Compute Relative Norm`` both default to ``false``. .. dropdown:: Linear Solver :icon: bookmark :color: light :animate: fade-in-slide-down Supplies the convergence request for the single Newton update. .. dropdown:: Pseudo-Transient :icon: bookmark :color: light :animate: fade-in-slide-down Used by the Thyra-only ``"Pseudo-Transient"`` solver. ``deltaInit``, ``deltaMax``, and ``deltaMin`` default to ``1.0e-4``, ``1.0``, and ``1.0e-5``, respectively. ``Use Transient Residual in Direction Computation`` defaults to ``true``. ``Maximum Number of Pseudo-Transient Iterations`` defaults to the maximum representable ``int`` value. NOX sublists ------------ Each documented NOX sublist has its own parameter-reference page: .. toctree:: :maxdepth: 1 :titlesonly: nonlinear_solve_direction.rst nonlinear_solve_line_search.rst nonlinear_solve_printing.rst nonlinear_solve_solver_options.rst nonlinear_solve_thyra_group_options.rst nonlinear_solve_status_tests.rst nonlinear_solve_reuse_preconditioner.rst Example ------- The following input contains the standard NOX configuration used by Vertex-CFD. The emphasized lines select the direction and line search, choose the nonlinear solver, and define its termination tests. .. literalinclude:: ../../../../examples/inputs/plasma_species/plasma_species_gauss_3d.xml :language: xml :linenos: :start-at: :end-at: :emphasize-lines: 3,5-6,14-16,19,36,39-49 :caption: Standard line-search-based NOX configuration for an implicit Tempus stepper.