9.13. Variables

This section lists commonly used variables that the user can be output to the results, history, or restart files. This includes global, nodal, and element variables. Material model specific output variables are described in the material model chapter (Section 5).

9.13.1. Global, Nodal, Face, and Element Variables

This section lists commonly used variables. The variables are presented in tables based on use as follows:

Table Table 9.1 Energy Variables
Table Table 9.2 Other Global Variables for All Analyses
Table Table 9.3 Memory Global Variables for All Analyses
Table Table 9.4 Global Variables for AL Control Contact
Table Table 9.5 Global Variables for Rigid Bodies
Table Table 9.6 Nodal Variables for All Analyses
Table Table 9.7 Nodal Variables for Implicit Analyses
Table Table 9.8 Nodal Variables for Shells
Table Table 9.9 Nodal Variables for Spot Welds
Table Table 9.10 Nodal Variables for Line Welds
Table Table 9.11 Nodal Variables for MPCs
Table Table 9.12 Nodal Variables for Contact
Table Table 9.13 Element Variables for All Elements, Part 1
Table Table 9.14 Element Variables for All Elements, Part 2
Table Table 9.15 Element Variables for Solid Elements, Part 1,
Table Table 9.16 Element Variables for Solid Elements, Part 2
Table Table 9.17 Element Variables for Solid Elements, Part 3
Table Table 9.18 Element Variables for Membranes
Table Table 9.19 Element Variables for Shells
Table Table 9.20 Element Variables for Trusses
Table Table 9.21 Element Variables for Cohesive Elements
Table Table 9.22 Element Variables for Nonlinear Beams
Table Table 9.23 Element Variables for Springs
Table Table 9.24 Element Variables for Line Welds
Table Table 9.25 Face Variables
Table Table 9.26 Derived Variable Equations

The tables provide the following information about each variable:

Variable Name. The variable can be accessed via this name in an results output block, user output block, user subroutine, etc.

Type. This is the intrinsic variable type. The various types are listed as follows:

Integer: A single integer value.
Integer[]: An array of integer values.
Real: A single floating point value.
Real[]: An array of floating point values.
Vector_2D: A two component vector value. Values will be output as name_x and name_y.
Vector_3D: A three component vector value. Values will be output as name_x, name_y, and name_z.
SymTen33: A symmetric 3x3 tensor with six unique components name_xx, name_yy, name_zz, name_xy, name_yz, name_zx.
FullTen36: A full 3x3 tensor with nine unique components name_xx, name_yy, name_zz, name_xy, name_yz, name_zx, name_yx, name_zy, and name_xz.

Derived. Standard variables are stored in the mesh database. A variable designed with a yes in this column is a derived variables. Derived variables are computed on the fly as a function of other variables. For example unrotated_stress is a standard variable while von_mises is a derived norm of the unrotated_stress field. Usually standard and derived variables can be used interchangeably. There are some distinctions. Derived variables cannot be set in initial conditions. Additional derived variables must be included in a BEGIN DERIVED OUTPUT command block if it is to be transferred to another procedure or region as described in Section 6.7.

Refer to Section 9.3.1.4 for details on output in the context of elements with multiple integration points.

For node-based tetrahedra the “element” variables are stored at both the elements and at the nodes; more details are available in Section 6.2.1.1. The tables of various types of variables follow.

Table 9.1 Global Energy Variables
Variable Name	Type	Comments
`contact_energy`	`Real`	The energy added or subtracted from the system by contact forces. Includes frictional loses and plastic contact. Computed as the integral of `contact_force` dot `velocity`
`external_energy`	`Real`	The energy added or subtracted from the system by external forces (force, pressure, kinematic BCs, etc.) Computed as integral of `force_external` dot `velocity`
`internal_energy`	`Real`	Energy stored by material and hourglass forces. Computed as integral of `internal+force` dot `velocity`
`kinetic_energy`	`Real`	Total kinetic energy of model. Computed as sum of nodal kinetic energies
`hourglass_energy`	`Real`	The internal energy due to hourglass forces. Will be present in under-integrated elements such as the uniform gradient hexahedron. `hourglass_energy` is a component of `internal_energy`
`stiffness_hourglass_energy`	`Real`	The internal energy due to hourglass stiffness. Currently only available for the uniform gradient hexahedron, fiber shell, and fiber membrane elements
`viscous_hourglass_energy`	`Real`	The internal energy due to hourglass viscosity. Currently only available for the uniform gradient hexahedron, fiber shell, and fiber membrane elements
`strain_energy`	`Real`	Total strain energy accumulated in all elements. Integral of stress dot strain. `strain_energy` is a component of `internal_energy`
`deposited_energy`	`Real`	Total energy deposited by `PRESCRIBED ENERGY DEPOSITION` boundary conditions. Generally only relevant to equation of state based material models
`external_viscous_energy`	`Real`	Viscous energy lost due to external viscous forces. At present, this includes velocity damping and mass damping (Section 7.16.6)
`internal_viscous_energy`	`Real`	Viscous energy lost due to internal viscous forces. At present, this only includes stiffness damping (Section 7.16.6)
`block<blockID>_external_viscous_energy`	`Real`	Viscous energy lost due to external viscous forces for a specific block, where `<blockID>` is replaced by the ID of the block requested.
`block<blockID>_internal_viscous_energy`	`Real`	Viscous energy lost due to internal viscous forces for a specific block, where `<blockID>` is replaced by the ID of the block requested.

Table 9.2 Other Global Variables For All Analyses
Variable Name	Type	Comments
`momentum`	`Vector_3D`	Total model momentum sum. Computed as `mass` dot `velocity`
`angular_momentum`	`Vector_3D`	Total model angular momentum sum. Includes angular momentum of both the translational and rotational degrees of freedom.
`momentum_block<blockID>_x`	`Real`	Momentum sum in the x direction for each block, e.g., `momentum_block1_x` for `blockID 1`
`momentum_block<blockID>_y`	`Real`	Momentum sum in the y direction for each block, e.g., `momentum_block1_y` for `blockID 1`
`momentum_block<blockID>_z`	`Real`	Momentum sum in the z direction for each block, e.g., `momentum_block1_z` for `blockID 1`
`stepcount`	`Real`	Step count (1, 2, …, N)
`timestep`	`Real`	Current time step
`timestep_element`	`Real`	Time step from element estimator
`timestep_nodal`	`Real`	Time step from nodal estimator
`timestep_material`	`Real`	Time step from material model
`timestep_lanczos`	`Real`	Time step from Lanczos estimator
`timestep_powermethod`	`Real`	Time step from power method estimator
`wall_clock_time`	`Real`	Accumulated wall clock run time in seconds
`wall_clock_time_per_step`	`Real`	Wall clock time for last time step in seconds
`cpu_time`	`Real`	Accumulated CPU time in seconds
`cpu_time_per_step`	`Real`	CPU time for last time step in seconds
`ghost_count`	`Real`	Total number of off-processor nodes and elements at any given time. If ghost count is growing substantially over time it may indicate that the analysis could be sped up via an automated rebalance.

Table 9.3 Global Memory Variables For All Analyses
Variable Name	Type	Comments
`memory`	`Real`	Total memory currently used in bytes
`memory_total`	`Real`	Sum of memory over all MPI ranks in bytes
`memory_max`	`Real`	Max of memory over all MPI ranks in bytes
`memory_min`	`Real`	Min of memory over all MPI ranks in bytes
`memory_avg`	`Real`	Average memory per MPI rank in bytes
`memory_hwm`	`Real`	High water mark memory in bytes

Table 9.4 Global Variables for Augmented Lagrange Control Contact (See Section 4.5.2)
Variable Name	Type	Comments
`num_interactions`	`Int`	Number of possible interactions that were found in contact search
`num_released`	`Int`	Number of interactions that are in a released state
`num_captured`	`Int`	Number of interactions that are in a captured state
`num_dubious`	`Int`	Number of interactions that are in a dubious state
`max_normal_gap`	`Real`	Maximum normal gap among all captured and dubious interactions
`max_normal_relative_gap`	`Real`	Maximum normal gap divided by interaction tolerance among all captured and dubious interactions
`max_tangential_gap`	`Real`	Maximum tangential gap among all captured and dubious interactions
`LM_norm`	`Real`	Magnitude of the Lagrange multiplier
`LM_last_relative_change`	`Real`	Relative change in `LM_norm` over the last control contact iteration

Table 9.5 Global Variables for Rigid Bodies. (See Section 9.12 for default output options.)
Variable	Type	Comments
`a<x\|y\|z>_<rb_name>`	`Real`	Translational acceleration
`vel<x\|y\|z>_<rb_name>`	`Real`	Translational velocity
`displ<x\|y\|z>_<rb__name>`	`Real`	Translational displacement
`rota<x\|y\|z>_<rb__name>`	`Real`	Rotational acceleration
`rotv<x\|y\|z>_<rb__name>`	`Real`	Rotational velocity
`rotd<x\|y\|z>_<rb__name>`	`Real`	Rotational displacement
`react<x\|y\|z>_<rb_name>`	`Real`	Translational reaction
`rreact<x\|y\|z>_<rb__name>`	`Real`	Rotational reaction
`qvec<1\|2\|3\|4>_<rb__name>`	`Real`	Unit quaternion

Example: ax_rb1 is the x translational acceleration for the rigid body specified in a BEGIN RIGID BODY rb1 block where rb1 is a name chosen by the user.

Table 9.6 Nodal Variables for All Analyses
Variable	Type	Comments
`model_coordinates`	`Vector_3D`	Original coordinates of nodes
`coordinates`	`Vector_3D`	Current coordinates of nodes
`displacement`	`Vector_3D`	Total displacement, generally `coordinates` minus `model_coordinates`
`velocity`	`Vector_3D`	Velocity of nodes, derivative of displacement
`acceleration`	`Vector_3D`	Acceleration of nodes, derivative of velocity
`force_internal`	`Vector_3D`	Force produced by element and material response. Also includes hourglass and other element stabilization forces.
`force_external`	`Vector_3D`	Force produced by external loading such as prescribed force, pressure, traction, and moment boundary conditions.
`force_inertial`	`Vector_3D`	Force that is equivalent to the nodal mass times the nodal acceleration (Implicit only)
`force_external_transferred`	`Vector_3D`	Force transferred from another physics (coupled problems only)
`force_contact`	`Vector_3D`	Force produced by contact
`reaction`	`Vector_3D`	Force produced by kinematic boundary conditions such as fixed displacement
`mass`	`Real`	Mass of each node
`nodal_time_step`	`Real`	Nodal stable time step (explicit control modes, coarse mesh only)
`node_id`	`Integer`	Global ID of each node
`quaternion`	`Real`	Current quaternion (rigid body reference nodes only)
`node_id`	`Int`	Exodus global id of the node

Table 9.7 Nodal Variables for Implicit Analyses
Variable	Type	Comments
`displacement_increment`	`Vector_3D`	Change in displacement over the current step
`residual`	`Vector_3D`	Nodal free body force imbalance at current time step

Table 9.8 Nodal Variables for Shells and Beams
Variable	Type	Comments
`rotational_displacement`	`Vector_3D`	Total spin of each node
`rotational_velocity`	`Vector_3D`	Spin rate of each node, derivative of `rotational_displacement`
`rotational_acceleration`	`Vector_3D`	Spin acceleration of each node, derivative of `rotational_velocity`
`moment_internal`	`Vector_3D`	Nodal moment from element and material response
`moment_external`	`Vector_3D`	Applied external moment, for example from a “PRESCRIBED MOMENT” boundary conditio
`moment_external_transferred`	`Vector_3D`	Moment transferred from another physics (coupled problems only)
`moment_inertial`	`Vector_3D`	Nodal moment from nodal rotational mass times the nodal rotational acceleration (Implicit Only)
`rotational_reaction`	`Vector_3D`	Applied moment to enforce a kinematic boundary condition such as “PRESCRIBED ROTATION”
`rotational_mass`	`Real`	Nodal inertia. A single value, nodal inertia assumed spherical.

Table 9.9 Nodal Variables for Spot Welds
Variable	Type	Comments
`spot_weld_parametric_coordinates`	`Vector_2D`	Parametric coordinates defining node location on face
`spot_weld_normal_force_at_death`	`Real`	Value of force normal to face when spot weld breaks
`spot_weld_tangential_force_at_death`	`Real`	Value of force tangential to face when spot weld breaks
`spot_weld_death_flag`	`Integer`	alive = 0, dead = FAILURE DECAY CYCLES (default is 10), -1 = no spot weld constructed at this node
`spot_weld_scale_factor`	`Real`	Nodal influence area of current node
`spot_weld_normal_displacement`	`Real`	Current displacement of weld normal to face
`spot_weld_tangential_displacement`	`Real`	Current displacement of weld tangential to face
`spot_weld_normal_force`	`Real`	Current force of weld normal to face
`spot_weld_tangential_force`	`Real`	Current force of weld tangential to face
`spot_weld_stiffness`	`Real`	Current stiffness of weld
`spot_weld_norm_stiffness`	`Real`	Current stiffness of weld normal to face
`spot_weld_tang_stiffness`	`Real`	Current stiffness of weld tangential to face
`spot_weld_initial_offset`	`Vector_3D`	The initial offset of the spot weld node from the spot weld surface. Does not change over time, only output if IGNORE INITIAL OFFSET = YES is specified at input
`spot_weld_initial_normal`	`Vector_3D`	The initial normal of the spot weld surface at the point of interaction. Only output if IGNORE INITIAL OFFSET = YES is specified at input.

Table 9.10 Nodal Variables for Line Welds
Variable	Type	Comments
`line_weld_force_applied`	`Vector_3D`	The force applied to the nodes of the beam and the face of the shell it is connected to
`line_weld_moment_applied`	`Vector_3D`	The moment applied to the nodes of the beam and the face of the shell it is connected to

Table 9.11 Nodal Variables for MPCs
Variable	Type	Comments
`force_constraint`	`Vector_3D`	The force applied to the nodes in the MPC
`moment_constraint`	`Vector_3D`	The moment applied to the nodes in the MPC
`constraint_mass`	`Real`	The mass used to compute the force applied to the node
`constraint_rotational_mass`	`Real`	The rotational mass used to compute the moment applied to the nodes with rotational DOFs
`status_constraint_flag`	`Integer`	0 = node not in MPC, 1 = Node is in one or more MPCs and among which it is always a side A MPC node, 2 = Node is in one or more MPCs and it is a side B node in at least one MPC

Table 9.12 Nodal Variables for Contact (See Section 8.10). \(^{*}\) indicates a variable only computed for explicit simulations.
Variable	Type	Comments
`contact_strength`	`Real`	Strength of contact interactions at the node, computed as nodal `contact_area` divided by `surface_area`. Nominal range is between 0.0 (no contact) and 1.0 (fully in contact). Values above 1.0 may be reported in some circumstances. Generally contact strength values between 0.85 and 1.15 will be seen in fully overlapped zones and the contact strength will fade to zero near the edge of contact zones.
`contact_status`	`Real`	Status of the interactions at the node. Possible values are as follows, 0.0 = Node is not a contact node (not in a defined contact surface); 0.5 = Node is not in contact. For explicit contact, 1.0 = Node is in contact. For implicit contact: 1.0 = Node is in contact and is tied or slipping; 0.75 = Node is in dubious contact (penalty enforcement only); -1.0 = Node is in contact and is sticking (`celement`).
`contact_friction_index`	`Int`	Records what friction model is being used by a node. The index number at the node can be compared to a table printed to the log file to determine what friction model name and type a given node is using. Note, a node in multiple interactions will report the friction model associated with the strongest interaction.
`contact_normal_direction`	`Vector_3D`	Direction of the constraint. This is, in general, the normal of the face in the interaction (`cdirnor`).
`force_contact`	`Vector_3D`	Force applied by contact.
`contact_tangential_direction`	`Vector_3D`	Direction of the contact tangential force (`cdirtan`).
`contact_normal_force_magnitude`	`Real`	Magnitude of the contact force at the node in the direction normal to the contact face. Magnitude of `contact_normal_direction`.
`contact_tangential_force_magnitude`	`Real`	Magnitude of the contact force at the node in the plane of the contact face. Magnitude of `contact_tangential_direction`.
`contact_normal_traction_magnitude`	`Real`	Contact traction normal to the contact face. `contact_normal_force_magnitude` divided by `contact_area`. If there are multiple interactions for this node, the traction only for the last interaction is given. Negative for compression tractions, positive for tensile tractions.
`contact_tangential_traction_magnitude`	`Real`	Traction in the plane of the contact face. `contact_traction_force_magnitude` divided by `contact_area`. If there are multiple interactions for this node, the traction only for the last interaction is given. This value is generally negative as it opposes slip.
`contact_incremental_slip_magnitude`	`Real`	Magnitude of incremental slip over the current time step (`cdtan`).
`contact_incremental_slip_direction`	`Vector_3D`	Normalized direction of incremental slip over the current time step (`cdirislp`).
`contact_accumulated_slip`	`Real`	Magnitude of tangential slip accumulated over the entire analysis. This is the distance along the slip path, and not the magnitude of `contact_accumulated_slip_vector` (`cstan`).
`contact_accumulated_slip_vector`	`Vector_3D`	Total accumulated tangential slip over the entire analysis (`cdirslp`).
`contact_frictional_energy`\(^{*}\)	`Real`	Accumulated amount of frictional energy dissipated over the entire analysis.
`contact_frictional_energy_density`\(^{*}\)	`Real`	Accumulated amount of frictional energy dissipated over the entire analysis, divided by the nodal surface area (`cetan`).
`contact_area`	`Real`	Contact area for the node. This is the tributary area around the node for this interaction. For multiple interactions, the reported area is the area associated with the last interaction (`carea`).
`surface_area`	`Real`	Exposed surface area for the node. This is the tributary area around the node.
`contact_normal_gap`	`Real`	Magnitude of gap in the direction normal to the face (`cgnor`).
`contact_tangential_gap`	`Real`	Magnitude of gap in the direction tangent to the face (only applicable for compliant friction models) (`cgtan`).
`removed_overlap`	`Vector_3D`	Direction and magnitude of removed overlap (only applicable for explicit).
`contact_energy`	`Real`	Work done by contact on a node by node basis. Positive values indicate contact added energy to the node, negative subtracted energy from the node.

Table 9.13 Element Variables for All Elements, Part 1 of 2. \(^{*}\) indicates a derived variable; see Section 6.7.
Variable	Type	Comments
`diagonal_ratio`	`Real`	See Section 2.5
`element_mass`	`Real`	Total mass of element
`element_id`	`Integer`	Global ID of the element
`perimeter_ratio`	`Real`	See Section 2.5
`solid_angle`	`Real`	See Section 2.5
`timestep`	`Real`	Critical time step for the element. The element in the model with the smallest time step controls the analysis time step.
`von_mises`\(^{*}\)	`Real`	Von Mises stress norm
`hydrostatic_stress`\(^{*}\)	`Real`	One-third the trace of the stress tensor
`fluid_pressure`\(^{*}\)	`Real`	Negative of `hydrostatic_stress`
`stress_invariant_1`\(^{*}\)	`Real`	\(I_1\), Trace of the stress tensor
`stress_invariant_2`\(^{*}\)	`Real`	\(I_2\), Second invariant of the stress tensor
`stress_invariant_3`\(^{*}\)	`Real`	\(I_3\), Third invariant of the stress tensor
`stress_invariant_j2`\(^{*}\)	`Real`	\(J_2\), Second invariant of the deviatoric stress tensor
`stress_invariant_j3`\(^{*}\)	`Real`	\(J_3\), Third invariant of the deviatoric stress tensor
`triaxiality`\(^{*}\)	`Real`	Ratio of hydrostatic pressure to Von Mises stress
`lode_angle`\(^{*}\)	`Real`	\(\frac{1}{3}\arccos(\frac{3}{2}\sqrt{3}(J_3/J_2^{3/2}))\)

Table 9.14 Element Variables for All Elements, Part 2 of 2. \(^{*}\) indicates a derived variable; see Section 6.7.
Variable	Type	Comments
`principal_stresses`\(^{*}\)	`Vector_3D`	All three eigenvalues of the stress tensor sorted smallest to largest
`max_principal_stress`\(^{*}\)	`Real`	Largest eigenvalue of the stress tensor
`intermediate_principal_stress`\(^{*}\)	`Real`	Middle eigenvalue of the stress tensor
`min_principal_stress`\(^{*}\)	`Real`	Smallest eigenvalue of the stress tensor
`max_shear_stress`\(^{*}\)	`Real`	Maximum shear stress from Mohr’s circle
`octahedral_shear_stress`\(^{*}\)	`Real`	Octahedral shear norm of the stress tensor
`internal_energy`	`Real`	Total internal energy for the element
`hourglass_energy`	`Real`	Total hourglass energy for the element
`stiffness_hourglass_energy`	`Real`	The internal energy due to hourglass stiffness. Currently only available for the uniform gradient hexahedron, fiber shell, and fiber membrane elements.
`viscous_hourglass_energy`	`Real`	The internal energy due to hourglass viscosity. Currently only available for the uniform gradient hexahedron, fiber shell, and fiber membrane elements.
`nonmaterial_strain_3d`	`SymTen33`	Total thermal and artificial strain (engineering strain) applied to the element
`nonmaterial_strain_rate_3d`	`SymTen33`	Current nonmaterial log strain rate applied to the element
`thermal_strain_rate_3d`	`SymTen33`	Current thermal log strain rate applied to the element
`artificial_strain_rate_3d`	`SymTen33`	Current artificial log strain rate applied to the element
`processor_id`	`Int`	Parallel processor rank that owns the element
`element_id`	`Int`	Exodus global ID of the element
`material_direction_1`\(^{*}\)	`Vector_3D`	Material direction 1 for orthotropic materials
`material_direction_2`\(^{*}\)	`Vector_3D`	Material direction 2 for orthotropic materials
`material_direction_3`\(^{*}\)	`Vector_3D`	Material direction 3 for orthotropic materials
`strain_energy_density`	`Real`	Volumetric material strain energy. Integral of material stress dotted with material strain. Note the `strain_energy_density` resultant removes the energy associated with thermal strains and artificial bulk viscosity that are included in the `deformation_energy_density`
`strain_energy`	`Real`	Total strain energy, strain energy times element volume

Table 9.15 Element Variables for Solid Elements, Part 1 of 2.
Variable	Type	Comments
`aspect_ratio`	`Real`	Tetrahedra only. See Section 2.5
`inradius`	`Real`	Tetrahedra only. See Section 2.5
`normalized_inradius`	`Real`	10-node tetrahedra only. See Section 2.5
`mean_ratio`	`Real`	Tetrahedra only. See Section 2.5
`dilmod`	`Real`	Dilatational modulus
`nodal_jacobian_ratio`	`Real`	Hex and Quad only. See Section 2.5
`scaled_jacobian`	`Real`	Hex only. See Section 2.5
`element_shape`	`Real`	Element shape quality metric. See Section 2.5
`rate_of_deformation`	`SymTen33`	Unrotated rate of deformation tensor, \({\bf D}\) (Hexahedra and node-based tetrahedra only)
`principal_rates_of_deformation`	`Vector_3D`	Principal rates of deformation (stretching)
`max_principal_rate_of_deformation`	`Real`	Maximum principal rate of deformation (stretching)
`intermediate_principal_rate_of_deformation`	`Real`	Intermediate principal rate of deformation (stretching)
`min_principal_rate_of_deformation`	`Real`	Minimum principal rate of deformation (stretching)
`max_principal_rate_of_deformation_direction`	`Vector_3D`	Direction of the maximum principal rate of deformation (stretching)
`intermediate_principal_rate_of_deformation_direction`	`Vector_3D`	Direction of the intermediate principal rate of deformation (stretching)
`min_principal_rate_of_deformation_direction`	`Vector_3D`	Direction of the minimum principal rate of deformation (stretching)
`deformation_gradient`	`FullTen36`	Deformation gradient tensor, \({\bf F}\)
`right_stretch`	`SymTen33`	Right stretch tensor, \({\bf U}\)
`left_stretch`	`SymTen33`	Left stretch tensor, \({\bf V}\)
`rotation`	`FullTen36`	Rotation tensor, \({\bf R}\)
`shrmod`	`Real`	Shear modulus
`stress`	`SymTen33`	Cauchy stress tensor in global configuration. This is a single volume averaged value for multiple integration point elements.
`cauchy_stress`	`SymTen33`	Cauchy stress tensor in the global configuration. This value is present at each integration point.
`unrotated_stress`	`SymTen33`	Cauchy stress in the unrotated material configuration. This value is present at each integration point.

Table 9.16 Element Variables for Solid Elements, Part 2 of 3.
Variable	Type	Comments
`max_principal_stress_direction`	`Vector_3D`	Eigenvector of the Cauchy stress tensor corresponding to the largest eigenvalue
`intermediate_principal_stress_direction`	`Vector_3D`	Eigenvector of the Cauchy stress tensor corresponding to the middle eigenvalue
`min_principal_stress_direction`	`Vector_3D`	Eigenvector of the Cauchy stress tensor corresponding to the smallest eigenvalue
`green_lagrange_strain`	`SymTen33`	Green-Lagrange strain tensor, \({\bf E} = (1/2) ({\bf F}^{T}\cdot{\bf F} - {\bf I})\)
`principal_green_lagrange_strains`	`Vector_3D`	All three eigenvalues of the Green-Lagrange strain tensor sorted smallest to largest
`max_principal_green_lagrange_strain`	`Real`	Largest eigenvalue of the Green-Lagrange strain tensor
`intermediate_principal_green_lagrange_strain`	`Real`	Middle eigenvalue of the Green-Lagrange strain tensor
`min_principal_green_lagrange_strain`	`Real`	Smallest eigenvalue of the Green-Lagrange strain tensor
`max_principal_green_lagrange_strain_direction`	`Vector_3D`	Eigenvector of the Green-Lagrange strain tensor corresponding to the largest eigenvalue
`intermediate_principal_green_lagrange_strain_direction`	`Vector_3D`	Eigenvector of the Green-Lagrange strain tensor corresponding to the middle eigenvalue
`min_principal_green_lagrange_strain_direction`	`Vector_3D`	Eigenvector of the Green-Lagrange strain tensor corresponding to the smallest eigenvalue
`green_lagrange_strain_rate`	`SymTen33`	Green-Lagrange strain rate tensor, \(\dot{\bf E} = {\bf F}^{T} \bf{ D F}\)
`principal_green_lagrange_strain_rates`	`Vector_3D`	All three eigenvalues of the Green-Lagrange strain rate tensor sorted smallest to largest
`max_principal_green_lagrange_strain_rate`	`Real`	Largest eigenvalue of the Green-Lagrange strain rate tensor
`intermediate_principal_green_lagrange_strain_rate`	`Real`	Middle eigenvalue of the Green-Lagrange strain rate tensor
`min_principal_green_lagrange_strain_rate`	`Real`	Smallest eigenvalue of the Green-Lagrange strain rate tensor
`max_principal_green_lagrange_strain_rate_direction`	`Vector_3D`	Eigenvector of the Green-Lagrange strain rate tensor corresponding to the largest eigenvalue
`intermediate_principal_green_lagrange_strain_rate_direction`	`Vector_3D`	Eigenvector of the Green-Lagrange strain rate tensor corresponding to the middle eigenvalue
`min_principal_green_lagrange_strain_rate_direction`	`Vector_3D`	Eigenvector of the Green-Lagrange strain rate tensor corresponding to the smallest eigenvalue

Table 9.17 Element Variables for Solid Elements, Part 3 of 3.
Variable	Type	Comments
`biot_strain`	`SymTen33`	Biot Strain tensor, \({\bf U - I}\)
`log_strain`	`SymTen33`	Log strain tensor, \(\ln{\bf V}\)
`unrotated_log_strain`	`SymTen33`	Log strain tensor in unrotated configuration, \(\ln{\bf U}\)
`effective_log_strain`	`Real`	Effective log strain
`log_strain_invariant_1`	`Real`	Trace of the log strain tensor
`log_strain_invariant_2`	`Real`	Second invariant of the log strain tensor
`log_strain_invariant_3`	`Real`	Third invariant of the log strain tensor
`max_principal_log_strain`	`Real`	Largest eigenvalue of the log strain tensor
`intermediate_principal_log_strain`	`Real`	Middle eigenvalue of the log strain tensor
`min_principal_log_strain`	`Real`	Smallest eigenvalue of the log strain tensor
`max_principal_strain_direction`	`Vector_3D`	Eigenvector of the log strain tensor corresponding to the largest eigenvalue
`intermediate_principal_strain_direction`	`Vector_3D`	Eigenvector of the log strain tensor corresponding to the middle eigenvalue
`min_principal_strain_direction`	`Vector_3D`	Eigenvector of the log strain tensor corresponding to the smallest eigenvalue
`max_shear_log_strain`	`Real`	Maximum shear log strain from Mohr’s circle
`octahedral_shear_log_strain`	`Real`	Octahedral strain norm of the log strain tensor
`volume`	`Real`	Element volume
`internal_energy_density`	`Real`	Element total internal energy divided by current element volume
`hourglass_energy_density`	`Real`	Element hourglass energy divided by current element volume
`deformation_energy_density`	`Real`	`internal_energy_density` minus `hourglass_energy_density`. Equivalent to the integral of total element stress dotted with total element deformation.
`iplocation`	`Vector_3D`	Location of each element integration points in the original model coordinates
`centroid`	`Vector_3D`	Location element mass-centroid in the original model coordinates

Table 9.18 Element Variables for Membranes.
Variable	Type	Comments
`memb_stress`	`SymTen33`	Cauchy membrane stress tensor in the global configuration.
`element_area`	`Real`	Surface area of the element
`element_thickness`	`Real`	Thickness provided to element

Table 9.19 Element Variables for Shells. \(^{*}\) indicates a derived variable; consult Section 6.7 for additional details. \(^{\dagger}\) indicates a variable which is available for analytic integration; refer to Section 6.2.5.
Variable	Type	Comments
`memb_stress`\(^{*,\dagger}\)	`SymTen33`	Cauchy stress at mid plane in global X, Y, and Z coordinates.
`bottom_stress`\(^{*,\dagger}\)	`SymTen33`	Cauchy stress at bottom integration point in global X, Y, and Z coordinates
`top_stress`\(^{*,\dagger}\)	`SymTen33`	Cauchy stress at top integration point in global X, Y, and Z coordinates
`unrotated_stress`	`SymTen33`	Cauchy stress in the unrotated material configuration. This value is present at each integration point. ZZ component is undefined.
`transform_shell_stress`\(^{*}\)	`SymTen21`	In-plane shell stress
`strain`	`SymTen33`	Integrated strain at mid plane in local shell coordinate system
`effective_strain`\(^{*}\)	`Real`	Effective strain norm
`strain_invariant_1`\(^{*}\)	`Real`	Trace of the strain tensor
`strain_invariant_2`\(^{*}\)	`Real`	Second invariant of the strain tensor
`strain_invariant_3`\(^{*}\)	`Real`	Third invariant of the strain tensor
`max_principal_strain`\(^{*}\)	`Real`	Largest eigenvalue of the strain tensor
`intermediate_principal_strain`\(^{*}\)	`Real`	Middle eigenvalue of the strain tensor
`min_principal_strain`\(^{*}\)	`Real`	Smallest eigenvalue of the strain tensor
`max_shear_strain`\(^{*}\)	`Real`	Maximum shear strain from Mohr’s circle
`octahedral_shear_strain`\(^{*}\)	`Real`	Octahedral strain norm of the strain tensor
`transform_shell_strain`\(^{*}\)	`Real`	In-plane shell strain
`element_area`	`Real`	Element surface area
`element_thickness`	`Real`	Element current thickness
`rate_of_deformation`	`SymTen33`	Rate of deformation (stretching) tensor
`thickness_to_length_ratio`\(^{*,\dagger}\)	`Real`	Ratio of shell thickness to in-plane element size. Shells with ratios beyond 1.0 may encounter stability issues

Table 9.20 Element Variables for Trusses
Variable	Type	Comments
`init_length`	`Real`	Initial length of the truss element
`truss_strain`	`Real`	Axial strain in the truss element
`unrotated_stress`	`SymTen33`	Axial Cauchy stress is stored in `unrotated_stress_xx`. All other components are zero. See Section 6.2.9 for more details.
`truss_force`	`Real`	Axial force in the truss

Table 9.21 Element Variables for Cohesive Elements
Variable	Type	Comments
`cse_traction`	`Vector_3D`	`_z` component is normal direction. `_x` and `_y` components are tangential directions.
`cse_separation`	`Vector_3D`	`_z` component is normal direction. `_x` and `_y` components are tangential directions.
`cse_initial_trac`	`Vector_3D`	Available only if traction initialization is used. `_z` component is normal direction. `_x` and `_y` components are tangential directions.
`cse_activated`	`Integer`	For intrinsic elements
`cse_initial_area`	`Real`	Initial area of the cohesive element
`cse_avg_normal_dir`	`Vector_3D`	Averaged normal direction over the element integration point locations
`cse_avg_t1_dir`	`Vector_3D`	Averaged tangent 1 direction over the element integration point locations
`cse_avg_t2_dir`	`Vector_3D`	Averaged tangent 2 direction over the element integration point locations
`cse_local_force`	`Vector_3D`	The element local force `z` is normal force, `x` and `y` are tangential forces.

Table 9.22 Element Variables for Nonlinear Beams
Variable	Type	Comments
`beam_strain_axial`	`Real`	Axial strain at each integration point.
`beam_strain_shear`	`Real`	Shear torsional strain at each integration point.
`beam_strain_inc`	`Vector_2D`	Strain increments at each integration point. Axial strain increments are `_x` and shear torsional strain increments are `_y`.
`beam_stress_axial`	`Real`	Axial Cauchy stress at each integration point.
`beam_stress_shear`	`Real`	Shear circumferential torsional stress at each integration point.
`unrotated_stress`	`SymTen33`	Cauchy stresses at each integration point. Only the `_xx` and `_xy` values per integration point contain actual stress values. Axial stresses are in `_xx` and circumferential torsional shear stresses are in `_xy`. See Section 6.2.8 for more details.
`beam_axial_force`	`Real`	Axial force at midpoint.
`beam_transverse_force_s`	`Real`	Transverse shear in \(s\)-direction at midpoint.
`beam_transverse_force_t`	`Real`	Transverse shear in \(t\)-direction at midpoint.
`beam_moment_r`	`Real`	Torsion at midpoint.
`beam_moment_s`	`Real`	Moment about \(s\)-direction at midpoint.
`beam_moment_t`	`Real`	Moment about \(t\)-direction at midpoint.
`beam_avg_rate_of_def`	`Real`	Average rate of deformation over all integration point.
`current_area`	`Real`	Current area of the beam cross-section.

Table 9.23 Element Variables for Springs
Variable	Type	Comments
`spring_force`	`Real`	Magnitude of the internal spring force.
`spring_engineering_strain`	`Real`	Change in length over initial length \(\frac{dL}{L_0}\).
`spring_init_length`	`Real`	Initial spring length, \(L_0\).

Table 9.24 Element Variables for Line Welds
Variable	Type	Comments
`line_weld_force`	`Vector_3D`	The force (in units force-per-unit-length) the weld is applying in the global XYZ coordinate system
`line_weld_moment`	`Vector_3D`	The moment (in units moment-per-unit-length) the weld is applying in the global XYZ coordinate system
`line_weld_force_rst`	`Vector_3D`	The force (in units force-per-unit-length) the weld is applying in the weld local RST coordinate system
`line_weld_moment_rst`	`Vector_3D`	The moment (in units moment-per-unit-length) the weld is applying in the weld local RST coordinate system
`line_weld_weld_active`	`Integer`	A flag on the beam elements of the line weld that states the weld is active or not 1 is active 0 is inactive due to the weld reaching the failure criterion, -1 is inactive due to the beam element not being found, -2 is inactive due to the connecting faces not being found, -3 is inactive due to the shells the weld is connecting not being found, -4 is inactive for any other reason
`line_weld_initial_weld_length`	`Real`	The original length of the beam element of the line weld. This length is used in computing the nodal forces to apply
`line_weld_death_flag`	`Integer`	A flag on the beam elements of the line weld that designates that portion of the weld has died (0 is alive; 1 is dead)
`line_weld_death_step`	`Integer`	The current death step of a beam element that is in the process of dying
`line_weld_force_at_death`	`Real`	A real array of size 12 that is the 3 force and moment components for each node of the beam. This value is zero as long as the beam element is alive, and is set to the current nodal forces/moments once the failure criteria is reached

Table 9.25 Face Variables
Variable	Type	Comments
`pressure`	`Real`	Pressure applied to faces via a pressure boundary condition

Table 9.26 Derived Variable Equations
Derived Variable	Equations
`effective_strain`	\(=\sqrt{(\frac{2}{9}\text{normPart})+(\frac{4}{3}\text{shearPart})}\)
	\(\text{normPart} = xmy^2 + ymy^2 + zmy^2\)
	\(\text{shearPart} = \text{strain\_xy}^2 + \text{strain\_yz}^2 + \text{strain\_zx}^2\)
	\(xmy = \text{strain\_xx} - \text{strain\_yy}\)
	\(ymz = \text{strain\_yy} - \text{strain\_zz}\)
	\(zmx = \text{strain\_zz} - \text{strain\_xx}\)
`effective_log_strain`	\(=\sqrt{(\frac{2}{9}\text{normPart})+(\frac{4}{3}\text{shearPart})}\)
	\(\text{normPart} = xmy^2 + ymy^2 + zmy^2\)
	\(\text{shearPart} = \text{left\_stretch\_xy}^2 + \text{left\_stretch\_yz}^2 + \text{left\_stretch\_zx}^2\)
	\(xmy = \text{left\_stretch\_xx} - \text{left\_stretch\_yy}\)
	\(ymz = \text{left\_stretch\_yy} - \text{left\_stretch\_zz}\)
	\(zmx = \text{left\_stretch\_zz} - \text{left\_stretch\_xx}\)

9.13.2. Variables for Material Models

State variables can be output from the material models. Most of the materials, with the exception of simple models such as the elastic model, have state variables. The state variables for material models in LAMÉ are accessible directly by name. For instance, the equivalent plastic strain variable is accessible by the name EQPS for all elastic-plastic material models. State variables can also be accessed by index.

Available LAMÉ state variable names for a material will also be listed in the log file from a run that uses the material model.

Tables of available material state variables for commonly used material models are provided in the Materials Section 5. Note, some models produce slightly different state variable sets for solids versus shells versus beams as described in the material model documentation.

9.13.3. Energy Output Variables

There are several variables available for monitoring energy throughout an analysis. Global energy variables will generally satisfy the relationship

\[IE+KE = EE,\]

with IE, KE, and EE denoting internal, kinetic, and external energies, respectively. Internal and external energies are generally computed incrementally through numerical integration of either internal or external nodal force vector dotted with the incremental nodal displacement vector. Kinetic energy is computed as \(1/2m(\mathbf{v}\cdot\mathbf{v})\) with \(m\) as nodal mass (including mass scaling) and \(\mathbf{v}\) as nodal velocity.

Internal energies come from the following sources:

Strain energy due to material stresses (strain_energy). Note that dissipated energy due to plastic deformation or material viscosity is also included, so strain_energy may be nonzero even in an unloaded state.
Hourglass forces including hourglass viscosity and hourglass stiffness (hourglass_energy)
Bulk viscosity forces including linear and quadratic terms (not active in implicit analyses by default). No output terms are currently available to monitor energy due to bulk viscosity directly.

External energies come from the following sources (may not be exhaustive):

Applied external forces via boundary conditions (pressures, forces, moments, gravity, tractions, etc.).
Contact forces (contact_energy); expected to be nonzero only for frictional contact.
Viscous damping due to Rayleigh damping (mass or stiffness proportional) or due to velocity damping.
ARS damping forces.

Energy added to induce thermal and artificial strains is not explicitly accounted for, so simulations that use these features may experience energy imbalance issues. For example, a fully-constrained body experiencing thermal expansion will have a nonzero stress state and thus nonzero strain energy, but zero internal_energy due to the fact that no work has been done due to internal or external forces (nodal displacements are zero). This inconsistency is because strain energy is computed from the inner product of Cauchy stress and rate of deformation, but internal energy is computed from the inner product of nodal force and displacement (zero).

Note that a few hyperelastic material models output the value of their strain energy potential function directly into the strain_energy and strain_energy_density variables.

Note that global energies outputs are generally computed as a summation of element or nodal energy quantities, and thus element blocks designated as INACTIVE will not contribute to the energy outputs.

Additional information may be found in the theory and verification manuals.

Known Issue

Strain energy may not be consistent with internal energy in analyses with artificial or thermal strain.

Known Issue

Strain energy reported by element blocks using both selective deviatoric elements and a hyper-elastic material model may differ slightly from internal energy. This is due to a known issue with how the selective-deviatoric element volume averages element quantities. The Total Lagrange element formulation with volume averaging of the Jacobian may provide a better alternative in cases where this is an issue.

9.13.4. Component Indexing

A specific syntax is used to access particular components of variables in an input file.

value(i), accesses the \(i\)th component of a multi-component variable such as a vector, tensor, etc. This index is one-based. For a vector vec,

vec_x = vec(1)
vec_y = vec(2)
vec_z = vec(3)

for a symmetric tensor sym,

sym_xx = sym(1)
sym_yy = sym(2)
sym_zz = sym(3)
sym_xy = sym(4)
sym_yz = sym(5)
sym_zx = sym(6)

and for a full tensor full,

full_xx = full(1)
full_yy = full(2)
full_zz = full(3)
full_xy = full(4)
full_yz = full(5)
full_zx = full(6)
full_yx = full(7)
full_zy = full(8)
full_xz = full(9)

Alternatively, the particular component can also be used. For a vector vec,

vec_x = vec(x)
vec_y = vec(y)
vec_z = vec(z)

for a symmetric tensor sym,

sym_xx = sym(xx)
sym_yy = sym(yy)
sym_zz = sym(zz)
sym_xy = sym(xy)
sym_yz = sym(yz)
sym_zx = sym(zx)

and for a full tensor full,

full_xx = full(xx)
full_yy = full(yy)
full_zz = full(zz)
full_xy = full(xy)
full_yz = full(yz)
full_zx = full(zx)
full_yx = full(yx)
full_zy = full(zy)
full_xz = full(xz)