.. _implicit-timestep:

**************************
Implicit Time Step Control
**************************

Time stepping in Sierra/SM is controlled by using a ``TIME CONTROL`` command block in the procedure scope. This command block controls the start time, the termination time, and the method by which time is advanced during the analysis. The analysis time can optionally be subdivided into a number of time periods. If the analysis is from time 0 to time :math:`T` and it is split into three periods, the first period is defined from time 0 to time :math:`t_1`, the second period is defined from time :math:`t_1` to time :math:`t_2`, and the third period is defined from time :math:`t_2` to time :math:`T`. (The times :math:`t_1` and :math:`t_2` are set in the input deck.)  The sum of the times for the three periods is :math:`T`. 

There are many reasons for splitting an analysis into multiple time periods. Boundary conditions may be turned on or off in different time periods. Different solver parameters may also be used in different time periods.

Time stepping can be uniform during a solution period, or it can vary during a solution period by using a function to control the time step as a function of analysis time. With implicit time stepping an automatic time stepping scheme can also be used to automatically take larger time steps at points in the analysis when the solution is relatively easy and take smaller time steps when it becomes more difficult to solve a time step.

A description of the ``TIME CONTROL`` command block follows in :numref:`implicit-timestep-comblocks`. :numref:`implicit-timestep-adapttime` describes the ``ADAPTIVE TIME STEPPING`` command block, which allows adaptation of the size of the time step based on solution difficulty. A simple example of a ``TIME CONTROL`` command block is presented in :numref:`implicit-timestep-example`.

.. _implicit-timestep-comblocks:

Command Blocks for Time Control and Time Stepping
=================================================

.. code-block:: sierrainput

   BEGIN TIME CONTROL
     BEGIN TIME STEPPING BLOCK <string>time_block_name
       START TIME = <real>start_time_value
       BEGIN PARAMETERS FOR ADAGIO REGION <string>region_name
         #
         # Time control parameters specific to ADAGIO 
         # are set in this command block.
         #
       END [PARAMETERS FOR ADAGIO REGION <string>region_name]
     END [TIME STEPPING BLOCK <string>time_block_name]
     TERMINATION TIME = <real>termination_time
   END [TIME CONTROL]

Sierra/SM time control resides in a ``TIME CONTROL`` command block. The command block begins with the input line

.. code-block:: sierrainput

   BEGIN TIME CONTROL

and terminates an input line of the following form:

.. code-block:: sierrainput

   END [TIME CONTROL]

Time control is defined at the procedure scope. If a procedure has multiple regions the time control for each region is defined in a single procedure time control block.

An arbitrary number of ``TIME STEPPING BLOCK`` command blocks can be present to define individual time stepping periods within the ``TIME CONTROL`` command block. Each ``TIME STEPPING BLOCK`` command block contains the time at which the time period starts and a number of time steps for time stepping within the period. Each time period terminates at the start time of the following time period. The start times for the ``TIME STEPPING BLOCK`` command blocks must appear in increasing time. The example in :numref:`implicit-timestep-example` shows the overall structure of the ``TIME CONTROL`` command block.

In the above input lines, the parameters are as follows:

- The string ``time_block_name`` is a name for the time period. Every time period must have a unique name. These names are referenced to control solution parameters or to activate/deactivate functionality.

- The real value ``start_time_value`` is the start time for this ``TIME STEPPING BLOCK`` time period. A time period goes from its start time until the start time of the next period or the termination time. The start time may be negative.

- The string ``region_name`` is the name of the region affected by the parameters (see :numref:`commands-procedure`).

The final termination time for the analysis is given by ``TERMINATION TIME`` command. The input ``termination_time`` is the time at which the analysis will stop. The ``TERMINATION TIME`` command line appears inside the ``TIME CONTROL`` command block but outside of any ``TIME STEPPING BLOCK`` command block.

The ``TERMINATION TIME`` command line can appear before the first ``TIME STEPPING BLOCK`` command block or after the last ``TIME STEPPING BLOCK`` command block. It is permissible to have ``TIME STEPPING BLOCK`` command blocks with start times greater than the termination time; but these  time periods will not executed and will have no effect on the analysis. Only one ``TERMINATION TIME`` command line can appear in the ``TIME CONTROL`` command block. If more than one of these command lines appears, an error is generated.

Nested inside the ``TIME STEPPING BLOCK`` command block is a ``PARAMETERS FOR ADAGIO REGION`` command block containing parameters that control the time stepping.

.. code-block:: sierrainput

   BEGIN PARAMETERS FOR ADAGIO REGION <string>region_name
     TIME INCREMENT = <real>time_increment_value
     NUMBER OF TIME STEPS = <integer>nsteps
     TIME INCREMENT FUNCTION = <string>time_function
   END [PARAMETERS FOR ADAGIO REGION <string>region_name]

The parameters in the ``BEGIN PARAMETERS FOR ADAGIO REGION`` block are specific to an implicit analysis. Note, similar parameters in a ``BEGIN PARAMETERS FOR PRESTO REGION`` block are specific to an explicit analysis :numref:`explicit`.

The command block begins with an input line of the form

.. code-block:: sierrainput

   BEGIN PARAMETERS FOR ADAGIO REGION <string>region_name

and is terminated with an input line of the following form:

.. code-block:: sierrainput

   END [PARAMETERS FOR ADAGIO REGION <string>region_name]

As noted previously, the string ``region_name`` is the name of the region to which the parameters apply. The command lines nested inside the ``PARAMETERS FOR ADAGIO REGION`` command block are used to control the way time stepping occurs, and are described in :numref:`implicit-timestep-comblocks-timeinc` through :numref:`implicit-timestep-comblocks-timeincfunc`. Only one of these command lines (``TIME INCREMENT``, ``NUMBER OF TIME STEPS``, or``TIME INCREMENT FUNCTION``) may be used in a given time period.

.. _implicit-timestep-comblocks-timeinc:

Time Increment
--------------

.. code-block:: sierrainput

   TIME INCREMENT = <real>time_increment_value

The ``TIME INCREMENT`` command line directly specifies the size of a uniform time step used during a time period. The size of the time step is specified with the parameter ``time_increment_value``. 

Number of Time Steps
--------------------

.. code-block:: sierrainput

   NUMBER OF TIME STEPS = <integer>nsteps

The ``NUMBER OF TIME STEPS`` command line specifies the number of uniform time steps used during a time period. The number of time steps is specified with the parameter ``nsteps``. If this command line is used, the time step size is computed by dividing the length of the time period by the specified number of time steps.

.. _implicit-timestep-comblocks-timeincfunc:

Time Increment Function
-----------------------

.. code-block:: sierrainput

   TIME INCREMENT FUNCTION = <string>time_function

The``TIME INCREMENT FUNCTION`` command line allows the time step to be specified as a function of analysis time. The function used to control the time step is referenced by the parameter ``time_function``. The actual function is defined within a ``FUNCTION`` command block within the SIERRA scope. It is often convenient to use a function of the ``PIECEWISE CONSTANT`` type (see :numref:`commands-scope-xyfuncs`) with this command line. Using a function to control time incrementation allows for the time increment to be conveniently switched many times during an analysis without creating a new time block every time the time step size needs to be changed.

.. _implicit-timestep-adapttime:

Adaptive Time Stepping
======================

.. code-block:: sierrainput

   BEGIN ADAPTIVE TIME STEPPING
     METHOD = <string>SOLVER|SOLVER_AVERAGE|MATERIAL|USER(SOLVER)
       [DURING <string list>period_names]
     TARGET ITERATIONS = <integer>target_iter(0) 
       [DURING <string list>period_names]
     ITERATION WINDOW = <integer>iter_window(0)
       [DURING <string list>period_names]
     CUTBACK FACTOR = <real>cutback_factor(0.5)
       [DURING <string list>period_names]
     GROWTH FACTOR = <real>growth_factor(1.5) 
       [DURING <string list>period_names]
     MAXIMUM FAILURE CUTBACKS = <integer>max_cutbacks(5)
       [DURING <string list>period_names]
     MAXIMUM MULTIPLIER = <real>max_multiplier(infinity)
       [DURING <string list>period_names]
     MINIMUM MULTIPLIER = <real>min_multiplier(1.0e-8)
       [DURING <string list>period_names]
     RESET AT NEW PERIOD = TRUE|FALSE(TRUE)
       [DURING <string list>period_names]
     ACTIVE PERIODS = <string list>period_names
     USER CRITERIA GLOBAL <string>var_name  <|<=|=|>=|> <real>cmp_val
     USE MATERIAL TIME STEP NEVER|ALWAYS|DURING_STEP|NEXT_STEP(ALWAYS)
   END [ADAPTIVE TIME STEPPING]

An Adagio region has the capability to adapt the time step size during an analysis based on either solution difficulty or on feedback from material models. This capability is enabled by inserting an ``ADAPTIVE TIME STEPPING`` command block in the region scope. If this adaptive command block is not present in the Adagio region, the time stepping specified in the ``TIME CONTROL`` command block will be used exclusively. In addition to adjusting the size of time steps as the analysis proceeds the adaptive time stepping algorithm can attempt to solve a load step by using a smaller time step if a solution fails to converge. Only a single  adaptive stepping time block can be used in a region.

The adaptive time stepping algorithm works by computing a multiplier that is applied to the time step specified in the ``TIME CONTROL`` command block. Thus, even if adaptive time stepping is used the base time step must be specified for all loading periods in the ``TIME CONTROL`` command block. For the initial load step in each solution period the Adagio region always uses the prescribed time step. In subsequent steps or after convergence failure the adaptive time stepping algorithm computes a factor that is multiplied by the prescribed time step to adjust the time step.

The command lines nested within the ``ADAPTIVE TIME STEPPING`` command are used to control the behavior of this feature and are described in :numref:`implicit-timestep-adapttime-adaptmethod` through :numref:`implicit-timestep-adapttime-adaptactive`.

Many of these command lines can optionally be set for a specific time period. To set a parameter for a specific time period the ``DURING`` keyword followed by a list of applicable period names to a command line may be used (see :numref:`implicit-cg-convergence`). Multiple instances of these command lines can exist to set the parameter differently for different time periods. If a command line is not appended with the ``DURING`` specification, it is used to set the default behavior for all time periods. Setting a default in this way does not preclude setting a period-specific value for that parameter with another instance of the same command line.

.. _implicit-timestep-adapttime-adaptmethod:

Method
------

.. code-block:: sierrainput

   METHOD = <string>SOLVER|SOLVER_AVERAGE|MATERIAL|USER(SOLVER)
     [DURING <string list>period_names]

The ``METHOD`` command line is used to select the adaptive time stepping algorithm. The default ``SOLVER`` method adapts the time step based on the difficulty of the solution over a time step. Solution difficulty is determined based on the number of iterations required to achieve convergence during a time step. If the ``SOLVER`` method is used, the ``TARGET ITERATIONS`` command line can be used to specify the target iterations used by this method to adapt the time step. 

The ``SOLVER_AVERAGE`` method can be used when the problem has a multi level solver control such as control contact. With the ``SOLVER_AVERAGE`` option the difficulty is determined as the average number of iterations the solver takes per model problem instead of the accumulated number of iterations taken per time step. 

The ``MATERIAL`` method uses the material models to inform an appropriate step size. A material may provide a maximum time step to prevent too much nonlinearity over a step. Note, only a handful of materials will define time steps and this option is primarily relevant to  materials that have time dependent creep or other rate effects. The material suggested time step multiplier will still be bounded by the adaptive time stepping block input parameters for ``MAXIMUM MULTIPLIER``, ``MINIMUM MULTIPLIER``, ``GROWTH FACTOR``, and ``CUTBACK FACTOR``. 

The ``USER`` method must be paired with a ``USER CRITERIA GLOBAL``, see :numref:`implicit-timestep-adapttime-adaptusercriteria`. When the criteria is satisfied a time step cutback is forced using the ``CUTBACK FACTOR``, a convergence failure is mimicked and the current solution is thrown away. The time step is still bounded by the adaptive time stepping block input parameters but the ``GROWTH FACTOR`` is unused.

.. warning::
    
   The ``USER`` method does not support the optional ``DURING``.

.. _implicit-timestep-adapttime-adapttarget:

Target Iterations
-----------------

.. code-block:: sierrainput

   TARGET ITERATIONS = <integer>target_iter(0) 
     [DURING <string list>period_names]

The solver method for adaptive time stepping adjusts the time step to achieve a target level of difficulty. The level of difficulty is determined by the total number of core solver iterations required to solve for a time step. The ``TARGET ITERATIONS`` command specifies a target number of iterations per time step. This command line is optional.

The specified value of ``target_iter`` is used in conjunction with the value of ``iter_window`` (specified with the ``ITERATION WINDOW`` command documented in Section :numref:`implicit-timestep-adapttime-adaptwindow`) to control the next step size. If the number of iterations for the previous step is greater than (``target_iter``-``iter_window``), and less than (``target_iter``+``iter_window``), the step size is kept the same. If the number of iterations is greater than (``target_iter``+``iter_window``), the step size is decreased, and if it is less than (``target_iter``-``iter_window``), the step size is increased.

If the target iterations is undefined or zero solver will not adjust the time step based on iteration count. The solver will cutback the time step if an element inverts, the solver fails to converge, or a material model suggests a smaller time step.

.. _implicit-timestep-adapttime-adaptwindow:

Iteration Window
----------------

.. code-block:: sierrainput

   ITERATION WINDOW = <integer>iter_window 
     [DURING <string list>period_names]

The ``ITERATION WINDOW`` command specifies the size of the window for the iteration count used in the solver type of adaptive time stepping. See :numref:`implicit-timestep-adapttime-adapttarget` for an explanation of how this is used in conjunction with the specified target iterations to adaptively choose the time step size. The default value of ``iter_window`` is the value specified in the ``TARGET ITERATIONS`` command line divided by 5.

Cutback Factor
--------------

.. code-block:: sierrainput

   CUTBACK FACTOR = <real>cutback_factor(0.5)
     [DURING <string list>period_names]

The ``CUTBACK FACTOR`` command line controls the amount by which the next time step is reduced if the solution is difficult. The parameter ``cutback_factor`` specifies the multiplier that is applied to the current time step with each cutback. The default value for the ``CUTBACK FACTOR`` is 0.5, the factor must be between zero and one. The cutback factor parameter also controls the amount that the current time step is cut back if a solution fails. The ``CUTBACK FACTOR`` command line can be appended with the ``DURING`` specification, as discussed in :numref:`implicit-cg-convergence`.

Growth Factor
-------------

.. code-block:: sierrainput

   GROWTH FACTOR = <real>growth_factor(1.5)
     [DURING <string list>period_names]

The ``GROWTH FACTOR`` command line controls the amount by which the next time step is increased if the solution is easy. It requires the user to set ``TARGET ITERATIONS``  to determine the level of difficulty in the solution, as described in :numref:`implicit-timestep-adapttime-adapttarget`. The parameter ``growth_factor``, which has a default value of 1.5, specifies the multiplier (a 50 percent increase) that is applied to the current time step each time the time step is increased. The ``GROWTH FACTOR`` command line can be appended with the ``DURING`` specification, as discussed in Section :numref:`implicit-cg-convergence`.

Maximum Failure Cutbacks
------------------------

.. code-block:: sierrainput

   MAXIMUM FAILURE CUTBACKS = <integer>max_cutbacks(5)
     [DURING <string list>period_names]

The ``MAXIMUM FAILURE CUTBACKS`` command line controls how many cutbacks to a time step can be taken if a solution fails to converge. The parameter ``max_cutbacks`` has a default value of 5 if adaptive time stepping is enabled. If an ``ADAPTIVE TIME STEPPING`` command block is not present, the code will exit rather than attempting to cut back after an unsuccessful solution. The ``MAXIMUM FAILURE CUTBACKS`` command line can be appended with the ``DURING`` specification, as discussed in :numref:`implicit-cg-convergence`.

Maximum Multiplier
------------------

.. code-block:: sierrainput

   MAXIMUM MULTIPLIER = <real>max_multiplier(infinity)
     [DURING <string list>period_names]

Time steps are adaptively adjusted by updating a multiplier that is applied to the base time step specified in the ``TIME CONTROL`` command block. By default, there are no limits on the size of this multiplier. The ``MAXIMUM MULTIPLIER`` command line can be used to limit the growth of the time step. The parameter ``max_multiplier`` specifies the upper bound for the multiplier. The largest possible time step in an analysis is the product of ``max_multiplier`` and the baseline time step size. This baseline size is specified in the ``TIME CONTROL`` command block. The ``MAXIMUM MULTIPLIER`` command line can be appended with the ``DURING`` specification, as discussed in :numref:`implicit-cg-convergence`.

Minimum Multiplier
------------------

.. code-block:: sierrainput

   MINIMUM MULTIPLIER = <real>min_multiplier(1.0e-8)
     [DURING <string list>period_names]

Time steps are adaptively adjusted by updating a multiplier that is applied to the base time step specified in the ``TIME CONTROL`` command block. By default, the ``MINIMUM MULTIPLIER`` is set to :math:`1.0e^{-8}`. The ``MINIMUM MULTIPLIER`` command  line can be used to limit the shrinkage of the time step. The parameter ``min_multiplier`` specifies the lower bound for the multiplier. The smallest possible time step in an analysis is the product of ``min_multiplier`` and the baseline time step size. The ``MINIMUM MULTIPLIER`` command line can be appended with the ``DURING`` specification, as discussed in :numref:`implicit-cg-convergence`.

Reset at New Period
-------------------

.. code-block:: sierrainput

   RESET AT NEW PERIOD = TRUE|FALSE(TRUE)
     [DURING <string list>period_names]

This command controls whether the time step is reset to the user-specified base time step at the beginning of a new time period. If this parameter is set to ``TRUE``, which is the default value, the time step is reset. If this parameter is set to ``FALSE``, the adaptive time stepping is maintained from the previous period. If the base time step is changed in the new period, the multiplier is scaled to maintain the time step originally calculated for the next step. The multiplier is scaled by the ratio: time increment of the previous period/time increment of the new period. If the resulting multiplier is outside of the specified range, it will be adjusted to stay within that range and the time step will change. In summary, the first time step of the new period will be equal to the base time step of the previous period times the scaled multiplier. The value of this parameter can optionally be specified per time period with the ``DURING`` option (see :numref:`implicit-cg-convergence`). If adaptive time stepping is inactive for a given period, the time step will always be reset even if it is requested that the adaptive time step not be reset.

.. _implicit-timestep-adapttime-adaptactive:

Active Periods
--------------

.. code-block:: sierrainput

   ACTIVE PERIODS = <string list>period_names

If the ``ADAPTIVE TIME STEPPING`` command block is present in the Adagio region, it is active for all periods by default. Adaptive time stepping can be activated for specific time periods with the ``ACTIVE PERIODS`` command line. See :numref:`commands-functionality` for more information about this optional command line.

.. _implicit-timestep-adapttime-adaptusercriteria:

User Criteria Global
--------------------

.. code-block:: sierrainput

   USER CRITERIA GLOBAL <string>var_name  <|<=|=|>=|> <real>cmp_val

The ``USER CRITERIA GLOBAL`` command is for paring with method ``USER``. At the end of a solve, the global variable ``var_name`` is compared to the  ``cmp_val`` with the specified comparison type. If the comparison is true a cutback to the timestep is forced. The ``CUTBACK FACTOR`` is used to reduce the time step while respecting bounds on the timestep defined by ``MINIMUM MULTIPLIER`` and ``MAXIMUM FAILURE CUTBACKS``.

User Material Time Step
-----------------------

.. code-block:: sierrainput

     USE MATERIAL TIME STEP NEVER|ALWAYS|DURING_STEP|NEXT_STEP(ALWAYS)

The ``USE MATERIAL TIME STEP`` command is for specifying if ``ADAPTIVE TIME STEPPING`` will use the material timestep when calculating the time step. The option ``NEXT_STEP``  will enable adaptive time stepping to calculate a multiplier that is applied to the next  times step if the material time step is less than the current one. ``DURING_STEP`` will  apply a cutback to the current time step if the material time step is less than the current time step. 

.. _implicit-timestep-example:

Time Control Example
====================

The following is a simple example of a ``TIME CONTROL`` command block:

.. code-block:: sierrainput

   BEGIN TIME CONTROL 
     BEGIN TIME STEPPING BLOCK p1
       START TIME = 0.0
       BEGIN PARAMETERS FOR ADAGIO REGION adagio_region
         NUMBER OF TIME STEPS = 10
       END
     END
     BEGIN TIME STEPPING BLOCK p2
       START TIME = 1.0
       BEGIN PARAMETERS FOR ADAGIO REGION adagio_region
         TIME INCREMENT = 0.2
       END
     END
     TERMINATION TIME = 2.0
   END

The first ``TIME STEPPING BLOCK``, ``p1``, begins at time 0.0, the initial start time, and terminates at time 1.0. The first time period will take ten time steps each of time 0.1 to reach time 1.0.

The second ``TIME STEPPING BLOCK``, ``p2``, begins at time 1.0 and terminates at time 2.0, the time listed on the ``TERMINATION TIME`` command line. The second time period will take five time steps each of time 0.2 to reach the final end time of 2.0.

The ``TIME STEPPING BLOCK`` names ``p1`` and ``p2`` can be referenced elsewhere to activate boundary conditions or control the solver in different ways during the two analysis time periods.
