.. _implicit-failure:

***************
Control Failure
***************

Control failure is used to improve the conditioning and accuracy of models that involve element death. To use control failure, an element death block (as defined in :numref:`elements-death`) and a multilevel solver control failure must both be defined.

When element death is used in the absence of control failure at the end of a load step all elements that meet the element death criteria are removed and the analysis moves on to the next step. There are two issues with this approach control failure will remedy. First death of one element may increase the load on remaining elements which should cause additional element failures. Second death of one element may relieve the load on another element, possibly putting that element below the failure criteria. Thus element death without control failure could either under predict or over predict the actual number of elements that should be removed in a given time step.

Control failure with material criterion limits the failure only to the single most critical element during each control failure iteration. With control failure when an element dies the model problem will be repeated with the element in a failed state in the presence of control failure. Iterations of the control failure continue until no additional elements are marked for failure.

The command block for control failure is as follows:

.. code-block:: sierrainput

   BEGIN CONTROL FAILURE [<string>failure_name]
     #
     #  convergence control command
     MAXIMUM ITERATIONS = <integer>max_iter 
       [DURING <string list>period_names]
     #
     # level selection command
     LEVEL = <integer>failure_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 FAILURE <string>failure_name]

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

Convergence of control failure is defined as having no new elements have been marked as failed in the previous model problem. Control failure will also complete if it reaches the ``MAXIMUM ITERATIONS`` number of model problem evaluations in a single load step. 

When element death is not controlled by a material criterion,  all elements that satisfy the specified criterion are marked at the end of the model problem.

When a material criterion is used, the material will set the variable "failure_flag" to 1.0 when the failure criterion is met. At the end of the model problem, control failure will set the "failure_flag" of the failed element with the largest "failure_measure" to 2.0, thereby marking it. For the marked element, at the beginning of the following model problem the material model will set the "failure_flag" to 3.0 as it begins decaying the material, while all other instances of "failure_flag" with a value of 1.0 are set back to 0.0. Control failure iterations continue until no elements are marked for failure (i.e. no elements have a "failure_flag" of 2.0) or the ``MAXIMUM ITERATIONS`` is reached. What this means is that only the most critical element is removed each model problem. This one-by-one element removal prevents potential over prediction of failure if several elements exceed the failure criterion on the same model problem.

.. _implicit-failure-convergence:

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

The only user input convergence criteria that is allowed for control failure is specification of maximum iterations.

.. code-block:: sierrainput

   MAXIMUM ITERATIONS = <integer>max_iter 
      [DURING <string list>period_names]

Iterations for control failure will continue until no new elements are failing unless the user specified number of maximum iterations is reached. If a maximum number of iterations is specified in the input, control failure iterations will only continue until this number is reached. If the maximum number of iterations is reached, the analysis will terminate in an unconverged state and with an explanatory message in the log file. This command can be appended with the ``DURING`` specification, as discussed in :numref:`implicit-cg-convergence`. The unconverged state can also trigger adaptive time stepping if it is active.

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

When used in a multilevel solver the ``CONTROL FAILURE`` command block should be processed at the highest solver level and should be the only control acting at that level. For more details on the ``LEVEL`` command see :numref:`implicit-multilevel-common`. 

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

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

Control Failure Input Example
=============================

The following example shows the setup for a general multilevel solver involving control contact and control failure. Each load step first a multilevel control contact model problem is solved. Control failure then removes the most failed element based off of the material failure criterion. Control contact again solves the model problem with that element removed. This process continues until no new elements fail. Due to the large number of iterative resolves required the accuracy provided by control failure for such a situation may come at a substantial run time cost.

.. code-block:: sierrainput

   begin element death
     include all blocks
     material criterion = on
   end
   
   Begin solver
     Begin control failure
       level = 2
     end control failure
   
     Begin control contact
       level = 1
       target relative residual = 1.0e-6
     end control contact
   	
     Begin cg
       target relative residual = 1.0e-8
     end cg
   End
