# Plug-n-Play System Overview in Tensor Mechanics

The tensor mechanics materials use a plug-and-play system where the main tensors used in the residual equation are defined in individual material classes in MOOSE. The plug-and-play approach used in the Tensor Mechanics module requires at least three separate classes to fully describe a material model.

note:Three Tensors Are Required for a Mechanics Problem

The three tensors that must be defined for any mechanics problem are the the strain or strain increment, elasticity tensor , and the stress . Optional tensors include stress-free strain (also known as an eigenstrain) and additional stress .

Figure 1: Tensors required to fully describe a mechanics material.

At times, a user may need to define multiple mechanics properties over a single block. For this reason, all material properties can be prepended by a name defined by the input parameter base_name.

## Strain Materials

The base material class to create strains () or strain increments is ComputeStrainBase; this class is a pure virtual class, requiring that all children override the computeQpProperties() method. For all strains the base class defines the property total_strain. For incremental strains, both finite and small, the compute strain base class defines the properties strain_rate, strain_increment, rotation_increment, and deformation_gradient. A discussion of the different types of strain formulations is available on the Strains page.

For small strains, use ComputeSmallStrain in which . For finite strains, use ComputeFiniteStrain in which an incremental form is employed such that the strain_increment and rotation_increment are calculated.

With the TensorMechanics master action, the strain formulation can be set with the strain= SMALL | FINITE parameter, as shown below.

[./TensorMechanics]
[./Master]
[./all]
strain = FINITE
[../]
[../]
[../]

(modules/tensor_mechanics/test/tests/finite_strain_elastic/finite_strain_elastic_new_test.i)

## Elasticity Tensor Materials

The primary class for creating elasticity tensors () is ComputeElasticityTensor. This class defines the property _elasticity_tensor. Given the elastic constants required for the applicable symmetry, such as symmetric9, this material calculates the elasticity tensor. If you wish to rotate the elasticity tensor, constant Euler angles can be provided. The elasticity tensor can also be scaled with a function, if desired. ComputeElasticityTensor also serves as a base class for specialized elasticity tensors, including:

The input file syntax for the isotropic elasticity tensor is

[./elasticity_tensor]
type = ComputeIsotropicElasticityTensor
youngs_modulus = 2.1e5
poissons_ratio = 0.3
[../]

(modules/tensor_mechanics/tutorials/basics/part_1.1.i)

and for an orthotropic material, such as a metal crystal, is

[./elasticity_tensor]
type = ComputeElasticityTensor
C_ijkl = '1.684e5 0.176e5 0.176e5 1.684e5 0.176e5 1.684e5 0.754e5 0.754e5 0.754e5'
fill_method = symmetric9
[../]

(modules/tensor_mechanics/test/tests/finite_strain_elastic/finite_strain_elastic_new_test.i)

## Stress Materials

The base class for constitutive equations to compute a stress () is ComputeStressBase. The ComputeStressBase class defines the properties stress and elastic_strain. It is a pure virtual class, requiring all children to override the method computeQpStress().

Two elastic constitutive models have been developed, one that assumes small strains ComputeLinearElasticStress, and a second which assumes finite strains and rotations increments ComputeFiniteStrainElasticStress The input file syntax for these materials is

[./stress]
type = ComputeFiniteStrainElasticStress
[../]

(modules/tensor_mechanics/test/tests/finite_strain_elastic/finite_strain_elastic_new_test.i)

There are a number of other constitutive models that have been implemented to calculate more complex elasticity problems, plasticity, and creep. An overview of these different materials is available on the Stresses page.

## Eigenstrain Materials

Eigenstrain is the term given to a strain which does not result directly from an applied force. The base class for eigenstrains is ComputeEigenstrainBase. It computes an eigenstrain, which is subtracted from the total strain in the Compute Strain classes. (1) Chapter 3 of Qu and Cherkaoui (2006) describes the relationship between total, elastic, and eigen- strains and provides examples using thermal expansion and dislocations.

Eigenstrains are also referred to as residual strains, stress-free strains, or intrinsic strains; translated from German, Eigen means own or intrinsic in English. The term eigenstrain was introduced by Mura (1982):

Eigenstrain is a generic name given to such nonelastic strains as thermal expansion, phase transformation, initial strains, plastic, misfit strains. Eigenstress is a generic name given to self-equilibrated internal stresses caused by one or several of these eigenstrains in bodies which are free from any other external force and surface constraint. The eigenstress fields are created by the incompatibility of the eigenstrains. This new English terminology was adapted from the German "Eigenspannungen and Eigenspannungsquellen," which is the title of H. Reissner's paper (1931) on residual stresses.

Thermal strains are a volumetric change resulting from a change in temperature of the material. The change in strains can be either a simple linear function of thermal change, e.g. () or a more complex function of temperature. The thermal expansion class, ComputeThermalExpansionEigenstrain computes the thermal strain as a linear function of temperature. The input file syntax is

[./thermal_expansion_strain]
type = ComputeThermalExpansionEigenstrain
stress_free_temperature = 298
thermal_expansion_coeff = 1.3e-5
temperature = temp
eigenstrain_name = eigenstrain
[../]

(modules/tensor_mechanics/test/tests/thermal_expansion/constant_expansion_coeff.i)

The eigenstrain material block name must also be added as an input parameter, eigenstrain_names to the strain material or TensorMechanics master action block. An example of the additional parameter in the TensorMechanics master action is shown below.

[./TensorMechanics]
[./Master]
[./all]
strain = SMALL
incremental = true
eigenstrain_names = eigenstrain
generate_output = 'strain_xx strain_yy strain_zz'
[../]
[../]
[../]

(modules/tensor_mechanics/test/tests/thermal_expansion/constant_expansion_coeff.i)

Other eigenstrains could be caused by defects such as over-sized or under-sized second phase particles. Such an eigenstrain material is ComputeVariableEigenstrain. This class computes a lattice mismatch due to a secondary phase, where the form of the tensor is defined by an input vector, and the scalar dependence on a phase variable is defined in another material. The input file syntax is

[./eigenstrain]
type = ComputeVariableEigenstrain
block = 0
eigen_base = '1 1 0 0 0 0'
prefactor = var_dep
args = c
eigenstrain_name = eigenstrain
[../]

(modules/combined/test/tests/eigenstrain/inclusion.i)

Note the DerivativeParsedMaterial, which evaluates an expression given in the input file, and its automatically generated derivatives, at each quadrature point.

[./var_dependence]
type = DerivativeParsedMaterial
block = 0
function = 0.005*c^2
args = c
outputs = exodus
output_properties = 'var_dep'
f_name = var_dep
enable_jit = true
derivative_order = 2
[../]

(modules/combined/test/tests/eigenstrain/inclusion.i)

## Extra Stress Materials

Extra stresses () can also be pulled into the residual calculation after the constitutive model calculation of the stress. The extra stress material property, extra_stress is defined in the ComputeExtraStressBase class and is added to the stress value.

(2)

An extra stress may be a residual stress, such as in large civil engineering simulations. An example of an extra stress material used in an input file is:

[./const_stress]
type = ComputeExtraStressConstant
block = 0
base_name = ppt
extra_stress_tensor = '-0.288 -0.373 -0.2747 0 0 0'
[../]

(modules/combined/test/tests/linear_elasticity/extra_stress.i)

## References

1. Toshio Mura. General theory of eigenstrains. In Micromechanics of Defects in Solids, pages 1–62. Springer, 1982.[BibTeX]
2. Jianmin Qu and Mohammed Cherkaoui. Fundamentals of micromechanics of solids. Wiley Online Library, 2006.[BibTeX]