© 2011 ANSYS, Inc. May 9, 20141
Lecture 4Implementing material models: using usermat.F
Implementing User-Programmable Features (UPFs) in ANSYS
© 2011 ANSYS, Inc. May 9, 20142
Lecture overview
• What is usermat.F used for?
• Stress, strain and material Jacobian matrix
• How is usermat.F used?
• usermat.F restrictions
• Example of application
• Where to find additional information
© 2011 ANSYS, Inc. May 9, 20143
The usermat.F subroutine allows writing the stress-strain
relationship of a material and applies to any analysis
procedure involving mechanical behaviour. The ANSYS
installation includes an example which corresponds to a
plasticity model, which is the same as TB,BISO , for
different stress states and that can be used as reference.
Such a routine can be found in the following folder:
… \ANSYS Inc\v150\ansys\customize\user
What is usermat.F used for?
© 2011 ANSYS, Inc. May 9, 20144
The stress measure (σ) used by the subroutine is the Cauchy
stress (true stress), and the strain measure (ε) is the
logarithmic strain (true strain). The strains and incremental
strains passed into usermat.F are the total mechanical
strains from which the thermal strains (if they exist) are
subtracted.
usermat.F must also provide the material Jacobian
matrix defined as:
the stress increment
being
the strain incrementij
ijJacobianεσ
∆∂∆∂
=
∆∂
∆∂
ij
ij
ε
σ
Stress, strain and material Jacobian matrix
© 2011 ANSYS, Inc. May 9, 20145
One important remark to mention is that ANSYS outputs
engineering shear strains whether NLGEOMis ONor OFF.
This is true for usermat.F as well. Engineering shear
strains are twice the tensor shear strains.
Stress, strain and material Jacobian matrix
© 2011 ANSYS, Inc. May 9, 20146
usermat.F is based on the current configuration for
nonlinear geometry analysis (NLGEOM,ON). The program
uses a co-rotational approach to account for rigid body
rotation. Because the program already accounts for the
strains passed into usermat.F for the rigid body rotation,
there is no need to apply additional rotation within
usermat.F .
The subroutine is called at every material integration point
of the elements during the solution phase. The program
passes in stresses, strains, and state variable values at the
beginning of the time increment and strain increment at the
current increment, then updates the stresses and state
variables to the appropriate values at the end of the time
increment.
Stress, strain and material Jacobian matrix
© 2011 ANSYS, Inc. May 9, 20147
usermat.F assumes use of a nonlinear constitutive
model, so results are copied from integration points to
nodes. In MAPDL, for linear elastic materials (or if stress
value < yield stress value), the default is to extrapolate
stresses and strains from integration points to nodes.
Consequently, when comparing results for usermat.Fwith linear elastic materials, differences may be seen.
Therefore, to make the comparison valid, one should use
the APDL command ERESX,NO to force copying stresses
and strains at integration points to nodes, even for linear
elastic materials. There is no way, currently, to have
usermat.F extrapolate stresses and strains from
integration points to nodes (they are always copied).
However, it is possible to do so in UserElem.F(explained in Lecture 7).
Stress, strain and material Jacobian matrix
© 2011 ANSYS, Inc. May 9, 20148
Stress, strain, and the material Jacobian tensors are stored
in a vector or matrix format. In particular, the order of
components for all tensors is as follows:
Stress, strain and material Jacobian matrix
© 2011 ANSYS, Inc. May 9, 20149
The order of components for the material Jacobian matrix is
as follows:
Stress, strain and material Jacobian matrix
© 2011 ANSYS, Inc. May 9, 201410
How is usermat.F used?
The file usermat.F consists of 4 routines which are called
depending on the corresponding stress state. Below is a list
of such 4 routines with a brief description of the stress/strain
state as well as finite elements they can be used in
conjunction with:
usermat3d 3D solid elements or plane elements in
plane strain or axisymmetric stress state
usermatps plane stress states (such as PLANE182,
PLANE183or SHELL181)
usermatbm 3D beam elements (BEAM188, BEAM189)
usermat1d 1D truss elements (LINK180)
© 2011 ANSYS, Inc. May 9, 201411
How is usermat.F used?
Number of state variables to be
defined with TB,STATE command
Number of material properties to be
defined with TB,USER command
T
T∆t
t∆ε ε∆
Vector of material properties
tFttF ∆+
Main input arguments are listed below:
© 2011 ANSYS, Inc. May 9, 201412
How is usermat.F used?
tStress at time to be updated
at time tt ∆+
State variables at time to be
updated at time
ttt ∆+
Main input/output arguments are listed below:
© 2011 ANSYS, Inc. May 9, 201413
How is usermat.F used?
Main output arguments are listed below:
Bisection occurs if
user routine does
not converge
material Jacobian
matrix
© 2011 ANSYS, Inc. May 9, 201414
usermat.F restrictions
The following restrictions apply to the usermat.Fsubroutine:
• The subroutine supports current-technology elements
only and is not applicable to legacy elements. Details on
current-technology elements can be found here:
ANSYS Documentation > Mechanical APDL > Element Reference >
2. Element Classifications > 2.4. Current-Technology Elements
• The subroutine usermat.F is not applicable to legacyelements for which dedicated subroutines should beused instead. Further information is available in theonline documentation:
ANSYS Documentation > Mechanical APDL > Feature Archive > IV. Legacy Elements
© 2011 ANSYS, Inc. May 9, 201415
usermat.F restrictions
• State variables (defined via the TB,STATE command)
are supported only by full graphics in the POST1
postprocessor;
• The subroutine is not intended for modelling
incompressible elastic materials(*), such as hyperelastic
materials. A special treatment such as a penalty
approach may be needed to ensure incompressibility. In
any case, if the material exhibits nearly incompressible
behavior, use a finite tangent bulk modulus.
(*) Fully-incompressible materials can be modeled using the subroutine UserHyper.F , which will
be described in Lecture 5.
© 2011 ANSYS, Inc. May 9, 201416
Example of application
A simple bilinear plasticity material model, identical to
TB,BISO , is used to demonstrate the user material
subroutine usermat.F .
The example is a two-element test case under simple
tension. Element 1 has material defined using the TB,BISOoption, while Element 2 has material defined using the
TB,USER option. A 100% deformation is applied to both
elements. Finite deformation (NLGEOM,ON) is considered.
The /POST26 processor results of stress components and
plastic strain components are printed for both elements and
are expected to be the same.
© 2011 ANSYS, Inc. May 9, 201417
Example of application
Below is the description of the APDL syntax needed to use
usermat.F . In this specific example the user material was
assigned to material #2 and its mechanical properties,
namely Young’s modulus, Poisson’s ratio, yielding stress and
tangent modulus, are temperature-dependent. The number
of state variables is 8.
TB,USER,2,2,4TBTEMP,1.0TBDATA,1,190000,0.3,100,10TBTEMP,2.0TBDATA,1,210000,0.3,200,10TB,STATE,2,,8
© 2011 ANSYS, Inc. May 9, 201418
Example of application
Output information: TB,BISO vs. TB,USER
Information regarding the number of state variables,
inputted using the TB,STATE syntax, is provided as well:
© 2011 ANSYS, Inc. May 9, 201419
Example of application
/POST26 output: results are identical
© 2011 ANSYS, Inc. May 9, 201420
Example of application
In order to be able to get the values of the state variables,
the following APDL command should be inserted at the
/SOLU processor level:
OUTRES,SVAR,ALL
In particular, the option ALL allows writing the results for
every substep. Also, it might be convenient to print the
values of the state variables (8 in this example) in the
output file. This can be achieved by means of the following
do-loop to be inserted at the /POST1 processor level:
*DO,AR99,1,8PRESOL,SVAR,AR99
*ENDDO
© 2011 ANSYS, Inc. May 9, 201421
Example of application
Below is the list of the state variables utilized in this example:
SVAR 1 ----- > Equivalent plastic strain
SVAR 2 ----- > X component of plastic strain
SVAR 3 ----- > Y component of plastic strain
SVAR 4 ----- > Z component of plastic strain
SVAR 5 ----- > XY component of plastic strain
SVAR 6 ----- > YZ component of plastic strain
SVAR 7 ----- > XZ component of plastic strain
SVAR 8 ----- > von Mises stress
as also specified in the subroutine usermat3d :
© 2011 ANSYS, Inc. May 9, 201422
Example of application
/POST1 output: printout of state variable #1 (equivalent
plastic strain) at last substep.
© 2011 ANSYS, Inc. May 9, 201423
Example of application
State variables can also be plotted (the first one in this
example). This can be done by means of the following APDL
command:
PLESOL,SVAR,1
However, it is worth mentioning that this is not supported
by PowerGraphics. Therefore there is the need to insert the
/GRAPH,FULL command in the script.
We can also print/plot the evolution of the state variables
by utilizing this undocumented APDL command:
ESOL,…,…,…,SVAR,1PRVAR,1 (or PLVAR,1 to plot)
© 2011 ANSYS, Inc. May 9, 201424
Example of application
/POST26 output: graph of the evolution of state variable #1
(equivalent plastic strain).
0.692053
© 2011 ANSYS, Inc. May 9, 201425
Example of application
/POST26 output: printout of the evolution of state
variable #1 (equivalent plastic strain).
© 2011 ANSYS, Inc. May 9, 201426
Example of application
(A) structure with TB,BISOmaterial model
(B) structure with user-defined
elasto-plastic material model
APDL commands:
/POST1
PLESOL,NL,EPEQ,0,1.0
/POST1 output: contour plot of the equivalent plastic
strain at last substep. We notice that the results are
identical for both models.
(A)(B)
© 2011 ANSYS, Inc. May 9, 201427
Example of application
/POST1 output: contour plot of state variable #1
(equivalent plastic strain) at last substep. We notice that it
is non-zero only when considering the structure (cube on
the right) with the user-defined routine.
(A) structure with TB,BISOmaterial model
(B) structure with user-defined
elasto-plastic material model
APDL commands:
/POST1
PLESOL,SVAR,1
(A)(B)
© 2011 ANSYS, Inc. May 9, 201428
Where to find additional information
Additional information on rate-independent plasticity can
be found in the online manual:
Also, the ANSYS training course “ANSYS Mechanical –
Advanced Nonlinear Materials” provides detailed
information regarding plasticity and, in this respect, it is
recommended.
ANSYS Documentation > Mechanical APDL > Material Reference > 3. Material Models // 3.4. Rate-Independent Plasticity
ANSYS Documentation > Mechanical APDL > Theory Reference > 4. Structures with Material Nonlinearities > 4.2. Rate-Independent Plasticity
ANSYS Documentation > Mechanical APDL > Structural Analysis Guide > 8. Nonlinear Structural Analysis > 8.4. Modeling Material Nonlinearities
© 2011 ANSYS, Inc. May 9, 201429
Where to find additional information
Another usage example of the usermat subroutine is
available in the online documentation, precisely in Chapter
40 of the Technology Demonstration Guide:
ANSYS Documentation > Mechanical APDL > Technology Demonstration Guide > 40. Large-Deformation Neo-Hookean Analysis (via UserMat Subroutine)
The problem formulates a 3-D large deformation,
hyperelastic material to demonstrate the user material
capability in nonlinear geometry analyses. Details are given
for stress and material tangent calculations and formulation
in a co-rotated frame, as well as conversion of tensor
quantities to Voigt notation.