.. ############################################################################
.. manual/packages/vertex-cfd/nonlinear_solve_thyra_group_options.rst
.. ############################################################################

.. _sec_nonlinear_solve_thyra_group_options:

***********************
NOX Thyra Group Options
***********************

The optional ``Thyra Group Options`` sublist controls residual and Jacobian scaling in the Thyra-backed NOX group.

.. dropdown:: <Thyra Group Options>
   :icon: multi-select
   :color: primary
   :animate: fade-in-slide-down

   The Thyra nonlinear-solver adapter parses this top-level NOX
   sublist when it constructs the NOX group. It is not specific to
   the pseudo-transient solver. No searched Vertex-CFD input
   populates it.

   .. py:data:: Function Scaling

      :type: string
      :value: ``"None"``, ``"Row Sum"``, or ``"User Defined"``
      :usage: Optional
      :default: ``"None"``
      :description: Selects residual and Jacobian scaling. ``"Row Sum"`` creates a row-sum scaling vector. ``"User Defined"`` requires the C++ vector entry documented below and therefore cannot be configured using XML values alone.

   .. py:data:: Update Row Sum Scaling

      :type: string
      :value: ``"Before Each Nonlinear Solve"`` or ``"Before Each Nonlinear Iteration"``
      :usage: Optional with ``Function Scaling = "Row Sum"``
      :default: ``"Before Each Nonlinear Solve"``
      :description: Selects when the inverse row-sum scaling vector is recomputed.

   .. py:data:: User Defined Scaling

      :type: ``Teuchos::RCP<Thyra::VectorBase<double>>``
      :value: C++ vector object
      :usage: Required with ``Function Scaling = "User Defined"``
      :default: ``Teuchos::null``
      :description: Supplies the user-defined function-scaling vector. This object-valued entry cannot be constructed by the Vertex-CFD XML input.

   .. py:data:: Do Right Scaling First

      :type: bool
      :value: ``true`` or ``false``
      :usage: Optional
      :default: ``false``
      :description: Controls the ordering when both right scaling and function scaling are present. The right-scaling vectors are C++ object entries on the NOX list and are not configurable as ordinary Vertex-CFD XML values.

Example
-------

.. code-block:: xml
   :linenos:
   :caption: Default Thyra group scaling options for an implicit solve.

   <ParameterList name="Thyra Group Options">
     <Parameter name="Function Scaling" type="string" value="None"/>
     <Parameter name="Update Row Sum Scaling" type="string" value="Before Each Nonlinear Solve"/>
     <Parameter name="Do Right Scaling First" type="bool" value="false"/>
   </ParameterList>