**************************
Control Reaction Diffusion
**************************

.. admonition:: Implicit only
   :class: admonition warning

   For implicit analyses, it is recommended to use the alternating minimization strategy to iterate between the phase-field update and displacement solution to ensure that an equilibrium state is reached. This is crucial for temporal convergence for implicit analyses with large time-steps.

.. admonition:: Explicit only
   :class: admonition warning

   For explicit analyses, it is assumed that the time-step is sufficiently small that the phase field is never far from equilibrium, so iteration between the two problems is unnecessary. In fact, given the relative cost of the phase-field solve compared to the explicit integration of the displacement system, alternating minimization would be prohibitively expensive.

The ``CONTROL REACTION DIFFUSION`` block within the implicit solver block provides the means to perform this iteration. Using this capability, the solver iterates between the displacement solve and the phase field solve until either convergence is realized or the maximum number of iterations is reached. Convergence is assessed using the displacement system residual immediately after the phase field solve; if the phase field update does not throw the displacement system out of equilibrium, it is said to have converged.

.. note::
    
   The phase field residual is not explicitly assessed. Implementation of a coupled energy-residual norm is under consideration.

.. warning::

   Due to the additional level of iteration, it is not recommended to use ``CONTROL REACTION DIFFUSION``  together with other control iterations such as ``CONTROL CONTACT``, ``CONTROL STIFFNESS``, ``CONTROL FAILURE``, or ``CONTROL DAMPED SOLVE``.

.. code-block:: sierrainput

   BEGIN CONTROL REACTION DIFFUSION
     ACCEPTABLE RELATIVE RESIDUAL = <real>accept_rel_resid
     ACCEPTABLE RESIDUAL = <real>accept_resid
     TARGET RELATIVE RESIDUAL = <real>target_rel_resid
     TARGET RESIDUAL = <real>target_resid
     
     ITERATION PLOT = <integer>iplot
     ITERATION PLOT OUTPUT BLOCKS = <string_list>plot_blocks
     
     LEVEL = <integer>control_rxndiff_level(1)
     
     MAXIMUM ITERATIONS = <integer>max_iter(100)
     MINIMUM ITERATIONS = <integer>min_iter(0)
     
     REFERENCE = EXTERNAL|INTERNAL|RESIDUAL|BELYTSCHKO|ENERGY(EXTERNAL)
     RESIDUAL NORM TYPE = ALL|ALLTRANSLATION|SCALE_RB_ROTATIONS(ALL)
     RESIDUAL ROUNDOFF TOLERANCE = <real>resid_roundoff_tol
   END

The commands in the ``CONTROL REACTION DIFFUSION`` mirror those found in other Sierra/SM control blocks.
