Lecture 1 - Introduction to UPFs

Implementing User-Programmable Features (UPFs) in ANSYS

1 © 2016 ANSYS, Inc. April 2, 2020

 Lecture overview
• What are UPFs?
• UPF capabilities
• Getting information on UPFs
• UPFs or APDL?
• What to know before using UPFs
• Planning/understanding UPFs
• Developing UPFs: a suggested strategy

2 © 2016 ANSYS, Inc. April 2, 2020

 What are UPFs?

User-Programmable Features (UPFs) are ANSYS capabilities

for which users can write their own Fortran routines(*). As
such, UPFs make it possible for users to tailor the
Mechanical APDL program to their needs.

For example, defining a new material behavior,

implementing a special finite element, or modifying a
failure criterion for composites are tasks that can be
achieved via UPFs.

More precisely, the next few slides provide a list of the UPF
capabilities.

(*)The C programming language can be used as well. An example of application can be found in the
folder: … \ANSYS Inc\v170\ansys\custom\user\winx64\Examples

3 © 2016 ANSYS, Inc. April 2, 2020

 UPF capabilities

UPFs provide many capabilities such as:

• Read information into or retrieve information from the

Mechanical APDL database;
• Specify various types of loads, including BF or BFE loads,
pressures, convections, heat fluxes, and charge densities;
• Customize contact interfacial behavior;
• Define the following material properties: plasticity, creep,
swelling law, viscoplasticity, hyperelasticity, and layered
element failure criteria;
• Implement new finite elements and adjust the nodal
orientation matrix.

4 © 2016 ANSYS, Inc. April 2, 2020

 UPF capabilities
Below is a Table summarizing the types of UPFs available:

The above Table as well as other information can be found in

the online manual:
ANSYS Documentation > Mechanical APDL > Advanced Analysis Guide > 9. User-Programmable Features
and Nonstandard Uses > 9.1. User-Programmable Features (UPFs)

5 © 2016 ANSYS, Inc. April 2, 2020

 Getting information on UPFs
UPF-related information can be found in the online manual, in
particular in Section II of the Programmer’s Reference:

ANSYS Documentation > Mechanical APDL > Programmer's Reference >

II. Guide to User-Programmable Features > 2. UPF Subroutines and Functions

6 © 2016 ANSYS, Inc. April 2, 2020

 UPFs or APDL?

There have been many situations in which it has been

mistakenly thought that UPFs were required in place of the
use of Mechanical APDL.

While APDL is a scripting language that may be slower to

execute than compiled code, APDL has vector functions that
speed up tasks considerably. Moreover, changing/adjusting
APDL input files is much easier than modifying subroutines
and recompiling/relinking them.

Hence, it should be considered whether or not the desired

functionality can be achieved via APDL, as that would
generally be a much easier, quicker approach than
implementing UPFs.

7 © 2016 ANSYS, Inc. April 2, 2020

 UPFs or APDL?
Also, let us note the following:

• APDL can be used to perform almost any task, including

creation of parametric models, modification of the FE
mesh, application of spatially- or time-varying boundary
conditions, or sophisticated postprocessing;
• APDL Math provides extraction and manipulation of the
matrices or vectors;
• UPFs are generally used when the built-in material laws
or element formulations are not sufficient. Examples
include defining one’s own constitutive law, changing the
way frictional contact is defined, or creating one’s own
special element type;
• APDL provides a wide breadth of functionality before or
after the SOLVE command is issued (i.e., preprocessing or
postprocessing). To change what the program does while
solving typically requires use of UPFs.
8 © 2016 ANSYS, Inc. April 2, 2020
 What to know before using UPFs

To use UPFs successfully, a strong working knowledge of the

following is required:
• The Mechanical APDL program, including the APDL
command language and how to activate the desired
UPFs;
• The UPF subroutines themselves. Before customizing
them, UPFs must be studied and the most appropriate
one(s) should be considered;
• The Fortran programming language. Also, the level of
the Fortran compiler should be at least as high as the
level mentioned in the ANSYS installation manual;
• The mathematics of the phenomenon to be included in
the appropriate UPF(s).

9 © 2016 ANSYS, Inc. April 2, 2020

 Planning/understanding UPFs

UPFs can range from a simple element output routine for

customized output to a complex user optimization.
Therefore, before starting programming, these points need
to be addressed:

1. Does the capability we need already exist in the ANSYS

program? A capability (e.g. an APDL command) may not
be obvious at first, especially to a novice user;

2. Search for the subroutine that would best address your

problem. Ensure that the subroutine supports the
element types you are using, and understand the
required input/output arguments.

10 © 2016 ANSYS, Inc. April 2, 2020

 Planning/understanding UPFs

A typical UPF involves the following steps:

1. Design and implement the desired user routine(s) in
Fortran;
2. Compile and link the user routine(s) into the Mechanical
APDL program;
3. Check if the changes made do not affect other, standard
ANSYS features;
4. Verify the user routine using an appropriate procedure. An
example of such procedure is given in the next slide.
Caution: using UPFs implies using the program in a nonstandard
way, one that ANSYS, Inc. verification testing does not cover.
The user is responsible for verifying that the results produced
are accurate and that the routines linked do not adversely
affect other, standard areas of the program.

11 © 2016 ANSYS, Inc. April 2, 2020

 Developing UPFs: a suggested strategy

In order to reduce debugging time, UPFs should be

implemented by following a gradual, orderly process.

It is highly recommended to start with a trivial test and then

add a few changes at a time in such a way that, if any errors
are encountered, the source of the problem could be
isolated and relatively easy to locate.

Also, it is suggested to study the examples given in this

documentation. A good understanding of them may reduce
the time spent in developing a brand new UPF.

12 © 2016 ANSYS, Inc. April 2, 2020