.. _implicit-damped:

********************
Control Damped Solve
********************

Control damped solve is used to aid implicit quasistatic runs in convergence. With implicit quasistatic problems, it is sometimes very difficult to achieve convergence with the cg solver alone (even when used in combination with the FETI equation solver). Some problems where convergence is difficult to achieve includes: problems with unconstrained rigid body motion, problems that contain very nonlinear physics, implicit contact problems that involve rebound or bounce, implicit contact problems where sliding occurs, and implicit fracture problems where failure introduces rigid body motion or softening materials.

At a high level, ``CONTROL DAMPED SOLVE`` places artificial springs to ground on nodes to allow the problem to converge. Once the springs are placed, ``CONTROL DAMPED SOLVE`` will iterate until the artificial spring force is below the user defined tolerance. To achieve convergence, the ground position of the springs is moved to the last predicted position at the control level. If the next predicted position is the same, the spring applies no force.

The command block for control damped solve is as follows:

.. code-block:: sierrainput

   BEGIN CONTROL DAMPED SOLVE [<string>damped solve_name]
     # Convergence commands
     TARGET SPRING FORCE = <real>target_spring_force 
     TARGET RELATIVE SPRING FORCE = <real>target_rel_spring_force
     ACCEPTABLE SPRING FORCE = <real>accept_spring_force 
     ACCEPTABLE RELATIVE SPRING FORCE = <real>accept_rel_spring_force
     REFERENCE = EXTERNAL|INTERNAL(EXTERNAL)
     MAXIMUM ITERATIONS = <integer>max_iter 
     MINIMUM ITERATIONS = <integer>min_iter 
     #
     # level selection command
     LEVEL = <integer>damped_solve_level
     #
     # artificial spring commands
     STIFFNESS FORM = SHIFTED|SCALED(SCALED)
     STIFFNESS FACTOR = <REAL>stiffness_factor
     FORCE DECAY = NONE|ITERFRAC|HALVED|TENTHED(HALVED)
     EVERY NTH NODE = <integer>nth_node(1)
     #
     # diagnostic output commands, off by default.
     ITERATION PLOT = <integer>iter_plot
       [DURING <string list>period_names]
     ITERATION PLOT OUTPUT BLOCKS  = <string list>plot_blocks
   END [CONTROL DAMPED SOLVE <string>damped solve_name]

To enable control damped solve, a ``CONTROL DAMPED SOLVE`` command block must exist in the ``SOLVER`` command block. The command lines within the ``CONTROL DAMPED SOLVE`` command block are used to establish convergence criteria, select the level for control damped solve within the multilevel solver, specify characteristics of the artificial springs, and output diagnostic information. These commands are described in detail in :numref:`implicit-damped-convergence` and :numref:`implicit-multilevel-common`.

.. _implicit-damped-convergence:

Convergence Command
===================

The command lines listed in this section specify convergence criteria for the control damped solve level.

.. code-block:: sierrainput

   TARGET SPRING FORCE = <real>target_spring_force 
   TARGET RELATIVE SPRING FORCE = <real>target_rel_spring_force
   ACCEPTABLE SPRING FORCE = <real>accept_spring_force 
   ACCEPTABLE RELATIVE SPRING FORCE = <real>accept_rel_spring_force
   REFERENCE = EXTERNAL|INTERNAL(EXTERNAL)
   MAXIMUM ITERATIONS = <integer>max_iter 
   MINIMUM ITERATIONS = <integer>min_iter 

Solver convergence is monitored for control damped solve by examining the force in the artificial springs. Convergence is evaluated by computing the :math:`L^2` norm of the spring forces and comparing that with a target convergence criteria specified by the user in the control damped solve block. The relative spring force is computed by dividing the spring force by a reference quantity that is indicative of the current loading conditions on the model. Note the spring force has units of force while the relative spring force is a dimensionless quantity where one or larger is an unconverged solution and the value moves towards zero for increasingly exact convergence. When using ``CONTROL DAMPED SOLVE``, at least one of the following must be specified: ``TARGET SPRING FORCE``, ``TARGET RELATIVE SPRING FORCE``, ``ACCEPTABLE SPRING FORCE``, or ``ACCEPTABLE RELATIVE SPRING FORCE``. 

The ``TARGET SPRING FORCE`` command specifies the target convergence force in terms of the actual spring force norm. The ``TARGET RELATIVE SPRING FORCE`` command specifies a convergence criterion in terms of the relative spring force norm. If both command lines are specified, the multilevel solver will accept the damped solve solution as converged if either the target spring force norm or the target relative spring force norm is below the specified values. 

Acceptable convergence criteria can also be used for damped solve convergence. If the solution has not converged to the specified target before the maximum number of iterations is reached, the spring force is checked against the acceptable convergence criteria. These criteria are specified via the ``ACCEPTABLE SPRING FORCE`` and ``ACCEPTABLE RELATIVE SPRING FORCE`` command lines. The concepts of acceptable spring force and acceptable relative spring force are the same as those used for the targets. If the solution has not met the target criteria but has met the acceptable criteria, the solution is allowed to proceed. The defaults for each of these acceptable criteria are 10 times the corresponding target criteria defaults.

If relative spring forces are given in the convergence criteria, the ``REFERENCE`` command line can be used to select the method for computing the reference load. This command line has two options: ``EXTERNAL`` and ``INTERNAL``. When using the default option (``EXTERNAL``), the  reference value is taken as the maximum of the :math:`L^2` norm of either the  current externally applied or reaction loads. The ``INTERNAL`` option uses the norm of the internal forces as the reference load. These criteria are further explained in :numref:`implicit-cg-convergence`.

The ``MAXIMUM ITERATIONS`` and ``MINIMUM ITERATIONS`` command lines specify the maximum and minimum number of damped solve updates, respectively. The default minimum number of iterations, ``min_iter``, is 0. If a number greater than 0 is specified, the multilevel solver will update the damped solve at least that many times, regardless of whether the convergence criteria have been met.

For an explanation of commands common to all controls, see :numref:`implicit-multilevel-common`.

Level Command
=============

When used in a multilevel solver the ``CONTROL DAMPED SOLVE`` command block is recommended to be at level 1 and be the only control acting at that level. This allows the artificial spring force to be minimized before considering other controls. For more details on the ``LEVEL`` command see :numref:`implicit-multilevel-common`. 

Control Damped Solve Artificial Spring Commands
===============================================

.. code-block:: sierrainput

   STIFFNESS FORM = SHIFTED|SCALED(SCALED)
   STIFFNESS FACTOR = <REAL>stiffness_factor
   FORCE DECAY = NONE|ITERFRAC|HALVED|TENTHED(HALVED)
   EVERY NTH NODE = <integer>nth_node(1)

Commands directly relating to the artificial springs created by ``CONTROL DAMPED SOLVE`` are described in this section. ``STIFFNESS FORM`` specifies how the stiffness of the artificial springs is determined. If option ``SHIFTED`` is used all artificial springs added have the same stiffness. That spring's stiffness is the maximum value of the nodal stiffness from the element stiffness contributions then scaled by the ``STIFFNESS FACTOR``. If the option ``SCALED`` is used the artificial springs stiffness is the node's nodal stiffness scaled by the ``STIFFNESS FACTOR``.

The ``STIFFNESS FACTOR`` command specifies the scale factor for which to scale the spring stiffness. This scale factor can be between 0.0 and 1.0.

The ``FORCE DECAY`` command is used to decrease the stiffness used in the internal force routine (but not the preconditioner) with each control level iteration. The option ``NONE`` does nothing to the stiffness. The option ``ITERFRAC`` decreases the stiffness by 1 over the current iteration number. The option ``HALVED`` decreases the stiffness by half with each iteration. The option ``TENTHED`` decreases the stiffness by a factor of 10 with each iteration. The current ``FORCE DECAY FACTOR`` is echoed in the log file.

The ``EVERY NTH NODE`` command specifies the nodes for which the artificial springs are applied to. If ``EVERY NTH NODE = 1``, springs will be applied to every node in the model. If ``EVERY NTH NODE = 5``, springs will be applied to every 5th node in the model and then perturbed by 1 every ``CONTROL DAMPED SOLVE`` iteration.

Currently, there is not an automated method of deciding which nodes need springs. More advanced options for spring placement are currently in-development.

When a ``CONTROL DAMPED SOLVE`` block is included in the input deck, an integer field named ``Control_NodeMask`` is created. A node with an integer value of ``Control_NodeMask`` greater than 0 will have a spring added to ground. This field is what Sierra/SM uses to determine which nodes should have artificial springs. If desired, a user can set this field manually either by using  a script like ``exodus.py`` or by setting the field with an initial condition block. To keep the field at the user defined value set ``EVERY NTH NODE = 0`` to avoid the internals from resetting the field.

Other Commands
==============

For an explanation of commands related to iteration plot, see :numref:`implicit-multilevel-common`.

Control Damped Solve Input Example
==================================

The following example shows the setup for a general multilevel solver involving control contact and control damped solve. Each load step first a multilevel control damped solve model problem is solved. Once the control damped solve force converges to the specified value, control contact is then solved at the next control level. Control damped solve again solves the model problem with the contact forces included, and the process continues until both levels converge to their specified criteria.

.. code-block:: sierrainput

   Begin solver
   
     Begin cg
       target relative residual = 1.0
     end cg
   
     Begin control damped solve
       level = 1
       target relative spring force = 1.0e-3
       stiffness shift factor = 1.0e-2
       maximum iterations = 100
     end control damped solve
   
     Begin control contact
       level = 2
       target relative residual = 1.0e-6
     end control contact
   End
