.. ############################################################################ .. manual/packages/vertex-cfd/nonlinear_solve_line_search.rst .. ############################################################################ .. _sec_nonlinear_solve_line_search: ******************* NOX Line Search ******************* The ``Line Search`` sublist selects how NOX scales and accepts the search direction before updating the nonlinear solution. .. dropdown:: :icon: multi-select :color: primary :animate: fade-in-slide-down .. py:data:: Method :no-index: :type: string :value: ``"Full Step"``, ``"Backtrack"``, ``"Polynomial"``, ``"More'-Thuente"``, ``"NonlinearCG"``, ``"Safeguarded Step"``, or ``"Safeguarded Direction"`` :usage: Optional with ``Nonlinear Solver = "Line Search Based"`` :default: ``"Full Step"`` :description: Selects a built-in NOX line-search algorithm. Vertex-CFD inputs use ``"Full Step"``. NOX also accepts ``"User Defined"`` when a C++ line-search-factory object is supplied; that object cannot be represented by an XML string alone. ``"Safeguarded Direction"`` is available only in Thyra-enabled NOX builds. .. dropdown:: Full Step :icon: bookmark :color: light :animate: fade-in-slide-down .. py:data:: Full Step :type: double :value: Step length :usage: Optional with ``Method = "Full Step"`` :default: ``1.0`` :description: Multiplies the computed search direction before updating the nonlinear solution. .. dropdown:: Alternative line-search sublists :icon: bookmark :color: light :animate: fade-in-slide-down This is a documentation grouping, not an XML sublist. The parameter names and defaults below come from Trilinos NOX. None of these methods occurs in the searched Vertex-CFD examples, regression inputs, or driver-test inputs, so their integration with Vertex-CFD is not covered by a project test. .. dropdown:: Backtrack :icon: bookmark :color: light :animate: fade-in-slide-down Selected by ``Method = "Backtrack"``. ``Minimum Step`` defaults to ``1.0e-12``, ``Default Step`` to ``1.0``, ``Recovery Step`` to the default step, ``Max Iters`` to ``100``, and ``Reduction Factor`` to ``0.5``. The reduction factor must be strictly between zero and one. .. dropdown:: Polynomial :icon: bookmark :color: light :animate: fade-in-slide-down Selected by ``Method = "Polynomial"``. Its principal defaults are ``"Armijo-Goldstein"`` for ``Sufficient Decrease Condition``, ``"Cubic"`` for ``Interpolation Type``, and ``"Constant"`` for ``Recovery Step Type``. ``Minimum Step`` defaults to ``1.0e-12``, ``Default Step`` to ``1.0``, ``Max Iters`` to ``100``, and ``Alpha Factor`` to ``1.0e-4``. NOX also reads ``Recovery Step``, interpolation-bound factors, counter controls, and the allowed-increase controls from this sublist. .. dropdown:: More'-Thuente :icon: bookmark :color: light :animate: fade-in-slide-down Selected by ``Method = "More'-Thuente"``. ``Sufficient Decrease``, ``Curvature Condition``, and ``Interval Width`` default to ``1.0e-4``, ``0.9999``, and ``1.0e-15``. The step bounds default to ``1.0e-12`` and ``1.0e6``; ``Max Iters`` defaults to ``20``; and the default and recovery steps are ``1.0``. It also accepts ``Sufficient Decrease Condition``, ``Recovery Step Type``, and ``Optimize Slope Calculation``. .. dropdown:: NonlinearCG :icon: bookmark :color: light :animate: fade-in-slide-down Selected by ``Method = "NonlinearCG"``. The NOX implementation does not read a ``NonlinearCG`` parameter sublist; it computes a single step from directional derivatives. .. dropdown:: Safeguarded Step :icon: bookmark :color: light :animate: fade-in-slide-down Selected by ``Method = "Safeguarded Step"``. .. py:data:: Update Limit Vector :type: ``Teuchos::RCP`` :value: C++ vector object :usage: Required with ``Method = "Safeguarded Step"`` :default: ``Teuchos::null`` :description: Supplies the maximum allowed update for each entry in the search direction. NOX rejects a null vector, and Vertex-CFD does not provide an XML factory for this object. .. py:data:: Step Size Lower Bound :type: double :value: Lower bound for the computed step :usage: Optional with ``Method = "Safeguarded Step"`` :default: ``1.0e-3`` :description: Clamps the safeguarded step to at least this value. .. py:data:: Step Size Upper Bound :type: double :value: Upper bound for the computed step :usage: Optional with ``Method = "Safeguarded Step"`` :default: ``1.0`` :description: Clamps the safeguarded step to at most this value. .. py:data:: Use Counters :type: bool :value: ``true`` or ``false`` :usage: Optional with ``Method = "Safeguarded Step"`` :default: ``false`` :description: Enables NOX line-search statistics for this method. A complete XML example cannot be provided for this method. Although the bounds and counter flag are XML-representable, the required ``Update Limit Vector`` is a C++ object. The owning NOX tests construct that vector programmatically, and no searched Vertex-CFD input exposes an XML factory for it. .. dropdown:: Safeguarded Direction :icon: bookmark :color: light :animate: fade-in-slide-down Selected by ``Method = "Safeguarded Direction"`` when NOX is built with Thyra support. It also requires an object-valued ``Update Limit Vector`` and cannot be configured using XML values alone. ``Use Counters`` defaults to ``false``. Example ------- .. literalinclude:: ../../../../examples/inputs/plasma_species/plasma_species_gauss_3d.xml :language: xml :linenos: :start-at: :end-at: :emphasize-lines: 2-4 :caption: Full-step line search used by a Vertex-CFD implicit solve.