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

.. _sec_nonlinear_solve_reuse_preconditioner:

************************
NOX Preconditioner Reuse
************************

The optional ``Reuse Preconditioner`` sublist configures the preconditioner-reuse observer installed by Vertex-CFD.

.. dropdown:: <Reuse Preconditioner>
   :icon: multi-select
   :color: primary
   :animate: fade-in-slide-down

   This optional sublist enables the NOX preconditioner-reuse
   observer installed by Vertex-CFD. At least one update trigger
   must be enabled, and the configured linear solver must provide a
   preconditioner.

   .. py:data:: Update prec at start of nonlinear solve

      :type: bool
      :value: ``true`` or ``false``
      :usage: Optional
      :default: ``true``
      :description: Rebuilds the preconditioner at nonlinear iteration zero of every solve.

   .. py:data:: Update prec after this many nonlinear solves

      :type: integer
      :value: Positive interval; zero or negative disables
      :usage: Optional
      :default: ``0``
      :description: Rebuilds the preconditioner at the start of every specified number of nonlinear solves.

   .. py:data:: Reset nonlinear solve count on failed solve

      :type: bool
      :value: ``true`` or ``false``
      :usage: Optional
      :default: ``true``
      :description: Resets the nonlinear-solve interval counter when a solve fails. This entry applies when periodic updates by nonlinear-solve count are enabled.

   .. py:data:: Update prec after this many nonlinear iterations

      :type: integer
      :value: Positive interval; zero or negative disables
      :usage: Optional
      :default: ``0``
      :description: Rebuilds the preconditioner at the specified nonlinear-iteration interval.

   .. py:data:: Update prec after this many stalled linear solves

      :type: integer
      :value: Positive count; zero or negative disables
      :usage: Optional
      :default: ``0``
      :description: Rebuilds the preconditioner after this many consecutive stalled linear solves. A failed linear solve also triggers an update.

   .. py:data:: Max linear iterations for stall

      :type: integer
      :value: Linear-iteration threshold
      :usage: Optional when stalled-linear-solve updates are enabled
      :default: ``50``
      :description: Declares a linear solve stalled when its iteration count reaches this threshold.

Example
-------

.. literalinclude:: ../../../../examples/inputs/incompressible/incompressible_2d_k_tau_channel.xml
   :language: xml
   :linenos:
   :start-at: <ParameterList name="Reuse Preconditioner">
   :end-at: </ParameterList> <!-- Reuse Preconditioner -->
   :caption: Rebuild the preconditioner at every solve and after every two nonlinear solves.