Rank Two Scalar Aux

Compute a scalar property of a RankTwoTensor

Description

The AuxKernel RankTwoScalarAux provides methods to calculate several different scalar quantities for a Rank-2 tensor, described below. In some types of calculations, the scalar quantity is calculated in a user-specified direction (by default set to the (0, 0, 1) axis); in other calculation types the user can specify the start and end points of a line along which the scalar quantity is calculated. Quantities commonly examined with RankTwoScalarAux are stress () and strain ().

If desired, RankTwoScalarAux can be restricted to calculate the scalar quantity data for a Rank-2 tensor at a single specified quadrature point per element. This option is generally used only for debugging purposes.

Axial Stress

The scalar type AxialStress calculates the scalar value of a Rank-2 tensor, , in the direction of the axis specified by the user. The user should give the starting point, , and the end point, which define the axis.

(1) where is the normalized direction vector for the axis defined by the points and .

Direction

The scalar type direction calculates the scalar value of a Rank-2 tensor, , in the direction selected by the user as shown by Eq. 2: (2) where is the direction vector specified in the input file.

Example Input File Syntax


[./direction]
  type = RankTwoScalarAux
  rank_two_tensor = stress
  variable = direction
  scalar_type = direction
  direction = '1 1 1'
[../]
(modules/tensor_mechanics/test/tests/elastic_patch/elastic_patch.i)

An AuxVariable is required to store the AuxKernel information. Note that the name of the AuxVariable is used as the argument for the variable input parameter in the RankTwoScalarAux block.


[./direction]
  order = CONSTANT
  family = MONOMIAL
[../]
(modules/tensor_mechanics/test/tests/elastic_patch/elastic_patch.i)

Effective Strain

The scalar type EffectiveStrain calculates an effective scalar measure of a Rank-2 tensor, often strain () according to Eq. 3. (3)

warning:This Strain Measure is not for Inelastic Strains

This effective strain measure, EffectiveStrain, should not be confused with the effective plastic strain or effective creep strain, which are computed as integrals over the history of the inelastic strain; these effective inelastic strain measures are computed as scalar material properties (named effective_plastic_strain and effective_creep_strain) for applicable models. The effective inelastic strains are computed as: (4) where is time and is the inelastic strain increment.

Example Input File Syntax


[./peeq]
  type = RankTwoScalarAux
  rank_two_tensor = plastic_strain
  variable = peeq
  scalar_type = EffectiveStrain
[../]
(modules/tensor_mechanics/test/tests/auxkernels/ranktwoscalaraux.i)

An AuxVariable is required to store the AuxKernel information. Note that the name of the AuxVariable is used as the argument for the variable input parameter in the RankTwoScalarAux block.


[./peeq]
  order = CONSTANT
  family = MONOMIAL
[../]
(modules/tensor_mechanics/test/tests/auxkernels/ranktwoscalaraux.i)

Hoop Stress

The scalar type HoopStress calculates the value of a Rank-2 tensor along the hoop direction of a cylinder, shown in Eq. 5. The cylinder is defined with a normal vector from the current position to the cylinder surface and a user specified axis of rotation. The user defines this rotation axis with a starting point, , and the end point, .

(5) where is the hoop direction normal, defined as (6) where is the current sampling position point, and is the direction normal to the plane defined by the cylinder axis of rotation vector and the direction normal to the axis of rotation at the current position .

Example Input File Syntax

[./hoop_stress]
  type = RankTwoScalarAux
  rank_two_tensor = stress
  variable = hoop_stress
  scalar_type = HoopStress
  execute_on = timestep_end
[../]
(modules/combined/test/tests/axisymmetric_2d3d_solution_function/2d.i)

An AuxVariable is required to store the AuxKernel information. Note that the name of the AuxVariable is used as the argument for the variable input parameter in the RankTwoScalarAux block.

[./hoop_stress]
  order = CONSTANT
  family = MONOMIAL
[../]
(modules/combined/test/tests/axisymmetric_2d3d_solution_function/2d.i)

Hydrostatic Stress

The scalar type Hydrostatic calculates the hydrostatic scalar of a Rank-2 tensor, , as shown in Eq. 7. (7)

Example Input File Syntax


[./pressure]
  type = RankTwoScalarAux
  rank_two_tensor = stress
  variable = pressure
  scalar_type = Hydrostatic
[../]
(modules/tensor_mechanics/test/tests/material_limit_time_step/creep/nafems_test5a_lim.i)

An AuxVariable is required to store the AuxKernel information. Note that the name of the AuxVariable is used as the argument for the variable input parameter in the RankTwoScalarAux block.

Invariant Values

First Invariant

The scalar type FirstInvariant calculates the first invariant of the specified Rank-2 tensor, , according to Eq. 8 from Malvern (1969). (8)

Example Input File Syntax


[./fi]
  type = RankTwoScalarAux
  rank_two_tensor = stress
  variable = firstinv
  scalar_type = firstinvariant
[../]
(modules/tensor_mechanics/test/tests/elastic_patch/elastic_patch.i)

An AuxVariable is required to store the AuxKernel information. Note that the name of the AuxVariable is used as the argument for the variable input parameter in the RankTwoScalarAux block.


[./firstinv]
  order = CONSTANT
  family = MONOMIAL
[../]
(modules/tensor_mechanics/test/tests/elastic_patch/elastic_patch.i)

Second Invariant

Similarly, the scalar type SecondInvariant finds the second invariant of the Rank-2 tensor, , as shown in Eq. 9. This method is defined in Hjelmstad (2007). (9)

Example Input File Syntax


[./si]
  type = RankTwoScalarAux
  rank_two_tensor = stress
  variable = secondinv
  scalar_type = secondinvariant
[../]
(modules/tensor_mechanics/test/tests/elastic_patch/elastic_patch.i)

An AuxVariable is required to store the AuxKernel information. Note that the name of the AuxVariable is used as the argument for the variable input parameter in the RankTwoScalarAux block.


[./secondinv]
  order = CONSTANT
  family = MONOMIAL
[../]
(modules/tensor_mechanics/test/tests/elastic_patch/elastic_patch.i)

Third Invariant

The scalar type ThirdInvariant computes the value of the Rank-2 tensor, , third invariant as given in Eq. 10 from Malvern (1969). (10) where is the Rank-3 permutation tensor.

Example Input File Syntax


[./ti]
  type = RankTwoScalarAux
  rank_two_tensor = stress
  variable = thirdinv
  scalar_type = thirdinvariant
[../]
(modules/tensor_mechanics/test/tests/elastic_patch/elastic_patch.i)

An AuxVariable is required to store the AuxKernel information. Note that the name of the AuxVariable is used as the argument for the variable input parameter in the RankTwoScalarAux block.


[./thirdinv]
  order = CONSTANT
  family = MONOMIAL
[../]
(modules/tensor_mechanics/test/tests/elastic_patch/elastic_patch.i)

L2 Norm

The scalar type L2Norm calculates the L2 normal of a Rank-2 tensor, , as shown in Eq. 11. (11)

Principal Values

Maximum Principal Quantity

The scalar type MaxPrincipal calculates the largest principal value for a symmetric tensor, using the calcEigenValues method from the Rank Two Tensor utility class.

Example Input File Syntax


[./maxprincipal]
  type = RankTwoScalarAux
  rank_two_tensor = stress
  variable = maxprincipal
  scalar_type = MaxPRiNCIpAl
[../]
(modules/tensor_mechanics/test/tests/elastic_patch/elastic_patch.i)

An AuxVariable is required to store the AuxKernel information. Note that the name of the AuxVariable is used as the argument for the variable input parameter in the RankTwoScalarAux block.


[./maxprincipal]
  order = CONSTANT
  family = MONOMIAL
[../]
(modules/tensor_mechanics/test/tests/elastic_patch/elastic_patch.i)

Middle Principal Quantity

Similarly, the scalar type MidPrincipal finds the second largest principal value for a symmetric tensor, using the calcEigenValues method from the Rank Two Tensor utility class.

Example Input File Syntax


[./midprincipal]
  type = RankTwoScalarAux
  rank_two_tensor = stress
  variable = midprincipal
  scalar_type = MidPRiNCIpAl
[../]
(modules/tensor_mechanics/test/tests/elastic_patch/elastic_patch.i)

An AuxVariable is required to store the AuxKernel information. Note that the name of the AuxVariable is used as the argument for the variable input parameter in the RankTwoScalarAux block.


[./midprincipal]
  order = CONSTANT
  family = MONOMIAL
[../]
(modules/tensor_mechanics/test/tests/elastic_patch/elastic_patch.i)

Minimum Principal Quantity

The scalar type MinPrincipal computes the smallest principal value for a symmetric tensor, using the calcEigenValues method from the Rank Two Tensor utility class.

Example Input File Syntax


[./minprincipal]
  type = RankTwoScalarAux
  rank_two_tensor = stress
  variable = minprincipal
  scalar_type = MiNPRiNCIpAl
[../]
(modules/tensor_mechanics/test/tests/elastic_patch/elastic_patch.i)

An AuxVariable is required to store the AuxKernel information. Note that the name of the AuxVariable is used as the argument for the variable input parameter in the RankTwoScalarAux block.


[./minprincipal]
  order = CONSTANT
  family = MONOMIAL
[../]
(modules/tensor_mechanics/test/tests/elastic_patch/elastic_patch.i)

Radial Stress

The scalar type RadialStress calculates the scalar component for a Rank-2 tensor, , in the direction of the normal vector from the user-defined axis of rotation, as shown in Eq. 12. (12) where is the direction normal to the plane defined by the cylinder axis of rotation vector and the direction normal to the axis of rotation at the current position .

Example Input File Syntax

[./stress_rr]
  type = RankTwoScalarAux
  rank_two_tensor = stress
  variable = stress_rr
  scalar_type = RadialStress
  point1 = '0 0 0'
  point2 = '0 0 1'
[../]
(modules/porous_flow/test/tests/thm_rehbinder/free_outer.i)

An AuxVariable is required to store the AuxKernel information. Note that the name of the AuxVariable is used as the argument for the variable input parameter in the RankTwoScalarAux block.

[./stress_rr]
  family = MONOMIAL
  order = CONSTANT
[../]
(modules/porous_flow/test/tests/thm_rehbinder/free_outer.i)

Triaxiality Stress

The scalar type TriaxialityStress finds the ratio of the hydrostatic measure, , to the von Mises measure, , as shown in Eq. 13. As the name suggests, this scalar measure is most often used for stress tensors. (13) where is the deviatoric tensor of the Rank-2 tensor .

Volumetric Strain

The scalar type VolumetricStrain computes the change in volume divided by the original volume and is most appliable for strain. For a Rank-2 tensor, , the volumetric strain quantity is calculated with Eq. 14. (14)

Example Input File Syntax

[./fred]
  type = RankTwoScalarAux
  rank_two_tensor = total_strain
  variable = volumetric_strain
  scalar_type = VolumetricStrain
  execute_on = timestep_end
[../]
(modules/combined/test/tests/internal_volume/rz_displaced.i)

An AuxVariable is required to store the AuxKernel information. Note that the name of the AuxVariable is used as the argument for the variable input parameter in the RankTwoScalarAux block.

[./volumetric_strain]
  order = CONSTANT
  family = MONOMIAL
[../]
(modules/combined/test/tests/internal_volume/rz_displaced.i)

Von Mises Stress

The scalar type VonMisesStress calculates the vonMises measure for a Rank-2 tensor, as shown in Eq. 15. This quantity is usually applied to the stress tensor. (15) where is the deviatoric tensor of the Rank-2 tensor .

Example Input File Syntax


[./vonmises]
  type = RankTwoScalarAux
  rank_two_tensor = stress
  variable = vonmises
  scalar_type = VonMisesStress
  execute_on = timestep_end
[../]
(modules/tensor_mechanics/test/tests/material_limit_time_step/elas_plas/nafems_nl1_lim.i)

An AuxVariable is required to store the AuxKernel information. Note that the name of the AuxVariable is used as the argument for the variable input parameter in the RankTwoScalarAux block.

As with the RankTwoAux AuxKernel, RankTwoScalarAux requires the inclusion of an AuxVariable block for each AuxKernel block.

AuxVariable Order

note:Elemental vs Nodal Visualization of Quadrature Field Values

Results will have different quality based on the AuxVariable:

  • Elemental Constant Monomial Using an AuxVariable with family = MONOMIAL and order = CONSTANT will give a constant value of the AuxVariable for the entire element, which is computed by taking a volume-weighted average of the integration point quantities. This is the default option using TensorMechanics Action and requires the least computational cost.

  • Elemental Higher-order Monomial Using an AuxVariable with family = MONOMIAL and order = FIRST or higher will result in fields that vary linearly (or with higher order) within each element. Because the Exodus mesh format does not support higher-order elemental variables, these AuxVariables are output by libMesh as nodal variables for visualization purposes. Using higher order monomial variables in this way can produce smoother visualizations of results for a properly converged simulation.

  • Nodal Lagrange Using an AuxVariable with family = LAGRANGE will result in a smooth nodal field of the material property, constructed using nodal patch recovery. patch_polynomial_order is set to equal the order of the AuxVariable by default. Use this option for the best (smoothest, most accurate) results, but there is some additional computational cost. Furthermore, this method is suitable only for serial simulations at present.

Input Parameters

  • rank_two_tensorThe rank two material tensor name

    C++ Type:MaterialPropertyName

    Options:

    Description:The rank two material tensor name

  • variableThe name of the variable that this object applies to

    C++ Type:AuxVariableName

    Options:

    Description:The name of the variable that this object applies to

Required Parameters

  • scalar_typeType of scalar output

    C++ Type:MooseEnum

    Options:VonMisesStress EffectiveStrain Hydrostatic L2norm MaxPrincipal MidPrincipal MinPrincipal VolumetricStrain FirstInvariant SecondInvariant ThirdInvariant AxialStress HoopStress RadialStress TriaxialityStress Direction

    Description:Type of scalar output

  • direction0 0 1Direction vector

    Default:0 0 1

    C++ Type:libMesh::Point

    Options:

    Description:Direction vector

  • point10 0 0Start point for axis used to calculate some cylinderical material tensor quantities

    Default:0 0 0

    C++ Type:libMesh::Point

    Options:

    Description:Start point for axis used to calculate some cylinderical material tensor quantities

  • point20 1 0End point for axis used to calculate some material tensor quantities

    Default:0 1 0

    C++ Type:libMesh::Point

    Options:

    Description:End point for axis used to calculate some material tensor quantities

  • execute_onLINEAR TIMESTEP_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:LINEAR TIMESTEP_END

    C++ Type:ExecFlagEnum

    Options:NONE INITIAL LINEAR NONLINEAR TIMESTEP_END TIMESTEP_BEGIN FINAL CUSTOM

    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.

  • boundaryThe list of boundary IDs from the mesh where this boundary condition applies

    C++ Type:std::vector

    Options:

    Description:The list of boundary IDs from the mesh where this boundary condition applies

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

    C++ Type:std::vector

    Options:

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

Optional Parameters

  • selected_qpEvaluate the tensor at this quadpoint. This option only needs to be used if you are interested in a particular quadpoint in each element: otherwise do not include this parameter in your input file

    C++ Type:unsigned int

    Options:

    Description:Evaluate the tensor at this quadpoint. This option only needs to be used if you are interested in a particular quadpoint in each element: otherwise do not include this parameter in your input file

  • enableTrueSet the enabled status of the MooseObject.

    Default:True

    C++ Type:bool

    Options:

    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

    Options:

    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.

  • patch_polynomial_orderPolynomial order used in least squares fitting of material property over the local patch of elements connected to a given node

    C++ Type:MooseEnum

    Options:CONSTANT FIRST SECOND THIRD FOURTH

    Description:Polynomial order used in least squares fitting of material property over the local patch of elements connected to a given node

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

    C++ Type:std::vector

    Options:

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

  • seed0The seed for the master random number generator

    Default:0

    C++ Type:unsigned int

    Options:

    Description:The seed for the master random number generator

Advanced Parameters

Input Files

References

  1. Keith D Hjelmstad. Fundamentals of Structural Mechanics. Springer Science & Business Media, 2007.[BibTeX]
  2. Lawrence E Malvern. Introduction to the Mechanics of a Continuous Medium. Prentice-Hall, 1969.[BibTeX]