# Material Time Step Postprocessor

This postprocessor estimates a timestep that reduces the increment change in a material property below a given threshold.

## Description

The MaterialTimeStepPostprocessor works in conjunction with material models to compute the appropriate maximum time step allowed by individual material models. For creep or plasticity models, this maximum time step size is governed by an allowable inelastic strain increment, but a variety of methods could be used by individual material models to compute their acceptable time step. For continuum damage models, the maximum time step size is governed by the allowable increment of damage over a single time step.

### Creep Strain Example

The maximum time step size is a numerical tool used to ensure the calculation of physically reasonable inelastic strains and to improve convergence of the inelastic material model. As an example, the maximum allowable time step computation for a creep model has the form (1) where is the maximum effective inelastic strain increment (a default value of 1e-4), set by the user, and is the current scalar effective inelastic strain increment.

### Mesh-Wide Evaluation

The MaterialTimeStepPostprocessor collects the time step limitations from all of the quadrature points in the simulation mesh and stores the minimum value. This minimum allowable time step size value is then used by the IterationAdaptiveDT to restrict the time step size based on the limit calculated in the previous time step.

Note that the IterationAdaptiveDT will apply the limiting time step size value from the MaterialTimeStepPostprocessor only if that value is less than maximum time step size value calculated by the internal IterationAdaptiveDT adaptive time step size algorithm.

note:Time Step Limiter Lags Calculation

The value of the maximum allowable time step as collected by the MaterialTimeStepPostprocessor is enforced in the next simulation time step.

### Minimum Time Step Calculated in Material Models

The calculation of the maximum allowable timestep is dependent on each individual material: both the maximum allowable inelastic strain increment and the method of calculating the current inelastic strain, Eq. 1, are defined separately for each material. Given this material dependent nature, the maximum time step value is calculated separately by the RadialReturnStressUpdate materials at each quadrature point. The MaterialTimeStepPostprocessor then determines the minimum time step size value from all of the quadrature points in the simulation.

Initially the value of the maximum time step size is set to std::numeric_limits<Real>::max(). Once the inelastic material model begins to calculate inelastic strain, the value of the allowable time step size varies with the inelastic strain computation.

The limiting time step size is stored within a material property called matl_timestep_limit. This material property can be set up either by the ComputeMultipleInelasticStress model (for creep or plastic strains) or the ComputeDamageStress for continuum damage models.

### Minimum Time Step Size Based on Number of Elements in which a Property Changes

The allowable time step size can also be controlled by the total number of elements in which a material property changes over the course of the time step. This can be used in the context of continuum damage to limit the number of elements damaged at a single time step. To do so, the user needs to define a scalar material property with the input parameter elements_changed_property as well as the maximum acceptable number of elements changed using the elements_changed input parameter. When these are defined, the MaterialTimeStepPostprocessor will sweep over the entire mesh and count the number of elements in which the selected property has changed at at least one quadrature point. The limiting time step is then calculated using the ratio between the current number of elements changed and the maximum value .

(2)

The user can define a elements_changed_threshold to detect a change in property. This can be for example used to count the number of elements in which the damage increases by at least a specific amount.

This method is optional and is only active if both elements_changed_property and elements_changed are defined. The MaterialTimeStepPostprocessor then uses the minimum between the value provided by the material model (see above) or by the number of elements changed. If the input parameter use_material_timestep_limit is set to false, only the number of elements changed is used.

## Example Input File

[./matl_ts_min]
type = MaterialTimeStepPostprocessor
[../]
(moose/modules/tensor_mechanics/test/tests/material_limit_time_step/elas_plas/nafems_nl1_lim.i)

The name of the MaterialTimeStepPostprocessor is passed to the IterationAdaptiveDT as the argument for the postprocessor_dtlim parameter


[./TimeStepper]
dt = 0.1
time_t = '1.0  2.0  3.0  4.0  5.0  6.0  7.0  8.0'
time_dt = '0.1 0.1  0.1  0.1  0.1  0.1  0.1  0.1'
optimal_iterations = 30
iteration_window = 9
growth_factor = 2.0
cutback_factor = 0.5
postprocessor_dtlim = matl_ts_min
[../]
(moose/modules/tensor_mechanics/test/tests/material_limit_time_step/elas_plas/nafems_nl1_lim.i)

and the max_inelastic_increment parameter in the inelastic material model(s) must be set to run the time step limit calculation.


[./isoplas]
type = IsotropicPlasticityStressUpdate
yield_stress = 5e6
hardening_constant = 0.0
relative_tolerance = 1e-20
absolute_tolerance = 1e-8
max_inelastic_increment = 0.000001
[../]
(moose/modules/tensor_mechanics/test/tests/material_limit_time_step/elas_plas/nafems_nl1_lim.i)

## Input Parameters

• elements_changed_thresholdMaximum permitted change in the value of 'elements_changed_property' in 'elements_changed' elements before the time step is limited.

C++ Type:double

Description:Maximum permitted change in the value of 'elements_changed_property' in 'elements_changed' elements before the time step is limited.

• elements_changedMaximum number of elements within which the property named in 'elements_changed_property' is allowed to change by more than 'elements_changed_threshold' before the time step is limited.

C++ Type:int

Description:Maximum number of elements within which the property named in 'elements_changed_property' is allowed to change by more than 'elements_changed_threshold' before the time step is limited.

• elements_changed_propertyName of the material property used to limit the time step if its value changes by more than 'elements_changed_threshold' in at least 'elements_changed' elements

C++ Type:MaterialPropertyName

Description:Name of the material property used to limit the time step if its value changes by more than 'elements_changed_threshold' in at least 'elements_changed' elements

• execute_onTIMESTEP_ENDThe list of flag(s) indicating when this object should be executed, the available options include NONE, INITIAL, LINEAR, NONLINEAR, TIMESTEP_END, TIMESTEP_BEGIN, FINAL, CUSTOM.

Default:TIMESTEP_END

C++ Type:ExecFlagEnum

Description:The list of flag(s) indicating when this object should be executed, the available options include NONE, INITIAL, LINEAR, NONLINEAR, TIMESTEP_END, TIMESTEP_BEGIN, FINAL, CUSTOM.

• use_material_timestep_limitTrueif true, the time step is limited by the minimum value of the matl_timestep_limit property

Default:True

C++ Type:bool

Description:if true, the time step is limited by the minimum value of the matl_timestep_limit property

• blockThe list of block ids (SubdomainID) that this object will be applied

C++ Type:std::vector

Description:The list of block ids (SubdomainID) that this object will be applied

### Optional Parameters

• enableTrueSet the enabled status of the MooseObject.

Default:True

C++ Type:bool

Description:Set the enabled status of the MooseObject.

• use_displaced_meshFalseWhether or not this object should use the displaced mesh for computation. Note that in the case this is true but no displacements are provided in the Mesh block the undisplaced mesh will still be used.

Default:False

C++ Type:bool

Description:Whether or not this object should use the displaced mesh for computation. Note that in the case this is true but no displacements are provided in the Mesh block the undisplaced mesh will still be used.

• outputsVector of output names were you would like to restrict the output of variables(s) associated with this object

C++ Type:std::vector

Description:Vector of output names were you would like to restrict the output of variables(s) associated with this object

• control_tagsAdds user-defined labels for accessing object parameters via control logic.

C++ Type:std::vector

Description:Adds user-defined labels for accessing object parameters via control logic.

• allow_duplicate_execution_on_initialFalseIn the case where this UserObject is depended upon by an initial condition, allow it to be executed twice during the initial setup (once before the IC and again after mesh adaptivity (if applicable).

Default:False

C++ Type:bool

Description:In the case where this UserObject is depended upon by an initial condition, allow it to be executed twice during the initial setup (once before the IC and again after mesh adaptivity (if applicable).

• seed0The seed for the master random number generator

Default:0

C++ Type:unsigned int

Description:The seed for the master random number generator

• implicitTrueDetermines whether this object is calculated using an implicit or explicit form

Default:True

C++ Type:bool

Description:Determines whether this object is calculated using an implicit or explicit form