User Output Subroutine

Sheldon Imaoka
Memo Number: STI0806B
ANSYS Release: 11.0
June 1, 2008

1 Introduction

There are various situations where a user may wish to define specific type
of output to postprocess — this can range from simple evaluation of safety
factors to more involved damage calculations. While APDL, the ANSYS
command language, allows users to manipulate results in any manner one
sees fit, user-programmable features (UPFs) also provide a means for users
to calculate specific output results efficiently at the solution level.

2 Two Methods of Defining User Output

There are two UPFs that let users specify their own output calculations.
userou.F appends the NMISC record of supported elements — these results
can then be listed or plotted via element tables (ETABLE). The benefit of
userou.F is that many elements are supported, and postprocessing of ele-
ment table results is quite straightforward to perform. The drawbacks to
this method are that the number of NMISC records can be limited, depending
on the element type, and only a single value per element is usually output,
which provides less spatial variation than typical nodal quantities.
The alternative is the use of the undocumented userOut.F subroutine.
While this UPF is only applicable to 18x continuum elements — namely,
PLANE182-183, SOLID185-187, and SOLSH190 — quantities are stored as
state variables, so calculations are performed at the integration point level,
not per element as with userou.F. This means that the user can postprocess
averaged or unaveraged results directly with PLxSOL or PRxSOL commands.
Also, because state variables are used, values can be initialized with the
TBDATA command, and these values can be updated during the course of the
analysis. Because of the attractive qualities of userOut.F, this subroutine
will be the focus of the remainder of this memo despite the fact that it

1
Sheldon’s ansys.net Tips User Output Subroutine

is currently an undocumented feature at ANSYS 11.0. One should note,

however, that state variables are considered to be nonlinear in nature so are
consequently not extrapolated to nodes like linear results.1 Also, note that
use of userOut.F will assume nonlinear materials, so nonlinear equilibrium
iterations will be triggered.

3 Procedure

To incorporate the userOut.F subroutine, the user must perform the fol-
lowing actions:
• Define output quantities to be calculated as state variables in userOut.F.
Compile and link userOut.F to create a custom ANSYS executable.2

• Define the number of state variables with TB,STATE. If required, ini-

tialize any values with TBDATA.

• Specify the frequency at which state variables will be saved via OUT-
RES,SVAR. Note that the default behavior is not to save any state
variable results.

• Activate the userOut.F routine via USRCAL,USEROUT. Please do not

confuse this with USRCAL,USEROU, which activates the userou.F sub-
routine.

• After solution is complete, postprocess state variable results via PLx-

SOL or PRxSOL commands.

4 Simple Fatigue Example

The ANSYS Fatigue Module provides ANSYS Workbench Simulation users

with fatigue analysis capabilities using stress-life and strain-life approaches.
Unlike the ANSYS /POST1 fatigue calculations, users can postprocess life
and damage as contour plots on the entire model using the ANSYS Fatigue
Module.
A sample userOut.F subroutine has been included for demonstration
purposes, which stores signed von Mises stresses, mean stresses, stress am-
plitude, and biaxiality indication as four state variables. Signed von Mises
1
At ANSYS 12.0, an option to linearly extrapolate state variables may be added with
ERESX,YES. Please refer to the ANSYS 12.0 Documentation when ANSYS 12.0 becomes
available.
2
For additional details, refer to Reference [1].

2
Sheldon’s ansys.net Tips User Output Subroutine

takes the sign of the larger of the maximum and minimum principal stresses.
Based on an input stress ratio, the mean stress is determined, which is used
in conjunction with a user-defined ultimate strength to estimate the stress
amplitude using Goodman theory. Lastly, the biaxiality indication is cal-
culated — this is defined as the ratio of the principal stress with largest
magnitude divided by the next smaller value: a value of 1 reflects biaxial
stress state, a value of of 0 indicates unaxial stress state, while a value of
−1 is pure shear.
In Figure 1, one can see the biaxiality indication from both the ANSYS
Fatigue Module and the sample userOut.F subroutine, and one may notice
that the results compare favorably.3

1
NODAL SOLUTION
STEP=1
SUB =1
TIME=1
SVAR4
DMX =.276E-03
SMN =-.986456 -1
SMX =.94603

-.6

-.2

.2

.6

Y 1

Z X

(a) Workbench Simulation (b) ANSYS with userOut.F

Figure 1: Biaxiality Indication

The ANSYS Fatigue module contains many useful features to aid the
user interested in uniaxial fatigue theory. However, this demonstration sub-
routine may hopefully show that user-defined results can be calculated quite
easily with userOut.F in ANSYS for those wishing to implement their own
damage or fatigue calculations.

3
Because output from userOut.F at ANSYS 11.0 does not currently allow for linear
extrapolation, for comparison purposes, ERESX,NO was used for both models.

3
Sheldon’s ansys.net Tips User Output Subroutine

5 Example 1 for Cap Model

The Extended Drucker-Prager Cap Model (TB,EDP,,,,CYFUN) provides users

with modeling the shear failure and compaction of soil or powder materials.
The development of the effective deviatoric plastic strain γp is defined in
relation with an isotropic hardening law, such as TB,PLAS,,,,MISO. On the
other hand, volumetric plastic strain ǫpv can develop (a) in shear, depend-
ing on the parameters of the flow potential (TB,EDP,,,,CFPOT) and (b) in
compaction, based on the following equation:
 
ǫpv = W1c e(D1 −D2 (Xo −Xi ))(Xo −Xi ) − 1
c c
(1)

One may wish to postprocess these inelastic output quantities — al-

though a simple APDL macro will suffice in calculating volumetric plastic
strains from ǫpv = ǫpx + ǫpy + ǫpz , for example, the included userOut.F demon-
strates a way of calculating results based on plastic strain increments. The
results are stored as state variables #7 and #8 for inelastic deviatoric and
volumetric strain, respectively, as shown in the sample model in Figure 2.
(State variable #9 is volumetric strain based on total strain.)

1 1
ELEMENT SOLUTION ELEMENT SOLUTION
STEP=1 STEP=1
SUB =89 SUB =89
TIME=1 TIME=1
SVAR8 SVAR7
DMX =.028156 DMX =.028156
SMX =.001905 SMN =-.001755
SMX =.697E-03

0 .423E-03 .847E-03 .00127 .001694 -.001755 -.00121 -.665E-03 -.120E-03 .425E-03

.212E-03 .635E-03 .001058 .001482 .001905 -.001482 -.938E-03 -.393E-03 .152E-03 .697E-03

(a) Deviatoric Plastic Strain (b) Volumetric Plastic Strain

Figure 2: Plastic Strain

4
Sheldon’s ansys.net Tips User Output Subroutine

6 Example 2 for Cap Model

Besides geotechnical applications, the Cap model is also used in pharmaceu-

tical applications, namely the powder compaction of tablets. The volumetric
strain and relative density are related by Equation (2):
ρ
− ǫv = ln (2)
ρo
Here, ρo is the initial density while ǫv can be taken as the plastic or total
volumetric strain, depending on the user’s preference. The supplied exam-
ple userOut.F subroutine stores these relative density calculations as state
variables #9 and #10.
A simple example of a compaction of an axisymmetric model is shown
below, where the relative density based on total volumetric strain is shown
at maximum compression and after unloading in Figure 3.

1 1
NODAL SOLUTION NODAL SOLUTION
STEP=2 STEP=3
SUB =122 SUB =113
TIME=2 TIME=3
SVAR11 SVAR11
DMX =2.194 DMX =1.925
SMN =1.112 SMN =.952682
SMX =1.289 SMX =1.13

1.112 1.151 1.191 1.23 1.269 .952682 .992022 1.031 1.071 1.11
1.132 1.171 1.21 1.25 1.289 .972352 1.012 1.051 1.09 1.13
Relative Density (based on total strain) Relative Density (based on total strain)

(a) Relative Density at Max Compression (b) Relative Density after Unloading

Figure 3: Plastic Strain

While these quantities could be calculated from element tables, the use
of state variables allows these quantities to be output directly, as well as
providing results at the integration points rather than element centroid.

5
Sheldon’s ansys.net Tips User Output Subroutine

7 Conclusion

Although one may also use the userou.F subroutine to store user-calculated
results as NMISC records, this memo introduced the undocumented userOut.F
subroutine to calculate results as state variables for 18x continuum elements.
Although there are many applications of user-defined output, simple exam-
ples of calculating fatigue-related quantities as well as volumetric and devia-
toric inelastic strains have been presented. Please note that the userOut.F
subroutine is undocumented and, hence, unsupported, and the provided
subroutines have not been extensively tested, so users are cautioned against
using these for any production purposes without validating the content
themselves; the supplied subroutines are only provided for demonstrative
purposes.

References

[1] Sheldon Imaoka. User Creep Subroutine. ansys.net Tips and Tricks,
http://ansys.net/collection/1061, October 2007.

Revisions to this Document

• STI0806A (June 7, 2008): correction made to userOut.F subroutine

for Cap model (factor of 0.5 forgotten on shear term) as well as addition
of relative density calculations. Also added section on relative density
in memo.

• STI0806B (June 19, 2008): forgot to mention that this is currently (at
ANSYS 11.0) an undocumented feature, so users know that it is not
officially supported.

6
Sheldon’s ansys.net Tips General Information

Sheldon’s ansys.net Tips and Tricks

Sheldon’s ansys.net Tips and Tricks are available at the following URL:
http://ansys.net/sheldon tips/
Please remember that, with each release of ANSYS, new features and tech-
niques may be introduced, so please refer to the ANSYS documentation as
well as your local ANSYS support office to verify that these tips are the
most up-to-date method of performing tasks.
Disclaimer: the author has made attempts to ensure that the informa-
tion contained in this memo is accurate. However, the author assumes no
liability for any use (or misuse) of the information presented in this docu-
ment or accompanying files. Please refer to ansys.net for the latest version
of this document. Also, this memo and any accompanying input files are
not official ANSYS, Inc. documentation.

ANSYS Training

ANSYS, Inc. as well as ANSYS Channel Partners provide training classes

for ANSYS, Workbench, CFX, FLUENT, ANSYS LS-DYNA, AUTODYN,
ASAS, AQWA, TAS, and ICEM CFD products. Information on training
classes and schedules can be found on the following page:
http://www.ansys.com/services/ts-courses.asp

ANSYS Customer Portal

Customers on active maintenance (TECS) can register for a user account

and access the ANSYS Customer Portal. Here, browsing documentation,
downloading software (including service packs), and submitting technical
support incidents are possible: http://www1.ansys.com/customer/

XANSYS Mailing List

The XANSYS mailing list is a forum for exchanging ideas, providing and
receiving assistance from other users, and general discussions related to
ANSYS and Workbench. (Note that it is recommended to contact your
local ANSYS support office for technical support.) You can obtain more
information by visiting the following URL: http://www.xansys.org/