.. _implicit-stiffness:

*****************
Control Stiffness
*****************

Control stiffness is an augmented Lagrange iterative solution strategy for solving mechanics models that have *widely* varying stiffness in various modes of material response. For instance, nearly incompressible materials have a bulk/volumetric response that is much stiffer than the corresponding shear/deviatoric response. A similar case arises for materials that are orthotropic or anisotropic in nature and exhibit widely varying stiffness in the principal material directions.

Using control stiffness allows part of the constitutive response of a material to be softened or stiffened to give a tangent response that results in model problems that can be solved more easily by the core solver. This is accomplished by scaling a chosen stress increment up or down in a given model problem and adding it to a saved reference stress to yield a scaled stress that is used for equilibrium evaluations. The reference stress accumulates the model problem stress increments so that the true material response for a time step is obtained after solving a sequence of model problems. 

This capability is highly specialized to certain use cases and is not recommended for most problems. It is also only available for use with certain specialized material models. Use of this capability should be considered only as a last resort when convergence cannot be achieved in any other way.

The command block for control stiffness is as follows:

.. code-block:: sierrainput

   BEGIN CONTROL STIFFNESS [<string>stiffness_name]
     #
     # convergence commands
     TARGET <string>RESIDUAL|PRESSURE INCREMENT|
       SDEV INCREMENT|STRESS INCREMENT 
       = <real>target [DURING <string list>period_names]
     TARGET RELATIVE <string>RESIDUAL|PRESSURE INCREMENT|
       SDEV INCREMENT|STRESS INCREMENT|
       STRAIN INCREMENT
       = <real>target_rel [DURING <string list>period_names]
     ACCEPTABLE <string>RESIDUAL|PRESSURE INCREMENT|
       SDEV INCREMENT|STRESS INCREMENT 
       = <real>accept [DURING <string list>period_names]
     ACCEPTABLE RELATIVE <string>RESIDUAL|PRESSURE INCREMENT|
       SDEV INCREMENT|STRESS INCREMENT|
       STRAIN INCREMENT
       = <real>accept_rel [DURING <string list>period_names]
     REFERENCE = EXTERNAL|INTERNAL|BELYTSCHKO|RESIDUAL|ENERGY(EXTERNAL)
       [DURING <string list>period_names]
     MINIMUM ITERATIONS  = <integer>min_iter(0) 
       [DURING <string list>period_names]
     MAXIMUM ITERATIONS  = <integer>max_iter 
       [DURING <string list>period_names]
     #
     # level selection command
     LEVEL = <integer>stiffness_level
     #
     # 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 STIFFNESS <string>stiffness_name]

To enable control stiffness, a ``CONTROL STIFFNESS`` command block must exist in the ``SOLVER`` command block. The command lines within the ``CONTROL STIFFNESS`` command block are used to control convergence during the control stiffness updates, select the level for control stiffness within the multilevel solver, and output diagnostic information. These commands are described in detail in :numref:`implicit-stiffness-convergence` and :numref:`implicit-multilevel-common`.

.. _implicit-stiffness-convergence:

Convergence Commands
====================

The command lines listed in this section are placed in the ``CONTROL STIFFNESS`` command block to control convergence criteria for stiffness control within the multilevel solver. 

.. code-block:: sierrainput

   TARGET <string>RESIDUAL|PRESSURE INCREMENT|
     SDEV INCREMENT|STRESS INCREMENT
     = <real>target [DURING <string list>period_names]
   TARGET RELATIVE <string>RESIDUAL|PRESSURE INCREMENT|
     SDEV INCREMENT|STRESS INCREMENT|STRAIN INCREMENT 
     = <real>target_rel [DURING <string list>period_names]
   ACCEPTABLE <string>RESIDUAL|PRESSURE INCREMENT|
     SDEV INCREMENT|STRESS INCREMENT 
     = <real>accept [DURING <string list>period_names]
   ACCEPTABLE RELATIVE <string>RESIDUAL|PRESSURE INCREMENT|
     SDEV INCREMENT|STRESS INCREMENT|STRAIN INCREMENT
     = <real>accept_rel [DURING <string list>period_names]
   REFERENCE = EXTERNAL|INTERNAL|BELYTSCHKO|RESIDUAL|ENERGY(EXTERNAL)
     [DURING <string list>period_names]
   MINIMUM ITERATIONS = <integer>min_iter(0) 
     [DURING <string list>period_names]
   MAXIMUM ITERATIONS = <integer>max_iter 
     [DURING <string list>period_names]

Convergence for problems using control stiffness requires that two criteria be met. The first criterion is that force equilibrium must be achieved. The second criterion is that the scaled stress used for equilibrium must be close enough to the unscaled stress that is determined from the unmodified material model.

The command lines listed above for the equilibrium evaluation are similar to those used for the core CG solver and have similar meaning. Here, the command lines are applied as part of determining convergence for the control stiffness series of model problems. Some of the command lines have multiple options, e.g., the command line beginning with ``TARGET`` has five options. This practice has been used for the command lines beginning with ``TARGET``, ``TARGET RELATIVE``. ``ACCEPTABLE``, and ``ACCEPTABLE RELATIVE``. That all of these command lines can be appended with the ``DURING`` specification, as discussed in :numref:`implicit-cg-convergence`.

Convergence of equilibrium using scaled stresses is measured by computing the :math:`L^2` norm of the residual and comparing that residual norm with target convergence criteria specified by the user. Convergence can be monitored either directly in terms of the residual norm, or in terms of a relative residual, which is the residual norm divided by a reference quantity that is indicative of the current loading conditions on a model. Either the residual, the relative residual, or both of these can be used for checking convergence at the same time. The ``TARGET RESIDUAL`` command line specifies the target convergence criterion in terms of the actual residual norm. The ``TARGET RELATIVE RESIDUAL`` command line specifies a convergence criterion in terms of the relative residual. If both absolute and relative criteria are specified for the residual calculation, equilibrium is accepted if either criterion is met.

The multilevel solver also allows acceptable convergence criteria to be input for residual convergence. If the solution has not converged to the specified targets before the maximum number of iterations is reached, the residual is checked against the acceptable convergence criteria. These criteria are specified via the ``ACCEPTABLE RESIDUAL`` and ``ACCEPTABLE RELATIVE RESIDUAL`` command lines. The concepts of absolute and relative values are the same here as discussed for the target limits. When a multilevel solver is being used, the level 0 (cg) acceptable residual and relative residual defaults are overridden and set to :math:`1e^{20}`. This choice was made to improve the overall robustness of the multilevel solver when faced with difficult contact problems. As long as the targets in the controls (contact, stiffness, failure, or damped solve) are met, then the solution is converged and allowed to continue time stepping.

If relative residuals 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 several options: ``EXTERNAL``, ``INTERNAL``, ``BELYTSCHKO``, ``RESIDUAL`` and ``ENERGY``. 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.  The ``BELYTSCHKO`` option uses the maximum of the norm of the external load, the norm of the reactions, the norm of the internal forces, and the norm of the inertial forces. The ``RESIDUAL`` option denotes that the residual from the initial residual should  be used as the reference quantity. The ``ENERGY`` residual is the energy  conjugate norm of the residual and reference vectors. These criteria are further  explained in :numref:`implicit-cg-convergence`.

For control stiffness, unlike other controls, the convergence of the series of model problems to obtain the final solution for a time step is also based on other criteria that measure how far apart the scaled and unscaled stress responses are from each other. Either a direct error measure of the difference of the scaled and unscaled stress is used or a relative strain error computed using the difference between the scaled and unscaled stress and a representative modulus is employed.

There are many variants of the ``TARGET`` command that can be used for the direct stress differences. The ``TARGET PRESSURE INCREMENT`` and ``TARGET SDEV INCREMENT`` commands are used to specify convergence for nearly incompressible materials based on the pressure and deviatoric stress increments, respectively. Also, ``TARGET STRESS INCREMENT`` is used to base convergence on the stress increment for materials which have their entire behavior softened as part of a control stiffness approach. If desired, the ``RELATIVE`` form of these convergence criteria can be used. If the ``TARGET RELATIVE STRAIN INCREMENT`` command is specified, the strain error measure between the scaled and unscaled stress will be computed and used. 

Any combination of these criteria can be specified. If more than one is specified, all the criteria must be satisfied. However, each material block contributes either to the direct stress error measures or to the relative strain error measure. If a material block specifies a positive non-zero ``REFERENCE STRAIN`` in its definition, it will contribute to the relative strain error measure. Otherwise, it will contribute to the direct stress error measures. Finally, acceptable convergence criteria can be input for converging the difference between the scaled and unscaled stress. If the solution has not met the target criteria for equilibrium and the difference between the scaled and unscaled stresses but meets the acceptable criteria, it is allowed to proceed to the next time step.

The ``MAXIMUM ITERATIONS`` and ``MINIMUM ITERATIONS`` command lines specify the maximum and minimum number of control stiffness updates, respectively. The default minimum number of iterations, ``min_iter``, is 0. If a number greater than 0 is specified for ``min_iter``, the multilevel solver will update stiffness 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`.

Separate from the iteration plot commands, control stiffness provides several other element variables for diagnostic output.

- bulk_strain_error

- shear_strain_error

- axial_strain_error

- anisotropic_strain_error
