.. _implicit-predictors:

**********
Predictors
**********

Predictors are an important component of the nonlinear implicit solution strategy in Sierra/SM. A predictor is used to generate an initial trial solution for a load step or for a multilevel solver model problem. The goal of the predictor is to generate a trial solution that is as close as possible to the actual converged solution. A good prediction that gives a trial solution close to the actual solution can dramatically reduce the number of iterations required for convergence.

There are two types of predictors used in Adagio: the load step predictor and the level 1 predictor. The load step predictor, documented in Section :numref:`implicit-predictors-loadstep`, estimates a solution at the beginning of a new load step, and is applicable to all types of models. The level 1 predictor estimates the solution at the beginning of a new level 1 model problem in the multilevel solver. This predictor type, documented in :numref:`implicit-predictors-mllevelpred`, is only applicable for the multilevel solver.

.. _implicit-predictors-loadstep:

Loadstep Predictor
==================

.. code-block:: sierrainput

   BEGIN LOADSTEP PREDICTOR
     TYPE = <string>SCALE_FACTOR|SECANT|
       EXTERNAL|EXTERNAL_FIRST(SECANT)
     SCALE FACTOR = <real>scale_factor(1.0)
       [<real>first_scale_factor]
       [DURING <string list>period_names]
     SLIP SCALE FACTOR = <real>slip_factor(1.0)
       [DURING <string list>period_names]
   END [LOADSTEP PREDICTOR]

The ``LOADSTEP PREDICTOR`` command block controls the behavior of the predictor that is used to predict the solution at the beginning of a new load step. This command block is placed in the ``SOLVER`` scope.

Predictor Type
--------------

.. code-block:: sierrainput

   TYPE = <string>SCALE_FACTOR|SECANT|
     EXTERNAL|EXTERNAL_FIRST(SECANT)

There are multiple types of load step predictors available in Adagio that are suitable for different types of analysis. The predictor type is selected using the ``TYPE`` command line in the ``LOADSTEP PREDICTOR`` command block.

- The scale factor predictor is selected with the ``SCALE_FACTOR`` option. This type of predictor extrapolates from the solution of the previous time step using the velocity field from that step, multiplied by a scale factor, to obtain a trial solution. The actual scale factor that is applied can be controlled with the ``SCALE FACTOR`` command line, which also appears in the ``LOADSTEP PREDICTOR`` command block. This type of predictor works well with models that have smoothly varying loads.

- The secant predictor is selected with the ``SECANT`` option, which is useful for scenarios in which the loading may not be monotonic. This type of predictor uses a line search to compute an optimal scaling factor for use in extrapolating from the previous solution. This type of predictor is the default, and provides good performance without requiring user intervention to select appropriate scale factors.

- The ``EXTERNAL`` predictor is experimental and should not generally be used. This option is discussed in more detail in the in development manual.

Scale Factor
------------

.. code-block:: sierrainput

   SCALE FACTOR = <real>scale_factor(1.0)
     [<real>first_scale_factor]
     [DURING <string list>period_names]

The ``SCALE FACTOR`` command controls the behavior of the ``SCALE_FACTOR`` predictor type. The velocity field of the previous step, multiplied by the value of ``scale_factor``, is used to extrapolate from the previous solution to obtain a trial solution. The default value of 1.0 provides good performance on models that experience smooth loading. 

Setting the value of ``scale_factor`` to 0.0 effectively turns off the predictor. Note, if an analysis has trouble reaching convergence turning off the predictor with a zero scale factor may be helpful. This is particularly true of analysis with contact or other potentially time discontinuous boundary conditions. Extrapolating the solution between steps with different boundary conditions may  overshoot the solution in a way from which is difficult to recover.

The optional ``first_scale_factor`` parameter is used as the scale factor for the first step of a time period. If ``first_scale_factor`` is omitted, the default behavior is to use ``scale_factor`` for all time steps. Models are often subjected to loading that is mostly monotonic, but with discontinuities at the beginning of a new period. Using 1.0 and 0.0 for the values of ``scale_factor`` and ``first_scale_factor``, respectively, often gives good performance in such cases.

The ``SCALE FACTOR`` command line can be appended with the ``DURING`` specification, as discussed in :numref:`implicit-cg-convergence`. This allows for the scale factor to be specified per time period.

Slip Scale Factor
-----------------

.. code-block:: sierrainput

   SLIP SCALE FACTOR = <real>slip_factor(1.0)
     [DURING <string list>period_names]

The ``SLIP SCALE FACTOR`` only has an effect in a analyses with contact that use the kinematic contact enforcement option, see :numref:`contact-enforcement` for details.

The prediction of slip on side B nodes that are currently active in sliding contact can be controlled separately from other nodes in the model by using the ``SLIP SCALE FACTOR`` command line. The parameter ``slip_factor`` controls the scaling of the predicted slip on these nodes. If ``slip_factor`` is left at its default value of 1.0, contact slip will be predicted using the same scale factor used for the rest of the model. If the value of ``slip_factor`` is set to 0.0, the predicted solution will not allow any sliding contact nodes to slip. This command line applies to both the ``SCALE_FACTOR`` and the ``SECANT`` types of predictors.

The ``SLIP SCALE FACTOR`` command line can be appended with the ``DURING`` specification, as discussed in :numref:`implicit-cg-convergence`.

.. _implicit-predictors-mllevelpred:

Level Predictor
===============

.. code-block:: sierrainput

   LEVEL 1 PREDICTOR = <string>NONE|DEFAULT(DEFAULT)

The ``LEVEL 1 PREDICTOR`` command line controls the level 1 predictor. This command line appears in the ``SOLVER`` command block and is only applicable if the multilevel solver is used. The level 1 predictor estimates the solution for the next model problem based on the solution of the previous model problem. The default behavior is to enable this predictor selectively based on what solver controls are used (indicated by ``DEFAULT``). The predictor can be turned off in all cases with the ``NONE``.

Loadstep Predictor Input Example
================================

The below example includes use of the predictor. The example predictor definition would be appropriate for an analysis with discontinuous loading during time period ``p1``  followed by a smoother loading during time period ``p2``. Turning off the predictor in time period ``p1`` prevents overshooting solutions during sharp changes in loading. Turning back on the predictor in time period ``p2`` allows acceleration of solution in the more uniformly loaded time period.

.. code-block:: sierrainput

   begin solver
     begin loadstep predictor
       type = secant
       scale factor = 0 0 during p1
       scale factor = 1 0 during p2
     end
     Begin cg
       target relative residual = 1.0e-09
       Maximum Iterations       = 100
     end
   end
